@volter/world-core 3.0.6 → 3.0.8

package/dist/generated/pack-facts.json

@@ -337,10 +337,13 @@
         ],
         "sdks": [
           "cloudflare",
-          "aws4fetch"
+          "aws4fetch",
+          "react-turnstile",
+          "@marsidev/react-turnstile"
         ],
         "envStems": [
-          "CLOUDFLARE"
+          "CLOUDFLARE",
+          "TURNSTILE"
         ],
         "tools": [
           {
@@ -355,7 +358,11 @@
         },
         {
           "host": "dash.cloudflare.com",
-          "pathPattern": "^/(login|oauth2/|profile/api-tokens|_twin/users/|[0-9a-f]{32}/r2/api-tokens)"
+          "pathPattern": "^/($|login|profile/api-tokens|_twin/users/|[0-9a-f]{32}/(r2/api-tokens|workers-and-pages))"
+        },
+        {
+          "host": "challenges.cloudflare.com",
+          "pathPattern": "^/turnstile/v0/"
         },
         {
           "suffix": ".r2.cloudflarestorage.com"
@@ -363,7 +370,7 @@
       ],
       "hostsClaimed": {
         "door": "/_twin/hosts",
-        "note": "R2 custom domains registered to a bucket; public read still requires enabled and active ownership/TLS."
+        "note": "R2 custom domains registered to a bucket (public read still requires enabled and active ownership/TLS), and Workers Custom Domains, answered with the Worker static assets."
       },
       "archetype": "crud",
       "protocol": {
@@ -380,8 +387,8 @@
         "worker_deployment",
         "worker_secret",
         "zone",
-        "dns_record",
         "custom_hostname",
+        "turnstile_widget",
         "r2_bucket",
         "r2_object",
         "r2_multipart",
@@ -401,9 +408,12 @@
         },
         "fill": {
           "CLOUDFLARE_API_TOKEN": "api_token",
+          "CLOUDFLARE_API_KEY": "api_token",
           "CLOUDFLARE_ACCOUNT_ID": "account_id",
           "R2_ACCESS_KEY_ID": "r2_access_key_id",
           "R2_SECRET_ACCESS_KEY": "r2_secret_access_key",
+          "CLOUDFLARE_ACCESS_KEY": "r2_access_key_id",
+          "CLOUDFLARE_SECRET_ACCESS_KEY": "r2_secret_access_key",
           "R2_ENDPOINT": "r2_endpoint"
         }
       },

package/dist/src/derived.d.ts

@@ -111,6 +111,13 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
     owners(): Record<string, DerivedOwner>;
     /** The vendor's sockets (sockets.ts), for the serve seam to upgrade to, when its manifest declares any. */
     upgrade?: WebSocketUpgrade;
+    /** The workspace screens it draws, its lanes' too (`GET /twin`'s `screens`). */
+    workspaces?(): Workspace[];
+};
+/** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */
+export type Workspace = {
+    id: string;
+    path: string;
 };
 export declare function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch;
 export {};

package/dist/src/index.d.ts

@@ -36,6 +36,7 @@ export { VendorUnreachableError } from './vendor-call.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.js';
 export { serveHttp, serveStream, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.js';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.js';
+export { twinSiteUrl } from './twin-fetch.js';
 export { statefulTwinManifest, twinManifest } from './scenario.js';
 export { assetContentType, packAsset } from './pack-assets.js';
 export { bytesResponse, contentTypeOf, fileResponse } from './file-response.js';

package/dist/src/index.js

@@ -28,6 +28,8 @@ export { VendorUnreachableError } from "./vendor-call.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from "./request-scope.js";
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
 export { serveHttp, serveStream } from "./serve-http.js";
+// where a page links a hostname its twin answers, inside the World that shows it
+export { twinSiteUrl } from "./twin-fetch.js";
 export { statefulTwinManifest, twinManifest } from "./scenario.js";
 export { assetContentType, packAsset } from "./pack-assets.js";
 export { bytesResponse, contentTypeOf, fileResponse } from "./file-response.js";

package/dist/src/pack-fetch.d.ts

@@ -1,5 +1,5 @@
 import { type DerivedManifest, type Handler, type HandlerContext, type VendorManifest } from './derived-core.js';
-import { type DerivedFetch, type DerivedOwner, type DerivedSurface } from './derived.js';
+import { type DerivedFetch, type DerivedOwner, type DerivedSurface, type Workspace } from './derived.js';
 import { type PackScenarioAdapter } from './scenario.js';
 import { type SocketEngine } from './sockets.js';
 import { type GraphqlPart } from './graphql-wire.js';
@@ -74,4 +74,5 @@ export type PackFetchOptions = {
 export declare function createPackFetch(parts: PackParts, options?: PackFetchOptions): DerivedFetch;
 export declare function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & {
     owners: () => Record<string, DerivedOwner>;
+    workspaces: () => Workspace[];
 };

package/dist/src/pack-fetch.js

@@ -208,6 +208,9 @@ export function createPackFetch(parts, options = {}) {
         const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
         return { decl: s, host: (h) => hosts.map((match) => match(h)).find(Boolean), path: pathMatcher(s.path, true), answer: parts.screens[s.id] };
     });
+    // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path, the pack's own
+    // and its lanes'
+    const workspaces = () => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
     // a context the kernel opens for what no surface operation names: a door, a screen, the clock
     const open = (request, id, method, path, params) => contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' }, params }, scope);
     const refusedReadOnly = () => vendorError(m, m.readOnly);
@@ -265,8 +268,7 @@ export function createPackFetch(parts, options = {}) {
         if (request.method === 'GET' && path === '/twin' && m.discovery) {
             const d = m.discovery;
             // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
-            const workspaces = (m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path }));
-            const shown = workspaces.length ? { screens: workspaces } : {};
+            const shown = workspaces().length ? { screens: workspaces() } : {};
             // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
             if (parts.scenario && d.behavior) {
                 return Response.json({ ...shown, ...twinManifest({
@@ -324,8 +326,14 @@ export function createPackFetch(parts, options = {}) {
         // reached at a World's place for the twin (`x-forwarded-prefix`, served-world's wire), the host is the World's: a
         // workspace is shown there by its path alone, its root too (the console frames it so)
         const placed = request.headers.has(TWIN_PREFIX_HEADER);
+        // a person's browser opening a page there (a navigation, a form, the console's frame) is asking for a screen: one
+        // whose path names it is taken before an API path of the same shape (a dashboard's /<account>/workers-and-pages
+        // over R2's /{Bucket}/{Key}), the root workspace at the root alone
+        const page = placed && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
+        const rooted = (x) => x.s.decl.path.replace(/\/+$/, '') === '';
         const byPath = hits.find((x) => x.onHost && exact(x.s))
-            ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? hits.find((x) => x.s.decl.path.replace(/\/+$/, '') !== '')
+            ?? (page ? hits.find((x) => !rooted(x)) ?? (path === '/' ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined) : undefined)
+            ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? hits.find((x) => !rooted(x))
                 ?? (placed ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined));
         if (byPath) {
             if (readOnly && request.method !== 'GET' && request.method !== 'HEAD')
@@ -388,7 +396,7 @@ export function createPackFetch(parts, options = {}) {
     async (asked) => engineOf()?.serve(asked)) : undefined;
     // what serves each operation: the pack's own, and each lane's
     const owners = () => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-    return derivedRequestScopes(m, Object.assign(served, { owners, serves, ...(upgrade ? { upgrade } : {}) }));
+    return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, ...(upgrade ? { upgrade } : {}) }));
 }
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
  *  route whose conditions all hold, then the default), behind the gateway's CORS; undefined when none takes it. */
@@ -438,13 +446,18 @@ function laneRouter(vendor, decl, lanes, rootServes = () => false) {
  *  discovery door, then its lanes as its gateway sends them; a request no lane takes is the vendor's not-found. */
 /** What serves each of a vendor's lanes' operations (a handler, the core, or the gap), as one map. */
 const lanesOwners = (lanes) => Object.assign({}, ...Object.values(lanes).map((l) => l.fetch.owners?.() ?? {}));
+/** The workspaces a vendor's lanes draw, as one list. */
+const lanesWorkspaces = (lanes) => Object.values(lanes).flatMap((l) => l.fetch.workspaces?.() ?? []);
 export function createVendorFetch(manifest, lanes) {
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
         const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
-        if (request.method === 'GET' && path === '/twin' && manifest.discovery)
-            return Response.json(statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }));
+        if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
+            // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
+            const screens = lanesWorkspaces(lanes);
+            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}) });
+        }
         const to = lane(request);
         return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });
-    }, { owners: () => lanesOwners(lanes) });
+    }, { owners: () => lanesOwners(lanes), workspaces: () => lanesWorkspaces(lanes) });
 }

package/dist/src/runtime.d.ts

@@ -3,7 +3,7 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.js';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.js';
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';

package/dist/src/runtime.js

@@ -11,7 +11,7 @@ export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullP
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from "./twin-fetch.js";
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";

package/dist/src/twin-fetch.d.ts

@@ -7,6 +7,14 @@ export declare const TWIN_PREFIX_HEADER = "x-forwarded-prefix";
  *  the twin under. A pack mints every live URL it hands back (an upload target, a file link, a
  *  callback) from this, never from the bare origin, so the URL works behind a served World. */
 export declare function twinPublicBase(request: Request): string;
+/** Where a World shows a hostname its twins answer (a Workers Custom Domain, an R2 public domain): the address a person
+ *  opens it at, `{host}` standing for the hostname (`http://{host}.<world>--<org>.localhost:<port>`). A World that routes
+ *  its sites to a browser sends it on every request it forwards to a twin. */
+export declare const TWIN_SITES_HEADER = "x-volter-world-sites";
+/** Where a page links a hostname the twin answers: the World's address for it when the World shows sites, else the
+ *  hostname itself (reached through the World's proxy, or the vendor). A pack's screen links a site from this, as it
+ *  mints its own URLs from twinPublicBase. */
+export declare function twinSiteUrl(request: Request, hostname: string): string;
 /** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves
  *  it over whatever carries the bytes — a local listener's socket, or a WebSocket to a hosted World.
  *  The pack owns framing and protocol; the host owns the transport. `open` greets through the sink;

package/dist/src/twin-fetch.js

@@ -40,6 +40,18 @@ export function twinPublicBase(request) {
     const origin = host && /^[A-Za-z0-9.-]+(:\d+)?$/.test(host) && (proto === 'http' || proto === 'https') ? `${proto}://${host}` : new URL(request.url).origin;
     return `${origin}${prefix.replace(/\/+$/, '')}`;
 }
+/** Where a World shows a hostname its twins answer (a Workers Custom Domain, an R2 public domain): the address a person
+ *  opens it at, `{host}` standing for the hostname (`http://{host}.<world>--<org>.localhost:<port>`). A World that routes
+ *  its sites to a browser sends it on every request it forwards to a twin. */
+export const TWIN_SITES_HEADER = 'x-volter-world-sites';
+/** Where a page links a hostname the twin answers: the World's address for it when the World shows sites, else the
+ *  hostname itself (reached through the World's proxy, or the vendor). A pack's screen links a site from this, as it
+ *  mints its own URLs from twinPublicBase. */
+export function twinSiteUrl(request, hostname) {
+    const at = request.headers.get(TWIN_SITES_HEADER);
+    const host = hostname.toLowerCase();
+    return at && /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(at) && /^[a-z0-9.-]+$/.test(host) ? at.replace('{host}', host) : `https://${host}`;
+}
 /** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as
  *  `requestScopes`: `read` — a request carrying `x-volter-read-only: 1` (request-scope.ts) has every
  *  write it attempts refused at the kernel's write seam, whatever operation it names. A World's doors

package/generated/pack-facts.json

@@ -337,10 +337,13 @@
         ],
         "sdks": [
           "cloudflare",
-          "aws4fetch"
+          "aws4fetch",
+          "react-turnstile",
+          "@marsidev/react-turnstile"
         ],
         "envStems": [
-          "CLOUDFLARE"
+          "CLOUDFLARE",
+          "TURNSTILE"
         ],
         "tools": [
           {
@@ -355,7 +358,11 @@
         },
         {
           "host": "dash.cloudflare.com",
-          "pathPattern": "^/(login|oauth2/|profile/api-tokens|_twin/users/|[0-9a-f]{32}/r2/api-tokens)"
+          "pathPattern": "^/($|login|profile/api-tokens|_twin/users/|[0-9a-f]{32}/(r2/api-tokens|workers-and-pages))"
+        },
+        {
+          "host": "challenges.cloudflare.com",
+          "pathPattern": "^/turnstile/v0/"
         },
         {
           "suffix": ".r2.cloudflarestorage.com"
@@ -363,7 +370,7 @@
       ],
       "hostsClaimed": {
         "door": "/_twin/hosts",
-        "note": "R2 custom domains registered to a bucket; public read still requires enabled and active ownership/TLS."
+        "note": "R2 custom domains registered to a bucket (public read still requires enabled and active ownership/TLS), and Workers Custom Domains, answered with the Worker static assets."
       },
       "archetype": "crud",
       "protocol": {
@@ -380,8 +387,8 @@
         "worker_deployment",
         "worker_secret",
         "zone",
-        "dns_record",
         "custom_hostname",
+        "turnstile_widget",
         "r2_bucket",
         "r2_object",
         "r2_multipart",
@@ -401,9 +408,12 @@
         },
         "fill": {
           "CLOUDFLARE_API_TOKEN": "api_token",
+          "CLOUDFLARE_API_KEY": "api_token",
           "CLOUDFLARE_ACCOUNT_ID": "account_id",
           "R2_ACCESS_KEY_ID": "r2_access_key_id",
           "R2_SECRET_ACCESS_KEY": "r2_secret_access_key",
+          "CLOUDFLARE_ACCESS_KEY": "r2_access_key_id",
+          "CLOUDFLARE_SECRET_ACCESS_KEY": "r2_secret_access_key",
           "R2_ENDPOINT": "r2_endpoint"
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/derived.ts

@@ -196,8 +196,13 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
   owners(): Record<string, DerivedOwner>;
   /** The vendor's sockets (sockets.ts), for the serve seam to upgrade to, when its manifest declares any. */
   upgrade?: WebSocketUpgrade;
+  /** The workspace screens it draws, its lanes' too (`GET /twin`'s `screens`). */
+  workspaces?(): Workspace[];
 };
 
+/** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */
+export type Workspace = { id: string; path: string };
+
 export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   const handlers = options.handlers ?? {};
   const known = new Set(options.surface.operations.map((o) => o.id));

package/src/index.ts

@@ -51,6 +51,8 @@ export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.ts'
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
 export { serveHttp, serveStream, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
+// where a page links a hostname its twin answers, inside the World that shows it
+export { twinSiteUrl } from './twin-fetch.ts';
 export { statefulTwinManifest, twinManifest } from './scenario.ts';
 export { assetContentType, packAsset } from './pack-assets.ts';
 export { bytesResponse, contentTypeOf, fileResponse } from './file-response.ts';

package/src/pack-fetch.ts

@@ -10,7 +10,7 @@ import { TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
 import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
-import { compileSurface, createDerivedFetch, matchOperation, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface } from './derived.ts';
+import { compileSurface, createDerivedFetch, matchOperation, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace } from './derived.ts';
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './request-scope.ts';
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
 import { getActiveWorldStore } from './world-store.ts';
@@ -242,6 +242,9 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
     return { decl: s, host: (h: string) => hosts.map((match) => match(h)).find(Boolean), path: pathMatcher(s.path, true), answer: parts.screens![s.id]! };
   });
+  // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path, the pack's own
+  // and its lanes'
+  const workspaces = (): Workspace[] => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
   // a context the kernel opens for what no surface operation names: a door, a screen, the clock
   const open = (request: Request, id: string, method: string, path: string, params: Record<string, string>): Promise<HandlerContext> =>
     contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' } as DerivedOperation, params }, scope);
@@ -295,8 +298,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (request.method === 'GET' && path === '/twin' && m.discovery) {
       const d = m.discovery;
       // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
-      const workspaces = (m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path }));
-      const shown = workspaces.length ? { screens: workspaces } : {};
+      const shown = workspaces().length ? { screens: workspaces() } : {};
       // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
       if (parts.scenario && d.behavior) {
         return Response.json({ ...shown, ...twinManifest({
@@ -342,8 +344,14 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // reached at a World's place for the twin (`x-forwarded-prefix`, served-world's wire), the host is the World's: a
     // workspace is shown there by its path alone, its root too (the console frames it so)
     const placed = request.headers.has(TWIN_PREFIX_HEADER);
+    // a person's browser opening a page there (a navigation, a form, the console's frame) is asking for a screen: one
+    // whose path names it is taken before an API path of the same shape (a dashboard's /<account>/workers-and-pages
+    // over R2's /{Bucket}/{Key}), the root workspace at the root alone
+    const page = placed && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
+    const rooted = (x: (typeof hits)[number]): boolean => x.s.decl.path.replace(/\/+$/, '') === '';
     const byPath = hits.find((x) => x.onHost && exact(x.s))
-      ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? hits.find((x) => x.s.decl.path.replace(/\/+$/, '') !== '')
+      ?? (page ? hits.find((x) => !rooted(x)) ?? (path === '/' ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined) : undefined)
+      ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? hits.find((x) => !rooted(x))
         ?? (placed ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined));
     if (byPath) {
       if (readOnly && request.method !== 'GET' && request.method !== 'HEAD') return refusedReadOnly();
@@ -395,7 +403,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     async (asked) => engineOf()?.serve(asked)) : undefined;
   // what serves each operation: the pack's own, and each lane's
   const owners = (): Record<string, DerivedOwner> => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-  return derivedRequestScopes(m, Object.assign(served, { owners, serves, ...(upgrade ? { upgrade } : {}) }));
+  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, ...(upgrade ? { upgrade } : {}) }));
 }
 
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
@@ -448,12 +456,20 @@ function laneRouter(vendor: string, decl: LanesDecl, lanes: Record<string, LaneP
 const lanesOwners = (lanes: Record<string, LanePart>): Record<string, DerivedOwner> =>
   Object.assign({}, ...Object.values(lanes).map((l) => (l.fetch as { owners?: () => Record<string, DerivedOwner> }).owners?.() ?? {}));
 
-export function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & { owners: () => Record<string, DerivedOwner> } {
+/** The workspaces a vendor's lanes draw, as one list. */
+const lanesWorkspaces = (lanes: Record<string, LanePart>): Workspace[] =>
+  Object.values(lanes).flatMap((l) => (l.fetch as { workspaces?: () => Workspace[] }).workspaces?.() ?? []);
+
+export function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & { owners: () => Record<string, DerivedOwner>; workspaces: () => Workspace[] } {
   const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
   return Object.assign(async (request: Request): Promise<Response> => {
     const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
-    if (request.method === 'GET' && path === '/twin' && manifest.discovery) return Response.json(statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }));
+    if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
+      // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
+      const screens = lanesWorkspaces(lanes);
+      return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}) });
+    }
     const to = lane(request);
     return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });
-  }, { owners: () => lanesOwners(lanes) });
+  }, { owners: () => lanesOwners(lanes), workspaces: () => lanesWorkspaces(lanes) });
 }

package/src/runtime.ts

@@ -12,7 +12,7 @@ export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrit
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.ts';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.ts';
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';

package/src/twin-fetch.ts

@@ -43,6 +43,20 @@ export function twinPublicBase(request: Request): string {
   return `${origin}${prefix.replace(/\/+$/, '')}`;
 }
 
+/** Where a World shows a hostname its twins answer (a Workers Custom Domain, an R2 public domain): the address a person
+ *  opens it at, `{host}` standing for the hostname (`http://{host}.<world>--<org>.localhost:<port>`). A World that routes
+ *  its sites to a browser sends it on every request it forwards to a twin. */
+export const TWIN_SITES_HEADER = 'x-volter-world-sites';
+
+/** Where a page links a hostname the twin answers: the World's address for it when the World shows sites, else the
+ *  hostname itself (reached through the World's proxy, or the vendor). A pack's screen links a site from this, as it
+ *  mints its own URLs from twinPublicBase. */
+export function twinSiteUrl(request: Request, hostname: string): string {
+  const at = request.headers.get(TWIN_SITES_HEADER);
+  const host = hostname.toLowerCase();
+  return at && /^https?:\/\/\{host\}\.[A-Za-z0-9.-]+(:\d+)?$/.test(at) && /^[a-z0-9.-]+$/.test(host) ? at.replace('{host}', host) : `https://${host}`;
+}
+
 /** A twin's BYTE-STREAM door: a pack whose clients speak a TCP protocol (SMTP, the MySQL wire) serves
  *  it over whatever carries the bytes — a local listener's socket, or a WebSocket to a hosted World.
  *  The pack owns framing and protocol; the host owns the transport. `open` greets through the sink;