@voxgig/build 4.3.0 → 4.11.0

package/tm/web/backend/test/unit/srv/ent/proxy.test.ts.frag

@@ -0,0 +1,109 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert'
+
+import { makeSeneca, as } from './ent.setup'
+
+
+// The browser proxies: aim:web,on:ent,cmd:* -> aim:ent,cmd:*
+//
+// A browser may only send aim:web, so these four actions ARE the entity
+// surface. Two things matter: they forward faithfully, and they are not a
+// way around the rules the real commands enforce.
+//
+// Forwarding is checked on the action functions directly - they are plain
+// modules, so a fake `this` records what they post. No boot, no store, and
+// nothing that depends on which entities this model happens to have.
+
+const ALICE = { id: 'u-alice', email: 'alice@ex.com' }
+
+const OPS = ['list', 'load', 'save', 'remove']
+
+function proxyAction(op: string) {
+  return require('../../../../dist/srv/ent/web_cmd_' + op + '.js')()
+}
+
+// A `this` that records posts instead of sending them.
+function recorder(result: any = { ok: true }) {
+  const posts: any[] = []
+  return {
+    posts,
+    ctx: {
+      post: async (pattern: string, msg: any) => {
+        posts.push({ pattern, msg })
+        return result
+      },
+    },
+  }
+}
+
+
+describe('entity browser proxies', () => {
+
+  test('each proxy forwards to its own entity command', async () => {
+    for (const op of OPS) {
+      const rec = recorder()
+      await proxyAction(op).call(rec.ctx, { ent: 'x/y' })
+      assert.strictEqual(rec.posts.length, 1, op)
+      assert.strictEqual(rec.posts[0].pattern, 'aim:ent,cmd:' + op, op)
+    }
+  })
+
+
+  test('arguments travel through unchanged', async () => {
+    const rec = recorder()
+
+    await proxyAction('list').call(rec.ctx, { ent: 'x/y', q: { a: 1 } })
+    assert.deepStrictEqual(rec.posts[0].msg.q, { a: 1 })
+    assert.strictEqual(rec.posts[0].msg.ent, 'x/y')
+
+    await proxyAction('load').call(rec.ctx, { ent: 'x/y', id: 'e01' })
+    assert.strictEqual(rec.posts[1].msg.id, 'e01')
+
+    await proxyAction('save').call(rec.ctx, { ent: 'x/y', item: { t: 'v' } })
+    assert.deepStrictEqual(rec.posts[2].msg.item, { t: 'v' })
+
+    await proxyAction('remove').call(rec.ctx, { ent: 'x/y', id: 'e01' })
+    assert.strictEqual(rec.posts[3].msg.id, 'e01')
+  })
+
+
+  test('the result is returned unchanged', async () => {
+    const rec = recorder({ ok: true, list: [{ id: 'e01' }] })
+    const out = await proxyAction('list').call(rec.ctx, { ent: 'x/y' })
+    assert.deepStrictEqual(out, { ok: true, list: [{ id: 'e01' }] })
+
+    const failed = recorder({ ok: false, why: 'forbidden' })
+    const bad = await proxyAction('load').call(failed.ctx, { ent: 'x/y', id: 'e01' })
+    assert.deepStrictEqual(bad, { ok: false, why: 'forbidden' })
+  })
+
+
+  test('proxies enforce the same rules, not weaker ones', async () => {
+    const seneca = await makeSeneca()
+
+    // Unauthenticated: refused, exactly like the real commands.
+    for (const cmd of OPS) {
+      const out = await seneca.post({
+        aim: 'web', on: 'ent', cmd, ent: 'sys/user', id: 'x', item: {},
+      })
+      assert.strictEqual(out.ok, false, cmd)
+      assert.strictEqual(out.why, 'not-authenticated', cmd)
+    }
+
+    // The sys zone stays unreachable through the proxy.
+    const sys = await as(seneca, ALICE,
+      { aim: 'web', on: 'ent', cmd: 'list', ent: 'sys/apikey' })
+    assert.strictEqual(sys.ok, false)
+    assert.strictEqual(sys.why, 'unknown-entity')
+
+    // sys/user remains read-only through it too.
+    const write = await as(seneca, ALICE, {
+      aim: 'web', on: 'ent', cmd: 'save', ent: 'sys/user', item: { name: 'Hacked' },
+    })
+    assert.strictEqual(write.ok, false)
+    assert.strictEqual(write.why, 'read-only')
+
+    await seneca.close()
+  })
+})
+

package/tm/web/docs/explanation/web-architecture.md.frag

@@ -0,0 +1,50 @@
+# Explanation: web app architecture
+
+*Diátaxis: explanation — why the generated app is built this way.*
+
+## One primitive: Seneca messages
+
+The frontend is web components on a browser Seneca bus. Every data flow —
+backend CRUD, auth, cross-component events, cache reactivity — is a
+pattern-matched message. `aim:*` messages travel transparently to the
+backend gateway (the same patterns the backend services answer); local
+concerns stay local. One primitive means one debugging story (the
+in-window devtools show every flow), one interception point (the store
+cache), and no parallel event system to keep consistent.
+
+## Model-driven at runtime
+
+The app fetches `/model.json` and derives its UI from it: the entity
+menu, list columns, forms, relationship pickers and drill-down (from
+`ref` fields), project scoping. Adding an entity to the model changes the
+running UI on reload — no regeneration, no per-entity components, no
+merge conflicts. This is what lets the same generated codebase serve an
+entity graph of hundreds of entities.
+
+## Access is membership, not ownership
+
+Signed-in users collaborate through projects: membership in a project
+grants access to the project's data (any entity carrying a
+`ref: 'proj/project'` field is scoped to the selected project). The
+generic backend `ent` service enforces this on every message — the
+frontend only *reflects* scoping (the project selector), it never
+enforces it.
+
+## Generated once, then yours
+
+The SPA is a starting point, not a framework artifact: after generation
+the project owns it. Customisation is layered so upgrades stay cheap —
+theme tokens (model) → CSS overrides (`custom.css`) → hooks
+(`customise.js`) → custom entity views (model-declared) → direct edits
+(last resort). Only `views.js` and `theme.css` regenerate, because they
+are pure functions of the model.
+
+## No framework, deliberately
+
+Vanilla custom elements + `innerHTML` rendering keep the generated code
+dependency-light, readable, and long-lived (no framework version
+treadmill in generated projects). The cost — manual re-render discipline —
+is contained by two conventions: explicit `reload()` calls after
+mutations, and a render token to discard stale async renders (see
+`cmp/admin.js`).
+

package/tm/web/docs/how-to/add-a-custom-entity-view.md.frag

@@ -0,0 +1,53 @@
+# How to add a custom entity view
+
+*Diátaxis: how-to guide — replace the generic admin UI for one entity
+with a hand-coded component, declared in the model.*
+
+## 1. Declare it in the model
+
+In `backend/model/ent.aontu`, mark the entity:
+
+```
+shop: product: ux: { view: 'custom' }
+```
+
+## 2. Generate the starter
+
+```bash
+cd backend && npm run model-build
+```
+
+This creates `web/src/cmp/view/shop_product.js` (a working starter
+component — create-once, so your edits survive every future build) and
+regenerates `web/src/views.js`, the index that imports all custom views.
+The shell now mounts `<vg-view-shop-product>` instead of the generic
+`<vg-entity-admin>` for that entity.
+
+## 3. Implement the view
+
+The component contract (same as the generic admin):
+
+- **Properties** (set by the shell before `reload()`):
+  - `canon` — the entity canon, e.g. `'shop/product'`
+  - `projectId` — current project id when the entity is project-scoped,
+    else `null`
+  - `detailId` — an entity id to open in detail, or `null`
+  - `onNavigate(canon, id)` — call to navigate elsewhere in the app
+- **Method**: `reload()` — re-fetch and re-render.
+
+Use the same building blocks the generic admin uses:
+
+```js
+import * as Model from '../../model.js'   // labels, fields, refs graph
+import * as Api from '../../api.js'       // Api.list/load/save/remove(canon, ...)
+```
+
+Data via `Api` goes through the generic `aim:ent` messages, so
+membership scoping and validation apply unchanged.
+
+## Reverting
+
+Remove the `ux` declaration and run `model-build` — `views.js` drops the
+import and the entity falls back to the generic admin. Your component
+file stays (delete it manually if unwanted).
+

package/tm/web/docs/how-to/change-the-theme.md.frag

@@ -0,0 +1,63 @@
+# How to change the theme
+
+*Diátaxis: how-to guide — the design theme is part of the model; modes
+and tokens flow from there into generated CSS.*
+
+## Change a token
+
+Edit `backend/model/theme.aontu` — each named mode (light, dark, ...) is
+a set of design tokens:
+
+```
+modes: {
+  light: {
+    primary: '#7c3aed'
+    # ...
+  }
+}
+```
+
+Then regenerate:
+
+```bash
+cd backend && npm run model-build
+```
+
+`web/src/theme.css` is rewritten: every token becomes a CSS variable
+(`--vg-primary`, ...) scoped to its mode
+(`:root[data-theme-mode="light"]`; the default mode also on `:root`).
+Do not edit `theme.css` by hand — it regenerates from the model.
+
+## Add a mode
+
+Add a new block under `modes:` (e.g. `sepia: { ... }`) with the same
+token set, and set `mode:` if it should be the default. After
+`model-build`, the shell's user menu automatically offers the new mode
+(the toggle appears whenever more than one mode exists), and the user's
+choice persists (localStorage `vg-theme-mode`).
+
+## Override per project without touching the model
+
+`web/src/custom.css` loads after the theme:
+
+```css
+:root { --vg-radius: 10px; }                      /* all modes */
+:root[data-theme-mode="dark"] { --vg-bg: #000; }  /* one mode */
+```
+
+## Add modes or intercept the mode list at runtime
+
+```js
+// web/src/customise.js
+import * as Hooks from './hooks.js'
+Hooks.addFilter('theme:modes', (modes) => [...modes, 'sepia'])
+```
+
+(Provide the CSS for a runtime-added mode yourself in `custom.css`.)
+
+## Standard tokens
+
+`primary`, `primary-dark`, `bg`, `surface`, `text`, `muted`, `border`,
+`topbar-bg`, `topbar-fg`, `accent-bg`, `font`, `radius`, `shadow-card`.
+Any additional token you add becomes `--vg-<token>` too.
+

package/tm/web/docs/how-to/customise-the-web-app.md.frag

@@ -0,0 +1,68 @@
+# How to customise the web app
+
+*Diátaxis: how-to guide — change the generated app's look and behaviour
+without editing generated components.*
+
+Customisations live in two create-once files that survive regeneration:
+`web/src/customise.js` (hook registrations) and `web/src/custom.css`
+(style overrides).
+
+## Inject or change HTML
+
+```js
+// web/src/customise.js
+import * as Hooks from './hooks.js'
+
+Hooks.addHtml('shell:topbar:right', () => '<span class="vg-badge">Beta</span>')
+Hooks.addHtml('admin:row:actions', ({ canon }) =>
+  'todo/item' === canon ? '<button class="vg-star" data-act="star">star</button>' : '')
+```
+
+## Transform data
+
+```js
+// Sort or filter list rows before render:
+Hooks.addFilter('admin:list:items', (items, { canon }) =>
+  'todo/item' === canon
+    ? items.slice().sort((a, b) => (a.done === b.done ? 0 : a.done ? 1 : -1))
+    : items)
+
+// Adjust the save payload:
+Hooks.addFilter('admin:save:data', (data) => ({ ...data, source: 'web' }))
+```
+
+## Run behaviour at lifecycle moments
+
+```js
+Hooks.addAction('admin:list:after', ({ root, canon, items }) => {
+  // wire events on injected elements, integrate analytics, etc.
+})
+```
+
+All hooks are synchronous and failure-isolated (a throwing hook is logged
+and skipped). The full list of points is in the
+[web app reference](../reference/web-app.md#hook-points).
+
+## Override styles
+
+Generated styles use CSS variables from the theme. Override tokens or add
+rules in `web/src/custom.css`:
+
+```css
+:root { --vg-primary: #7c3aed; }
+.vg-badge { background: gold; color: #333; }
+```
+
+For theme-wide changes (all modes, or new modes), change the model
+instead — see [Change the theme](change-the-theme.md).
+
+## When hooks aren't enough
+
+- Replace an entity's whole view:
+  [Add a custom entity view](add-a-custom-entity-view.md).
+- Backend behaviour: override Seneca actions with priors in the backend
+  services.
+- As a last resort, edit the generated components directly — they are
+  create-once and yours; just note that framework updates then need a
+  manual merge.
+

package/tm/web/docs/how-to/use-the-api.md.frag

@@ -0,0 +1,53 @@
+# How to use the REST API
+
+*Diátaxis: how-to guide — the strict-JSON REST API generated from the
+model (`main.api` in `backend/model/api.aontu`).*
+
+## Get an API key
+
+Sign in to the web app → user menu → **Settings & security** → **API
+keys** → create a key. Copy it immediately — it is shown only once (only
+a hash is stored). Revoke keys there too; revocation is immediate.
+
+## Call the API
+
+Uniform semantic paths per entity — `<prefix>/<version>/<zone>/<name>`:
+
+```bash
+KEY=vk_...
+B=http://localhost:8080/api/v1
+
+curl -H "Authorization: Bearer $KEY" $B/proj/project            # list
+curl -H "Authorization: Bearer $KEY" "$B/proj/project?name=X"   # filtered list
+curl -H "Authorization: Bearer $KEY" $B/proj/project/<id>       # load
+curl -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
+  -d '{"name":"New project"}' $B/proj/project                   # create -> 201
+curl -X PUT -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
+  -d '{"note":"updated"}' $B/proj/project/<id>                  # partial update
+curl -X DELETE -H "Authorization: Bearer $KEY" $B/proj/project/<id>
+```
+
+Results: `{ items: [...] }` (list), `{ item: {...} }` (load/create/update),
+`{ ok: true, id }` (delete). Errors carry an HTTP status and
+`{ error: { code, message?, details? } }`.
+
+The API is **strict**: request bodies are validated against the entity's
+model definition (generated shapes) — unknown fields are rejected (400),
+required fields enforced, server-managed fields (`id`, `owner_id`,
+`t_c`, `t_m`) are read-only. Access is the same project-membership
+scoping as the web app, as the key's owning user.
+
+## The OpenAPI spec
+
+Generated from the model on every model-build:
+`backend/gen/api/openapi.json`, also served unauthenticated at
+`<prefix>/openapi.json`. Schemas come from the entity field definitions;
+operation ids are uniform (`list_<zone>_<name>`, `create_...`, ...) so an
+SDK can be generated from it (e.g. with sdkgen).
+
+## Configure
+
+`backend/model/api.aontu` — `prefix`, `version`, `active`, and per-entity
+exposure (`ent: 'zone/name': { active: false }`). The sys zone is never
+exposed. Run `npm run model-build` after changes.
+

package/tm/web/docs/reference/web-app.md.frag

@@ -0,0 +1,98 @@
+# Reference: the web app
+
+*Diátaxis: reference — the generated SPA's structure, messages, hook
+points, and theme contract.*
+
+## Files (web/src/)
+
+| File | Role | Regenerated? |
+|---|---|---|
+| `main.js` | Entry: imports css, bus, components, views, customise | no |
+| `bus.js` | The browser Seneca bus (transport to the backend gateway) | no |
+| `model.js` | Runtime model: fetches `/model.json`; entities, refs graph, labels, project scoping, custom-view tags | no |
+| `api.js` | Client for `aim:ent` CRUD + `aim:auth` | no |
+| `hooks.js` | Customisation hook registry | no |
+| `theme.js` | Theme mode controller (persisted; applies `data-theme-mode`) | no |
+| `style.css` | App styles (consume `--vg-*` variables) | no |
+| `theme.css` | CSS variables per theme mode | **yes — from the model** |
+| `views.js` | Index importing custom entity views | **yes — from the model** |
+| `customise.js` / `custom.css` | Project customisations | no (yours) |
+| `cmp/app.js` | Router: signed-out → public, signed-in → shell | no |
+| `cmp/public.js` | Public site + login mount | no |
+| `cmp/auth.js` | Login / forgot-password form | no |
+| `cmp/shell.js` | App shell: topbar, project selector, user menu, entity nav | no |
+| `cmp/admin.js` | Generic entity admin (list/detail/form, relationship drill) | no |
+| `cmp/settings.js` | Profile + change password | no |
+| `cmp/view/*.js` | Custom entity views (one per `ux:{view:'custom'}` entity) | no (starters) |
+
+## Backend messages used
+
+**The browser may only send `aim:web` messages.** The gateway allow-list
+names that one namespace, and every message the SPA sends is declared in
+the model as an `aim:web` PROXY that forwards to the real service message
+(`web_*` action files). Service namespaces (`aim:auth`, `aim:ent`,
+`aim:api`, ...) are internal: posting one from a browser is rejected with
+`not-allowed`. API-key clients have the same shape - the REST router
+posts `aim:api`, which is likewise not browser-reachable.
+
+| Browser message | Proxies to | Purpose |
+|---|---|---|
+| `aim:web,on:ent,cmd:list,ent:<canon>` (+`q`) | `aim:ent,cmd:list` | List (membership/project-scoped) |
+| `aim:web,on:ent,cmd:load,ent:<canon>` (+`id`) | `aim:ent,cmd:load` | Load one |
+| `aim:web,on:ent,cmd:save,ent:<canon>` (+`item`) | `aim:ent,cmd:save` | Create/update |
+| `aim:web,on:ent,cmd:remove,ent:<canon>` (+`id`) | `aim:ent,cmd:remove` | Delete |
+| `aim:web,on:auth,load:auth` | `aim:auth,load:auth` | Current principal |
+| `aim:web,on:auth,signin:user` / `signout:user` | `aim:auth,*` | Session (sets/clears the cookie) |
+| `aim:web,on:auth,change:pass` / `update:user` | `aim:auth,*` | Settings & security |
+| `aim:web,on:auth,remind:pass` | `aim:auth,remind:pass` | Password reminder (server stub) |
+| `aim:web,on:auth,create:apikey` / `list:apikey` / `revoke:apikey` | `aim:auth,*` | API keys |
+
+To expose a new operation to the browser, declare an `aim:web` proxy for
+it in the model and implement the `web_*` action - never widen the
+allow-list.
+
+## Hook points
+
+Register in `customise.js`; kinds: `html` (inject markup), `filter`
+(transform a value), `action` (side effect). All synchronous,
+failure-isolated.
+
+| Point | Kind | Context / value |
+|---|---|---|
+| `shell:topbar:right` | html | `{ user }` |
+| `shell:sidebar:top` | html | `{ user }` |
+| `shell:nav:items` | filter | entity list for the nav menu |
+| `admin:list:toolbar` | html | list toolbar region |
+| `admin:list:items` | filter | rows before render |
+| `admin:list:columns` | filter | column defs |
+| `admin:row:actions` | html | per-row action cell |
+| `admin:list:after` | action | `{ root, canon, items }` |
+| `admin:form:fields` | filter | form field defs |
+| `admin:form:extra` | html | extra form markup |
+| `admin:form:after` | action | after form render |
+| `admin:save:data` | filter | payload before save |
+| `admin:save:after` | action | after successful save |
+| `public:sections` | html | extra public-site sections |
+| `auth:form:footer` | html | login form footer |
+| `settings:sections` | html | extra settings sections |
+| `theme:modes` | filter | available theme mode list |
+
+## Theme contract
+
+- Model: `main.theme` = `{ mode, modes: { <name>: { <token>: <value> } } }`
+  (source: `backend/model/theme.aontu`).
+- Generated CSS: each token → `--vg-<token>` under
+  `:root[data-theme-mode="<name>"]`; default mode also on `:root`.
+- Runtime: `theme.js` sets `data-theme-mode` on `<html>`; choice persists
+  in localStorage `vg-theme-mode`; shell user menu toggles when more than
+  one mode exists.
+- Standard tokens: `primary`, `primary-dark`, `bg`, `surface`, `text`,
+  `muted`, `border`, `topbar-bg`, `topbar-fg`, `accent-bg`, `font`,
+  `radius`, `shadow-card`.
+
+## Custom entity view contract
+
+Tag `vg-view-<zone>-<name>`; properties `canon`, `projectId`, `detailId`,
+`onNavigate(canon, id)`; method `reload()`. Declared by
+`ux: { view: 'custom' }` on the model entity.
+

package/tm/web/web/AGENTS.md.frag

@@ -0,0 +1,52 @@
+# Agent guide: $$name$$ web app
+
+The model-driven SPA for $$name$$: vanilla web components on a browser
+Seneca message bus (no framework). Generated once by @voxgig/build EnvWeb;
+now developer-owned. Backend guide: ../AGENTS.md. Concept docs:
+../docs/ (see reference/web-app.md and explanation/web-architecture.md).
+
+## Commands (run in web/)
+
+```bash
+npm install
+npm run dev        # vite dev server (backend must be running: npm run web in backend/)
+npm run e2e        # playwright e2e (headless; starts its own backend)
+```
+
+E2e tests run headless Chromium with workers=1 against a shared backend —
+keep new specs independent of execution order but tolerant of shared seed
+data.
+
+## Architecture in one paragraph
+
+`main.js` imports theme/css, the bus, all components, `views.js`
+(generated index of custom views), and `customise.js` (project hooks).
+All data flows are Seneca messages on `bus.js`. **Only `aim:web`
+messages leave the browser** - that is the sole namespace the gateway
+accepts, and each one is a declared proxy to a real service message;
+`cmp:*` and events stay local. The transport pin is `aim:web` too, so a
+stray service-message post fails locally instead of travelling. The UI is
+model-driven at runtime — `model.js` fetches `/model.json` and derives
+the entity menu, forms, and relationship navigation; `api.js` wraps the
+`aim:web,on:ent,cmd:*` CRUD proxies and the `aim:web,on:auth,*` proxies.
+
+## Editing rules
+
+- Everything here is create-once EXCEPT `src/views.js` and
+  `src/theme.css` — those are REGENERATED from the model
+  (`npm run model-build` in backend/); never hand-edit them. Theme tokens
+  live in `backend/model/theme.aontu`; per-project overrides in
+  `src/custom.css`.
+- Prefer customisation over editing generated components: hooks in
+  `src/customise.js` (see `src/hooks.js` for points), CSS variables in
+  `src/custom.css`, or a custom entity view (`ux:{view:'custom'}` in the
+  model). Edit components directly only when those layers can't express
+  the change.
+- Components re-render by setting `innerHTML`; async renders must guard
+  against stale overwrites (see the render-token pattern in
+  `cmp/admin.js`: capture a token at method start, bail before writing if
+  superseded).
+- `bus.sub` has no auto-unsubscribe: long-lived subscriptions in
+  components must guard callbacks with `this.isConnected`.
+- Escape all user data with the local `esc()` helpers when building HTML.
+

package/tm/web/web/e2e/smoke.spec.js.frag

@@ -1,21 +1,23 @@
 import { test, expect } from '@playwright/test'
 
-// Generic smoke test: the SPA boots, a seeded user can sign in, and the
-// model-driven entity admin renders with at least one entity. Add
-// project-specific CRUD flows alongside this file.
+// Generic smoke test: the public site loads, a seeded user can sign in, and
+// the model-driven app shell renders with an entity menu. Add project-specific
+// flows (CRUD, relationship drill, settings) in your own spec files.
 
-test('sign in and load the entity admin', async ({ page }) => {
+test('public site, sign in, and the app shell', async ({ page }) => {
   await page.goto('/')
 
+  // Public content site with a login form.
   await expect(page.locator('vg-auth h2')).toHaveText('Sign in')
 
-  await page.fill('input[name=email]', '$$seedEmail$$')
-  await page.fill('input[name=password]', '$$seedPassword$$')
+  await page.fill('vg-auth input[name=email]', '$$seedEmail$$')
+  await page.fill('vg-auth input[name=password]', '$$seedPassword$$')
   await page.click('vg-auth button[type=submit]')
 
-  await expect(page.locator('.vg-auth-bar b')).toHaveText('$$seedEmail$$')
-  await expect(page.locator('vg-entity-admin nav a')).not.toHaveCount(0)
-
-  // The first entity's list loads (count line rendered).
-  await expect(page.locator('#vg-count')).toBeVisible()
+  // The enterprise shell: top bar with the signed-in user, and a
+  // model-driven entity menu with at least one entity.
+  await expect(page.locator('.vg-shell')).toBeVisible()
+  await expect(page.locator('.vg-user-btn')).toContainText('$$seedEmail$$')
+  await expect(page.locator('.vg-navlink')).not.toHaveCount(0)
 })
+

package/tm/web/web/index.html.frag

@@ -5,9 +5,12 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>$$Name$$</title>
     <script src="/seneca-browser.js"></script>
+    <script src="/seneca-browser-store.js"></script>
+    <script src="/seneca-browser-debug.js"></script>
   </head>
   <body>
     <vg-app></vg-app>
     <script type="module" src="/src/main.js"></script>
   </body>
 </html>
+

package/tm/web/web/package.json.frag

@@ -4,14 +4,17 @@
   "private": true,
   "description": "$$Name$$ SPA: web components on a Seneca service bus",
   "scripts": {
-    "postinstall": "node -e \"require('fs').copyFileSync(require.resolve('seneca-browser'),'public/seneca-browser.js')\"",
+    "postinstall": "node -e \"const fs=require('fs');fs.mkdirSync('public',{recursive:true});for(const p of ['seneca-browser','@voxgig/seneca-browser-store','@voxgig/seneca-browser-debug'])fs.copyFileSync(require.resolve(p),'public/'+p.replace('@voxgig/','')+'.js')\"",
     "dev": "vite",
     "build": "vite build",
     "e2e": "playwright test"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
+    "@voxgig/seneca-browser-debug": "^0.1.0",
+    "@voxgig/seneca-browser-store": "^0.1.0",
     "seneca-browser": "^8.0.0-rc4",
     "vite": "^7.3.4"
   }
 }
+

package/tm/web/web/playwright.config.js.frag

@@ -9,6 +9,10 @@ export default defineConfig({
   testDir: './e2e',
   timeout: 30000,
   fullyParallel: false,
+  // One worker: all specs share a single backend web runner with one
+  // in-memory store and the same seeded users, so they must run serially to
+  // avoid cross-spec contention on shared state.
+  workers: 1,
   reporter: [['list']],
   use: {
     baseURL: `http://localhost:${PORT}`,
@@ -26,7 +30,7 @@ export default defineConfig({
     },
   ],
   webServer: {
-    command: `npm run build && cd ../backend && PORT=${PORT} node dist/env/web/web.js`,
+    command: `npm run build && cd ../backend && PORT=${PORT} REPL=false node dist/env/web/web.js`,
     url: `http://localhost:${PORT}/`,
     timeout: 60000,
     reuseExistingServer: false,
@@ -34,3 +38,4 @@ export default defineConfig({
     stderr: 'pipe',
   },
 })
+