@volter/world-runtime 3.0.9 → 3.0.10

package/dist/src/served-world.d.ts

@@ -35,6 +35,8 @@ export type ServedWorld = {
 export declare function sessionsFile(worldRoot: string): string;
 /** Where a World keeps its named keys (their hashes, never a key): `.volter/keys.json`. */
 export declare function keysFile(worldRoot: string): string;
+/** Where a World keeps its boards as its people arranged them (what each hides or includes, and its frames' places): `.volter/board.json`. */
+export declare function boardFile(worldRoot: string): string;
 /** The served name: `bare.name` (`acme/team`), else `<id>/<id>`. */
 export declare function servedName(worldRoot: string, configRef: string): string;
 /** A world MOUNTED for serving: its doors, its tokens, and a boot that writes the serve record once the
@@ -63,7 +65,8 @@ export declare function mountWorld(name: string, opts?: {
     passIssuers?: TrustedIssuer[];
     root?: string; /** the host's branches of this World, by its served name */
     branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */
-    browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */
+    browserOrigin?: (served: string) => string | null; /** DoorHost.sitesOrigin */
+    sitesOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */
     localTrust?: boolean; /** the person signed in on this machine: its own page acts as them (DoorHost.localPerson) */
     localPerson?: string; /** DoorHost.serveBranch */
     serveBranch?: (branch: string) => Promise<void>;
@@ -118,6 +121,9 @@ export type DoorHost = {
      *  host gives each World one: its session lives only there (docs/contributing/architecture.md,
      *  "Viewing a World"). Null, or absent, on a host whose Worlds share one origin. */
     browserOrigin?: () => string | null;
+    /** The origin under which this host routes the hostnames the World's twins answer, each at `<hostname>.<origin's host>`
+     *  (siteOfHost); none where it routes no sites (behind a proxy, on a hosted World). */
+    sitesOrigin?: () => string | null;
     /** The origin another World this host serves (a branch of this one) is reached at, where it has one of its own. */
     originOf?: (served: string) => string | null;
     /** This World is served on this machine's loopback, for the person at it: a page of this World, reached by a
@@ -350,6 +356,13 @@ export declare class WorldDoors {
     private branchesDoor;
     /** The newest entry's instant across the World's twins (ms), or null when it has none. */
     private newestEntry;
+    /** THE BOARD: every twin's frames as its pack lays them out (`GET /twin/board`), each where this World shows it (a
+     *  hostname a twin answers as a site at its own origin, a vendor page under the twin's place, or nowhere: a frame no
+     *  screen draws yet) and the changes not yet cut on the records it covers, counted by the request that made them; and
+     *  the boards as this World's people arranged them. */
+    private board;
+    /** The boards as the World keeps them, and the version a save names: the default board when none was ever kept. */
+    private savedBoards;
     /** THE MAP: every twin and what it holds, by resource type, and the workspaces it shows. */
     private map;
     /** THE TIMELINE: the entries of every twin's log merged, newest first, by each entry's instant, then

package/dist/src/served-world.js

@@ -87,6 +87,43 @@ export function readServeRecord(worldRoot) {
 export function sessionsFile(worldRoot) { return join(worldRoot, stateDirName(), 'sessions.json'); }
 /** Where a World keeps its named keys (their hashes, never a key): `.volter/keys.json`. */
 export function keysFile(worldRoot) { return join(worldRoot, stateDirName(), 'keys.json'); }
+/** Where a World keeps its boards as its people arranged them (what each hides or includes, and its frames' places): `.volter/board.json`. */
+export function boardFile(worldRoot) { return join(worldRoot, stateDirName(), 'board.json'); }
+const BOARD_KEY = /^[a-z0-9-]+:[^\s]{1,300}$/;
+/** The largest board document a World keeps. */
+const BOARD_BYTES = 256 * 1024;
+/** A board document from a request, or the reason it is refused: every field of its type, nothing else. */
+/** A kept board document's version: its bytes' digest, or `none` before one is kept. */
+const boardVersion = (text) => (text === null ? 'none' : createHash('sha256').update(text).digest('hex').slice(0, 16));
+function boardsOf(body) {
+    const list = body?.boards;
+    if (!Array.isArray(list) || list.length < 1 || list.length > 50)
+        return 'boards: a list of 1-50 boards';
+    const ids = new Set();
+    for (const b of list) {
+        if (!b || typeof b !== 'object' || Object.keys(b).some((k) => !['id', 'name', 'include', 'hidden', 'placed'].includes(k)))
+            return 'a board has only id, name, include, hidden and placed';
+        if (typeof b.id !== 'string' || !/^[a-z0-9-]{1,64}$/.test(b.id) || ids.has(b.id))
+            return 'a board id is unique, a-z 0-9 -';
+        ids.add(b.id);
+        if (typeof b.name !== 'string' || !b.name.trim() || b.name.length > 80)
+            return 'a board name is 1-80 characters';
+        for (const k of ['include', 'hidden'])
+            if (b[k] !== undefined && (!Array.isArray(b[k]) || b[k].length > 2000 || !b[k].every((x) => typeof x === 'string' && BOARD_KEY.test(x))))
+                return `${k}: frame and section names`;
+        if (b.placed !== undefined) {
+            const placed = b.placed;
+            if (!placed || typeof placed !== 'object' || Array.isArray(placed) || Object.keys(placed).length > 2000)
+                return 'placed: a frame name to its place';
+            for (const [k, v] of Object.entries(placed))
+                if (!BOARD_KEY.test(k) || !v || typeof v !== 'object' || Object.keys(v).join() !== 'x,y' || !Object.values(v).every((n) => typeof n === 'number' && Number.isFinite(n)))
+                    return 'placed: { x, y } by frame name';
+        }
+    }
+    if (list[0].include !== undefined)
+        return 'the first board is everything: it includes no list';
+    return list;
+}
 const keyHash = (key) => createHash('sha256').update(key).digest('hex');
 function mintToken(prefix) { return `${prefix}${Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('base64url')}`; }
 function writeSecret(path, value) { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${value}\n`, { mode: 0o600 }); chmodSync(path, 0o600); }
@@ -135,6 +172,7 @@ export async function mountWorld(name, opts = {}) {
         clockPath: () => clockFile(worldRoot, name),
         ...(opts.branches?.(served) ? { branches: opts.branches(served) } : {}),
         ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin(served), originOf: (other) => opts.browserOrigin(other) } : {}),
+        ...(opts.sitesOrigin ? { sitesOrigin: () => opts.sitesOrigin(served) } : {}),
         ...(opts.localTrust ? { localTrust: () => true, ...(opts.localPerson ? { localPerson: () => opts.localPerson } : {}) } : {}),
         ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
         ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers } : {}),
@@ -943,9 +981,9 @@ export class WorldDoors {
         headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
         // where this World shows the hostnames its twins answer, for a page that links one (twinSiteUrl): under its own
         // origin on this machine (siteOfHost); a World without one shows none
-        const own = this.host.browserOrigin?.() ?? null;
-        const sites = own ? new URL(own) : null;
-        if (sites && sites.hostname.endsWith('.localhost'))
+        const at = this.host.sitesOrigin?.() ?? null;
+        const sites = at ? new URL(at) : null;
+        if (sites)
             headers.set(TWIN_SITES_HEADER, `${sites.protocol}//{host}.${sites.host}`);
         else
             headers.delete(TWIN_SITES_HEADER);
@@ -1181,6 +1219,50 @@ export class WorldDoors {
         }
         if (kind === 'map' && !name && request.method === 'GET')
             return Response.json(await this.map());
+        if (kind === 'board' && !name && request.method === 'GET')
+            return Response.json(await this.board(url));
+        if (kind === 'board' && !name && request.method === 'PUT') {
+            if (!/^application\/json\b/i.test(request.headers.get('content-type') ?? ''))
+                return Response.json({ error: 'the board is sent as application/json' }, { status: 415 });
+            if (Number(request.headers.get('content-length') ?? '0') > BOARD_BYTES)
+                return Response.json({ error: `the board is at most ${BOARD_BYTES} bytes` }, { status: 413 });
+            // read as it arrives, never past the cap (a chunked body names no length)
+            const chunks = [];
+            let size = 0;
+            const reader = request.body?.getReader();
+            for (let part = await reader?.read(); part && !part.done; part = await reader.read()) {
+                size += part.value.byteLength;
+                if (size > BOARD_BYTES) {
+                    await reader.cancel();
+                    return Response.json({ error: `the board is at most ${BOARD_BYTES} bytes` }, { status: 413 });
+                }
+                chunks.push(part.value);
+            }
+            const text = Buffer.concat(chunks).toString('utf8');
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                return Response.json({ error: 'the board is JSON' }, { status: 400 });
+            }
+            // a save names the version it was made from: one made from a version another save has since replaced is refused,
+            // with the boards as they now stand, never written over them
+            return this.serialized('board', async () => {
+                const held = this.savedBoards();
+                const from = body?.version;
+                if (typeof from !== 'string')
+                    return Response.json({ error: 'a board save names the version it was made from (the version GET answered)', ...held }, { status: 409 });
+                if (from !== held.version)
+                    return Response.json({ error: 'the board changed since this was made from it', ...held }, { status: 409 });
+                const boards = boardsOf({ boards: body.boards });
+                if (typeof boards === 'string')
+                    return Response.json({ error: boards }, { status: 400 });
+                const kept = `${JSON.stringify({ boards })}\n`;
+                getActiveWorldStore().write(boardFile(this.worldRoot), kept);
+                return Response.json({ world: this.served, boards, version: boardVersion(kept) });
+            });
+        }
         if (kind === 'timeline' && !name && request.method === 'GET')
             return this.timeline(url);
         if (kind === 'diff' && !name && request.method === 'GET') {
@@ -1794,6 +1876,72 @@ export class WorldDoors {
         }
         return newest;
     }
+    /** THE BOARD: every twin's frames as its pack lays them out (`GET /twin/board`), each where this World shows it (a
+     *  hostname a twin answers as a site at its own origin, a vendor page under the twin's place, or nowhere: a frame no
+     *  screen draws yet) and the changes not yet cut on the records it covers, counted by the request that made them; and
+     *  the boards as this World's people arranged them. */
+    async board(url) {
+        const claimed = new Map((await this.claimedHosts(url.origin)).map(({ vendor, hosts }) => [vendor, new Set(hosts)]));
+        const routed = this.host.sitesOrigin?.() ?? null;
+        const sites = routed ? new URL(routed) : null;
+        const delta = diffWorld(this.name, { root: this.worldRoot });
+        const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
+        const changes = delta.actions.filter((a) => !received.has(a.action.id));
+        const frames = [];
+        for (const vendor of Object.keys(this.up().services)) {
+            const twin = this.host.twinFetch(vendor);
+            let listed = [];
+            try {
+                const answer = twin ? await twin(new Request('http://world.local/twin/board', { headers: { [READ_ONLY_HEADER]: '1' } })) : null;
+                listed = answer?.ok ? ((await answer.json()).frames ?? []) : [];
+            }
+            catch {
+                listed = [];
+            }
+            // a pack that lays out no board yet keeps its vendor's home on it: its root workspace, else its first unparameterized one
+            if (!listed.length) {
+                const screens = await this.screensOf(vendor);
+                const home = screens.find((w) => w.path.replace(/\/+$/, '') === '') ?? screens.find((w) => !/[{<]/.test(w.path));
+                if (home)
+                    frames.push({ vendor, id: `home:${home.id}`, kind: 'home', title: vendor, section: { id: 'home', title: 'Home' }, url: home.path, at: { screen: home.path.startsWith('/') ? home.path : `/${home.path}` }, changes: changes.filter((c) => c.service === vendor).length ? new Set(changes.filter((c) => c.service === vendor).map((c) => (typeof c.action.correlationId === 'string' ? c.action.correlationId : undefined) ?? c.action.id)).size : 0 });
+            }
+            for (const f of listed) {
+                let at = null;
+                // why a frame opens nowhere: its twin draws no page for it yet, or this host routes no sites
+                let unseen;
+                try {
+                    const u = new URL(f.url);
+                    if (claimed.get(vendor)?.has(u.hostname.toLowerCase()))
+                        at = sites ? { site: `${sites.protocol}//${u.hostname.toLowerCase()}.${sites.host}${u.pathname}${u.search}` } : null;
+                    else if (f.drawn)
+                        at = { screen: `${u.pathname}${u.search}` };
+                    if (!at)
+                        unseen = claimed.get(vendor)?.has(u.hostname.toLowerCase()) ? 'sites-not-routed' : 'not-drawn';
+                }
+                catch {
+                    at = null;
+                    unseen = 'not-drawn';
+                }
+                const covered = new Set(f.covers.map((c) => `${c.type}:${c.id}`));
+                // one change per request that made it: a deploy's script, versions and assets are one act, its domain another
+                const acts = new Set(changes.filter((c) => c.service === vendor && covered.has(`${c.action.subject.type}:${c.action.subject.id}`)).map((c) => (typeof c.action.correlationId === 'string' ? c.action.correlationId : undefined) ?? c.action.id));
+                frames.push({ vendor, id: f.id, kind: f.kind, title: f.title, section: f.section, url: f.url, at, ...(unseen ? { unseen } : {}), changes: acts.size });
+            }
+        }
+        return { world: this.served, frames, ...this.savedBoards() };
+    }
+    /** The boards as the World keeps them, and the version a save names: the default board when none was ever kept. */
+    savedBoards() {
+        const text = getActiveWorldStore().read(boardFile(this.worldRoot));
+        let boards = [{ id: 'everything', name: 'Everything' }];
+        try {
+            const kept = boardsOf(JSON.parse(text ?? 'null'));
+            if (typeof kept !== 'string')
+                boards = kept;
+        }
+        catch { /* never arranged */ }
+        return { boards, version: boardVersion(text) };
+    }
     /** THE MAP: every twin and what it holds, by resource type, and the workspaces it shows. */
     async map() {
         const twins = [];

package/dist/src/world-view.js

@@ -48,7 +48,9 @@ export async function serveWorldView(name, opts = {}) {
     // (the first World mounted is the World; every later one is a branch of it)
     let base = null;
     const browserOrigin = origins ? (served) => (proxied && (base === null || served === base) ? proxied.origin : port ? localWorldOrigin(served, port) : null) : undefined;
-    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
+    // sites are routed at each World's own *.localhost origin, never behind the proxy
+    const sitesOrigin = origins && !proxied ? (served) => (port ? localWorldOrigin(served, port) : null) : undefined;
+    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
     const branches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
     // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
     // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
@@ -90,7 +92,7 @@ export async function serveWorldView(name, opts = {}) {
             switching = false;
         }
     };
-    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
+    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
     let world = await mountWorld(name, mountOpts);
     base = world.served;
     worlds.set(world.served, world);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.9",
+  "version": "3.0.10",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -68,14 +68,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.9",
-    "@volter/world-console": "3.0.4"
+    "@volter/world-core": "3.0.10",
+    "@volter/world-console": "3.0.5"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.9",
+    "@volter/world-core": "3.0.10",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/served-world.ts

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync , rmSync} from 'node:fs';
-import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core/runtime';
+import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink, type BoardFrame } from '@volter/world-core/runtime';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
 import { packFacts } from './pack-facts.ts';
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
@@ -80,6 +80,36 @@ export type ServedWorld = { url: string; base: string; name: string; port: numbe
 export function sessionsFile(worldRoot: string): string { return join(worldRoot, stateDirName(), 'sessions.json'); }
 /** Where a World keeps its named keys (their hashes, never a key): `.volter/keys.json`. */
 export function keysFile(worldRoot: string): string { return join(worldRoot, stateDirName(), 'keys.json'); }
+/** Where a World keeps its boards as its people arranged them (what each hides or includes, and its frames' places): `.volter/board.json`. */
+export function boardFile(worldRoot: string): string { return join(worldRoot, stateDirName(), 'board.json'); }
+/** A board as the World keeps it: a frame or a section is named `<vendor>:<frame id>` or `<vendor>:section:<section id>`.
+ *  The first board is everything the packs lay out; another holds what it includes, a section with its frames to come. */
+type SavedBoard = { id: string; name: string; include?: string[]; hidden?: string[]; placed?: Record<string, { x: number; y: number }> };
+const BOARD_KEY = /^[a-z0-9-]+:[^\s]{1,300}$/;
+/** The largest board document a World keeps. */
+const BOARD_BYTES = 256 * 1024;
+/** A board document from a request, or the reason it is refused: every field of its type, nothing else. */
+/** A kept board document's version: its bytes' digest, or `none` before one is kept. */
+const boardVersion = (text: string | null): string => (text === null ? 'none' : createHash('sha256').update(text).digest('hex').slice(0, 16));
+function boardsOf(body: unknown): SavedBoard[] | string {
+  const list = (body as { boards?: unknown } | null)?.boards;
+  if (!Array.isArray(list) || list.length < 1 || list.length > 50) return 'boards: a list of 1-50 boards';
+  const ids = new Set<string>();
+  for (const b of list as Array<Record<string, unknown>>) {
+    if (!b || typeof b !== 'object' || Object.keys(b).some((k) => !['id', 'name', 'include', 'hidden', 'placed'].includes(k))) return 'a board has only id, name, include, hidden and placed';
+    if (typeof b.id !== 'string' || !/^[a-z0-9-]{1,64}$/.test(b.id) || ids.has(b.id)) return 'a board id is unique, a-z 0-9 -';
+    ids.add(b.id);
+    if (typeof b.name !== 'string' || !b.name.trim() || b.name.length > 80) return 'a board name is 1-80 characters';
+    for (const k of ['include', 'hidden'] as const) if (b[k] !== undefined && (!Array.isArray(b[k]) || (b[k] as unknown[]).length > 2000 || !(b[k] as unknown[]).every((x) => typeof x === 'string' && BOARD_KEY.test(x)))) return `${k}: frame and section names`;
+    if (b.placed !== undefined) {
+      const placed = b.placed as Record<string, unknown>;
+      if (!placed || typeof placed !== 'object' || Array.isArray(placed) || Object.keys(placed).length > 2000) return 'placed: a frame name to its place';
+      for (const [k, v] of Object.entries(placed)) if (!BOARD_KEY.test(k) || !v || typeof v !== 'object' || Object.keys(v).join() !== 'x,y' || !Object.values(v).every((n) => typeof n === 'number' && Number.isFinite(n))) return 'placed: { x, y } by frame name';
+    }
+  }
+  if ((list[0] as SavedBoard).include !== undefined) return 'the first board is everything: it includes no list';
+  return list as SavedBoard[];
+}
 /** A named key as the World keeps it: the SHA-256 of the key, what it may do, and when it was made and last used. */
 type HeldKey = { id: string; name: string; scope: 'read' | 'write'; hash: string; createdAt: string; lastUsedAt?: string;
   /** who made it: the World's token, or a person's session (the subject a pass named, and its platform) */
@@ -119,7 +149,7 @@ export type MountedWorld = { name: string; served: string; root: string; readonl
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
 type HeldSession = { scope: 'read' | 'write'; until: number; /** opened by this machine's own page (localSession) */ local?: true; who?: string; /** the platform whose pass opened it */ issuer?: string; /** the person's subject there */ sub?: string; /** the read key a shared link opened it with: it lasts only while that key does */ key?: string };
 
-export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean; /** the person signed in on this machine: its own page acts as them (DoorHost.localPerson) */ localPerson?: string; /** DoorHost.serveBranch */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
+export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** DoorHost.sitesOrigin */ sitesOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean; /** the person signed in on this machine: its own page acts as them (DoorHost.localPerson) */ localPerson?: string; /** DoorHost.serveBranch */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
   const worldRoot = resolve(opts.root ?? process.cwd());
   const configRef = configRefFor(worldRoot, name);
   if (loadWorldConfig(configRef, worldRoot).config.resources) {
@@ -147,6 +177,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     clockPath: () => clockFile(worldRoot, name),
     ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
     ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => opts.browserOrigin!(other) } : {}),
+    ...(opts.sitesOrigin ? { sitesOrigin: () => opts.sitesOrigin!(served) } : {}),
     ...(opts.localTrust ? { localTrust: () => true, ...(opts.localPerson ? { localPerson: () => opts.localPerson } : {}) } : {}),
     ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
     ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers! } : {}),
@@ -298,6 +329,9 @@ export type DoorHost = {
    *  host gives each World one: its session lives only there (docs/contributing/architecture.md,
    *  "Viewing a World"). Null, or absent, on a host whose Worlds share one origin. */
   browserOrigin?: () => string | null;
+  /** The origin under which this host routes the hostnames the World's twins answer, each at `<hostname>.<origin's host>`
+   *  (siteOfHost); none where it routes no sites (behind a proxy, on a hosted World). */
+  sitesOrigin?: () => string | null;
   /** The origin another World this host serves (a branch of this one) is reached at, where it has one of its own. */
   originOf?: (served: string) => string | null;
   /** This World is served on this machine's loopback, for the person at it: a page of this World, reached by a
@@ -829,9 +863,9 @@ export class WorldDoors {
     headers.set('x-forwarded-host', url.host); headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
     // where this World shows the hostnames its twins answer, for a page that links one (twinSiteUrl): under its own
     // origin on this machine (siteOfHost); a World without one shows none
-    const own = this.host.browserOrigin?.() ?? null;
-    const sites = own ? new URL(own) : null;
-    if (sites && sites.hostname.endsWith('.localhost')) headers.set(TWIN_SITES_HEADER, `${sites.protocol}//{host}.${sites.host}`); else headers.delete(TWIN_SITES_HEADER);
+    const at = this.host.sitesOrigin?.() ?? null;
+    const sites = at ? new URL(at) : null;
+    if (sites) headers.set(TWIN_SITES_HEADER, `${sites.protocol}//{host}.${sites.host}`); else headers.delete(TWIN_SITES_HEADER);
     const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
     const answer = await twin(new Request(`${url.origin}/${tail.join('/')}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
     // an upgrade the twin answered (a tunnel's control or visitor socket) goes back as it is
@@ -1017,6 +1051,35 @@ export class WorldDoors {
       return Response.json({ world: this.served, at: new Date(Date.parse(instant)).toISOString(), views });
     }
     if (kind === 'map' && !name && request.method === 'GET') return Response.json(await this.map());
+    if (kind === 'board' && !name && request.method === 'GET') return Response.json(await this.board(url));
+    if (kind === 'board' && !name && request.method === 'PUT') {
+      if (!/^application\/json\b/i.test(request.headers.get('content-type') ?? '')) return Response.json({ error: 'the board is sent as application/json' }, { status: 415 });
+      if (Number(request.headers.get('content-length') ?? '0') > BOARD_BYTES) return Response.json({ error: `the board is at most ${BOARD_BYTES} bytes` }, { status: 413 });
+      // read as it arrives, never past the cap (a chunked body names no length)
+      const chunks: Uint8Array[] = []; let size = 0;
+      const reader = request.body?.getReader();
+      for (let part = await reader?.read(); part && !part.done; part = await reader!.read()) {
+        size += part.value.byteLength;
+        if (size > BOARD_BYTES) { await reader!.cancel(); return Response.json({ error: `the board is at most ${BOARD_BYTES} bytes` }, { status: 413 }); }
+        chunks.push(part.value);
+      }
+      const text = Buffer.concat(chunks).toString('utf8');
+      let body: unknown;
+      try { body = JSON.parse(text); } catch { return Response.json({ error: 'the board is JSON' }, { status: 400 }); }
+      // a save names the version it was made from: one made from a version another save has since replaced is refused,
+      // with the boards as they now stand, never written over them
+      return this.serialized('board', async () => {
+        const held = this.savedBoards();
+        const from = (body as { version?: unknown } | null)?.version;
+        if (typeof from !== 'string') return Response.json({ error: 'a board save names the version it was made from (the version GET answered)', ...held }, { status: 409 });
+        if (from !== held.version) return Response.json({ error: 'the board changed since this was made from it', ...held }, { status: 409 });
+        const boards = boardsOf({ boards: (body as { boards?: unknown }).boards });
+        if (typeof boards === 'string') return Response.json({ error: boards }, { status: 400 });
+        const kept = `${JSON.stringify({ boards })}\n`;
+        getActiveWorldStore().write(boardFile(this.worldRoot), kept);
+        return Response.json({ world: this.served, boards, version: boardVersion(kept) });
+      });
+    }
     if (kind === 'timeline' && !name && request.method === 'GET') return this.timeline(url);
     if (kind === 'diff' && !name && request.method === 'GET') {
       const delta = diffWorld(this.name, { root: this.worldRoot });
@@ -1500,6 +1563,57 @@ export class WorldDoors {
     return newest;
   }
 
+  /** THE BOARD: every twin's frames as its pack lays them out (`GET /twin/board`), each where this World shows it (a
+   *  hostname a twin answers as a site at its own origin, a vendor page under the twin's place, or nowhere: a frame no
+   *  screen draws yet) and the changes not yet cut on the records it covers, counted by the request that made them; and
+   *  the boards as this World's people arranged them. */
+  private async board(url: URL): Promise<unknown> {
+    const claimed = new Map((await this.claimedHosts(url.origin)).map(({ vendor, hosts }) => [vendor, new Set(hosts)]));
+    const routed = this.host.sitesOrigin?.() ?? null;
+    const sites = routed ? new URL(routed) : null;
+    const delta = diffWorld(this.name, { root: this.worldRoot });
+    const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
+    const changes = delta.actions.filter((a) => !received.has(a.action.id));
+    const frames: unknown[] = [];
+    for (const vendor of Object.keys(this.up().services)) {
+      const twin = this.host.twinFetch(vendor);
+      let listed: BoardFrame[] = [];
+      try {
+        const answer = twin ? await twin(new Request('http://world.local/twin/board', { headers: { [READ_ONLY_HEADER]: '1' } })) : null;
+        listed = answer?.ok ? (((await answer.json()) as { frames?: BoardFrame[] }).frames ?? []) : [];
+      } catch { listed = []; }
+      // a pack that lays out no board yet keeps its vendor's home on it: its root workspace, else its first unparameterized one
+      if (!listed.length) {
+        const screens = await this.screensOf(vendor);
+        const home = screens.find((w) => w.path.replace(/\/+$/, '') === '') ?? screens.find((w) => !/[{<]/.test(w.path));
+        if (home) frames.push({ vendor, id: `home:${home.id}`, kind: 'home', title: vendor, section: { id: 'home', title: 'Home' }, url: home.path, at: { screen: home.path.startsWith('/') ? home.path : `/${home.path}` }, changes: changes.filter((c) => c.service === vendor).length ? new Set(changes.filter((c) => c.service === vendor).map((c) => (typeof c.action.correlationId === 'string' ? c.action.correlationId : undefined) ?? c.action.id)).size : 0 });
+      }
+      for (const f of listed) {
+        let at: { site: string } | { screen: string } | null = null;
+        // why a frame opens nowhere: its twin draws no page for it yet, or this host routes no sites
+        let unseen: 'not-drawn' | 'sites-not-routed' | undefined;
+        try {
+          const u = new URL(f.url);
+          if (claimed.get(vendor)?.has(u.hostname.toLowerCase())) at = sites ? { site: `${sites.protocol}//${u.hostname.toLowerCase()}.${sites.host}${u.pathname}${u.search}` } : null;
+          else if (f.drawn) at = { screen: `${u.pathname}${u.search}` };
+          if (!at) unseen = claimed.get(vendor)?.has(u.hostname.toLowerCase()) ? 'sites-not-routed' : 'not-drawn';
+        } catch { at = null; unseen = 'not-drawn'; }
+        const covered = new Set(f.covers.map((c) => `${c.type}:${c.id}`));
+        // one change per request that made it: a deploy's script, versions and assets are one act, its domain another
+        const acts = new Set(changes.filter((c) => c.service === vendor && covered.has(`${c.action.subject.type}:${c.action.subject.id}`)).map((c) => (typeof c.action.correlationId === 'string' ? c.action.correlationId : undefined) ?? c.action.id));
+        frames.push({ vendor, id: f.id, kind: f.kind, title: f.title, section: f.section, url: f.url, at, ...(unseen ? { unseen } : {}), changes: acts.size });
+      }
+    }
+    return { world: this.served, frames, ...this.savedBoards() };
+  }
+  /** The boards as the World keeps them, and the version a save names: the default board when none was ever kept. */
+  private savedBoards(): { boards: SavedBoard[]; version: string } {
+    const text = getActiveWorldStore().read(boardFile(this.worldRoot));
+    let boards: SavedBoard[] = [{ id: 'everything', name: 'Everything' }];
+    try { const kept = boardsOf(JSON.parse(text ?? 'null')); if (typeof kept !== 'string') boards = kept; } catch { /* never arranged */ }
+    return { boards, version: boardVersion(text) };
+  }
+
   /** THE MAP: every twin and what it holds, by resource type, and the workspaces it shows. */
   private async map(): Promise<unknown> {
     const twins: unknown[] = [];

package/src/world-view.ts

@@ -49,7 +49,9 @@ export async function serveWorldView(name: string, opts: { /** the person signed
   // (the first World mounted is the World; every later one is a branch of it)
   let base: string | null = null;
   const browserOrigin = origins ? (served: string) => (proxied && (base === null || served === base) ? proxied.origin : port ? localWorldOrigin(served, port) : null) : undefined;
-  const mountAt = (at: string): Promise<MountedWorld> => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
+  // sites are routed at each World's own *.localhost origin, never behind the proxy
+  const sitesOrigin = origins && !proxied ? (served: string) => (port ? localWorldOrigin(served, port) : null) : undefined;
+  const mountAt = (at: string): Promise<MountedWorld> => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
   const branches: LocalBranches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
   // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
   // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
@@ -80,7 +82,7 @@ export async function serveWorldView(name: string, opts: { /** the person signed
       if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id) rmSync(current, { force: true }); else writeFileSync(current, `${branch}\n`);
     } finally { switching = false; }
   };
-  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
+  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
   let world = await mountWorld(name, mountOpts);
   base = world.served;
   worlds.set(world.served, world);