Support modules for composer apps

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 dist/
+module/
+logs/
 .DS_Store

AGENTS.md

@@ -11,23 +11,30 @@ This template provides:
 - Consistent layout components (header, sidebar, main content area)
 - Help modal system
 - Local development server with WebSocket support
+- **Composer-ready bundle**: `npm run build:module` outputs `module/` for hosts that load `/simulations/{id}/content.html`, `simulation.css`, and `simulation.js`
 - Standardized file structure and naming conventions
 
 ## Quick Start
 
 1. **Customize the HTML template** (`client/index.html`):
    - Replace `<!-- APP_TITLE -->` with your page title
    - Replace `<!-- APP_NAME -->` with your app name
-   - Add your main content at `<!-- APP_SPECIFIC_MAIN_CONTENT -->`
+   - Replace the default `<main id="standalone-sim-mount" …>` block with your layout (keep that `id` and `data-bespoke-sim-root` if you use `standalone.js` and composer hosts)
+   - Keep `client/content.html` in sync with the same inner markup for `build:module`
    - Add app-specific CSS links at `<!-- APP_SPECIFIC_CSS -->`
    - Add app-specific JavaScript at `<!-- APP_SPECIFIC_SCRIPTS -->`
 
 2. **Create your application files**:
    - App-specific CSS (e.g., `my-app.css`)
-   - App-specific JavaScript (e.g., `my-app.js`)
+   - App-specific JavaScript (e.g., `my-app.js`); export `init(context)` from `simulation-app.js` for composer hosts
    - Help content (based on `help-content-template.html`)
 
-3. **Start the development server**:
+3. **Composer / multi-app host** (optional):
+   - Run `npm run build` for the full static app (`dist/`) and `npm run build:module` for the host bundle (`module/`)
+   - Serve the module tree with `IS_PRODUCTION=true SERVE_DIR=module PORT=<port> node server.js` (each app on its own port when the host proxies `/simulations/{id}/…`)
+   - Match `SIM_ID` in `client/standalone.js` to the `id` in the host’s `simulations.json`
+
+4. **Start the development server**:
    ```bash
    npm start
    ```
@@ -93,17 +100,17 @@ See [BESPOKE-TEMPLATE.md](./BESPOKE-TEMPLATE.md).
 
 ```
 client/
-  ├── index.html              # Main HTML template
-  ├── app.js                  # Application logic
-  ├── bespoke-template.css    # Template-specific styles
-  ├── help-modal.js           # Help modal system
-  ├── help-content-template.html  # Help content template
-  └── design-system/          # CodeSignal Design System
-      ├── colors/
-      ├── spacing/
-      ├── typography/
-      └── components/
-server.js                      # Development server
+  ├── index.html               # Main HTML template
+  ├── app.js                   # Shell: help modal + WebSocket
+  ├── standalone.js            # Standalone init(context) + /api/log
+  ├── simulation-app.js        # Composer entry: export init(context)
+  ├── content.html             # Fragment for composer host
+  ├── bespoke-simulation.css   # Styles for fragment → module/simulation.css
+  ├── bespoke-template.css     # Template layout
+  ├── help-content.html        # Help body HTML
+  └── design-system/           # CodeSignal Design System (git submodule)
+server.js                       # API + static (dist/ or module/ via SERVE_DIR)
+vite.config.module.js          # build:module → module/
 ```
 
 ## Notes for AI Agents

BESPOKE-TEMPLATE.md

@@ -3,7 +3,7 @@
 This document provides precise implementation instructions for creating
 embedded applications using the Bespoke Simulation template. Follow these
 instructions exactly to ensure consistency across all applications.
-NOTE: Never edit this `BESPOKE-TEMPLATE.md` file. Codebase changes should be reflected in the `AGENTS.md` file.
+Keep this document aligned with template behavior; `AGENTS.md` summarizes the same conventions for contributors.
 
 ## Required Files Structure
 
@@ -37,9 +37,10 @@ Every application should include these files in the following order:
       Replace with your application's display name (appears in header)
       Example: "Database Designer" or "Task Manager"
 
-   c) `<!-- APP_SPECIFIC_MAIN_CONTENT -->`
-      Add your application's main content area
-      Example: `<div id="canvas"></div>` or `<div id="editor"></div>`
+   c) Main content area
+      Replace the default `<main id="standalone-sim-mount" data-bespoke-sim-root>…</main>` block with your layout.
+      If you use a composer host, keep the same inner markup in `client/content.html` (fragment the host injects).
+      Preserve `id="standalone-sim-mount"` when using `standalone.js` unless you update `simulation-app.js` accordingly.
 
    d) `<!-- APP_SPECIFIC_CSS -->`
       Add links to your application-specific CSS files
@@ -49,7 +50,23 @@ Every application should include these files in the following order:
       Add links to your application-specific JavaScript files
       Example: `<script src="./my-app-logic.js"></script>`
 
-2. DO NOT modify the core structure (header, script loading order, etc.)
+2. DO NOT modify the core structure (header, script loading order, etc.) without reviewing `app.js`, `standalone.js`, and host loaders.
+
+## Composer hosts (multi-app workspace)
+
+Composer-style hosts load each app from the same origin under `/simulations/{id}/`:
+
+1. `content.html` — HTML fragment injected into a `.sim-slot[data-sim-id="{id}"]`
+2. `simulation.css` — styles for that fragment (from `bespoke-simulation.css` in this template)
+3. `simulation.js` — ES module exporting `init(context)` (and optionally `onAction`, `onMessage`)
+
+**Build:** `npm run build:module` writes these files under `module/`. The Rollup build marks `design-system/*` as external so the host page supplies those assets once.
+
+**Serve for the host:** `IS_PRODUCTION=true SERVE_DIR=module PORT=<port> node server.js` serves `module/` as static files. Use a distinct `PORT` per app when the host reverse-proxies to each repo.
+
+**Runtime contract:** `context` includes `config` (spread from the host registry, plus `basePath` like `/simulations/your-id`) and `emit(eventType, payload)` for telemetry. The template resolves DOM via `.sim-slot[data-sim-id]` + `[data-bespoke-sim-root]`; standalone mode uses `#standalone-sim-mount`.
+
+**Logging:** `POST /api/log` accepts `{ "entries": [...] }` and appends JSON lines to `logs/events.jsonl` (used by `standalone.js` and typical hosts).
 
 ## CSS Implementation
 

README.md

@@ -2,6 +2,8 @@
 
 This directory contains a template for creating embedded applications that share a consistent design system and user experience.
 
+Each app can run as a **normal static site** (`npm run build` → `dist/`) and as a **bundle for composer hosts** (`npm run build:module` → `module/`). Hosts fetch `/simulations/{id}/content.html`, `simulation.css`, and `simulation.js`; serve the module tree with `IS_PRODUCTION=true SERVE_DIR=module PORT=<port> node server.js`. See `AGENTS.md` and `BESPOKE-TEMPLATE.md`.
+
 ## Components
 
 ### 1. Design System Integration
@@ -24,12 +26,8 @@ A base HTML template that includes:
 - Help modal integration
 - Proper CSS and JavaScript loading
 
-### 4. `client/help-modal.js`
-A dependency-free JavaScript module for the help modal system:
-- Consistent modal behavior across all apps
-- Keyboard navigation (ESC to close)
-- Focus management
-- Custom event system
+### 4. `client/app.js` and `client/standalone.js`
+Shell behavior (help modal via design system `Modal`, WebSocket) plus standalone `init(context)` wiring for the same contract composer hosts use.
 
 ### 5. `client/help-content-template.html`
 A template for creating consistent help content:
@@ -52,7 +50,7 @@ A template for creating consistent help content:
    - `<!-- APP_TITLE -->` - Your application title
    - `<!-- APP_NAME -->` - Your application name (appears in header)
    - `<!-- APP_SPECIFIC_HEADER_CONTENT -->` - Any additional header elements
-   - `<!-- APP_SPECIFIC_MAIN_CONTENT -->` - Your main content area
+   - Default `<main id="standalone-sim-mount" …>` / `client/content.html` — your main UI (keep in sync for composer)
    - `<!-- APP_SPECIFIC_CSS -->` - Links to your app-specific CSS files
    - `<!-- APP_SPECIFIC_SCRIPTS -->` - Links to your app-specific JavaScript files
 

client/bespoke-simulation.css

@@ -0,0 +1,12 @@
+/* Styles for simulation fragment (bundled as module/simulation.css) */
+.bespoke-sim-intro {
+  max-width: 36rem;
+}
+
+.bespoke-sim-hint code {
+  font-size: 0.9em;
+}
+
+.bespoke-sim-standalone-mount {
+  padding: var(--UI-Spacing-spacing-ml, 1rem);
+}

client/content.html

@@ -0,0 +1,10 @@
+<!-- Fragment mounted by composer hosts under /simulations/{id}/content.html -->
+<main data-bespoke-sim-root>
+  <section class="box card bespoke-sim-intro">
+    <h2 class="heading-small">Your app</h2>
+    <p class="body-default bespoke-sim-hint">
+      Replace this markup and extend <code>simulation-app.js</code>. Keep this file in sync with the standalone block in <code>index.html</code> when you use both modes.
+    </p>
+    <button type="button" class="button button-primary" id="btn-sim-demo">Send sample event</button>
+  </section>
+</main>

client/index.html

@@ -24,22 +24,32 @@
 
   <!-- Template-specific components (layout, utilities, temporary components) -->
   <link rel="stylesheet" href="./bespoke-template.css" />
+  <link rel="stylesheet" href="./bespoke-simulation.css" />
   <!-- APP_SPECIFIC_CSS -->
 </head>
 <body class="bespoke">
   <!-- Navigation Header -->
   <header class="header">
-    <h1 class="heading-small">APP NAME</h1>
+    <h1 class="heading-small"><!-- APP_NAME --></h1>
     <!-- APP_SPECIFIC_HEADER_CONTENT -->
     <div class="spacer"></div>
     <button id="btn-help" class="button button-text">Help</button>
   </header>
 
-  <!-- Main Application Content -->
-  <!-- APP_SPECIFIC_MAIN_CONTENT -->
+  <!-- Main Application Content: default starter below — replace when customizing; keep id & data-bespoke-sim-root if you use standalone.js + composer -->
+  <main id="standalone-sim-mount" class="bespoke-sim-standalone-mount" data-bespoke-sim-root>
+    <section class="box card bespoke-sim-intro">
+      <h2 class="heading-small">Your app</h2>
+      <p class="body-default bespoke-sim-hint">
+        Replace this block when customizing; keep in sync with <code>client/content.html</code> for composer builds.
+      </p>
+      <button type="button" class="button button-primary" id="btn-sim-demo">Send sample event</button>
+    </section>
+  </main>
 
   <!-- Core Scripts -->
   <script type="module" src="./app.js"></script>
+  <script type="module" src="./standalone.js"></script>
   <!-- APP_SPECIFIC_SCRIPTS -->
 </body>
 </html>

client/simulation-app.js

@@ -0,0 +1,47 @@
+/**
+ * Simulation entry for composer hosts: exports init(context).
+ * Hosts load content.html, simulation.css, then import ./simulation.js
+ * (see composer template simulation-loader.js).
+ */
+
+function escapeSelector(id) {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(id);
+  }
+  return id.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function resolveRoot(context) {
+  const simId = context.config?.id;
+  if (simId) {
+    const slot = document.querySelector(
+      `.sim-slot[data-sim-id="${escapeSelector(simId)}"]`
+    );
+    const inner = slot?.querySelector('[data-bespoke-sim-root]');
+    if (inner) return inner;
+    if (slot) return slot;
+  }
+  return document.getElementById('standalone-sim-mount');
+}
+
+function bindDemo(root, emit) {
+  const btn = root.querySelector('#btn-sim-demo');
+  if (!btn) return;
+  btn.addEventListener('click', () => {
+    emit('demo:click', { source: 'template' });
+  });
+}
+
+export function init(context = {}) {
+  const emit =
+    typeof context.emit === 'function'
+      ? context.emit
+      : () => {};
+
+  const root = resolveRoot(context);
+  if (!root) {
+    console.warn('simulation-app: no mount root found');
+    return;
+  }
+  bindDemo(root, emit);
+}

client/standalone.js

@@ -0,0 +1,43 @@
+/**
+ * Standalone page: same init(context) contract as composer hosts.
+ * Set SIM_ID to the id used in the host's simulations.json.
+ */
+import { init } from './simulation-app.js';
+
+const SIM_ID = 'bespoke-app';
+
+const logBuffer = [];
+let flushTimer = null;
+
+function flushLogs() {
+  const entries = logBuffer.splice(0);
+  flushTimer = null;
+  if (entries.length === 0) return;
+  fetch('/api/log', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ entries })
+  }).catch(err => console.error('Failed to flush logs:', err));
+}
+
+function pushLog(entry) {
+  logBuffer.push({ ...entry, ts: new Date().toISOString() });
+  if (!flushTimer) flushTimer = setTimeout(flushLogs, 1000);
+}
+
+const context = {
+  config: { id: SIM_ID, basePath: '' },
+  emit: (eventType, payload = {}) => {
+    pushLog({ simId: SIM_ID, dir: 'event', type: eventType, payload });
+  }
+};
+
+function boot() {
+  init(context);
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}

package.json

@@ -9,7 +9,8 @@
     "start:dev": "concurrently \"npm run dev:vite\" \"npm run dev:api\"",
     "dev:vite": "vite",
     "dev:api": "PORT=3001 node server.js",
-    "build": "vite build"
+    "build": "vite build",
+    "build:module": "vite build --config vite.config.module.js"
   },
   "keywords": [
     "bespoke",