@volter/world-core 3.0.163 → 3.0.164

package/dist/src/browser-session.d.ts

@@ -1,7 +1,13 @@
 import type { HandlerContext } from './derived-core.js';
+import { type Person } from './people.js';
 type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
-/** The named cookie, without interpreting any other vendor's cookie. */
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export declare function cookieOf(request: Request, name: string): string | undefined;
+/** The named session cookie; malformed encodings do not name a session. */
 export declare function browserSessionToken(request: Request, name: string): string | undefined;
+/** The person the request's session cookie names, or undefined when nobody is signed in; with `scope`, only a session
+ *  begun in it (a vendor's sandbox dashboard and its production one sign a person in apart). */
+export declare function signedIn(ctx: HandlerContext, cookie: string, scope?: string): Person | undefined;
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export declare function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string>;
 /** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */

package/dist/src/browser-session.js

@@ -1,18 +1,29 @@
-/** The named cookie, without interpreting any other vendor's cookie. */
-export function browserSessionToken(request, name) {
+import { personOf } from "./people.js";
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export function cookieOf(request, name) {
     for (const part of (request.headers.get('cookie') ?? '').split(';')) {
         const at = part.indexOf('=');
-        if (at > 0 && part.slice(0, at).trim() === name) {
-            try {
-                return decodeURIComponent(part.slice(at + 1).trim());
-            }
-            catch {
-                return undefined;
-            }
-        }
+        if (at > 0 && part.slice(0, at).trim() === name)
+            return decodeURIComponent(part.slice(at + 1).trim());
     }
     return undefined;
 }
+/** The named session cookie; malformed encodings do not name a session. */
+export function browserSessionToken(request, name) {
+    try {
+        return cookieOf(request, name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The person the request's session cookie names, or undefined when nobody is signed in; with `scope`, only a session
+ *  begun in it (a vendor's sandbox dashboard and its production one sign a person in apart). */
+export function signedIn(ctx, cookie, scope) {
+    const token = cookieOf(ctx.call.request, cookie);
+    const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token && (scope === undefined || s.scope === scope)) : undefined;
+    return session ? personOf(ctx, String(session.email)) : undefined;
+}
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export async function startBrowserSession(ctx, email, cookie, scope) {
     const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });

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

@@ -914,7 +914,7 @@ 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) */
+    /** the application a walk stands in for: vendor requests and declared events are answered by it (events.ts) */
     application?: ApplicationStandIn;
 };
 /** World-owned generated values use the same private seed and log as pack secrets. */

package/dist/src/derived-core.js

@@ -623,9 +623,9 @@ function mintId(m, resource, root, at, snapshot) {
  *  increment. One space over every snowflake resource of the vendor, as its one generator's: the instant's first, or one
  *  past the greatest the World holds when that is later (a frozen clock, or several ids in one millisecond), so ids
  *  rise with time and never repeat. */
-/** The last snowflake minted per vendor and World in this process: two mints before the first is written (a message
+/** The last snowflake minted per store, vendor and World: two mints before the first is written (a message
  *  and its attachment) must not meet. */
-const lastSnowflake = new Map();
+const lastSnowflake = new WeakMap();
 function mintSnowflake(m, epoch, root, at, snapshot) {
     const ms = BigInt(Date.parse(at) || 0);
     const base = ms > epoch ? (ms - epoch) << 22n : 0n;
@@ -640,11 +640,13 @@ function mintSnowflake(m, epoch, root, at, snapshot) {
                     max = v;
             }
     }
+    const store = getActiveWorldStore();
+    const reservations = lastSnowflake.get(store) ?? lastSnowflake.set(store, new Map()).get(store);
     const key = `${m.service}\0${root ?? ''}`;
-    const last = lastSnowflake.get(key) ?? -1n;
+    const last = reservations.get(key) ?? -1n;
     const floor = max > last ? max : last;
     const id = base > floor ? base : floor + 1n;
-    lastSnowflake.set(key, id);
+    reservations.set(key, id);
     return String(id);
 }
 /** The next KSUID for a resource (Clerk's and Svix's ids, `ksuidFrom`): the World's instant, then the type's mint
@@ -947,7 +949,7 @@ async function finishWrite(m, call, resource, row, result, operation, params, ro
         const endpoint = (kind) => ({ ...kind, storedAs: storedType(m, kind.storedAs), ...(kind.joins ? { joins: Object.fromEntries(Object.entries(kind.joins).map(([name, join]) => [name, { ...join, storedAs: storedType(m, join.storedAs) }])) } : {}) });
         const events = { ...m.events, ...(m.events.store ? { store: storedType(m, m.events.store) } : {}), endpoints: 'storedAs' in m.events.endpoints ? endpoint(m.events.endpoints) : m.events.endpoints.map(endpoint) };
         const write = { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() };
-        await deliverEvents(m.service, events, write, async (type) => (events.render ? events.render(await context(), write, type) : body), undefined, events.values ? async (type) => events.values(await context(), write, type) : undefined);
+        await deliverEvents(m.service, events, write, async (type) => (events.render ? events.render(await context(), write, type) : body), undefined, events.values ? async (type) => events.values(await context(), write, type) : undefined, scopeOfCall.get(call)?.application);
     }
     if (m.sockets?.length)
         socketWrite(m.service, root, { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() });

package/dist/src/derived-real.js

@@ -682,10 +682,10 @@ function refreshOf(units, service) {
                         const sent = asked.length ? `${target}${target.includes('?') ? '&' : '?'}${new URLSearchParams(asked)}` : target;
                         const answer = await execute({ method: op.method.toUpperCase(), path: sentTo(m, sent, subject), ...onLane, headers: fixedHeaders(op) });
                         // a door's subject the vendor does not show the root (another bot's private chat) stays as the World holds it
-                        if (!rooted.has(key) && answer.status >= 400 && answer.status !== 429)
-                            continue;
                         if (answer.status === 401)
                             throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
+                        if (!rooted.has(key) && answer.status >= 400 && answer.status !== 429)
+                            continue;
                         if (answer.status === 403) {
                             unread.push({ type, path, status: 403 });
                             refused = true;
@@ -700,7 +700,19 @@ function refreshOf(units, service) {
                             continue;
                         if (answer.status >= 400 || refusedIn(m, parse(answer)))
                             throw new Error(`${m.vendor}: ${resource} refresh ${op.id} (${op.method.toUpperCase()} ${op.path}): ${answer.status}: ${refusalWords(m, parse(answer))}`);
-                        const full = object(op.answers?.key ? at(parse(answer), op.answers.key) : parse(answer)) ?? {};
+                        const parsed = parse(answer);
+                        let full;
+                        if (op.answers?.list) {
+                            const items = itemsOf(op, parsed);
+                            const matching = items.find((item) => (scopeIdOf(scope, item) ?? storedIdOf(decl, item)) === vendorId);
+                            if (!matching && items.length)
+                                throw new Error(`${m.vendor}: ${resource} refresh ${op.id} omitted the requested subject; nothing folded`);
+                            if (!matching)
+                                continue;
+                            full = matching;
+                        }
+                        else
+                            full = object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {};
                         const local = m.worldFields?.[resource] ?? {};
                         const fields = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
                         if (decl.parent) {

package/dist/src/events.d.ts

@@ -164,6 +164,8 @@ export declare function eventTypeOf(decl: Pick<EventsDecl, 'types' | 'known'>, o
 /** Whether an endpoint's list of event types takes a type: every type when the list is empty, `*` or `<family>.*`
  *  its patterns, else the type itself. */
 export declare function takesEvent(list: unknown, type: string): boolean;
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export declare function settleEventDeliveries(root: string): Promise<void>;
 /** Who watches signed packets before dispatch (a walk reading each as its receiver would). This is not evidence of
  *  transport or acceptance. Set and restored by the walk, as its World store is; unset, nothing watches. */
 export type DeliveryObserver = (delivery: EventDelivery & {
@@ -179,13 +181,14 @@ 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
+/** Who answers a vendor's requests to the application 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. `bodyError` models a
- *  disconnect after the response headers; a caller needing the complete body receives no complete answer. */
+ *  disconnect after the response headers; a caller needing the complete body receives no complete answer, while an
+ *  event dispatch acknowledges the response status without reading its body. */
 export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
     status: number;
     headers?: Record<string, string>;
@@ -198,4 +201,4 @@ export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
 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>>): Promise<EventDelivery[]>;
+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>>, application?: ApplicationStandIn): Promise<EventDelivery[]>;

package/dist/src/events.js

@@ -7,6 +7,7 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
+import { resolve } from 'node:path';
 import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from "./serve.js";
 import { equalSecrets as same, ksuidFrom } from "./signing.js";
 import { deliveryTraceHeaders } from "./trace-context.js";
@@ -223,6 +224,28 @@ const worldTransport = async (url, body, headers) => {
         return 0;
     }
 };
+const pendingDeliveries = new WeakMap();
+function forgetDeliveries(store, root, deliveries) {
+    const roots = pendingDeliveries.get(store), pending = roots?.get(root);
+    if (!pending)
+        return;
+    for (const delivery of deliveries)
+        pending.delete(delivery);
+    if (!pending.size)
+        roots.delete(root);
+    if (!roots.size)
+        pendingDeliveries.delete(store);
+}
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export async function settleEventDeliveries(root) {
+    const store = getActiveWorldStore(), path = resolve(root);
+    const deliveries = [...(pendingDeliveries.get(store)?.get(path) ?? [])];
+    const outcomes = await Promise.allSettled(deliveries);
+    forgetDeliveries(store, path, deliveries);
+    const failures = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+    if (failures.length)
+        throw new AggregateError(failures, 'Declared-event dispatch failed');
+}
 let deliveryObserver;
 export function setDeliveryObserver(observer) {
     const previous = deliveryObserver;
@@ -266,12 +289,16 @@ export async function askApplication(url, init, within, standIn) {
 }
 /** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
  *  that takes it, and recorded. */
-export async function deliverEvents(service, decl, write, data, transport = worldTransport, values) {
+export async function deliverEvents(service, decl, write, data, transport = worldTransport, values, application) {
     if (write.storedType === decl.store)
         return [];
+    const dispatch = application ? async (url, body, headers) => {
+        const answer = await application(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+        return answer === undefined ? transport(url, body, headers) : answer === 'unreachable' ? 0 : answer.status;
+    } : transport;
     const sent = [];
     for (const type of eventTypesOf(decl, write.operation))
-        sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
+        sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
     return sent;
 }
 /** One event type a write sends: to the live endpoints that take it, stored when the vendor keeps its events. */
@@ -364,11 +391,29 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
     for (const d of sent)
         deliveryObserver?.({ ...d, service });
-    for (const packet of recorded)
-        setTimeout(() => {
-            // Persistence failure leaves a queued/sending claim for explicit recovery;
-            // it must not fail the already-committed vendor write or cause a blind resend.
-            void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => { });
+    const roots = pendingDeliveries.get(store) ?? new Map();
+    pendingDeliveries.set(store, roots);
+    const pending = roots.get(deliveryRoot) ?? new Set();
+    roots.set(deliveryRoot, pending);
+    for (const packet of recorded) {
+        let finish;
+        let fail;
+        const dispatched = new Promise((done, reject) => { finish = done; fail = reject; });
+        // Live writes return before dispatch; an explicit settlement reports persistence failures.
+        void dispatched.catch(() => { });
+        pending.add(dispatched);
+        setTimeout(async () => {
+            try {
+                await withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace));
+                finish();
+                forgetDeliveries(store, deliveryRoot, [dispatched]);
+            }
+            catch (error) {
+                // Keep the rejection until explicit settlement consumes it. The queued/sending claim remains for
+                // native recovery; this must not fail the already-committed vendor write or cause a blind resend.
+                fail(error);
+            }
         }, 0);
+    }
     return sent;
 }

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

@@ -5,6 +5,10 @@ export declare function fileResponse(path: string, init?: ResponseInit): Respons
  * 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.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `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;
+export declare function bytesResponse(request: Request, bytes: Uint8Array | {
+    size: number;
+    range(start: number, end: number): Promise<Uint8Array | null>;
+}, contentType: string, cacheControl?: string): Response;

package/dist/src/file-response.js

@@ -24,10 +24,11 @@ export function fileResponse(path, init) {
  * 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.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `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;
+    const total = bytes instanceof Uint8Array ? bytes.length : bytes.size;
     const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': cacheControl };
     const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
     let start = 0;
@@ -47,9 +48,32 @@ export function bytesResponse(request, bytes, contentType, cacheControl = 'publi
     // 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]), {
+    let body = null;
+    if (request.method !== 'HEAD') {
+        if (bytes instanceof Uint8Array)
+            body = new Blob([bytes.slice(start, end + 1)]);
+        else {
+            let at = start;
+            body = new ReadableStream({
+                async pull(controller) {
+                    if (at > end) {
+                        controller.close();
+                        return;
+                    }
+                    const last = Math.min(at + 8 * 1024 * 1024 - 1, end);
+                    const chunk = await bytes.range(at, last);
+                    if (!chunk) {
+                        controller.error(new Error('stored bytes are gone'));
+                        return;
+                    }
+                    controller.enqueue(chunk);
+                    at = last + 1;
+                },
+            });
+        }
+    }
+    return new Response(body, {
         status: partial ? 206 : 200,
-        headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+        headers: { ...base, 'content-length': String(end + 1 - start), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
     });
 }

package/dist/src/index.d.ts

@@ -67,6 +67,7 @@ export * as protobuf from './protobuf.js';
 export * as grpc from './grpc-wire.js';
 export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.js';
 export { placeholderPng } from './placeholder-image.js';
+export { imageDimensions, readImageHeader, readMp4Header } from './media-header.js';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.js';
 export * as redis from './redis/index.js';
 export * as mysql from './mysql/index.js';
@@ -76,7 +77,7 @@ export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
 export { verifyAttestationBundle } from './attestation.js';
-export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
+export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
 export { readHostPort } from './host-port.js';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.js';
 export * as managedOriginalInputs from './managed-original-inputs.js';

package/dist/src/index.js

@@ -59,6 +59,7 @@ export * as protobuf from "./protobuf.js";
 export * as grpc from "./grpc-wire.js";
 export { acceptH2Connection } from "./h2.js";
 export { placeholderPng } from "./placeholder-image.js";
+export { imageDimensions, readImageHeader, readMp4Header } from "./media-header.js";
 export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
 export * as redis from "./redis/index.js";
 export * as mysql from "./mysql/index.js";
@@ -68,7 +69,7 @@ export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
 export { verifyAttestationBundle } from "./attestation.js";
-export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
+export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
 export { readHostPort } from "./host-port.js";
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost } from "./browser-state.js";
 export * as managedOriginalInputs from "./managed-original-inputs.js";

package/dist/src/managed-database.d.ts

@@ -76,9 +76,11 @@ export declare function managedDatabase(url: string, options?: {
  *  walk/journey-kit.ts), its statements sent as its client sends them: a text alone as one simple Query (a migration
  *  file, a `BEGIN`), a text with values as one extended-protocol statement, the values bind parameters. A transaction it
  *  opens stays open across its statements until it ends it, as on the application's own connection. Each statement's
- *  answer is its results in Postgres's text format, untyped. */
+ *  answer is its results in Postgres's text format, with native column type OIDs retained beside the values. */
 export type DatabaseSession = {
-    query(text: string, values?: ReadonlyArray<string | null>): Promise<StatementResult[]>;
+    query(text: string, values?: ReadonlyArray<string | null>): Promise<Array<StatementResult & {
+        fieldTypes: number[];
+    }>>;
     end(): Promise<void>;
 };
 /** The World's Postgres at `url` as one connection held until `end()`. */

package/dist/src/managed-database.js

@@ -255,6 +255,7 @@ export async function databaseSession(url) {
                 const answer = (await client.query({ text, ...(values === undefined ? {} : { values }), rowMode: 'array', types: raw }));
                 return (Array.isArray(answer) ? answer : [answer]).map((r) => ({
                     fields: (r.fields ?? []).map((f) => f.name),
+                    fieldTypes: (r.fields ?? []).map((f) => f.dataTypeID),
                     rows: r.rows ?? [],
                     command: [r.command ?? '', r.command === 'INSERT' ? '0' : '', r.rowCount ?? ''].filter((part) => part !== '').join(' '),
                 }));

package/dist/src/media-header.d.ts

@@ -0,0 +1,34 @@
+type ImageType = 'image/png' | 'image/gif' | 'image/jpeg' | 'image/webp';
+type Dimensions = {
+    width: number;
+    height: number;
+};
+type ImageHeader = Dimensions & {
+    jpeg?: {
+        frameEnd: number;
+        nonMarkerBytes: boolean;
+        standaloneMarkers: boolean;
+        fillBytes: boolean;
+        shortSegments: boolean;
+    };
+};
+/** Dimensions in a caller-declared image format, or undefined for an incomplete header. */
+export declare function imageDimensions(bytes: Uint8Array, type: ImageType): ImageHeader | undefined;
+/** An image's signature and dimensions, without deciding whether a vendor accepts that format or size. */
+export declare function readImageHeader(bytes: Uint8Array): (ImageHeader & {
+    type: ImageType;
+}) | undefined;
+/** ISO BMFF's bounded top-level boxes and movie headers, with raw duration and 16.16 track dimensions. */
+export declare function readMp4Header(bytes: Uint8Array): {
+    fileType: boolean;
+    hasMediaData: boolean;
+    movies: Array<{
+        headers: Array<{
+            timescale: number;
+            duration: number;
+            payloadSize: number;
+        }>;
+        tracks: Dimensions[];
+    }>;
+};
+export {};

package/dist/src/media-header.js

@@ -0,0 +1,129 @@
+const tag = (bytes, at) => String.fromCharCode(...bytes.subarray(at, at + 4));
+/** Dimensions in a caller-declared image format, or undefined for an incomplete header. */
+export function imageDimensions(bytes, type) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (type === 'image/png')
+        return bytes.length >= 24 ? { width: view.getUint32(16), height: view.getUint32(20) } : undefined;
+    if (type === 'image/gif')
+        return bytes.length >= 10 ? { width: view.getUint16(6, true), height: view.getUint16(8, true) } : undefined;
+    if (type === 'image/webp') {
+        if (bytes.length < 30)
+            return undefined;
+        const chunk = tag(bytes, 12);
+        if (chunk === 'VP8 ')
+            return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+        if (chunk === 'VP8L') {
+            const bits = view.getUint32(21, true);
+            return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >>> 14) & 0x3fff) };
+        }
+        if (chunk === 'VP8X') {
+            const u24 = (at) => bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+            return { width: 1 + u24(24), height: 1 + u24(27) };
+        }
+        return undefined;
+    }
+    let at = 2;
+    const jpeg = { frameEnd: 0, nonMarkerBytes: false, standaloneMarkers: false, fillBytes: false, shortSegments: false };
+    while (at + 4 <= bytes.length) {
+        if (bytes[at] !== 0xff) {
+            jpeg.nonMarkerBytes = true;
+            at += 1;
+            continue;
+        }
+        const marker = bytes[at + 1];
+        if (marker === 0xff) {
+            jpeg.fillBytes = true;
+            at += 1;
+            continue;
+        }
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            jpeg.standaloneMarkers = true;
+            at += 2;
+            continue;
+        }
+        const length = view.getUint16(at + 2);
+        if (length < 2)
+            jpeg.shortSegments = true;
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+            return at + 9 <= bytes.length ? { width: view.getUint16(at + 7), height: view.getUint16(at + 5), jpeg: { ...jpeg, frameEnd: at + 9 } } : undefined;
+        }
+        if (marker === 0xda)
+            return undefined;
+        at += 2 + length;
+    }
+    return undefined;
+}
+/** An image's signature and dimensions, without deciding whether a vendor accepts that format or size. */
+export function readImageHeader(bytes) {
+    let type;
+    if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
+        type = 'image/png';
+    else if (tag(bytes, 0).startsWith('GIF'))
+        type = 'image/gif';
+    else if (bytes[0] === 0xff && bytes[1] === 0xd8)
+        type = 'image/jpeg';
+    else if (tag(bytes, 0) === 'RIFF' && tag(bytes, 8) === 'WEBP')
+        type = 'image/webp';
+    else
+        return undefined;
+    const dimensions = imageDimensions(bytes, type);
+    return dimensions ? { type, ...dimensions } : undefined;
+}
+/** ISO BMFF's bounded top-level boxes and movie headers, with raw duration and 16.16 track dimensions. */
+export function readMp4Header(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    function* boxes(from, to) {
+        let at = from;
+        while (at + 8 <= to) {
+            let size = view.getUint32(at);
+            const type = tag(bytes, at + 4);
+            let header = 8;
+            if (size === 1) {
+                if (at + 16 > to)
+                    return;
+                size = Number(view.getBigUint64(at + 8));
+                header = 16;
+            }
+            if (size === 0)
+                size = to - at;
+            if (!Number.isSafeInteger(size) || size < header || size > to - at)
+                return;
+            yield { type, start: at + header, end: at + size };
+            at += size;
+        }
+    }
+    const result = { fileType: bytes.length >= 8 && tag(bytes, 4) === 'ftyp', hasMediaData: false, movies: [] };
+    for (const box of boxes(0, bytes.length)) {
+        if (box.type === 'mdat' && box.end > box.start)
+            result.hasMediaData = true;
+        if (box.type !== 'moov')
+            continue;
+        const movie = { headers: [], tracks: [] };
+        result.movies.push(movie);
+        for (const child of boxes(box.start, box.end)) {
+            const { type, start, end } = child;
+            if (type === 'mvhd' && start < end) {
+                const version = bytes[start];
+                const payloadSize = end - start;
+                if (version === 0 && payloadSize >= 20)
+                    movie.headers.push({ timescale: view.getUint32(start + 12), duration: view.getUint32(start + 16), payloadSize });
+                if (version === 1 && payloadSize >= 32)
+                    movie.headers.push({ timescale: view.getUint32(start + 20), duration: Number(view.getBigUint64(start + 24)), payloadSize });
+            }
+            if (type !== 'trak')
+                continue;
+            for (const track of boxes(start, end)) {
+                if (track.type !== 'tkhd' || track.start >= track.end)
+                    continue;
+                const version = bytes[track.start];
+                const at = version === 1 ? track.start + 88 : version === 0 ? track.start + 76 : track.end;
+                if (at + 8 > track.end)
+                    continue;
+                const width = view.getUint32(at) / 65536;
+                const height = view.getUint32(at + 4) / 65536;
+                movie.tracks.push({ width, height });
+            }
+        }
+    }
+    return result;
+}

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

@@ -1,5 +1,5 @@
-import { type DerivedManifest, type Handler, type HandlerContext, type ScreenDecl, type VendorManifest } from './derived-core.js';
-import { type DerivedFetch, type DerivedSurface, type BoardFrame } from './derived.js';
+import { type DerivedManifest, type Handler, type HandlerContext, type LanesDecl, type ScreenDecl, type VendorManifest } from './derived-core.js';
+import { compileSurface, type DerivedFetch, type DerivedSurface, type BoardFrame } from './derived.js';
 import { type PackScenarioAdapter } from './scenario.js';
 import type { ApplicationStandIn } from './events.js';
 import { type SocketEngine } from './sockets.js';
@@ -83,13 +83,34 @@ 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 */
+    /** the application a walk stands in for: this fetch's requests and declared events are answered by it */
     application?: ApplicationStandIn;
 };
+/** The host a request is for: the vendor host the World's injector names, else its own. */
+export declare const hostOf: (request: Request) => string;
 /** Where a workspace asked `?show=<type>:<id>` opens the record (architecture, "Workspace"): the built workspace page
  *  that shows that type, its parameter the id; else the one that lists the type; else the workspace's home (its root
  *  page). Every other parameter a page's path names is the asking page's, and a page that cannot be filled is passed
  *  over. Undefined when nothing is asked; the path (with no `show`) otherwise. */
 export declare function shownRecord(url: URL, workspaces: ReadonlyArray<ScreenDecl>, params: Record<string, string>): string | undefined;
+/** A declared World door, matched by the same normalized path for serving and response ownership. */
+export declare function worldDoorMatcher<Door extends {
+    method: string;
+    path: string;
+}>(doors: ReadonlyArray<Door>): (method: string, path: string) => {
+    door: Door;
+    params: Record<string, string>;
+} | undefined;
+/** A request with its path's repeated slashes merged, as a front that merges them routes it (the manifest's
+ *  `mergeSlashes`); one with none is itself. */
+export declare function slashesMerged(request: Request): Request;
+/** The selected unit's request transformation, shared by serving and response judgment. */
+export declare function unitRequestRouter(m: Pick<DerivedManifest, 'pathPrefix' | 'basePathAlias' | 'pathFromHost' | 'hostParams' | 'headerParams'>, surface: DerivedSurface, routes: ReturnType<typeof compileSurface>): (request: Request) => Request;
+/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export declare function createPackFetch(parts: PackParts, options?: PackFetchOptions): DerivedFetch;
+/** The lane selected by the vendor gateway, shared by serving and response judgment. */
+export declare function laneSelector(decl: LanesDecl, lanes: Record<string, {
+    manifest: LanePart['manifest'];
+    fetch: Pick<LanePart['fetch'], 'serves' | 'contentHosts'>;
+}>, rootServes?: (method: string, path: string) => boolean): (request: Request) => string | undefined;
 export declare function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): DerivedFetch;