@volter/world-runtime 3.0.26 → 3.0.28

package/dist/src/local-branches.js

@@ -84,6 +84,10 @@ export class LocalBranches {
             create: (at, ttl, _origin, parentKey, byKey) => this.create(parent, at, ttl, parentKey, byKey),
             remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent)
                 return false; await this.remove(name); return true; },
+            board: async (name, frame) => {
+                const w = this.o.worlds.get(name);
+                return w && this.record(w)?.from === parent ? w.branchBoard(frame) : null;
+            },
             // a branch of this parent only, served in this process beside it: its own content plane's pass
             pagesPass: async (name, scope, land, grant) => {
                 const w = this.o.worlds.get(name);

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

@@ -63,6 +63,7 @@ export type MountedWorld = {
         framer?: string;
         asker?: string;
     }) => string | null;
+    branchBoard: (frame?: string) => Promise<Response>;
     boot: (url: string) => Promise<void>;
     stop: () => Promise<void>;
 };
@@ -208,6 +209,8 @@ export type BranchDoors = {
         framer?: string;
         asker?: string;
     }) => Promise<string | null>;
+    /** the branch's own board, counting from its fork; a frame names its changes alone */
+    board?: (name: string, frame?: string) => Promise<Response | null>;
 };
 /** A World's browser-origin label, `<world>--<org>`, or null when its names cannot make one (a DNS
  *  label: lowercase letters, digits and single hyphens, 63 at most). A host maps a label back by the
@@ -444,6 +447,7 @@ export declare class WorldDoors {
      *  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`). */
+    branchBoard(frame?: string): Promise<Response>;
     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>`. */

package/dist/src/served-world.js

@@ -18,6 +18,9 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 //   GET  map | timeline | diff       every twin and what it holds; the logs merged newest first; the changes since the base
 //   GET/PUT clock, POST clock/advance   the frozen instant every twin stamps from, forward only
 //   GET/POST branches, DELETE branches/<org>/<world>   the host's branches of this World ("as of" views)
+//   GET  branches/<org>/<world>/board[/changes]   a branch's pages and changes from its fork, through its host
+//   GET  branches/<org>/<world>/pages?land=<path>   a read pass to the branch's own content plane
+//   GET/PUT board, GET board/changes  the pages and their changes; the boards as people arranged them
 //   GET  history?at=<instant>        each twin's history cut at an instant (where such a branch starts)
 //   GET/POST marks                   where the World's changes count from; POST { note? } marks it now
 //   GET  /<org>/<world>/<vendor>/<path>   the vendor's own screens, the pack's workspaces (its `GET /twin` lists them)
@@ -216,6 +219,7 @@ export async function mountWorld(name, opts = {}) {
         handle: (request) => world.handle(request),
         site: (request, host) => world.site(request, host),
         pagesPass: (scope, land, grant) => world.pagesPass(scope, land, grant),
+        branchBoard: (frame) => world.branchBoard(frame),
         async boot(url) {
             keep();
             const port = Number(new URL(url).port) || 0;
@@ -2121,6 +2125,16 @@ export class WorldDoors {
      *  and removes them; a host that makes none answers 404, and a view offers no "as of". */
     async branchesDoor(request, url, rest, via) {
         const branches = this.host.branches;
+        if (rest[2] === 'board' && request.method === 'GET' && (rest.length === 3 || (rest.length === 4 && rest[3] === 'changes'))) {
+            if (!branches)
+                return Response.json({ error: `this host cannot read branches of ${this.served}` }, { status: 501 });
+            const name = `${decodeURIComponent(rest[0])}/${decodeURIComponent(rest[1])}`;
+            if (!(await branches.list()).some((b) => b.name === name))
+                return Response.json({ error: `no branch ${name} of ${this.served}` }, { status: 404 });
+            if (!branches.board)
+                return Response.json({ error: `this host cannot read ${name}'s board` }, { status: 501 });
+            return (await branches.board(name, rest[3] === 'changes' ? url.searchParams.get('frame') ?? '' : undefined)) ?? Response.json({ error: `no branch ${name} of ${this.served}` }, { status: 404 });
+        }
         if (!branches)
             return Response.json({ error: `this host makes no branches of ${this.served}` }, { status: 404 });
         if (rest.length === 0 && request.method === 'GET') {
@@ -2255,18 +2269,26 @@ export class WorldDoors {
      *  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
+    async branchBoard(frame) {
+        const url = new URL(this.host.browserOrigin?.() ?? 'http://world.local');
+        if (frame !== undefined) {
+            url.searchParams.set('frame', frame);
+            return this.boardChanges(url, true);
+        }
+        return Response.json(await this.board(url, true));
+    }
+    async board(url, fork = false) {
+        const { frames, delta } = await this.boardFrames(url, fork);
+        // the World's last cut, or the branch's whole ledger when its parent is looking at it
         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) {
+    async boardChanges(url, fork = false) {
         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);
+        const found = (await this.boardFrames(url, fork)).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();
@@ -2284,7 +2306,7 @@ export class WorldDoors {
         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) {
+    async boardFrames(url, fork = false) {
         const claimed = new Map((await this.claimedHosts(url.origin)).map(({ vendor, hosts }) => [vendor, new Set(hosts)]));
         const sitesAt = this.host.sitesTemplate?.() ?? null;
         // a site private to the World's people (a `{site}` template: a hosted World) opens through this World's own origin,
@@ -2300,9 +2322,10 @@ export class WorldDoors {
             const own = this.host.browserOrigin?.() ?? null;
             return own ? `${own}/-/${this.served}/sites/go?${new URLSearchParams({ host: hostname, land: rest }).toString()}` : null;
         };
-        const delta = diffWorld(this.name, { root: this.worldRoot });
+        // inherited history is the parent log: the branch's own ledger starts at its fork, even after a cut
+        const delta = diffWorld(this.name, { root: this.worldRoot, ...(fork ? { base: 'world-boot' } : {}) });
         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 changes = fork ? delta.actions : 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.26",
+  "version": "3.0.28",
   "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.26",
-    "@volter/world-console": "3.0.21"
+    "@volter/world-core": "3.0.28",
+    "@volter/world-console": "3.0.23"
   },
   "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.26",
+    "@volter/world-core": "3.0.28",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/local-branches.ts

@@ -93,6 +93,10 @@ export class LocalBranches {
       list: async () => this.list(parent),
       create: (at, ttl, _origin, parentKey, byKey) => this.create(parent, at, ttl, parentKey, byKey),
       remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent) return false; await this.remove(name); return true; },
+      board: async (name, frame) => {
+        const w = this.o.worlds.get(name);
+        return w && this.record(w)?.from === parent ? w.branchBoard(frame) : null;
+      },
       // a branch of this parent only, served in this process beside it: its own content plane's pass
       pagesPass: async (name, scope, land, grant) => {
         const w = this.o.worlds.get(name);

package/src/served-world.ts

@@ -18,6 +18,9 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 //   GET  map | timeline | diff       every twin and what it holds; the logs merged newest first; the changes since the base
 //   GET/PUT clock, POST clock/advance   the frozen instant every twin stamps from, forward only
 //   GET/POST branches, DELETE branches/<org>/<world>   the host's branches of this World ("as of" views)
+//   GET  branches/<org>/<world>/board[/changes]   a branch's pages and changes from its fork, through its host
+//   GET  branches/<org>/<world>/pages?land=<path>   a read pass to the branch's own content plane
+//   GET/PUT board, GET board/changes  the pages and their changes; the boards as people arranged them
 //   GET  history?at=<instant>        each twin's history cut at an instant (where such a branch starts)
 //   GET/POST marks                   where the World's changes count from; POST { note? } marks it now
 //   GET  /<org>/<world>/<vendor>/<path>   the vendor's own screens, the pack's workspaces (its `GET /twin` lists them)
@@ -160,7 +163,7 @@ function configRefFor(worldRoot: string, name: string): string {
 /** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
  *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
  *  with the call — and keeps them beside the world like `boot` does. */
-export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
+export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; branchBoard: (frame?: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
 /** What a content-plane pass, and the session it opens, carry: its scope; the control session that asked (the content
  *  session ends with it; none when the World's token asked); the person; the console that frames it; and whether it
@@ -225,6 +228,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     handle: (request) => world.handle(request),
     site: (request, host) => world.site(request, host),
     pagesPass: (scope, land, grant) => world.pagesPass(scope, land, grant),
+    branchBoard: (frame) => world.branchBoard(frame),
     async boot(url) {
       keep();
       const port = Number(new URL(url).port) || 0;
@@ -396,6 +400,8 @@ export type BranchDoors = {
   /** the address that opens a branch's content plane with a one-time pass at `scope`, landing on `land` (a path of the
    *  branch): how its parent's console frames the branch's pages beside its own (the comparison) */
   pagesPass?: (name: string, scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => Promise<string | null>;
+  /** the branch's own board, counting from its fork; a frame names its changes alone */
+  board?: (name: string, frame?: string) => Promise<Response | null>;
 };
 
 /** A World's browser-origin label, `<world>--<org>`, or null when its names cannot make one (a DNS
@@ -1793,6 +1799,13 @@ export class WorldDoors {
    *  and removes them; a host that makes none answers 404, and a view offers no "as of". */
   private async branchesDoor(request: Request, url: URL, rest: string[], via: 'token' | 'key' | 'session' | null): Promise<Response> {
     const branches = this.host.branches;
+    if (rest[2] === 'board' && request.method === 'GET' && (rest.length === 3 || (rest.length === 4 && rest[3] === 'changes'))) {
+      if (!branches) return Response.json({ error: `this host cannot read branches of ${this.served}` }, { status: 501 });
+      const name = `${decodeURIComponent(rest[0]!)}/${decodeURIComponent(rest[1]!)}`;
+      if (!(await branches.list()).some((b) => b.name === name)) return Response.json({ error: `no branch ${name} of ${this.served}` }, { status: 404 });
+      if (!branches.board) return Response.json({ error: `this host cannot read ${name}'s board` }, { status: 501 });
+      return (await branches.board(name, rest[3] === 'changes' ? url.searchParams.get('frame') ?? '' : undefined)) ?? Response.json({ error: `no branch ${name} of ${this.served}` }, { status: 404 });
+    }
     if (!branches) return Response.json({ error: `this host makes no branches of ${this.served}` }, { status: 404 });
     if (rest.length === 0 && request.method === 'GET') {
       // beside the host's snapshots, the World's own NAMED branches (`volter world branch`): one runs at a time, and
@@ -1899,17 +1912,22 @@ export class WorldDoors {
    *  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
+  async branchBoard(frame?: string): Promise<Response> {
+    const url = new URL(this.host.browserOrigin?.() ?? 'http://world.local');
+    if (frame !== undefined) { url.searchParams.set('frame', frame); return this.boardChanges(url, true); }
+    return Response.json(await this.board(url, true));
+  }
+  private async board(url: URL, fork = false): Promise<unknown> {
+    const { frames, delta } = await this.boardFrames(url, fork);
+    // the World's last cut, or the branch's whole ledger when its parent is looking at it
     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> {
+  private async boardChanges(url: URL, fork = false): 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);
+    const found = (await this.boardFrames(url, fork)).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) {
@@ -1924,7 +1942,7 @@ export class WorldDoors {
     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]> }> }> {
+  private async boardFrames(url: URL, fork = false): 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 sitesAt = this.host.sitesTemplate?.() ?? null;
     // a site private to the World's people (a `{site}` template: a hosted World) opens through this World's own origin,
@@ -1937,9 +1955,10 @@ export class WorldDoors {
       const own = this.host.browserOrigin?.() ?? null;
       return own ? `${own}/-/${this.served}/sites/go?${new URLSearchParams({ host: hostname, land: rest }).toString()}` : null;
     };
-    const delta = diffWorld(this.name, { root: this.worldRoot });
+    // inherited history is the parent log: the branch's own ledger starts at its fork, even after a cut
+    const delta = diffWorld(this.name, { root: this.worldRoot, ...(fork ? { base: 'world-boot' } : {}) });
     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 changes = fork ? delta.actions : 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);