@volter/world-runtime 3.0.9 → 3.0.11

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,19 @@ 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, with
+     *  when the first was made; and the boards as this World's people arranged them. A frame's changes themselves are read
+     *  one frame at a time (`board/changes`). */
+    private board;
+    /** One frame's changes not yet cut, newest first: each the writes one request made, as words read them (the operation,
+     *  the record, its few naming fields), the frame named `<vendor>:<frame id>`. */
+    private boardChanges;
+    /** Every twin's frames, where each opens here, and each with the changes not yet cut that are its own. */
+    private boardFrames;
+    /** 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,59 @@ 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));
+/** A change's act: the request that made it (its writes share one correlation id), else the write itself. */
+const actOf = (c) => (typeof c.action.correlationId === 'string' ? c.action.correlationId : c.action.id);
+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', 'sections'].includes(k)))
+            return 'a board has only id, name, include, hidden, placed and sections';
+        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 (b.sections !== undefined) {
+            const sections = b.sections;
+            if (!sections || typeof sections !== 'object' || Array.isArray(sections) || Object.keys(sections).length > 500)
+                return 'sections: a section name to its region';
+            for (const [k, v] of Object.entries(sections)) {
+                const r = v;
+                // a section is a pack's group (`<vendor>:section:<id>`) or one people drew (`user:<id>`), on the board's plane
+                if (!BOARD_KEY.test(k) || !(/^user:[a-z0-9]{1,32}$/.test(k) || /^[a-z0-9-]+:section:/.test(k)) || !r || typeof r !== 'object' || Object.keys(r).some((f) => !['x', 'y', 'w', 'h', 'name', 'gone'].includes(f))
+                    || !['x', 'y'].every((f) => typeof r[f] === 'number' && Math.abs(r[f]) <= 1e7) || !['w', 'h'].every((f) => typeof r[f] === 'number' && r[f] >= 0 && r[f] <= 1e6)
+                    || (r.gone !== true && (r.w < 100 || r.h < 100))
+                    || (r.name !== undefined && (typeof r.name !== 'string' || !r.name.trim() || r.name.length > 80)) || (r.gone !== undefined && r.gone !== true))
+                    return 'sections: { x, y, w, h, name?, gone? } by section 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 +188,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 } : {}),
@@ -795,6 +849,11 @@ export class WorldDoors {
             }
             return new Response(request.method === 'HEAD' ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
         }
+        // a person's browser is told in words (often the site is not there yet, or was not in a copy of the World as it was)
+        if ((request.headers.get('accept') ?? '').includes('text/html')) {
+            const shown = host.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+            return new Response(`<!doctype html><meta charset="utf-8"><title>${shown}</title><body style="font:16px system-ui;margin:3em;color:#555"><p>Nothing is served at <b>${shown}</b> in this World.</p></body>`, { status: 404, headers: { 'content-type': 'text/html; charset=utf-8' } });
+        }
         return Response.json({ error: `no twin of ${this.served} answers ${host}` }, { status: 404 });
     }
     async handle(request) {
@@ -943,9 +1002,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 +1240,52 @@ 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 === 'changes' && !verb && request.method === 'GET')
+            return await this.boardChanges(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 +1899,101 @@ 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, with
+     *  when the first was made; and the boards as this World's people arranged them. A frame's changes themselves are read
+     *  one frame at a time (`board/changes`). */
+    async board(url) {
+        const { frames, delta } = await this.boardFrames(url);
+        // the changes are counted from the World's base: what was last cut or received, and when
+        return { world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, frames: frames.map(({ frame, mine }) => ({ ...frame, changes: new Set(mine.map(actOf)).size, since: mine.map((c) => c.action.occurredAt).sort()[0] ?? null })), ...this.savedBoards() };
+    }
+    /** One frame's changes not yet cut, newest first: each the writes one request made, as words read them (the operation,
+     *  the record, its few naming fields), the frame named `<vendor>:<frame id>`. */
+    async boardChanges(url) {
+        const key = url.searchParams.get('frame') ?? '';
+        if (!key)
+            return Response.json({ error: 'board/changes?frame=<vendor>:<frame id>' }, { status: 400 });
+        const found = (await this.boardFrames(url)).frames.find(({ frame }) => `${frame.vendor}:${frame.id}` === key);
+        if (!found)
+            return Response.json({ error: `no frame ${key} on ${this.served}'s board` }, { status: 404 });
+        const acts = new Map();
+        for (const c of found.mine) {
+            const act = acts.get(actOf(c)) ?? { at: c.action.occurredAt, writes: 0, entries: [] };
+            if (c.action.occurredAt > act.at)
+                act.at = c.action.occurredAt;
+            act.writes += 1;
+            const named = Object.fromEntries(['title', 'name', 'hostname', 'email', 'text', 'subject', 'summary', 'description'].flatMap((k) => { const v = c.action.fields?.[k]; return typeof v === 'string' ? [[k, v.slice(0, 120)]] : []; }));
+            if (act.entries.length < 50)
+                act.entries.push({ op: c.action.op, ...(c.action.operation ? { operation: c.action.operation } : {}), subject: c.action.subject, fields: named });
+            acts.set(actOf(c), act);
+        }
+        const all = [...acts.values()].sort((a, b) => b.at.localeCompare(a.at));
+        return Response.json({ frame: key, total: all.length, since: found.mine.map((c) => c.action.occurredAt).sort()[0] ?? null, acts: all.slice(0, 100) });
+    }
+    /** Every twin's frames, where each opens here, and each with the changes not yet cut that are its own. */
+    async boardFrames(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), whose changes are all of the vendor's
+            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({ frame: { 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}` } }, mine: changes.filter((c) => c.service === vendor) });
+            }
+            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}`));
+                frames.push({ frame: { vendor, id: f.id, kind: f.kind, title: f.title, section: f.section, url: f.url, at, ...(unseen ? { unseen } : {}) }, mine: changes.filter((x) => x.service === vendor && covered.has(`${x.action.subject.type}:${x.action.subject.id}`)) });
+            }
+        }
+        return { delta, frames };
+    }
+    /** 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.11",
   "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.11",
+    "@volter/world-console": "3.0.6"
   },
   "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.11",
     "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,50 @@ 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 }>; /** each section's region and name, by a pack's group or `user:<id>`; a pack's group removed is `gone` */ sections?: Record<string, { x: number; y: number; w: number; h: number; name?: string; gone?: true }> };
+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));
+/** A change's act: the request that made it (its writes share one correlation id), else the write itself. */
+const actOf = (c: { action: { id: string; correlationId?: unknown } }): string => (typeof c.action.correlationId === 'string' ? c.action.correlationId : c.action.id);
+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', 'sections'].includes(k))) return 'a board has only id, name, include, hidden, placed and sections';
+    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 (b.sections !== undefined) {
+      const sections = b.sections as Record<string, unknown>;
+      if (!sections || typeof sections !== 'object' || Array.isArray(sections) || Object.keys(sections).length > 500) return 'sections: a section name to its region';
+      for (const [k, v] of Object.entries(sections)) {
+        const r = v as Record<string, unknown> | null;
+        // a section is a pack's group (`<vendor>:section:<id>`) or one people drew (`user:<id>`), on the board's plane
+        if (!BOARD_KEY.test(k) || !(/^user:[a-z0-9]{1,32}$/.test(k) || /^[a-z0-9-]+:section:/.test(k)) || !r || typeof r !== 'object' || Object.keys(r).some((f) => !['x', 'y', 'w', 'h', 'name', 'gone'].includes(f))
+          || !['x', 'y'].every((f) => typeof r[f] === 'number' && Math.abs(r[f] as number) <= 1e7) || !['w', 'h'].every((f) => typeof r[f] === 'number' && (r[f] as number) >= 0 && (r[f] as number) <= 1e6)
+          || (r.gone !== true && ((r.w as number) < 100 || (r.h as number) < 100))
+          || (r.name !== undefined && (typeof r.name !== 'string' || !r.name.trim() || r.name.length > 80)) || (r.gone !== undefined && r.gone !== true)) return 'sections: { x, y, w, h, name?, gone? } by section 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 +163,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 +191,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 +343,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
@@ -706,6 +754,11 @@ export class WorldDoors {
       if (location) { try { const to = new URL(location, `https://${host}`); if (to.hostname === host) out.set('location', `${to.pathname}${to.search}${to.hash}`); } catch { /* left as answered */ } }
       return new Response(request.method === 'HEAD' ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
     }
+    // a person's browser is told in words (often the site is not there yet, or was not in a copy of the World as it was)
+    if ((request.headers.get('accept') ?? '').includes('text/html')) {
+      const shown = host.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+      return new Response(`<!doctype html><meta charset="utf-8"><title>${shown}</title><body style="font:16px system-ui;margin:3em;color:#555"><p>Nothing is served at <b>${shown}</b> in this World.</p></body>`, { status: 404, headers: { 'content-type': 'text/html; charset=utf-8' } });
+    }
     return Response.json({ error: `no twin of ${this.served} answers ${host}` }, { status: 404 });
   }
 
@@ -829,9 +882,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 +1070,36 @@ 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 === 'changes' && !verb && request.method === 'GET') return await this.boardChanges(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 +1583,82 @@ 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, with
+   *  when the first was made; and the boards as this World's people arranged them. A frame's changes themselves are read
+   *  one frame at a time (`board/changes`). */
+  private async board(url: URL): Promise<unknown> {
+    const { frames, delta } = await this.boardFrames(url);
+    // the changes are counted from the World's base: what was last cut or received, and when
+    return { world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, frames: frames.map(({ frame, mine }) => ({ ...frame, changes: new Set(mine.map(actOf)).size, since: mine.map((c) => c.action.occurredAt).sort()[0] ?? null })), ...this.savedBoards() };
+  }
+  /** One frame's changes not yet cut, newest first: each the writes one request made, as words read them (the operation,
+   *  the record, its few naming fields), the frame named `<vendor>:<frame id>`. */
+  private async boardChanges(url: URL): Promise<Response> {
+    const key = url.searchParams.get('frame') ?? '';
+    if (!key) return Response.json({ error: 'board/changes?frame=<vendor>:<frame id>' }, { status: 400 });
+    const found = (await this.boardFrames(url)).frames.find(({ frame }) => `${frame.vendor}:${frame.id}` === key);
+    if (!found) return Response.json({ error: `no frame ${key} on ${this.served}'s board` }, { status: 404 });
+    const acts = new Map<string, { at: string; writes: number; entries: Array<{ op: string; operation?: string; subject: { type: string; id: string }; fields: Record<string, string> }> }>();
+    for (const c of found.mine) {
+      const act = acts.get(actOf(c)) ?? { at: c.action.occurredAt, writes: 0, entries: [] };
+      if (c.action.occurredAt > act.at) act.at = c.action.occurredAt;
+      act.writes += 1;
+      const named = Object.fromEntries(['title', 'name', 'hostname', 'email', 'text', 'subject', 'summary', 'description'].flatMap((k) => { const v = (c.action.fields as Record<string, unknown> | undefined)?.[k]; return typeof v === 'string' ? [[k, v.slice(0, 120)]] : []; }));
+      if (act.entries.length < 50) act.entries.push({ op: c.action.op, ...(c.action.operation ? { operation: c.action.operation } : {}), subject: c.action.subject, fields: named });
+      acts.set(actOf(c), act);
+    }
+    const all = [...acts.values()].sort((a, b) => b.at.localeCompare(a.at));
+    return Response.json({ frame: key, total: all.length, since: found.mine.map((c) => c.action.occurredAt).sort()[0] ?? null, acts: all.slice(0, 100) });
+  }
+  /** Every twin's frames, where each opens here, and each with the changes not yet cut that are its own. */
+  private async boardFrames(url: URL): Promise<{ delta: ReturnType<typeof diffWorld>; frames: Array<{ frame: Record<string, unknown> & { vendor: string; id: string }; mine: Array<ReturnType<typeof diffWorld>['actions'][number]> }> }> {
+    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: Array<{ frame: Record<string, unknown> & { vendor: string; id: string }; mine: typeof changes }> = [];
+    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), whose changes are all of the vendor's
+      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({ frame: { 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}` } }, mine: changes.filter((c) => c.service === vendor) });
+      }
+      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}`));
+        frames.push({ frame: { vendor, id: f.id, kind: f.kind, title: f.title, section: f.section, url: f.url, at, ...(unseen ? { unseen } : {}) }, mine: changes.filter((x) => x.service === vendor && covered.has(`${x.action.subject.type}:${x.action.subject.id}`)) });
+      }
+    }
+    return { delta, frames };
+  }
+  /** 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);