@ultimat3/cli 29.4.0 → 30.1.0

package/src/client-emit-schemas.ts

@@ -0,0 +1,175 @@
+// The vendor client's `schemas.ts`: every type the operations reach as a TypeScript type AND a `t`
+// schema of the same name, so a vendor's answer is parsed, never cast. Components are declared in
+// dependency order; only a reference back into a cycle is `lazy`, which is how recursion survives.
+
+import type { DocumentNames } from './client-emit-types';
+import { documentNames, parametersType, propertyKey, typeText } from './client-emit-types';
+import type { ClientOperation, ClientType, CompiledDocument } from './openapi-compile-ir';
+
+/** Helpers a document needs only when it has a cycle or a value that is only ever null. */
+const LAZY = `/** A schema read through a getter, so a recursive type can name itself. */
+const lazy = <T>(get: () => Schema<unknown, T>): Schema<unknown, T> =>
+  makeSchema<unknown, T>({ kind: 'unknown' }, (value, path) => {
+    const result = get().safeParse(value);
+    if ('value' in result) return pass(result.value as T);
+    return failWith(result.issues.map((issue) => ({ ...issue, path: [...path, ...(issue.path ?? [])] })));
+  });`;
+const NULL_ONLY = `/** The one value \`null\`. */
+const nullValue: Schema<unknown, null> = makeSchema<unknown, null>({ kind: 'unknown' }, (value, path) =>
+  value === null ? pass(null) : fail(path, 'expected null'),
+);`;
+
+interface Printer {
+  readonly declared: Set<string>;
+  readonly names: DocumentNames;
+  usesLazy: boolean;
+  usesNull: boolean;
+}
+
+/** `t` text for one type. A component not yet declared is reached through `lazy`. */
+export function schemaText(type: ClientType, printer: Printer): string {
+  switch (type.kind) {
+    case 'unknown':
+      return 't.json()';
+    case 'string':
+      return 't.string';
+    case 'number':
+      return type.integer ? 't.number.int()' : 't.number';
+    case 'boolean':
+      return 't.boolean';
+    case 'null':
+      printer.usesNull = true;
+      return 'nullValue';
+    case 'literal':
+      return `t.literal(${JSON.stringify(type.value)})`;
+    case 'array':
+      return `t.array(${schemaText(type.items, printer)})`;
+    case 'record':
+      return `t.record(${schemaText(type.values, printer)})`;
+    case 'object':
+      return `t.object({ ${type.fields
+        .map((field) => {
+          const inner = schemaText(field.type, printer);
+          return `${propertyKey(field.name)}: ${field.required ? inner : `t.optional(${inner})`}`;
+        })
+        .join(', ')} })`;
+    case 'ref': {
+      const name = printer.names.component(type.name);
+      if (printer.declared.has(type.name)) return name;
+      printer.usesLazy = true;
+      return `lazy(() => ${name})`;
+    }
+    case 'union': {
+      const rest = type.members.filter((member) => member.kind !== 'null');
+      const nullable = rest.length < type.members.length;
+      const strings = rest.every((m) => m.kind === 'literal' && typeof m.value === 'string');
+      const inner =
+        rest.length === 0
+          ? undefined
+          : rest.length === 1
+            ? schemaText(rest[0] as ClientType, printer)
+            : strings
+              ? `t.enumerated(${rest.map((m) => (m.kind === 'literal' ? JSON.stringify(m.value) : '')).join(', ')})`
+              : `t.union(${rest.map((member) => schemaText(member, printer)).join(', ')})`;
+      if (inner === undefined) return schemaText({ kind: 'null' }, printer);
+      return nullable ? `t.nullable(${inner})` : inner;
+    }
+  }
+}
+
+/** Component names in an order where each is declared after what it names, cycles aside. */
+function dependencyOrder(types: ReadonlyMap<string, ClientType>): readonly string[] {
+  const order: string[] = [];
+  const state = new Map<string, 'open' | 'done'>();
+  const refs = (type: ClientType): readonly string[] => {
+    switch (type.kind) {
+      case 'ref':
+        return [type.name];
+      case 'array':
+        return refs(type.items);
+      case 'record':
+        return refs(type.values);
+      case 'union':
+        return type.members.flatMap(refs);
+      case 'object':
+        return type.fields.flatMap((field) => refs(field.type));
+      default:
+        return [];
+    }
+  };
+  const visit = (name: string): void => {
+    if (state.has(name)) return;
+    state.set(name, 'open');
+    const type = types.get(name);
+    for (const next of type === undefined ? [] : refs(type)) visit(next);
+    state.set(name, 'done');
+    order.push(name);
+  };
+  for (const name of types.keys()) visit(name);
+  return order;
+}
+
+const opSchema = (op: ClientOperation, part: 'Params' | 'Body' | 'Response'): string =>
+  `${op.name}${part}`;
+
+/** `schemas.ts`, unstamped. */
+export function emitSchemas(document: CompiledDocument): string {
+  const names = documentNames(document);
+  const printer: Printer = { declared: new Set(), names, usesLazy: false, usesNull: false };
+  const body: string[] = [];
+  for (const name of dependencyOrder(document.types)) {
+    const type = document.types.get(name) as ClientType;
+    const id = names.component(name);
+    body.push(`export type ${id} = ${typeText(type, names.component)};`);
+    body.push(`export const ${id}: Schema<unknown, ${id}> = ${schemaText(type, printer)};`);
+    printer.declared.add(name);
+  }
+  for (const op of document.operations) {
+    const types = names.operation.get(op.name);
+    if (types?.request?.text !== undefined) {
+      body.push(`export type ${types.request.name} = ${types.request.text};`);
+    }
+    const params = parametersType(op);
+    if (params !== undefined) {
+      body.push(`export const ${opSchema(op, 'Params')} = ${schemaText(params, printer)};`);
+    }
+    if (op.body !== undefined && op.body.type.kind !== 'ref') {
+      body.push(`export const ${opSchema(op, 'Body')} = ${schemaText(op.body.type, printer)};`);
+    }
+    if (types?.response?.text !== undefined && op.response !== undefined) {
+      const id = types.response.name;
+      body.push(`export type ${id} = ${types.response.text};`);
+      body.push(
+        `export const ${opSchema(op, 'Response')}: Schema<unknown, ${id}> = ${schemaText(op.response, printer)};`,
+      );
+    }
+  }
+  const builders = [
+    ...(printer.usesNull ? ['fail'] : []),
+    ...(printer.usesLazy ? ['failWith'] : []),
+    ...(printer.usesLazy || printer.usesNull ? ['makeSchema', 'pass'] : []),
+    't',
+  ].sort();
+  return [
+    `// The shapes of ${document.title} ${document.version}: each a type and a schema of one name.`,
+    "import type { Schema } from '@ultimat3/schema';",
+    `import { ${builders.join(', ')} } from '@ultimat3/schema';`,
+    '',
+    ...(printer.usesLazy ? [LAZY, ''] : []),
+    ...(printer.usesNull ? [NULL_ONLY, ''] : []),
+    ...body,
+    '',
+  ].join('\n');
+}
+
+/** The schema expression `client.ts` parses one operation's part with, through `S.`. */
+export function opSchemaRef(
+  op: ClientOperation,
+  part: 'Params' | 'Body' | 'Response',
+  names: DocumentNames,
+): string | undefined {
+  if (part === 'Params') return op.parameters.length === 0 ? undefined : `S.${opSchema(op, part)}`;
+  const type = part === 'Body' ? op.body?.type : op.response;
+  if (type === undefined) return undefined;
+  return type.kind === 'ref' ? `S.${names.component(type.name)}` : `S.${opSchema(op, part)}`;
+}

package/src/client-emit-types.ts

@@ -0,0 +1,121 @@
+// `ClientType` to TypeScript type text, and the names both emitters give a document's types —
+// components and the per-operation request and response. One printer for both clients, so the
+// customer's `types.ts` and the vendor's `schemas.ts` cannot describe one document two ways.
+
+import type { ClientOperation, ClientType, CompiledDocument } from './openapi-compile-ir';
+import { typeName } from './openapi-compile-schema';
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** A property key as TypeScript accepts it: bare when it can be, quoted otherwise. */
+export const propertyKey = (name: string): string =>
+  IDENTIFIER.test(name) ? name : JSON.stringify(name);
+
+/** Type text for one value, `ref` naming each component the way its file declares it. */
+export function typeText(type: ClientType, ref: (component: string) => string): string {
+  switch (type.kind) {
+    case 'unknown':
+    case 'string':
+    case 'boolean':
+    case 'null':
+      return type.kind;
+    case 'number':
+      return 'number';
+    case 'literal':
+      return JSON.stringify(type.value);
+    case 'array': {
+      const items = typeText(type.items, ref);
+      return type.items.kind === 'union' ? `(${items})[]` : `${items}[]`;
+    }
+    case 'record':
+      return `Record<string, ${typeText(type.values, ref)}>`;
+    case 'union':
+      return type.members.map((member) => typeText(member, ref)).join(' | ');
+    case 'ref':
+      return ref(type.name);
+    case 'object':
+      if (type.fields.length === 0) return 'Record<string, never>';
+      return `{ ${type.fields
+        .map((field) =>
+          field.required
+            ? `${propertyKey(field.name)}: ${typeText(field.type, ref)}`
+            : `${propertyKey(field.name)}?: ${typeText(field.type, ref)} | undefined`,
+        )
+        .join('; ')} }`;
+  }
+}
+
+/** What an operation's caller passes and gets back, as type text over the document's names. */
+export interface OperationTypes {
+  /** The input's type text; `undefined` when the operation takes nothing. */
+  readonly request?: { readonly name: string; readonly text?: string | undefined } | undefined;
+  /** The answer's type name; `undefined` when a success has no body. */
+  readonly response?: { readonly name: string; readonly text?: string | undefined } | undefined;
+}
+
+export interface DocumentNames {
+  /** Component name → the identifier its type and schema are declared under. */
+  readonly component: (name: string) => string;
+  readonly operation: ReadonlyMap<string, OperationTypes>;
+}
+
+/** The parameters as one object type, or `undefined` when there are none. */
+export function parametersType(operation: ClientOperation): ClientType | undefined {
+  if (operation.parameters.length === 0) return undefined;
+  return {
+    kind: 'object',
+    fields: operation.parameters.map((p) => ({ name: p.name, type: p.type, required: p.required })),
+  };
+}
+
+/**
+ * Every name the document's types take. An operation's request is the body's own name when it is
+ * a component and nothing else rides beside it; otherwise `<Op>Request`, suffixed `Op` until it
+ * clashes with no component — a vendor's `CreateInvoiceRequest` component keeps its name.
+ */
+export function documentNames(document: CompiledDocument): DocumentNames {
+  const taken = new Set([...document.types.keys()].map(typeName));
+  const fresh = (base: string): string => {
+    let name = base;
+    while (taken.has(name)) name = `${name}Op`;
+    taken.add(name);
+    return name;
+  };
+  const component = (name: string): string => typeName(name);
+  const operation = new Map<string, OperationTypes>();
+  for (const op of document.operations) {
+    const pascal = typeName(op.name);
+    const params = parametersType(op);
+    const paramsText = params === undefined ? undefined : typeText(params, component);
+    const body = op.body;
+    let request: OperationTypes['request'];
+    if (body === undefined) {
+      request =
+        paramsText === undefined
+          ? undefined
+          : { name: fresh(`${pascal}Request`), text: paramsText };
+    } else if (body.mode === 'value') {
+      const value = `{ body${body.required ? '' : '?'}: ${typeText(body.type, component)}${body.required ? '' : ' | undefined'} }`;
+      request = {
+        name: fresh(`${pascal}Request`),
+        text: paramsText === undefined ? value : `${paramsText} & ${value}`,
+      };
+    } else if (paramsText === undefined && body.type.kind === 'ref') {
+      request = { name: component(body.type.name) };
+    } else {
+      const bodyText = typeText(body.type, component);
+      request = {
+        name: fresh(`${pascal}Request`),
+        text: paramsText === undefined ? bodyText : `${paramsText} & ${bodyText}`,
+      };
+    }
+    const response =
+      op.response === undefined
+        ? undefined
+        : op.response.kind === 'ref'
+          ? { name: component(op.response.name) }
+          : { name: fresh(`${pascal}Response`), text: typeText(op.response, component) };
+    operation.set(op.name, { request, response });
+  }
+  return { component, operation };
+}

package/src/client-emit-vendor.ts

@@ -0,0 +1,146 @@
+// The vendor client: one async method per operation of a third party's document, each a single
+// `outbound()` call — the caller's wrapper decides `dial` and the deadline. Input is parsed with
+// `t` before a byte leaves; the answer through `answer.json(schema)`, so a renamed field is
+// `X_OUTBOUND_BODY_INVALID` naming it, and a documented non-2xx is outbound's `X_OUTBOUND_REFUSED`.
+
+import { emitSchemas, opSchemaRef } from './client-emit-schemas';
+import type { DocumentNames } from './client-emit-types';
+import { documentNames, propertyKey } from './client-emit-types';
+import type { ClientOperation, CompiledDocument } from './openapi-compile-ir';
+import { typeName } from './openapi-compile-schema';
+
+export interface VendorFiles {
+  readonly 'client.ts': string;
+  readonly 'schemas.ts': string;
+}
+
+const RUNTIME = (
+  pascal: string,
+  vendor: string,
+): string => `/** How this vendor is reached: decided by the app's own wrapper, never by the document. */
+export interface ${pascal}ClientOptions {
+  readonly baseUrl: string;
+  /** \`'public'\` for an internet vendor; \`'named'\` for a host the app names in config. */
+  readonly dial: 'named' | 'public';
+  /** The whole call, retries included. */
+  readonly deadlineMs: number;
+  /** Called before every request: credentials are the app's to store. */
+  readonly headers?:
+    | (() => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>)
+    | undefined;
+  readonly deps?: OutboundDeps | undefined;
+}
+
+export interface CallOptions {
+  readonly signal?: AbortSignal | undefined;
+}
+
+interface CallSpec {
+  readonly method: OutboundMethod;
+  readonly path: string;
+  readonly params: object;
+  readonly pathParams: readonly string[];
+  readonly query: readonly string[];
+  readonly headers: readonly string[];
+  readonly body?: unknown;
+}
+
+const read = (input: object, key: string): unknown =>
+  Object.hasOwn(input, key) ? (input as Readonly<Record<string, unknown>>)[key] : undefined;
+
+function sender(options: ${pascal}ClientOptions) {
+  return async (spec: CallSpec, call: CallOptions) => {
+    let path = spec.path;
+    for (const name of spec.pathParams) {
+      path = path.replace(\`{\${name}}\`, encodeURIComponent(String(read(spec.params, name))));
+    }
+    const url = new URL(\`\${options.baseUrl.replace(/\\/$/, '')}\${path}\`);
+    for (const name of spec.query) {
+      const value = read(spec.params, name);
+      if (value === undefined) continue;
+      for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(name, String(item));
+    }
+    const headers: Record<string, string> = { accept: 'application/json', ...(await options.headers?.()) };
+    for (const name of spec.headers) {
+      const value = read(spec.params, name);
+      if (value !== undefined) headers[name] = String(value);
+    }
+    if (spec.body !== undefined) headers['content-type'] = 'application/json';
+    return outbound(
+      {
+        url,
+        vendor: ${JSON.stringify(vendor)},
+        dial: options.dial,
+        deadlineMs: options.deadlineMs,
+        method: spec.method,
+        headers,
+        ...(spec.body === undefined ? {} : { body: JSON.stringify(spec.body) }),
+        ...(call.signal === undefined ? {} : { signal: call.signal }),
+      },
+      options.deps,
+    );
+  };
+}
+`;
+
+function operationMethod(op: ClientOperation, names: DocumentNames): string {
+  const types = names.operation.get(op.name);
+  const request = types?.request === undefined ? undefined : `S.${types.request.name}`;
+  const response = types?.response === undefined ? 'void' : `S.${types.response.name}`;
+  const params = opSchemaRef(op, 'Params', names);
+  const bodySchema = opSchemaRef(op, 'Body', names);
+  const responseSchema = opSchemaRef(op, 'Response', names);
+  const where = (place: 'path' | 'query' | 'header'): string =>
+    JSON.stringify(op.parameters.filter((p) => p.in === place).map((p) => p.name));
+  const bodyValue =
+    op.body === undefined || bodySchema === undefined
+      ? undefined
+      : op.body.mode === 'value'
+        ? `${bodySchema}.parse(input.body)`
+        : `${bodySchema}.parse(input)`;
+  const optionalBody = op.body?.required === false && op.body.mode === 'value';
+  const body =
+    bodyValue === undefined
+      ? ''
+      : optionalBody
+        ? `\n        body: input.body === undefined ? undefined : ${bodyValue},`
+        : `\n        body: ${bodyValue},`;
+  const doc = op.summary === undefined ? '' : `    /** ${op.summary.replace(/\*\//g, '* /')} */\n`;
+  const input = request === undefined ? 'input: Record<string, never> = {}' : `input: ${request}`;
+  return `${doc}    async ${propertyKey(op.name)}(${input}, call: CallOptions = {}): Promise<${response}> {
+      const answer = await send({
+        method: ${JSON.stringify(op.method)},
+        path: ${JSON.stringify(op.path)},
+        params: ${params === undefined ? '{}' : `${params}.parse(input)`},
+        pathParams: ${where('path')},
+        query: ${where('query')},
+        headers: ${where('header')},${body}
+      }, call);
+      ${responseSchema === undefined ? 'void answer;' : `return answer.json(${responseSchema});`}
+    },`;
+}
+
+/** Both files' text, unstamped. `name` is the vendor label every log line and cause carries. */
+export function emitVendor(name: string, document: CompiledDocument): VendorFiles {
+  const names = documentNames(document);
+  const pascal = typeName(name);
+  const client = [
+    `// The ${name} client, compiled from ${document.title} ${document.version}: one outbound() call per operation.`,
+    "import type { OutboundDeps, OutboundMethod } from '@ultimat3/core/outbound';",
+    "import { outbound } from '@ultimat3/core/outbound';",
+    "import * as S from './schemas';",
+    '',
+    RUNTIME(pascal, name),
+    `/** One method per operation of ${document.title}, named by its \`operationId\`. */`,
+    `export function create${pascal}Client(options: ${pascal}ClientOptions) {`,
+    '  const send = sender(options);',
+    '  return {',
+    ...document.operations.map((op) => operationMethod(op, names)),
+    '  };',
+    '}',
+    '',
+    `export type ${pascal}Client = ReturnType<typeof create${pascal}Client>;`,
+    '',
+  ].join('\n');
+  return { 'client.ts': client, 'schemas.ts': emitSchemas(document) };
+}

package/src/client-errors-routes.ts

@@ -0,0 +1,229 @@
+// Single responsibility: the server half of client error reporting — `GET /x-client-errors.js`
+// and `POST /_client-errors`, which turns one browser report into one `reportError` call with
+// `source: 'browser'`. A framework route like `/_storage`, never an action: it must not appear in
+// OpenAPI or as an MCP tool. Mounted by `x dev` and the container alike, only when enabled.
+
+import type { ClientErrorsConfig } from '@ultimat3/core';
+import {
+  escapeHtml,
+  isJsonObject,
+  proveSameOrigin,
+  readWithinLimit,
+  renderFixShellArg,
+  reportError,
+  UltimateError,
+} from '@ultimat3/core';
+import type { RequestContext, Route, UltimateRequest } from '@ultimat3/http';
+import { HttpError, NO_STORE, selfOrigin } from '@ultimat3/http';
+import type { RouteEntry } from '@ultimat3/render';
+import { routeEntries } from '@ultimat3/render';
+import { t } from '@ultimat3/schema';
+import {
+  CLIENT_ERRORS_LIMITS,
+  CLIENT_ERRORS_PATH,
+  CLIENT_ERRORS_SCRIPT_PATH,
+  clientErrorsScript,
+} from './client-errors-script';
+import { revalidatedResponse } from './revalidated-response';
+
+/** A report is five short strings; 32 KiB is every cap below with room, and nothing more. */
+export const CLIENT_ERRORS_MAX_BODY_BYTES = 32 * 1024;
+
+const KINDS = ['error', 'rejection', 'island'] as const;
+
+/**
+ * A path, never a URL and never a query: a query string is where a token or an email rides. No C0
+ * control or DEL either: the path lands in `scope.extra`, and a monitor or a terminal renders it.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the class REFUSES them, by design.
+const PATH = /^\/[^?#\s\x00-\x1f\x7f]*$/;
+
+/** An island's id is `islandModuleId`'s `[a-z0-9-]`; anything else did not come from a page. */
+const ISLAND = /^[a-z0-9-]+$/;
+
+const REPORT = t.object({
+  kind: t.enumerated(...KINDS),
+  message: t.string.max(CLIENT_ERRORS_LIMITS.message),
+  path: t.string.max(CLIENT_ERRORS_LIMITS.path).pattern(PATH),
+  build: t.string.max(CLIENT_ERRORS_LIMITS.build),
+  stack: t.string.max(CLIENT_ERRORS_LIMITS.stack).optional(),
+  island: t.string.min(1).max(CLIENT_ERRORS_LIMITS.island).pattern(ISLAND).optional(),
+});
+
+/** CLOSED: the schema drops an unknown key, and a report shape that grows quietly is not closed. */
+const KEYS: ReadonlySet<string> = new Set(Object.keys(REPORT.shape));
+
+/** The page facts the operation is resolved from — `routeEntries()`, or a test's list. */
+export type ClientErrorPage = Pick<RouteEntry, 'path' | 'surface' | 'pattern' | 'islands'>;
+
+export interface ClientErrorsRouteOptions {
+  readonly pages?: () => readonly ClientErrorPage[];
+}
+
+const refused = (pathname: string, why: string): HttpError =>
+  new HttpError({
+    code: 'X_BODY_INVALID',
+    cause: `${pathname} refused a client error report: ${why}`,
+    fix: "reportError(error, { source: 'http' }) from @ultimat3/core for a server-side failure — this route takes only the shape /x-client-errors.js sends from an app/ page",
+  });
+
+/**
+ * Same-origin PROVEN, stricter than the pipeline's `csrf` stage: that one lets an anonymous request
+ * with no browser evidence through as a webhook, and this route has no webhook caller. A cross-site
+ * page must not file through a signed-in browser, and a script with no headers is not a browser.
+ */
+function assertSameOrigin(request: UltimateRequest, ctx: RequestContext): void {
+  const verdict = proveSameOrigin({
+    selfOrigins: [selfOrigin(ctx.url, ctx.https)],
+    origin: request.header('origin'),
+    secFetchSite: request.header('sec-fetch-site') || null,
+    listed: () => false,
+    listName: "the app's own origin",
+  });
+  if (verdict.ok) return;
+  throw new HttpError({
+    code: 'X_CSRF_BLOCKED',
+    cause: `${ctx.url.pathname} refused a client error report it could not show came from this app: ${verdict.reason}`,
+    fix: "fetch('/_client-errors', { method: 'POST', credentials: 'same-origin' }) from a page served on this same origin — /x-client-errors.js on an app/ document does exactly that; a request with neither sec-fetch-site nor Origin is refused",
+  });
+}
+
+/** The parsed report, or the refusal naming what was wrong — never the body echoed back. */
+async function reportOf(request: UltimateRequest, pathname: string) {
+  const read = await readWithinLimit(request.raw.body, CLIENT_ERRORS_MAX_BODY_BYTES);
+  if ('over' in read) {
+    throw refused(pathname, `the body is over ${CLIENT_ERRORS_MAX_BODY_BYTES} bytes`);
+  }
+  let body: unknown;
+  try {
+    body = JSON.parse(new TextDecoder().decode(read.bytes));
+  } catch {
+    throw refused(pathname, 'the body is not JSON');
+  }
+  if (!isJsonObject(body)) throw refused(pathname, 'the body is not a JSON object');
+  const unknown = Object.keys(body).filter((key) => !KEYS.has(key));
+  if (unknown.length > 0) {
+    throw refused(pathname, `${unknown.length} key(s) outside ${[...KEYS].join(', ')}`);
+  }
+  const parsed = REPORT.safeParse(body);
+  if (parsed.issues !== undefined) {
+    const where = parsed.issues.map((issue) => issue.path?.map(String).join('.') ?? '').join(', ');
+    throw refused(pathname, `field(s) out of shape: ${where}`);
+  }
+  return parsed.value;
+}
+
+/**
+ * The grouping facet: the page PATTERN, plus the island id only when this build serves it. The id
+ * is the browser's to choose, and an invented one per report would be a new fingerprint group per
+ * report — so a report naming an island no page declares is filed (`meta.island`) with NO
+ * operation, one group for every such report.
+ */
+function operationOf(
+  pages: readonly ClientErrorPage[],
+  path: string,
+  island: string | undefined,
+): string | undefined {
+  const pattern = patternOf(pages, path);
+  if (pattern === undefined || island === undefined) return pattern;
+  return pages.some((page) => page.islands.includes(island)) ? `${pattern} ${island}` : undefined;
+}
+
+/** The most specific `app/` page the path names — the PATTERN, the one bounded grouping facet. */
+function patternOf(pages: readonly ClientErrorPage[], path: string): string | undefined {
+  let best: ClientErrorPage | undefined;
+  for (const page of pages) {
+    if (page.surface !== 'app' || !page.pattern.regex.test(path)) continue;
+    if (best === undefined || page.pattern.specificity > best.pattern.specificity) best = page;
+  }
+  return best?.path;
+}
+
+export function clientErrorsRoutes(
+  config: ClientErrorsConfig,
+  options: ClientErrorsRouteOptions = {},
+): readonly Route[] {
+  const pages = options.pages ?? routeEntries;
+  const source = clientErrorsScript();
+  return [
+    {
+      method: 'GET',
+      path: CLIENT_ERRORS_SCRIPT_PATH,
+      meta: { name: 'clientErrors.script', auth: 'public' },
+      // No content hash in the URL — every `app/` document names it — so revalidated, as
+      // `/x-sw-register.js` is: a changed script reaches a returning tab on its next load.
+      handler: (request) => revalidatedResponse(request, source, 'text/javascript; charset=utf-8'),
+    },
+    {
+      method: 'POST',
+      path: CLIENT_ERRORS_PATH,
+      meta: {
+        name: 'clientErrors.report',
+        // `required` unless the app opened the door: the pipeline answers an anonymous caller 401.
+        auth: config.anonymous ? 'public' : 'required',
+        cache: NO_STORE,
+        // The pipeline's `rate-limit` stage spends it, per actor or (anonymous) per address, on the
+        // app's own store — fleet-wide when the app declared `scope: 'shared'`, never a second one.
+        rateLimit: 'clientErrors.report',
+        rateLimitBucket: { capacity: config.perMinute, refillPerSecond: config.perMinute / 60 },
+      },
+      handler: async (request, ctx) => {
+        assertSameOrigin(request, ctx);
+        const report = await reportOf(request, ctx.url.pathname);
+        const operation = operationOf(pages(), report.path, report.island);
+        const error = new UltimateError({
+          code: 'X_CLIENT_ERROR',
+          cause: report.message === '' ? `a ${report.kind} with no message` : report.message,
+          fix: `x shot ${renderFixShellArg(report.path, '<route>')} --json`,
+          meta: {
+            clientBuild: report.build,
+            kind: report.kind,
+            ...(report.island === undefined ? {} : { island: report.island }),
+          },
+        });
+        // The BROWSER's stack is the report's; the one this line just captured is the server's.
+        Object.defineProperty(error, 'stack', { value: report.stack, configurable: true });
+        reportError(error, {
+          source: 'browser',
+          scope: {
+            // Pattern plus island: `errorFingerprint` groups on it, so one island's fault is one
+            // group on every `/posts/:id`, and two islands on one page are two.
+            ...(operation === undefined ? {} : { operation }),
+            extra: { path: report.path },
+          },
+        });
+        return new Response(null, { status: 204 });
+      },
+    },
+  ];
+}
+
+/** The tag an `app/` document carries: the build it was rendered BY, so a stale tab says so. */
+export const clientErrorsHead = (buildId: string): string =>
+  `<script src="${CLIENT_ERRORS_SCRIPT_PATH}" data-build="${escapeHtml(buildId)}" defer></script>`;
+
+export interface ClientErrorsSurface {
+  readonly routes: readonly Route[];
+  /** For `DocumentOptions.appHead`: `app/` documents only — `site/` never pays for it. */
+  readonly head: string;
+}
+
+/** What a boot mounts for `app.config.ts`'s `clientErrors`: nothing at all unless enabled. */
+export function clientErrorsSurface(
+  config: ClientErrorsConfig | undefined,
+  buildId: string,
+): ClientErrorsSurface | undefined {
+  if (config?.enabled !== true) return undefined;
+  return { routes: clientErrorsRoutes(config), head: clientErrorsHead(buildId) };
+}
+
+/**
+ * A static export runs no route table, so there is nothing to receive a report: no document names
+ * the script, and the build SAYS so — `originWarning`'s shape, into the report's `warnings`.
+ */
+export function clientErrorsStaticWarning(config: ClientErrorsConfig | undefined): string[] {
+  if (config?.enabled !== true) return [];
+  return [
+    'clientErrors.enabled is true and a static export serves no /_client-errors route, so no exported document names /x-client-errors.js — serve the app (x dev, or the container) for browser reports',
+  ];
+}