@volter/world-core 3.0.17 → 3.0.19

package/dist/src/content-route.d.ts

@@ -0,0 +1,8 @@
+/** A `/@<host>/<path>` address: the host normalised, the path under it (slashes collapsed), and why the spelling cannot
+ *  be the host's content (`refused`: a port other than the default), when it cannot. */
+export type ContentAddress = {
+    host: string;
+    path: string;
+    refused?: string;
+};
+export declare function contentAddressOf(pathname: string): ContentAddress | undefined;

package/dist/src/content-route.js

@@ -0,0 +1,27 @@
+// THE CONTENT ROUTE'S ADDRESS (architecture, "Screens", "A page at a World's place"): at a World's place, what a page
+// reaches on another of the pack's hosts that a content screen serves is `<base>/@<host>/<path>`. This reads that
+// address as a browser would have written it: a doubled slash collapsed, `%40` for `@`, the host's case, a trailing dot
+// and a default port (80, 443) normalised away. What it reads is a candidate only: the route is taken when the host is
+// one a built content screen names (pack-fetch.ts), and a request naming no such host is general routing's, as before.
+export function contentAddressOf(pathname) {
+    const collapsed = pathname.replace(/\/{2,}/g, '/');
+    const named = /^\/(?:@|%40)([^/]+)(\/.*)?$/i.exec(collapsed);
+    if (!named)
+        return undefined;
+    let token;
+    try {
+        token = decodeURIComponent(named[1]).toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    const at = /^([^:]*)(?::(\d*))?$/.exec(token);
+    if (!at)
+        return undefined;
+    const host = at[1].replace(/\.$/, '');
+    if (!/^[a-z0-9_-]+(?:\.[a-z0-9_-]+)+$/.test(host))
+        return undefined;
+    const port = at[2];
+    const refused = port && port !== '80' && port !== '443' ? `port ${port} is not the host's` : undefined;
+    return { host, path: named[2] ?? '/', ...(refused ? { refused } : {}) };
+}

package/dist/src/derived-core.d.ts

@@ -3,7 +3,7 @@ import { GitObjectStore } from './git/objects.js';
 import { GitRefs } from './git/refs.js';
 import { type SocketDecl, type SocketSession } from './sockets.js';
 import { type MachinePool } from './machines.js';
-import { type ApplicationAnswer, type EventRender, type EventScheme, type EventsDecl, type EventValues } from './events.js';
+import { type ApplicationAnswer, type ApplicationStandIn, type EventRender, type EventScheme, type EventsDecl, type EventValues } from './events.js';
 import type { RateBudgetDeclaration } from './rateBudget.js';
 import { type HandlerCrypto } from './signing.js';
 import { type ManagedDatabase } from './managed-database.js';
@@ -268,6 +268,8 @@ export type VendorManifest = {
     descriptor: Omit<PackDescriptor, 'vendor'>;
     ingest?: IngestDecl;
     rateBudget?: RateBudgetDeclaration;
+    /** the vendor has no vendor-backed half (architecture, "The descriptor"): packOf copies it, and derives no state system */
+    vendorBacked?: DerivedManifest['vendorBacked'];
 };
 /** `code` as the vendor writes it: a string, or a number (Discord's JSON error codes are integers) */
 export type ErrorSpec = {
@@ -293,6 +295,15 @@ export type ScreenDecl = {
     demand: string;
     status: 'done' | 'todo';
     controls?: string[];
+    /** wherever this screen would answer (its host, a World's place, its path alone), a request the pack's API names for
+     *  its method is the operation's, not this screen's: a site whose pages draw while its forms and links act on
+     *  operations the spec writes at the same paths (Hacker News's /login page posts to POST /login; its front page at `/`
+     *  would otherwise take GET /vote) (architecture, "Screens") */
+    yieldsToApi?: true;
+    /** a content screen that takes a form at a World's place (`<base>/@<host>/…`), beside GET and HEAD: the methods it
+     *  takes, with its demand (an upload bucket a page posts a lease's form to: Reddit's S3 hosts) (architecture, "A page
+     *  at a World's place") */
+    takes?: ReadonlyArray<'POST'>;
     /** the vendor's documentation of the round trip or the screen */
     source: string;
 };
@@ -651,6 +662,9 @@ export declare function flagOf(m: Pick<DerivedManifest, 'booleans'>, value: unkn
  *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
  *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
  *  (`metadata[order]=007`, `name=2024`). */
+/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
+ *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
+export declare function ownField(node: Record<string, unknown> | unknown[], key: string, value: unknown): void;
 export declare function parseBracketForm(text: string, scalars?: Readonly<Record<string, string | undefined>>): Record<string, unknown>;
 /** A request's parameters, its query's and its body's. With the manifest's `body.form.coerce`, a form's fields the
  *  operation's spec types as numbers or booleans are read as them (parseBracketForm); without an operation (a twin door)
@@ -686,6 +700,8 @@ export type CoreScope = {
     readOnly?: boolean;
     /** `semantics/tenant.ts`: the tenant the caller acts in (the manifest's `tenant`), or undefined for none */
     tenant?: (ctx: HandlerContext) => string | undefined | Promise<string | undefined>;
+    /** the application a walk stands in for: what the vendor asks it (`ctx.ask`) is answered by it (events.ts) */
+    application?: ApplicationStandIn;
 };
 /** The lane a vendor's router sent a request to (pack-fetch's laneRouter sets it). */
 export declare const LANE_HEADER = "x-volter-lane";

package/dist/src/derived-core.js

@@ -124,6 +124,13 @@ export function flagOf(m, value) {
  *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
  *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
  *  (`metadata[order]=007`, `name=2024`). */
+/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
+ *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
+export function ownField(node, key, value) {
+    Object.defineProperty(node, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** A field the object holds as its own, never one it inherits (`constructor` is every object's). */
+const ownValue = (node, key) => (Object.hasOwn(node, key) ? node[key] : undefined);
 export function parseBracketForm(text, scalars) {
     const out = {};
     for (const [rawKey, raw] of new URLSearchParams(text)) {
@@ -133,22 +140,35 @@ export function parseBracketForm(text, scalars) {
             : kind === 'integer' ? (/^-?\d+$/.test(raw) ? Number(raw) : raw)
                 : kind === 'number' ? (/^-?\d+(\.\d+)?$/.test(raw) ? Number(raw) : raw)
                     : raw;
+        // every field is the node's own, read and written as such: a key naming an object's machinery (`__proto__[x]`,
+        // `constructor[prototype][x]`) is a field of that name, never a walk into what every object inherits
         let node = out;
-        parts.forEach((key, i) => {
+        for (const [i, key] of parts.entries()) {
+            // an array holds its items by index (`a[]`, `a[0]`): a named key under one (`a[]=1&a[length]=-1`) has nowhere to
+            // go, as a key under text has none (`a=1&a[b]=2`): the first shape stands
+            if (Array.isArray(node) && key !== '' && !/^\d+$/.test(key))
+                break;
             if (i === parts.length - 1) {
                 if (key === '') {
                     if (Array.isArray(node))
                         node.push(value);
                 }
                 else
-                    node[key] = value;
-                return;
+                    ownField(node, key, value);
+                break;
             }
             const next = parts[i + 1];
-            if (node[key] === undefined)
-                node[key] = next === '' || /^\d+$/.test(next) ? [] : {};
-            node = node[key];
-        });
+            if (key === '')
+                break;
+            let child = ownValue(node, key);
+            if (child === undefined) {
+                child = next === '' || /^\d+$/.test(next) ? [] : {};
+                ownField(node, key, child);
+            }
+            if (child === null || typeof child !== 'object')
+                break;
+            node = child;
+        }
     }
     return out;
 }
@@ -186,24 +206,32 @@ export async function readParams(manifest, request, operation) {
         const parts = boundary === null ? [] : multipartParts(new Uint8Array(await request.arrayBuffer()), boundary);
         const out = { ...query };
         for (const part of parts) {
+            // each part a field of its own name, whatever the name (`__proto__` included: ownField)
             if (part.filename === null) {
-                out[part.name] = new TextDecoder().decode(part.body);
+                ownField(out, part.name, new TextDecoder().decode(part.body));
                 continue;
             }
             const bytes = part.body;
             const parsed = { name: part.filename, type: part.type ?? '', size: bytes.byteLength, content: new TextDecoder().decode(bytes) };
-            out[part.name] = Object.defineProperty(parsed, 'bytes', { value: bytes, enumerable: false });
+            ownField(out, part.name, Object.defineProperty(parsed, 'bytes', { value: bytes, enumerable: false }));
         }
         return out;
     }
+    // NDJSON (`application/x-ndjson`) is lines of JSON, not a JSON document: the handler reads its text
+    const media = (type.split(';')[0] ?? '').trim().toLowerCase();
+    const isJson = media.includes('json') && !media.includes('ndjson');
+    // a form is a body labelled one (application/x-www-form-urlencoded); a body of any other type (an image, a video, an
+    // octet-stream PUT to an upload URL, a text/plain SQL statement, an NDJSON batch) is no form: its parameters are the
+    // query's, and the handler reads its text or bytes itself
+    const isForm = media === 'application/x-www-form-urlencoded';
+    const asJson = isJson || manifest.body.json === 'always';
+    if (!isForm && !asJson)
+        return query;
     const text = await bodyTextOf(request);
     if (!text)
         return query;
-    // NDJSON (`application/x-ndjson`) is lines of JSON, not a JSON document: the handler reads its text
-    const isJson = type.includes('json') && !type.includes('ndjson');
-    const asJson = isJson || manifest.body.json === 'always';
     // `json: 'always'` reads a body labelled otherwise as JSON (GitHub reads curl -d's); a body that is not JSON is read
-    // as the form it is labelled, never a crash (a sign-in page's own form, posted to the vendor's page)
+    // as a form only when it is labelled one (a sign-in page's own form, posted to the vendor's page), never a crash
     let body;
     if (asJson) {
         try {
@@ -212,6 +240,8 @@ export async function readParams(manifest, request, operation) {
         catch {
             if (isJson)
                 throw new SyntaxError('malformed JSON body');
+            if (!isForm)
+                return query;
             body = parseBracketForm(text, scalars);
         }
     }
@@ -598,6 +628,8 @@ function recordedInput(m, call, merged) {
         return { door: id, ...asSent };
     return { operationId: id, ...asSent };
 }
+/** The scope each call is served in (serveCore, contextFor), for the contexts a write opens for its hooks. */
+const scopeOfCall = new WeakMap();
 async function writeDetailed(m, call, resource, id, fields, operation, params, root, occurredAt) {
     const withFiles = async (input) => { const files = input.operationId ? await keptFiles(m, call, root) : undefined; return files ? { ...input, files } : input; };
     const { resource: row, result } = await applyTwinWrite(m.service, 
@@ -609,7 +641,9 @@ async function writeDetailed(m, call, resource, id, fields, operation, params, r
         : { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: await withFiles(recordedInput(m, call, params)), occurredAt, actor: { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) } }, root);
     await keepCounts(m, call, resource, row, params, root, occurredAt);
     const body = view(m, resource, row);
-    const context = () => contextFor(m, { ...call, request: call.request.clone() }, { ...(root !== undefined ? { root } : {}), clock: () => occurredAt });
+    // the write's own context for its hooks, in the scope the call was served in (a walk's application answers, a tenant,
+    // the managed database), at the write's moment
+    const context = () => contextFor(m, { ...call, request: call.request.clone() }, { ...(scopeOfCall.get(call) ?? {}), ...(root !== undefined ? { root } : {}), clock: () => occurredAt });
     if (m.onWrite)
         await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request, context });
     if (m.events) {
@@ -940,6 +974,7 @@ export async function serveCore(m, call, scope = {}) {
     if (!resource || !decl)
         return { unmodeled: `no manifest entry for resource ${resource ?? '(none)'}` };
     call = adoptedPath(m, call, root);
+    scopeOfCall.set(call, scope);
     // the body is read from a copy, so the call's own request is still unread for the write hook's context
     const params = await boundaryParams(m, { ...call, request: call.request.clone() }, root);
     const idParam = subjectOf(m, resource, call);
@@ -1094,6 +1129,7 @@ export async function contextFor(m, call, scope) {
     const root = scope.root;
     const asAsked = call;
     call = adoptedPath(m, call, root);
+    scopeOfCall.set(call, scope);
     const at = (scope.clock ?? worldNow)();
     // the guard's parse when it made one (taken once), else this context's own
     const parsed = takeParsedBody(call.request);
@@ -1134,7 +1170,7 @@ export async function contextFor(m, call, scope) {
         publicBase: twinPublicBase(call.request),
         scenario: scenarioDecisionOf(call.request),
         deliver: (url, init) => deliverToApplication(url, init),
-        ask: (url, init, within) => askApplication(url, init, within),
+        ask: (url, init, within) => askApplication(url, init, within, scope.application),
         worldEnv: (name) => worldEnvValue(name),
         asVendor: (fn) => runAsVendorMove(fn),
         git: (name) => {

package/dist/src/derived.d.ts

@@ -117,6 +117,9 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
     boards?: boolean;
     /** Whether a built screen of it takes a URL: a board frame it draws. */
     draws?(url: string): boolean;
+    /** The hosts its built content screens name: a vendor's lane router sends `<base>/@<host>/<path>` for one of them to
+     *  this fetch (pack-fetch.ts). */
+    contentHosts?: ReadonlyArray<string>;
 };
 /** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */
 export type Workspace = {

package/dist/src/events.d.ts

@@ -198,9 +198,20 @@ export type ApplicationAnswer = {
     body: string;
     missed?: 'timeout' | 'unreachable';
 };
+/** Who answers what the vendor asks the application (`ctx.ask`) before the World's application route does, given to a
+ *  pack's fetch (`PackFetchOptions.application`) and belonging to that fetch alone: an answer it gives is the
+ *  application's; `'unreachable'` is a question nobody answers (a walk's life, a sealed World, takes no other); undefined
+ *  is a question it does not take, which goes on as any other does: the application route, the World's egress rule, the
+ *  network. A walk's stand-in answers every question (its life's answers, else unreachable); a hosted World's router
+ *  answers only what it can answer truthfully (WorldDoors.askInWorld) and leaves the rest. */
+export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
+    status: number;
+    body: string;
+} | 'unreachable' | undefined>;
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
- *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds. */
-export declare function askApplication(url: string, init: RequestInit, within: number): Promise<ApplicationAnswer>;
+ *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds, the
+ *  fetch's stand-in first when it was given one (its window the same). */
+export declare function askApplication(url: string, init: RequestInit, within: number, standIn?: ApplicationStandIn): Promise<ApplicationAnswer>;
 /** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
  *  that takes it, and recorded. */
 export declare function deliverEvents(service: string, decl: EventsDecl, write: EventWrite, data: (type: string) => Promise<Record<string, unknown>>, transport?: EventTransport, values?: (type: string) => Promise<Record<string, unknown>>, onAnswer?: (answer: DeliveryAnswer) => Promise<void>): Promise<EventDelivery[]>;

package/dist/src/events.js

@@ -223,8 +223,20 @@ export async function deliverToApplication(url, init) {
     }
 }
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
- *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds. */
-export async function askApplication(url, init, within) {
+ *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds, the
+ *  fetch's stand-in first when it was given one (its window the same). */
+export async function askApplication(url, init, within, standIn) {
+    if (standIn) {
+        let timer;
+        const late = new Promise((done) => { timer = setTimeout(() => done('late'), within); });
+        const stood = await Promise.race([standIn(url, init), late]).finally(() => clearTimeout(timer));
+        if (stood === 'late')
+            return { status: 0, body: '', missed: 'timeout' };
+        if (stood === 'unreachable')
+            return { status: 0, body: '', missed: 'unreachable' };
+        if (stood !== undefined)
+            return stood;
+    }
     const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
         import('../app-route.cjs'),
         import('../network-policy.cjs'),

package/dist/src/file-response.d.ts

@@ -2,8 +2,9 @@
 export declare function contentTypeOf(path: string): string;
 export declare function fileResponse(path: string, init?: ResponseInit): Response;
 /**
- * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range that does not parse, a
- * first-byte-pos past its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed
- * range that starts past the end is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
+ * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
+ * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
+ * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
 export declare function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl?: string): Response;

package/dist/src/file-response.js

@@ -21,9 +21,10 @@ export function fileResponse(path, init) {
     return new Response(readFileSync(path), { ...init, headers });
 }
 /**
- * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range that does not parse, a
- * first-byte-pos past its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed
- * range that starts past the end is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
+ * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
+ * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
+ * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
 export function bytesResponse(request, bytes, contentType, cacheControl = 'public, max-age=604800, immutable') {
     const total = bytes.length;
@@ -43,7 +44,9 @@ export function bytesResponse(request, bytes, contentType, cacheControl = 'publi
         if (start >= total || (range[1] === '' && Number(range[2]) === 0))
             return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
     }
-    const partial = start !== 0 || end !== total - 1;
+    // every satisfiable range is answered as one, the whole body's `bytes=0-` included: a media player (Safari's) reads a
+    // 206 with its Content-Range as the server taking ranges, and a 200 as one it cannot seek in
+    const partial = valid;
     const body = bytes.slice(start, end + 1);
     return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
         status: partial ? 206 : 200,

package/dist/src/index.d.ts

@@ -36,7 +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 { siteLabel, siteUrlOf, 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

@@ -29,7 +29,7 @@ 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 { siteLabel, siteUrlOf, 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,6 +1,7 @@
 import { type DerivedManifest, type Handler, type HandlerContext, type VendorManifest } from './derived-core.js';
 import { type DerivedFetch, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.js';
 import { type PackScenarioAdapter } from './scenario.js';
+import type { ApplicationStandIn } from './events.js';
 import { type SocketEngine } from './sockets.js';
 import { type GraphqlPart } from './graphql-wire.js';
 /** What a pack declares and writes, and nothing it assembles itself. */
@@ -56,6 +57,8 @@ export type LanePart = {
         serves?: (method: string, path: string) => boolean;
         boards?: boolean;
         draws?: (url: string) => boolean;
+        /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
+        contentHosts?: ReadonlyArray<string>;
     };
     manifest: {
         doors?: ReadonlyArray<{
@@ -73,6 +76,8 @@ export type PackFetchOptions = {
     clock?: () => string;
     database?: string;
     scenarioPath?: string;
+    /** the application a walk stands in for (a life's `application` answers): this fetch's `ctx.ask` is answered by it */
+    application?: ApplicationStandIn;
 };
 /** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export declare function createPackFetch(parts: PackParts, options?: PackFetchOptions): DerivedFetch;

package/dist/src/pack-fetch.js

@@ -6,7 +6,7 @@
 // one of them is answered over the contract's context, which the kernel opens: a pack opens none, reads the tree and
 // writes it only through one.
 import { ORIGINAL_PATH_HEADER } from "./sigv4.js";
-import { TWIN_PREFIX_HEADER } from "./twin-fetch.js";
+import { placedCookies, TWIN_PREFIX_HEADER } from "./twin-fetch.js";
 import { PREFIX_PARAMS_HEADER } from "./derived.js";
 import { withHeaders } from "./with-headers.js";
 import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
@@ -17,6 +17,9 @@ import { getActiveWorldStore } from "./world-store.js";
 import { runWithCorrelationId } from "./actions.js";
 import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError } from "./head.js";
 import { withCors } from "./cors.js";
+import { contentAddressOf } from "./content-route.js";
+import { getPack } from "./packRegistry.js";
+import { hostRules } from '../vendor-hosts.cjs';
 import { socketUpgrade } from "./sockets.js";
 import { MACHINE_POOL, POOL_KINDS } from "./machines.js";
 import { applyTwinWrite } from "./serve.js";
@@ -112,6 +115,7 @@ export function createPackFetch(parts, options = {}) {
         ...(options.clock ? { clock: options.clock } : {}),
         ...(options.database !== undefined ? { database: options.database, readOnly: options.readOnly ?? false } : {}),
         ...(parts.tenant ? { tenant: parts.tenant } : {}),
+        ...(options.application ? { application: options.application } : {}),
     };
     // a command table's surface (Redis's, a vendor that carries Redis over HTTP) names no HTTP operation: its wire is the
     // pack's front (its `around`), and the table is the denominator the grade counts
@@ -267,6 +271,78 @@ export function createPackFetch(parts, options = {}) {
     };
     const rootServes = (method, path) => Boolean(matchOperation(routes, method, path));
     const lane = m.lanes ? laneRouter(m.vendor, m.lanes, parts.lanes ?? {}, rootServes) : undefined;
+    // at a World's place, a page's asset or upload on another of the pack's content hosts is `<base>/@<host>/<path>`
+    // (architecture, "A page at a World's place"): answered by the built content screen that names that host exactly,
+    // routed from it, and by nothing else; a request naming no such host is general routing's
+    const contentScreens = screens.filter((s) => s.decl.kind === 'content');
+    for (const s of contentScreens)
+        if (s.decl.yieldsToApi)
+            throw new Error(`${m.vendor}: the content screen ${s.decl.id} declares yieldsToApi; a content screen answers its host's requests alone (architecture, "Screens")`);
+    const contentHosts = [...new Set(contentScreens.flatMap((s) => [s.decl.host, ...(s.decl.hosts ?? [])]).filter((h) => !/[{<]/.test(h)).map((h) => h.toLowerCase()))];
+    const contentNotFound = (host, path) => {
+        const nf = m.notFound;
+        return vendorError(m, { status: nf.status, message: nf.message.replace(/\{object\}/g, host).replace(/\{id\}/g, path), ...(nf.code !== undefined ? { code: nf.code } : {}), ...(nf.kind !== undefined ? { kind: nf.kind } : {}) });
+    };
+    /** A request at a World's place for `/@<host>/<path>`, `<host>` one a built content screen of this unit names exactly:
+     *  that screen's answer, or the pack's not-found for what the host or the screen does not take. The path is held to
+     *  the descriptor's host rules (`rules`: this unit's, or its vendor's for a lane), read as the injector reads them.
+     *  Undefined for any other request. */
+    // the descriptor's host rules: this unit's, or, for a lane (which declares none), its vendor's as registered
+    const descriptorHosts = () => m.descriptor?.hosts ?? getPack(m.vendor)?.hosts;
+    const atContentHost = async (request, rules = descriptorHosts()) => {
+        if (!request.headers.has(TWIN_PREFIX_HEADER))
+            return undefined;
+        const url = new URL(request.url);
+        const address = contentAddressOf(url.pathname);
+        if (!address || !contentHosts.includes(address.host))
+            return undefined;
+        const { host, path: inner } = address;
+        if (address.refused)
+            return contentNotFound(host, inner);
+        const declared = hostRules(rules);
+        if (declared.names(host) && !declared.takes(host, inner))
+            return contentNotFound(host, inner);
+        const onHost = contentScreens.filter((s) => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => h.toLowerCase() === host));
+        const method = request.method.toUpperCase();
+        const allowed = (s) => method === 'GET' || method === 'HEAD' || (method === 'POST' && (s.decl.takes ?? []).includes('POST'));
+        // the request as it reaches the content host, through the pack's own routing of a host (its path prefix and labels)
+        url.pathname = inner;
+        const headers = new Headers(request.headers);
+        headers.set('x-volter-twin-original-host', host);
+        const sent = method === 'POST' && request.body ? { body: request.body, duplex: 'half' } : {};
+        const there = routed(new Request(url, { method, headers, signal: request.signal, ...sent }));
+        const path = new URL(there.url).pathname.replace(/\/+$/, '') || '/';
+        const hit = onHost.map((s) => ({ s, hit: s.path(path) })).find((x) => x.hit && allowed(x.s));
+        if (!hit)
+            return contentNotFound(host, inner);
+        const asked = options.readOnly && !isReadOnlyRequest(there) ? withHeaders(there, new Headers([...there.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : there;
+        if (method === 'POST' && ((options.readOnly ?? false) || isReadOnlyRequest(asked)))
+            return refusedReadOnly();
+        if (parts.clock)
+            await runAsVendorMove(async () => parts.clock(await open(new Request(asked.url, m.tenant ? { headers: asked.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+        return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit.params }));
+    };
+    /** A request as the kernel reads it: the headers only the kernel names taken off, its body decoded (undefined when it
+     *  does not decode as its Content-Encoding says). */
+    const prepared = async (arrived) => {
+        if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
+            const headers = new Headers(arrived.headers);
+            headers.delete(SCENARIO_DECISION_HEADER);
+            headers.delete(PREFIX_PARAMS_HEADER);
+            arrived = new Request(arrived, { headers });
+        }
+        return decoded(m, arrived);
+    };
+    const undecodable = (arrived) => vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+    /** The content route at the request's arrival: the answer, or undefined when this unit's content screens name no such
+     *  host. */
+    const answerContent = async (arrived) => {
+        const address = arrived.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(arrived.url).pathname) : undefined;
+        if (!address || !contentHosts.includes(address.host))
+            return undefined;
+        const readable = await prepared(arrived);
+        return readable ? atContentHost(readable) : undecodable(arrived);
+    };
     const fetch = async (arrived) => {
         // the discovery door is the pack's own, whichever lane would take its path
         const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
@@ -280,19 +356,18 @@ export function createPackFetch(parts, options = {}) {
             const frames = await parts.board(await open(request, 'board', 'GET', '/twin/board', {}));
             return Response.json({ frames: frames.map((f) => ({ ...f, drawn: drawsUrl(f.url) })) });
         }
+        // `<base>/@<host>/<path>` at a World's place, for a host a built content screen of this pack names, is that screen's
+        // alone (only the kernel names a scenario's decision or a path prefix's parameters: `prepared` takes them off); for
+        // one a lane's names, the lane router sends it to that lane's own fetch, wrapped as any request to it is
+        const own = await answerContent(arrived);
+        if (own)
+            return own;
         const toLane = discovery ? undefined : lane?.(arrived);
         if (toLane)
             return toLane(arrived);
-        // only the kernel names a scenario's decision, or a path prefix's parameters
-        if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
-            const headers = new Headers(arrived.headers);
-            headers.delete(SCENARIO_DECISION_HEADER);
-            headers.delete(PREFIX_PARAMS_HEADER);
-            arrived = new Request(arrived, { headers });
-        }
-        const readable = await decoded(m, arrived);
+        const readable = await prepared(arrived);
         if (!readable)
-            return vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+            return undecodable(arrived);
         const incoming = routed(readable);
         // a twin started read-only marks every request so, so every context it opens knows (isReadOnlyRequest)
         const request = options.readOnly && !isReadOnlyRequest(incoming) ? withHeaders(incoming, new Headers([...incoming.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : incoming;
@@ -355,8 +430,10 @@ export function createPackFetch(parts, options = {}) {
         // whichever host the twin is reached (its links carry the twin's own base), never a root screen off its own host
         const host = hostOf(request);
         const exact = (s) => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => !/[{<]/.test(h) && h.toLowerCase() === host);
-        const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit);
         const apiPath = Boolean(matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers));
+        // a screen that yields to the API draws only what no operation names, wherever it would answer (architecture,
+        // "Screens": Hacker News's /login page, whose form posts to POST /login)
+        const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit && !(apiPath && x.s.decl.yieldsToApi));
         // 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);
@@ -421,7 +498,9 @@ export function createPackFetch(parts, options = {}) {
         headers.set('content-type', m.jsonContentType);
         return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
     };
-    const served = m.cors ? withCors(m.cors, labelled) : labelled;
+    const cors = m.cors ? withCors(m.cors, labelled) : labelled;
+    // at a World's place every cookie the twin sets is kept to the twin's base path (twin-fetch.ts, placedCookies)
+    const served = async (request) => placedCookies(request, await cors(request));
     // which paths this pack's API serves, for a vendor's lane router that asks (unlessOnlyRoot)
     const serves = (method, path) => Boolean(matchOperation(routes, method, path));
     // the vendor's sockets: a request to a declared socket's path opens a session of its engine, over a context of the
@@ -434,7 +513,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, workspaces, boards: Boolean(parts.board), draws: drawsUrl, ...(upgrade ? { upgrade } : {}) }));
+    return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, contentHosts, ...(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. */
@@ -470,6 +549,13 @@ function laneRouter(vendor, decl, lanes, rootServes = () => false) {
     });
     const fallback = decl.default !== undefined ? served(decl.default) : undefined;
     return (request) => {
+        // `<base>/@<host>/<path>` at a World's place, for a host a lane's built content screen names, goes to that lane, before
+        // any lane is picked by the request's host or path: its own fetch answers it by its content route, under the vendor's
+        // host rules (architecture, "A page at a World's place")
+        const address = request.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(request.url).pathname) : undefined;
+        const content = address && Object.keys(lanes).find((l) => lanes[l].fetch.contentHosts?.includes(address.host));
+        if (content)
+            return served(content);
         const path = new URL(request.url).pathname.replace(/\/{2,}/g, '/');
         if (path.startsWith('/_twin/')) {
             const door = doors.find((d) => d.method === request.method && d.matches(path));

package/dist/src/runtime.d.ts

@@ -4,7 +4,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
 export { ORIGINAL_PATH_HEADER } from './sigv4.js';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.js';
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, 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

@@ -12,7 +12,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
 export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, 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";