@volter/world-runtime 3.0.12 → 3.0.13

package/dist/src/index.d.ts

@@ -44,7 +44,7 @@ export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCreden
 export type { DeployTwinOutcome, MaterializedRoot } from './root.js';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.js';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.js';
-export { LocalBranches } from './local-branches.js';
+export { followParentPins, LocalBranches } from './local-branches.js';
 export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.js';
 export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.js';
 export type { ViewConsole, WorldView } from './world-view.js';

package/dist/src/index.js

@@ -31,7 +31,7 @@ export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCredentials, credentialPayloadFrom, rootCredentialInput, bindLegacyCredentials, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
-export { LocalBranches } from "./local-branches.js";
+export { followParentPins, LocalBranches } from "./local-branches.js";
 export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
 export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";

package/dist/src/local-branches.d.ts

@@ -1,4 +1,15 @@
 import { type BranchDoors, type BranchRow, type MountedWorld } from './served-world.js';
+/** A branch mounted again beside its parent takes the parent's twin versions: it is the parent's config under another
+ *  name and runs on the packages the parent's root installs, so a parent moved to a new twin version (its pin and its
+ *  install, together) never leaves a branch pinning the old one and failing the next boot. */
+export declare function followParentPins(parentRoot: string, branchRoot: string): void;
+/** A write key of a branch, named for the key whose holder made it (the branch's own keys door): what that holder gets in
+ *  place of the branch's token, so the branch refuses it what a key is refused (seals, checks, keys, rules, sessions). */
+export declare function keyOfBranch(branch: {
+    served: string;
+    token: string;
+    handle: (request: Request) => Promise<Response>;
+}, origin: string, maker: string): Promise<string>;
 export type LocalBranchesOptions = {
     /** where branches live: `<dir>/<org>/<world>/` */
     dir: string;

package/dist/src/local-branches.js

@@ -19,6 +19,37 @@ function renamed(config, id, name) {
     }
     return { ...config, id, bare: { ...config.bare, name } };
 }
+/** A branch mounted again beside its parent takes the parent's twin versions: it is the parent's config under another
+ *  name and runs on the packages the parent's root installs, so a parent moved to a new twin version (its pin and its
+ *  install, together) never leaves a branch pinning the old one and failing the next boot. */
+export function followParentPins(parentRoot, branchRoot) {
+    const file = join(branchRoot, stateDirName(), 'world.json');
+    const pinOf = (s) => s.source?.version ?? s.version;
+    const parent = JSON.parse(readFileSync(join(parentRoot, stateDirName(), 'world.json'), 'utf8'));
+    const branch = JSON.parse(readFileSync(file, 'utf8'));
+    const pins = new Map((parent.services ?? []).flatMap((s) => { const pin = pinOf(s); return s.id && pin ? [[s.id, pin]] : []; }));
+    let moved = false;
+    for (const s of branch.services ?? []) {
+        const pin = s.id ? pins.get(s.id) : undefined;
+        if (!pin || pinOf(s) === pin)
+            continue;
+        if (s.source && typeof s.source === 'object')
+            s.source.version = pin;
+        else
+            s.version = pin;
+        moved = true;
+    }
+    if (moved)
+        writeFileSync(file, `${JSON.stringify(branch, null, 2)}\n`);
+}
+/** A write key of a branch, named for the key whose holder made it (the branch's own keys door): what that holder gets in
+ *  place of the branch's token, so the branch refuses it what a key is refused (seals, checks, keys, rules, sessions). */
+export async function keyOfBranch(branch, origin, maker) {
+    const made = await branch.handle(new Request(`${origin}/-/${branch.served}/keys`, { method: 'POST', headers: { [TOKEN_HEADER]: branch.token, 'content-type': 'application/json' }, body: JSON.stringify({ name: `${maker} (made this branch)`.slice(0, 100), scope: 'write' }) }));
+    if (!made.ok)
+        throw new Error(`a key of ${branch.served} for ${maker}: ${await made.text()}`);
+    return (await made.json()).key;
+}
 export class LocalBranches {
     o;
     sweeper = null;
@@ -50,15 +81,25 @@ export class LocalBranches {
     doorsFor(parent) {
         return {
             list: async () => this.list(parent),
-            create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+            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; },
+            // a branch of this parent only, served in this process beside it
+            show: async (name, request, vendor, rest, prefix) => {
+                const w = this.o.worlds.get(name);
+                const r = w ? this.record(w) : null;
+                if (!w || r?.from !== parent)
+                    return Response.json({ error: `no branch ${name} of ${parent}` }, { status: 404 });
+                if (!r.at?.instant || r.at.label || r.at.live)
+                    return Response.json({ error: `${name} is not a copy as of an instant: its pages are shown at its own address` }, { status: 403 });
+                return await w.shown(request, vendor, rest, prefix);
+            },
         };
     }
-    async create(parent, at, ttlSeconds, parentKey) {
+    async create(parent, at, ttlSeconds, parentKey, byKey) {
         this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
         try {
-            return await this.make(parent, at, ttlSeconds, parentKey);
+            return await this.make(parent, at, ttlSeconds, parentKey, byKey);
         }
         finally {
             const left = (this.making.get(parent) ?? 1) - 1;
@@ -68,7 +109,7 @@ export class LocalBranches {
                 this.making.delete(parent);
         }
     }
-    async make(parent, at, ttlSeconds, parentKey) {
+    async make(parent, at, ttlSeconds, parentKey, byKey) {
         const from = this.o.worlds.get(parent);
         if (!from)
             throw new Error(`no world ${parent} here`);
@@ -129,9 +170,11 @@ export class LocalBranches {
             }
             const createdAt = new Date().toISOString();
             const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
-            writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt }, null, 2)}\n`);
+            // what it was made as (a pull request's preview is labelled and may be live): what may be shown of it rests on that
+            const made = { ...(at.instant ? { instant: at.instant } : {}), ...(at.label ? { label: at.label } : {}), ...(at.live ? { live: true } : {}) };
+            writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: Object.keys(made).length ? made : null, createdAt, expiresAt }, null, 2)}\n`);
             this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);
-            return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+            return { name, token: byKey ? await keyOfBranch(mounted, origin, byKey) : mounted.token, readToken: mounted.readToken, expiresAt };
         }
         catch (error) {
             this.o.worlds.delete(name);

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

@@ -57,7 +57,8 @@ export type MountedWorld = {
         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>;
+    site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.shown */
+    shown: (request: Request, vendor: string, rest: string, prefix: string) => Promise<Response>;
     boot: (url: string) => Promise<void>;
     stop: () => Promise<void>;
 };
@@ -164,13 +165,17 @@ export type BranchDoors = {
         instant?: string;
         live?: boolean;
         label?: string;
-    }, ttlSeconds: number | null, origin: string, parentKey?: string) => Promise<{
+    }, ttlSeconds: number | null, origin: string, parentKey?: string, /** the name of the key that made it: whoever holds a key gets a key of the branch (named for it),
+     *  never the branch's own token, so the branch's doors refuse it what a key is refused */ byKey?: string) => Promise<{
         name: string;
         token: string;
         readToken: string;
         expiresAt: string | null;
     }>;
     remove: (name: string) => Promise<boolean>;
+    /** a page of a branch, read as its parent shows it (a vendor's screen at `prefix`, the parent's own path for it): where
+     *  the host holds the branch beside its parent; absent, a branch's pages are seen only at the branch's own address */
+    show?: (name: string, request: Request, vendor: string, rest: string, prefix: string) => Promise<Response>;
 };
 /** 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
@@ -303,6 +308,11 @@ export declare class WorldDoors {
         vendor: string;
         hosts: string[];
     }>>;
+    /** A vendor's page of this World as another World shows it at `prefix` (a parent showing its branch, the comparison's
+     *  "before"): read with this World's read token (a twin that enforces the read scope refuses any write), its links
+     *  minted under `prefix`.
+     *  The host calls it for the parent, which has checked its own caller; nothing of this World's session is involved. */
+    shown(request: Request, vendor: string, rest: string, prefix: string): Promise<Response>;
     /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
      *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
      *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */

package/dist/src/served-world.js

@@ -213,6 +213,7 @@ export async function mountWorld(name, opts = {}) {
         rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
         handle: (request) => world.handle(request),
         site: (request, host) => world.site(request, host),
+        shown: (request, vendor, rest, prefix) => world.shown(request, vendor, rest, prefix),
         async boot(url) {
             keep();
             const port = Number(new URL(url).port) || 0;
@@ -816,6 +817,31 @@ export class WorldDoors {
         }
         return out;
     }
+    /** A vendor's page of this World as another World shows it at `prefix` (a parent showing its branch, the comparison's
+     *  "before"): read with this World's read token (a twin that enforces the read scope refuses any write), its links
+     *  minted under `prefix`.
+     *  The host calls it for the parent, which has checked its own caller; nothing of this World's session is involved. */
+    async shown(request, vendor, rest, prefix) {
+        if (request.method !== 'GET' && request.method !== 'HEAD')
+            return Response.json({ error: "a copy's pages are read: GET and HEAD" }, { status: 405 });
+        if (!this.host.ready())
+            return Response.json({ error: 'booting', world: this.served }, { status: 503, headers: { 'retry-after': '1' } });
+        // a twin's pages only: a link forwards to the vendor itself, never something shown on another World's origin
+        if (this.link(vendor) || !this.host.twinFetch(vendor))
+            return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+        const url = new URL(request.url);
+        // only what a browser's read of a page says, as a site's read (site()): never a caller's credential, cookie, or
+        // the signed-address headers a session may not name
+        const headers = new Headers();
+        for (const name of ['accept', 'accept-language', 'if-none-match', 'if-modified-since', 'range', 'user-agent', 'sec-fetch-dest']) {
+            const v = request.headers.get(name);
+            if (v !== null)
+                headers.set(name, v);
+        }
+        headers.set(TOKEN_HEADER, this.readToken);
+        const at = new URL(`${url.origin}/${this.served}/${vendor}/${rest}${url.search}`);
+        return await this.wire(new Request(at, { method: request.method, headers, redirect: 'manual' }), at, `${vendor}/${rest}`, prefix);
+    }
     /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
      *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
      *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
@@ -946,7 +972,7 @@ export class WorldDoors {
         return enforced;
     }
     /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
-    async wire(request, url, rest) {
+    async wire(request, url, rest, /** the path its twin's pages are shown at, when not this World's own */ shownAt) {
         const [vendor, ...tail] = rest.split('/');
         const { scope, via } = this.credential(request);
         const manifestAsk = request.method === 'GET' && tail.join('/').replace(/\/+$/, '') === 'twin';
@@ -1003,7 +1029,7 @@ export class WorldDoors {
         else
             headers.delete('cookie');
         // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
-        headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
+        headers.set(TWIN_PREFIX_HEADER, shownAt ?? `/${this.served}/${vendor}`);
         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
@@ -1256,6 +1282,34 @@ export class WorldDoors {
             return this.session(request, url, scope, via === 'key' ? this.presentedKey(request) : undefined);
         if (kind === 'keys')
             return this.keysDoor(request, name, scope, via, this.credential(request).session);
+        // A COPY'S PAGES SHOWN HERE: `copies/<branch>/<vendor>/…`, a vendor's page in a branch of this World, read on this
+        // World's origin under its caller's credential (the comparison frames its "before" beside "now" this way: the
+        // branch's own session opens only on the branch's own pages). Only a copy as of an instant, which only a writer of
+        // this World makes, so its pages run here with nothing a stranger wrote (a labelled or live branch, a pull request's
+        // preview written by the app it tests, is shown at its own address). Read only; no cookie the copy sets is kept
+        if (kind === 'copies' && name && verb) {
+            const show = this.host.branches?.show;
+            if (!show)
+                return Response.json({ error: "this host shows a copy's pages only at the copy's own address" }, { status: 501 });
+            const [org] = this.served.split('/');
+            // the path after the vendor as it came, empty segments and a trailing slash kept (an object key may hold `//`)
+            const full = `${org}/${name}`;
+            // made by the World's token or a person's session: a key's copy is written by whoever holds the key, and its pages
+            // would run here under the viewer's session
+            const madeBy = this.keys().find((k) => k.branch === full && (!k.expiresAt || Date.parse(k.expiresAt) > Date.now()))?.createdBy?.via;
+            if (madeBy !== 'token' && madeBy !== 'session')
+                return Response.json({ error: `${full} was not made by this World's token or a person here: its pages are shown at its own address` }, { status: 403 });
+            // the path after the vendor as it came (empty segments and a trailing slash kept: an object key may hold `//`)
+            const exact = /^copies\/[^/]+\/[^/]+(?:\/(.*))?$/.exec(path);
+            if (!exact)
+                return Response.json({ error: 'copies/<branch>/<vendor>/<path>' }, { status: 404 });
+            const answer = await show(full, request, verb, exact[1] ?? '', `/-/${this.served}/copies/${name}/${verb}`);
+            if (answer.status < 200)
+                return Response.json({ error: "a copy's pages are read, never upgraded" }, { status: 400 });
+            const out = new Headers(answer.headers);
+            out.delete('set-cookie');
+            return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+        }
         if (scope === 'read' && request.method !== 'GET')
             return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
         if (kind === 'clock')
@@ -1896,7 +1950,7 @@ export class WorldDoors {
             const expiresAt = ttl === null ? undefined : new Date(now + ttl * 1000).toISOString();
             this.keepKeys([...this.keys(), { id: keyId, name: 'a branch (being made)', scope: 'write', hash: keyHash(parentKey), createdAt: new Date(now).toISOString(), createdBy, ...(person ? { for: person } : {}), ...(expiresAt ? { expiresAt } : {}), ...(maker ? { madeWith: maker.id } : {}) }]);
             try {
-                const made = await branches.create(typeof instant === 'string' ? { instant: new Date(Date.parse(instant)).toISOString() } : { ...(body?.live === true ? { live: true } : {}), ...(typeof body?.label === 'string' ? { label: body.label } : {}) }, ttl, url.origin, parentKey);
+                const made = await branches.create(typeof instant === 'string' ? { instant: new Date(Date.parse(instant)).toISOString() } : { ...(body?.live === true ? { live: true } : {}), ...(typeof body?.label === 'string' ? { label: body.label } : {}) }, ttl, url.origin, parentKey, maker ? maker.name : undefined);
                 this.keepKeys(this.keys().map((k) => (k.id === keyId ? { ...k, name: `the branch ${made.name}`, branch: made.name, ...(made.expiresAt ? { expiresAt: made.expiresAt } : {}) } : k)));
                 // a browser's session is answered the branch's read token only: a page views a branch, and the parent's
                 // session removes it, so no write token ever reaches a page's script (or a frame beside it)

package/dist/src/world-view.js

@@ -6,7 +6,7 @@ import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from "./configs.js";
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core/runtime';
-import { LocalBranches } from "./local-branches.js";
+import { followParentPins, LocalBranches } from "./local-branches.js";
 import { mountWorld } from "./served-world.js";
 import { localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export const VIEW_CONSOLE_BASE = '/-/console';
@@ -158,6 +158,7 @@ export async function serveWorldView(name, opts = {}) {
         await world.boot(url);
         // branches an earlier view made: mounted again (the sweep then removes those whose time ran out)
         for (const at of branchRoots(join(root, stateDirName(), 'branches'))) {
+            followParentPins(root, at);
             const b = await mountAt(at);
             await b.boot(url);
             worlds.set(b.served, b);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.12",
+  "version": "3.0.13",
   "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.12",
-    "@volter/world-console": "3.0.7"
+    "@volter/world-core": "3.0.13",
+    "@volter/world-console": "3.0.8"
   },
   "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.12",
+    "@volter/world-core": "3.0.13",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/index.ts

@@ -166,7 +166,7 @@ export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCreden
 export type { DeployTwinOutcome, MaterializedRoot } from './root.ts';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.ts';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
-export { LocalBranches } from './local-branches.ts';
+export { followParentPins, LocalBranches } from './local-branches.ts';
 export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.ts';
 export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
 export type { ViewConsole, WorldView } from './world-view.ts';

package/src/local-branches.ts

@@ -24,6 +24,35 @@ function renamed(config: Record<string, unknown>, id: string, name: string): Rec
   return { ...config, id, bare: { ...(config.bare as Record<string, unknown> | undefined), name } };
 }
 
+/** A branch mounted again beside its parent takes the parent's twin versions: it is the parent's config under another
+ *  name and runs on the packages the parent's root installs, so a parent moved to a new twin version (its pin and its
+ *  install, together) never leaves a branch pinning the old one and failing the next boot. */
+export function followParentPins(parentRoot: string, branchRoot: string): void {
+  const file = join(branchRoot, stateDirName(), 'world.json');
+  // a twin's pin: format 2 keeps it on the service's source, format 1 on the service itself
+  type Service = { id?: string; version?: string; source?: { version?: string } };
+  const pinOf = (s: Service): string | undefined => s.source?.version ?? s.version;
+  const parent = JSON.parse(readFileSync(join(parentRoot, stateDirName(), 'world.json'), 'utf8')) as { services?: Service[] };
+  const branch = JSON.parse(readFileSync(file, 'utf8')) as { services?: Service[] };
+  const pins = new Map((parent.services ?? []).flatMap((s) => { const pin = pinOf(s); return s.id && pin ? [[s.id, pin] as const] : []; }));
+  let moved = false;
+  for (const s of branch.services ?? []) {
+    const pin = s.id ? pins.get(s.id) : undefined;
+    if (!pin || pinOf(s) === pin) continue;
+    if (s.source && typeof s.source === 'object') s.source.version = pin; else s.version = pin;
+    moved = true;
+  }
+  if (moved) writeFileSync(file, `${JSON.stringify(branch, null, 2)}\n`);
+}
+
+/** A write key of a branch, named for the key whose holder made it (the branch's own keys door): what that holder gets in
+ *  place of the branch's token, so the branch refuses it what a key is refused (seals, checks, keys, rules, sessions). */
+export async function keyOfBranch(branch: { served: string; token: string; handle: (request: Request) => Promise<Response> }, origin: string, maker: string): Promise<string> {
+  const made = await branch.handle(new Request(`${origin}/-/${branch.served}/keys`, { method: 'POST', headers: { [TOKEN_HEADER]: branch.token, 'content-type': 'application/json' }, body: JSON.stringify({ name: `${maker} (made this branch)`.slice(0, 100), scope: 'write' }) }));
+  if (!made.ok) throw new Error(`a key of ${branch.served} for ${maker}: ${await made.text()}`);
+  return ((await made.json()) as { key: string }).key;
+}
+
 export type LocalBranchesOptions = {
   /** where branches live: `<dir>/<org>/<world>/` */
   dir: string;
@@ -62,19 +91,27 @@ export class LocalBranches {
   doorsFor(parent: string): BranchDoors {
     return {
       list: async () => this.list(parent),
-      create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+      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; },
+      // a branch of this parent only, served in this process beside it
+      show: async (name, request, vendor, rest, prefix) => {
+        const w = this.o.worlds.get(name);
+        const r = w ? this.record(w) : null;
+        if (!w || r?.from !== parent) return Response.json({ error: `no branch ${name} of ${parent}` }, { status: 404 });
+        if (!r.at?.instant || r.at.label || r.at.live) return Response.json({ error: `${name} is not a copy as of an instant: its pages are shown at its own address` }, { status: 403 });
+        return await w.shown(request, vendor, rest, prefix);
+      },
     };
   }
 
-  private async create(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+  private async create(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string, byKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
     this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
-    try { return await this.make(parent, at, ttlSeconds, parentKey); } finally {
+    try { return await this.make(parent, at, ttlSeconds, parentKey, byKey); } finally {
       const left = (this.making.get(parent) ?? 1) - 1;
       if (left > 0) this.making.set(parent, left); else this.making.delete(parent);
     }
   }
-  private async make(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+  private async make(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string, byKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
     const from = this.o.worlds.get(parent);
     if (!from) throw new Error(`no world ${parent} here`);
     const [org, world] = parent.split('/') as [string, string];
@@ -124,9 +161,11 @@ export class LocalBranches {
       if (clock) { const file = clockFile(root, id); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${clock}\n`); }
       const createdAt = new Date().toISOString();
       const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
-      writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt } satisfies BranchRecord, null, 2)}\n`);
+      // what it was made as (a pull request's preview is labelled and may be live): what may be shown of it rests on that
+      const made = { ...(at.instant ? { instant: at.instant } : {}), ...(at.label ? { label: at.label } : {}), ...(at.live ? { live: true } : {}) };
+      writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: Object.keys(made).length ? made : null, createdAt, expiresAt } satisfies BranchRecord, null, 2)}\n`);
       this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);
-      return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+      return { name, token: byKey ? await keyOfBranch(mounted, origin, byKey) : mounted.token, readToken: mounted.readToken, expiresAt };
     } catch (error) {
       this.o.worlds.delete(name);
       try { await mounted?.stop(); } catch { /* reported below */ }

package/src/served-world.ts

@@ -159,7 +159,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>; 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.shown */ shown: (request: Request, vendor: string, rest: string, prefix: 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. */
 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 };
 
@@ -215,6 +215,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
     handle: (request) => world.handle(request),
     site: (request, host) => world.site(request, host),
+    shown: (request, vendor, rest, prefix) => world.shown(request, vendor, rest, prefix),
     async boot(url) {
       keep();
       const port = Number(new URL(url).port) || 0;
@@ -373,8 +374,12 @@ export type BranchRow = { name: string; from: string; at: { instant?: string; li
 export type BranchDoors = {
   list: () => Promise<BranchRow[]>;
   /** `parentKey`: the key the branch reaches this World with (never this World's own token), made for whoever asked */
-  create: (at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, origin: string, parentKey?: string) => Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }>;
+  create: (at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, origin: string, parentKey?: string, /** the name of the key that made it: whoever holds a key gets a key of the branch (named for it),
+   *  never the branch's own token, so the branch's doors refuse it what a key is refused */ byKey?: string) => Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }>;
   remove: (name: string) => Promise<boolean>;
+  /** a page of a branch, read as its parent shows it (a vendor's screen at `prefix`, the parent's own path for it): where
+   *  the host holds the branch beside its parent; absent, a branch's pages are seen only at the branch's own address */
+  show?: (name: string, request: Request, vendor: string, rest: string, prefix: string) => Promise<Response>;
 };
 
 /** A World's browser-origin label, `<world>--<org>`, or null when its names cannot make one (a DNS
@@ -734,6 +739,25 @@ export class WorldDoors {
     return out;
   }
 
+  /** A vendor's page of this World as another World shows it at `prefix` (a parent showing its branch, the comparison's
+   *  "before"): read with this World's read token (a twin that enforces the read scope refuses any write), its links
+   *  minted under `prefix`.
+   *  The host calls it for the parent, which has checked its own caller; nothing of this World's session is involved. */
+  async shown(request: Request, vendor: string, rest: string, prefix: string): Promise<Response> {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: "a copy's pages are read: GET and HEAD" }, { status: 405 });
+    if (!this.host.ready()) return Response.json({ error: 'booting', world: this.served }, { status: 503, headers: { 'retry-after': '1' } });
+    // a twin's pages only: a link forwards to the vendor itself, never something shown on another World's origin
+    if (this.link(vendor) || !this.host.twinFetch(vendor)) return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+    const url = new URL(request.url);
+    // only what a browser's read of a page says, as a site's read (site()): never a caller's credential, cookie, or
+    // the signed-address headers a session may not name
+    const headers = new Headers();
+    for (const name of ['accept', 'accept-language', 'if-none-match', 'if-modified-since', 'range', 'user-agent', 'sec-fetch-dest']) { const v = request.headers.get(name); if (v !== null) headers.set(name, v); }
+    headers.set(TOKEN_HEADER, this.readToken);
+    const at = new URL(`${url.origin}/${this.served}/${vendor}/${rest}${url.search}`);
+    return await this.wire(new Request(at, { method: request.method, headers, redirect: 'manual' }), at, `${vendor}/${rest}`, prefix);
+  }
+
   /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
    *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
    *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
@@ -841,7 +865,7 @@ export class WorldDoors {
   }
 
   /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
-  private async wire(request: Request, url: URL, rest: string): Promise<Response> {
+  private async wire(request: Request, url: URL, rest: string, /** the path its twin's pages are shown at, when not this World's own */ shownAt?: string): Promise<Response> {
     const [vendor, ...tail] = rest.split('/');
     const { scope, via } = this.credential(request);
     const manifestAsk = request.method === 'GET' && tail.join('/').replace(/\/+$/, '') === 'twin';
@@ -881,7 +905,7 @@ export class WorldDoors {
     const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !/^(?:__Host-)?volter_world=/.test(c));
     if (cookies.length) headers.set('cookie', cookies.join('; ')); else headers.delete('cookie');
     // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
-    headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
+    headers.set(TWIN_PREFIX_HEADER, shownAt ?? `/${this.served}/${vendor}`);
     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
@@ -1089,6 +1113,29 @@ export class WorldDoors {
     if (kind === 'session' && !name && request.method === 'POST' && via === 'key' && scope !== 'read') return Response.json({ error: 'a key opens no browser session: open the World with its token, or from the platform' }, { status: 403 });
     if (kind === 'session' && !name && (request.method === 'POST' || request.method === 'DELETE')) return this.session(request, url, scope, via === 'key' ? this.presentedKey(request) : undefined);
     if (kind === 'keys') return this.keysDoor(request, name, scope, via, this.credential(request).session);
+    // A COPY'S PAGES SHOWN HERE: `copies/<branch>/<vendor>/…`, a vendor's page in a branch of this World, read on this
+    // World's origin under its caller's credential (the comparison frames its "before" beside "now" this way: the
+    // branch's own session opens only on the branch's own pages). Only a copy as of an instant, which only a writer of
+    // this World makes, so its pages run here with nothing a stranger wrote (a labelled or live branch, a pull request's
+    // preview written by the app it tests, is shown at its own address). Read only; no cookie the copy sets is kept
+    if (kind === 'copies' && name && verb) {
+      const show = this.host.branches?.show;
+      if (!show) return Response.json({ error: "this host shows a copy's pages only at the copy's own address" }, { status: 501 });
+      const [org] = this.served.split('/');
+      // the path after the vendor as it came, empty segments and a trailing slash kept (an object key may hold `//`)
+      const full = `${org}/${name}`;
+      // made by the World's token or a person's session: a key's copy is written by whoever holds the key, and its pages
+      // would run here under the viewer's session
+      const madeBy = this.keys().find((k) => k.branch === full && (!k.expiresAt || Date.parse(k.expiresAt) > Date.now()))?.createdBy?.via;
+      if (madeBy !== 'token' && madeBy !== 'session') return Response.json({ error: `${full} was not made by this World's token or a person here: its pages are shown at its own address` }, { status: 403 });
+      // the path after the vendor as it came (empty segments and a trailing slash kept: an object key may hold `//`)
+      const exact = /^copies\/[^/]+\/[^/]+(?:\/(.*))?$/.exec(path);
+      if (!exact) return Response.json({ error: 'copies/<branch>/<vendor>/<path>' }, { status: 404 });
+      const answer = await show(full, request, verb, exact[1] ?? '', `/-/${this.served}/copies/${name}/${verb}`);
+      if (answer.status < 200) return Response.json({ error: "a copy's pages are read, never upgraded" }, { status: 400 });
+      const out = new Headers(answer.headers); out.delete('set-cookie');
+      return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+    }
     if (scope === 'read' && request.method !== 'GET') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
 
     if (kind === 'clock') return await this.clockDoor(request, name);
@@ -1582,7 +1629,7 @@ export class WorldDoors {
       const expiresAt = ttl === null ? undefined : new Date(now + ttl * 1000).toISOString();
       this.keepKeys([...this.keys(), { id: keyId, name: 'a branch (being made)', scope: 'write', hash: keyHash(parentKey), createdAt: new Date(now).toISOString(), createdBy, ...(person ? { for: person } : {}), ...(expiresAt ? { expiresAt } : {}), ...(maker ? { madeWith: maker.id } : {}) }]);
       try {
-        const made = await branches.create(typeof instant === 'string' ? { instant: new Date(Date.parse(instant)).toISOString() } : { ...(body?.live === true ? { live: true } : {}), ...(typeof body?.label === 'string' ? { label: body.label } : {}) }, ttl, url.origin, parentKey);
+        const made = await branches.create(typeof instant === 'string' ? { instant: new Date(Date.parse(instant)).toISOString() } : { ...(body?.live === true ? { live: true } : {}), ...(typeof body?.label === 'string' ? { label: body.label } : {}) }, ttl, url.origin, parentKey, maker ? maker.name : undefined);
         this.keepKeys(this.keys().map((k) => (k.id === keyId ? { ...k, name: `the branch ${made.name}`, branch: made.name, ...(made.expiresAt ? { expiresAt: made.expiresAt } : {}) } : k)));
         // a browser's session is answered the branch's read token only: a page views a branch, and the parent's
         // session removes it, so no write token ever reaches a page's script (or a frame beside it)

package/src/world-view.ts

@@ -6,7 +6,7 @@ import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from './configs.ts';
 import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core/runtime';
-import { LocalBranches } from './local-branches.ts';
+import { followParentPins, LocalBranches } from './local-branches.ts';
 import { mountWorld, type MountedWorld } from './served-world.ts';
 import { localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
 
@@ -138,6 +138,7 @@ export async function serveWorldView(name: string, opts: { /** the person signed
     await world.boot(url);
     // branches an earlier view made: mounted again (the sweep then removes those whose time ran out)
     for (const at of branchRoots(join(root, stateDirName(), 'branches'))) {
+      followParentPins(root, at);
       const b = await mountAt(at);
       await b.boot(url);
       worlds.set(b.served, b);