@jimhoyd/urlcode 0.4.1 → 0.4.6

package/dist/types/config.d.ts

@@ -1,4 +1,5 @@
-import type { LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
+import type { ErrorObject } from 'ajv';
+import type { LoadedDocument, ProjectDocument, RouteConfig, SharedBlock } from './types.ts';
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
 export type ConfigWorkerResult = {
     value: LoadedDocument;
@@ -10,7 +11,14 @@ export interface ConfigWorkerData {
 }
 export declare const MAX_CONFIG_BYTES: number;
 export declare function parseYaml(text: string): unknown;
-export declare function validateDocument(data: unknown): ProjectDocument;
+/**
+ * One line for the first schema violation. Closed-key-set failures name the offending key and the keys the
+ * schema allows, and required failures name the missing key, because a bare keyword sends the reader hunting.
+ * Only key names, which come from the schema or the author's own mapping keys, are echoed, never values
+ * (values may hold secrets), and never more than MAX_NAMED_KEY characters of a key.
+ */
+export declare function describeSchemaError(e: ErrorObject): string;
+export declare function validateDocument(data: unknown, inherited?: Record<string, SharedBlock>): ProjectDocument;
 /** The input declaration a short-form function gets for each `{param}` it does not declare itself. */
 export declare const SHORT_FORM_PATH_SCHEMA: {
     readonly type: "string";

package/dist/types/context.d.ts

@@ -62,5 +62,5 @@ export declare function estimateTokens(text: string): number;
 export declare function renderContext(context: ProjectContext): string;
 /** Derived only from the compiled project and the capability catalog, never from prose. Key order is fixed. */
 export declare function buildContext(project: string, options?: ContextOptions): Promise<ProjectContext>;
-/** Estimated size of the shipped documentation (docs/*.md and llms.txt), for comparison with an emitted context. */
+/** Estimated size of the shipped offline documentation bundle, for comparison with an emitted context. */
 export declare function documentationTokens(): Promise<number>;

package/dist/types/errors.d.ts

@@ -2,6 +2,14 @@ export declare class ConfigError extends Error {
 }
 export declare class HttpError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** A pre-rendered, fixed-content answer that replaces the plain-text message (used for negotiated 422 bodies). */
+    readonly answer: {
+        contentType: string;
+        text: string;
+    } | undefined;
+    constructor(status: number, message: string, answer?: {
+        contentType: string;
+        text: string;
+    });
 }
 export declare function assert(condition: unknown, message: string): asserts condition;

package/dist/types/examples.d.ts

@@ -31,7 +31,7 @@ export interface ExampleSearchResult {
         matchedRoutes: RouteIndexEntry[];
     })[];
 }
-export declare const exampleNames: readonly ["assets", "aws", "cloudflare", "compliance", "conditions", "cookbook", "egress", "extensions", "monitoring", "prerender", "provider-conformance", "tunnel", "vercel"];
+export declare const exampleNames: readonly ["assets", "aws", "body-validation", "cloudflare", "compliance", "conditions", "cookbook", "coverage-waiver", "data-dir", "egress", "extensions", "lifecycle", "monitoring", "not-found", "prerender", "provider-conformance", "shared-blocks", "tunnel", "vercel"];
 export declare const routeIndexFile = "route-index.json";
 export declare function listExamples(): Promise<ExampleSummary[]>;
 /**

package/dist/types/extensions.d.ts

@@ -66,6 +66,83 @@ export interface ExtensionInstance {
 export interface ExtensionImmutableAssets {
     prefix: string;
 }
+export interface ExtensionHookReference {
+    source: string;
+    export?: string;
+    sandbox?: boolean;
+    sandboxReason?: string;
+}
+export type ExtensionHookConfig = string | ExtensionHookReference;
+export type ExtensionHookKind = 'filter' | 'action';
+/** Machine-readable contract for one project hook an extension exposes. */
+export interface ExtensionHookContract {
+    name: string;
+    kind: ExtensionHookKind;
+    description: string;
+    inputSchema: object;
+    outputSchema?: object;
+}
+export type ExtensionAuthoringKind = 'configuration' | 'theme' | 'copy' | 'component' | 'template' | 'stylesheet' | 'hook' | 'extension';
+/** One project-owned customization surface, shown to people and authoring agents by CLI/MCP inspection. */
+export interface ExtensionAuthoringSurface {
+    kind: ExtensionAuthoringKind;
+    name: string;
+    description: string;
+    /** Project-relative convention or configuration path, when the surface has one. */
+    path?: string;
+    /** A bounded local command that discovers, previews or checks the surface. */
+    command?: string;
+}
+/**
+ * Machine-readable guidance for changing an installed extension without
+ * copying its behavior into the application. This is descriptive only: it
+ * grants nothing and is never executed by the runtime.
+ */
+export interface ExtensionAuthoringContract {
+    description: string;
+    surfaces: readonly ExtensionAuthoringSurface[];
+    fastChecks?: readonly string[];
+}
+export type LoadedExtensionHooks<T extends string = string> = Partial<Record<T, (input: unknown) => unknown>>;
+/** Shared schema for project hook references. Omission means trusted execution. */
+export declare const extensionHookReferenceSchema: {
+    readonly oneOf: readonly [{
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly maxLength: 1024;
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["source"];
+        readonly properties: {
+            readonly source: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            };
+            readonly export: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+            };
+            readonly sandbox: {
+                readonly type: "boolean";
+            };
+            readonly sandboxReason: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+        };
+    }];
+};
+/** Builds the strict `config.hooks` schema from an extension's declared hook names. */
+export declare function extensionHooksSchema(contracts: readonly ExtensionHookContract[]): object;
+/**
+ * Loads project hooks once per activation. Project hooks are trusted first-party
+ * code by default, matching function/middleware routes. Sandboxed arbitrary-value
+ * hooks are not part of contract v1 and are refused rather than run trusted.
+ */
+export declare function loadExtensionHooks<T extends string>(config: Readonly<Record<string, unknown>> | undefined, contracts: readonly ExtensionHookContract[], context: Pick<ExtensionActivation, 'root'>): Promise<LoadedExtensionHooks<T>>;
 export interface RuntimeExtension {
     name: string;
     version: '1';
@@ -75,6 +152,10 @@ export interface RuntimeExtension {
     policySchema?: object;
     credentialHeaders?: string[];
     immutableAssets?: ExtensionImmutableAssets;
+    /** Project customization points, exposed by CLI/MCP for authors and agents. */
+    hooks?: readonly ExtensionHookContract[];
+    /** Supported project-owned customization surfaces, exposed by CLI/MCP. */
+    authoring?: ExtensionAuthoringContract;
     /**
      * Reviewed, operator-declared cache sensitivity for `policies.extensions.<name>`
      * routes (never for an `extension:` mount, which is always treated as
@@ -102,8 +183,15 @@ export interface ScaffoldRequest {
     project: string;
     /** Absolute path of the combined host module core writes, `<directory>/host.mjs`. */
     hostFile: string;
-    /** Every extension name being scaffolded together, in `--with` order, including this one. */
+    /** Every extension name being scaffolded together, including this one, in a canonical (sorted) order that is independent of the `--with` spelling. */
     names: readonly string[];
+    /**
+     * Operator acknowledgements from repeated `--ack <extension>:<id>` flags, sorted and de-duplicated; empty when none. Core treats
+     * them as opaque strings and never invents one. An extension reads only the ones qualified with its own name. To require one, throw
+     * an Error carrying `acknowledgement: '<name>:<id>'` whose message states the risk; core appends the exact re-run command with
+     * `--ack <name>:<id>`. List each one the scaffold used in `ScaffoldResult.acknowledged`.
+     */
+    acknowledgements: readonly string[];
 }
 export interface ScaffoldFile {
     path: string;
@@ -113,6 +201,21 @@ export interface ScaffoldFile {
 export interface ScaffoldResult {
     /** Must equal the requested name. */
     name: string;
+    /**
+     * Declarative composition contract; `--with` is an unordered set and core derives the host, activation and README order from these.
+     * `provides`: capability names this extension offers (a name must not equal an extension name). `requires`: extensions or
+     * capabilities that must be in the set and are placed before this one; a missing one refuses. `after`: the same ordering
+     * without requiring presence. `conflicts`: extensions or capabilities that must not be in the set. A cycle refuses. Core never
+     * adds an extension or infers policy from these lists.
+     */
+    provides?: string[];
+    requires?: string[];
+    after?: string[];
+    conflicts?: string[];
+    /** The `<name>:<id>` acknowledgements this scaffold consumed. Core refuses any passed `--ack` that no scaffold lists here, so an acknowledgement cannot be passed with no effect. */
+    acknowledged?: string[];
+    /** One-line notes written as comments above this extension's routes in the route fragment (for example the selected access model). */
+    routeNotes?: string[];
     /** Fragments merged into the project's top-level `extensions` and `routes`; duplicate keys are refused. */
     extensions: Record<string, unknown>;
     routes: Record<string, unknown>;
@@ -123,7 +226,7 @@ export interface ScaffoldResult {
     hostClose?: string[];
     /** Files written relative to `directory` with their modes; never inside the project, never overwriting. */
     files: ScaffoldFile[];
-    /** Markdown appended to README.md under a heading core adds; the numbered steps merged in `--with` order. */
+    /** Markdown appended to README.md under a heading core adds; the numbered steps merged in the resolved order. */
     readme: string;
     nextSteps: string[];
     /** Environment variables the host reads, with one-line descriptions. */

package/dist/types/http-policy.d.ts

@@ -1,5 +1,6 @@
 import type { HandlerResult, HeaderPair } from './http-response.ts';
 import type { HeadersLike } from './match.ts';
+import type { BodySchema } from './body-schema.ts';
 export interface RespondSpec {
     status?: number;
     json?: unknown;
@@ -10,6 +11,7 @@ export interface RequestBodyPolicy {
     required?: boolean;
     contentTypes?: string[];
     format?: 'json' | 'text';
+    schema?: BodySchema;
 }
 /** A static reply compiled from `respond`; the body is bytes so every host, including the Worker, shares the type. */
 export interface Reply {
@@ -32,6 +34,7 @@ export interface HttpRoute {
     responseHeaders?: HeaderPair[];
     reply?: Reply | undefined;
 }
+export declare const reservedResponseHeaders: Set<string>;
 export declare function compileHttp(route: HttpRoute): void;
 export declare function checkRequest(route: HttpRoute, body: Uint8Array, headers: HeadersLike, counts?: Record<string, number>): void;
 export declare function decorateResponse(route: HttpRoute & {

package/dist/types/init-with.d.ts

@@ -1,3 +1,4 @@
+import type { ScaffoldResult } from './extensions.ts';
 import type { DependencyPin } from './project-dependencies.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
@@ -5,6 +6,8 @@ export interface InitWithOptions {
     manifest?: boolean | undefined;
     /** `--pin <package>=<specifier>` overrides, for local tarballs, checkouts and mirrors. */
     pins?: ReadonlyMap<string, string> | undefined;
+    /** `--ack <extension>:<id>`, repeatable: opaque qualified acknowledgements handed to every scaffold. Core refuses one that no scaffold consumed. */
+    acknowledgements?: readonly string[] | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -16,9 +19,15 @@ export interface InitWithResult {
     dependencies: DependencyPin[];
 }
 export declare function parseWithNames(value: string): string[];
+/**
+ * Orders the requested set from the scaffolds' declared `requires`, `after`, `provides` and `conflicts`, never from
+ * the `--with` spelling. Kahn's algorithm with the lexically smallest ready extension first, so the result is
+ * deterministic and identical for every permutation. Refuses a missing requirement, a conflict or a cycle by name.
+ */
+export declare function orderScaffolds(results: readonly ScaffoldResult[]): ScaffoldResult[];
 /**
  * `urlcode init <directory> --with a,b`: the starter under `app/`, every extension's fragments merged into one
  * `urlcode.yaml`, one `host.mjs`, one `README.md` and the extensions' own files. All packages are resolved and
  * their scaffolds computed before anything is written, so a refusal leaves no directory behind.
  */
-export declare function initProjectWith(destination: string, names: readonly string[], { cwd, manifest, pins }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements }?: InitWithOptions): Promise<InitWithResult>;

package/dist/types/pattern-guard.d.ts

@@ -0,0 +1,10 @@
+export declare const maxPatternLength = 128;
+export declare const maxPatternInputLength = 128;
+/**
+ * Accepts an author regex only when it is conservatively safe to run on every
+ * request in the host process. Node has no linear-time engine, so this refuses
+ * the constructs that make backtracking blow up — repeated groups, lookaround
+ * and backreferences — and caps unbounded quantifiers. It is a restriction, not
+ * a proof: callers must also bound the input length to `maxPatternInputLength`.
+ */
+export declare function assertSafePattern(pattern: string): void;

package/dist/types/project-tests.d.ts

@@ -1,4 +1,5 @@
 import type { ServerOptions } from './server.ts';
+import type { RestartableApp } from './readiness.ts';
 import type { LogFn } from './types.ts';
 export interface ProjectTestOptions {
     extensions?: ServerOptions['extensions'];
@@ -11,4 +12,12 @@ export interface ProjectTestResult {
     total: number;
     failed: number;
 }
+/**
+ * A server that fixture `restart` steps can close and start again on the same project and the
+ * same data directory. The data directory is fresh and empty, offered to the project as
+ * `URLCODE_DATA_DIR`, and removed by `close()`; on a filesystem where it cannot be created, none is offered. `restart()` gets a new port; read `address` after it.
+ */
+export declare function startRestartable(options: ServerOptions): Promise<RestartableApp & {
+    close(): Promise<void>;
+}>;
 export declare function runProjectTests(project: string, { log, permissions, origin, extensions, plugins }?: ProjectTestOptions): Promise<ProjectTestResult>;

package/dist/types/readiness.d.ts

@@ -23,17 +23,38 @@ export interface RequestCase {
     body?: string | undefined;
     expectHeaders?: Record<string, string> | undefined;
     expectBody?: string | undefined;
+    /** Only inside `steps`: values kept from this step's response for later steps' `{{name}}` references. */
+    capture?: Record<string, CaptureSpec> | undefined;
 }
+/** Where a captured value comes from: a dotted path into a JSON response body, or one response header. */
+export type CaptureSpec = {
+    json: string;
+} | {
+    header: string;
+};
+/** A step that closes and restarts the runtime on the same project and data directory. */
+export interface RestartStep {
+    restart: true;
+}
+/** An ordered fixture: requests that share captured values, optionally with restarts between them. */
+export interface StepsFixture {
+    steps: (RequestCase | RestartStep)[];
+}
+export type Fixture = RequestCase | StepsFixture;
+export declare const isStepsFixture: (fixture: Fixture) => fixture is StepsFixture;
+export declare const isRestartable: (app: AuditableApp) => app is RestartableApp;
 export interface ProjectPlan {
     inventory: RouteInventory[];
     cases: RequestCase[];
     resolve: (path: string) => string | undefined;
 }
+/** `captured` holds values from a step's `capture`; callers use it for substitution only and never print it. */
 export interface HitResult {
     pass: boolean;
     status: number;
     durationMs: number;
     error?: string;
+    captured?: Record<string, string>;
 }
 export interface BenchmarkTarget {
     protocol: string;
@@ -48,6 +69,10 @@ export interface AuditableApp {
         policies?: Record<string, PolicyInventory>;
     };
 }
+/** An app that can also close and restart itself on the same project and data directory (fixture `restart` steps). */
+export interface RestartableApp extends AuditableApp {
+    restart(): Promise<void>;
+}
 export type { ComplianceOptions, ComplianceReport } from './compliance.ts';
 export interface AuditOptions {
     expectRoutes?: number | undefined;
@@ -57,8 +82,15 @@ export interface AuditOptions {
 export interface AuditReport {
     elapsedMs: number;
     ready: boolean;
+    /** Empty when `ready`; otherwise one stable code per failed condition:
+     * `no-active-routes`, `route-count-mismatch`, `failed-checks`, `uncovered-route-methods`. */
+    notReadyReasons: string[];
+    /** `configured` is every route in the table, including routes generated from `site` keys; `--expect-routes` compares against it.
+     * `declared` + `generated` always equals `configured`. */
     counts: {
         configured: number;
+        declared: number;
+        generated: number;
         active: number;
         disabled: number;
         expired: number;
@@ -75,6 +107,24 @@ export interface AuditReport {
         route: string;
         method: string;
     }[];
+    /** Route/method pairs excused by a `coveredElsewhere` waiver, with the reason. Shown even when `ready`. */
+    waivedRouteMethods: {
+        route: string;
+        method: string;
+        reason: string;
+    }[];
+    /** Waivers not honored (the route has no normally covered method, e.g. an error-only function route); their pairs stay in `uncovered`. */
+    ignoredWaivers: {
+        route: string;
+        method: string;
+        reason: string;
+    }[];
+    /** Waivers whose pair already has a passing normal-response fixture: remove them. Never blocks `ready`. */
+    redundantWaivers: {
+        route: string;
+        method: string;
+        reason: string;
+    }[];
     policies: Record<string, PolicyInventory>;
     compliance: ComplianceReport | null;
     /** Non-blocking `audit` observations, e.g. a route that looks webhook-shaped
@@ -123,7 +173,28 @@ export declare const hasRedirect: (route: CompiledRoute) => route is CompiledRou
 };
 export declare const probeAgent = "Mozilla/5.0 (compatible; RouteProbe/0.1)";
 export declare function projectPlan(compiled: CompiledRoutes<CompiledRoute>): ProjectPlan;
+export declare function readFixtures(root: string, optional?: boolean): Promise<Fixture[]>;
+/** Single-request fixtures only: the benchmark replays these and cannot run ordered steps. */
 export declare function readCases(root: string, optional?: boolean): Promise<RequestCase[]>;
+/** One request a fixture run sent: `test` is the request as sent (captured values filled in), `original` as written. Print `original`, never `test`. */
+export interface FixtureStep {
+    case: number;
+    fixture: number;
+    test: RequestCase;
+    original: RequestCase;
+    result: HitResult;
+}
+export interface FixtureHost {
+    app: AuditableApp;
+    agent: Agent;
+    target?: BenchmarkTarget | undefined;
+    /** Close and restart the runtime on the same project and data directory. Absent: the host cannot restart. */
+    restart?: (() => Promise<void>) | undefined;
+    /** Called with the 1-based fixture number and a reason when a fixture with a restart step is skipped because the host cannot restart. Absent: such a fixture is refused with an error. */
+    skipped?: ((fixture: number, reason: string) => void) | undefined;
+}
+/** Runs every fixture in file order. A step after a failed step in the same fixture is reported failed with error `skipped` and never sent, so a broken chain cannot pass. */
+export declare function runFixtures(fixtures: Fixture[], host: FixtureHost, visit: (step: FixtureStep) => void | Promise<void>, firstCase?: number): Promise<void>;
 export declare function benchmarkTarget(value: string): BenchmarkTarget;
 export declare function hit(app: AuditableApp, test: RequestCase, agent: Agent, target?: BenchmarkTarget): Promise<HitResult>;
 export declare function auditProject(app: AuditableApp, { expectRoutes, log, compliance }?: AuditOptions): Promise<AuditReport>;

package/dist/types/recipes.d.ts

@@ -20,7 +20,7 @@ export interface RecipeSearchResult {
         matched: string[];
     })[];
 }
-export declare const recipeNames: readonly ["redirect", "json-api", "typescript", "middleware", "health-page", "static-plus-api", "cors-api", "webhook-receiver", "contact-form", "authenticated-json-api", "protected-download"];
+export declare const recipeNames: readonly ["redirect", "json-api", "typescript", "middleware", "health-page", "static-page", "static-plus-api", "cors-api", "webhook-receiver", "contact-form", "authenticated-json-api", "protected-download", "store-crud"];
 export declare function listRecipes(): Promise<RecipeSummary[]>;
 /** Matches id, description, tags and capabilities locally; no service is consulted. */
 export declare function searchRecipes(text: string): Promise<RecipeSearchResult>;

package/dist/types/runtime.d.ts

@@ -34,6 +34,10 @@ export interface RuntimeOptions {
      * whole project denies every binding it grants. Prerendering uses it to render a
      * project too large for one function snapshot in passes (docs/PRERENDER.md). */
     only?: readonly string[] | undefined;
+    /** Test harness only (set by `startServer` when it is given a data directory): also grant every
+     * route's `{env: URLCODE_DATA_DIR}` binding, and only that name, for this project revision. The value
+     * is the harness's own directory, not an ambient secret. Never supplied by project YAML or guest code. */
+    grantDataDir?: boolean | undefined;
 }
 /** Per-request facts the host may read after handle() settles; never request text. */
 export interface RequestTrace {

package/dist/types/server.d.ts

@@ -16,6 +16,12 @@ export interface ServerOptions extends Omit<RuntimeOptions, 'observers'> {
     observers?: Observer[] | undefined;
     metrics?: boolean | undefined;
     metricsIntervalMs?: number | undefined;
+    /** Test helper. Directory the project may use for its own files, offered as the `URLCODE_DATA_DIR`
+     * environment value (a route reads it through a declared `env` binding). Created if absent and
+     * never deleted by `close()`, so a later server started on the same directory sees the same data. */
+    dataDir?: string | undefined;
+    /** Test helper. Create a fresh empty data directory, offer it as `URLCODE_DATA_DIR`, and remove it on `close()`. Exclusive with `dataDir`. */
+    isolateData?: boolean | undefined;
 }
 export interface Server {
     server: http.Server;
@@ -31,4 +37,6 @@ export interface Server {
     origin: string;
     close(): Promise<void>;
 }
-export declare function startServer({ project, host, port, watch, local, log, maxBodyBytes, maxInFlightRequests, maxInFlightHealthRequests, requestLog, trustRequestId, origin, trustedProxies, observers, metrics, metricsIntervalMs, ...runtimeOptions }?: ServerOptions): Promise<Server>;
+/** Starts the server. `port: 0` picks a free port, so this is also the in-process helper for tests:
+ * `startServer({ project, port: 0, local: true, isolateData: true })`. */
+export declare function startServer(options?: ServerOptions): Promise<Server>;

package/dist/types/tooling.d.ts

@@ -93,6 +93,8 @@ export interface ExtensionInspection {
         credentialHeaders: string[];
         schema: object;
         policySchema: object | null;
+        hooks: object[];
+        authoring: object | null;
         declared: boolean;
         revisionPinned: boolean;
         mounts: string[];

package/dist/types/types.d.ts

@@ -113,6 +113,7 @@ export interface SiteConfig {
     favicon?: string;
     securityTxt?: SecurityTxtConfig;
     llms?: string;
+    notFound?: string;
 }
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
 export interface ConditionalReply {
@@ -169,6 +170,8 @@ export interface RouteConfig {
      * Never inferred or enforced: the trust decision remains the author's judgment call
      * (docs/AI-AUTHORING.md, "Deciding when a route needs sandbox: true"). */
     sandboxReason?: string;
+    /** Per-method `audit` coverage waiver: method to a non-empty reason. Project file only (docs/READINESS.md). */
+    coveredElsewhere?: Record<string, string>;
     parameters?: ParameterConfig[];
     redirect?: RedirectConfig;
     function?: FunctionConfig;
@@ -186,9 +189,16 @@ export interface RouteConfig {
     respond?: RespondSpec;
     middleware?: MiddlewareConfig[];
     policies?: PoliciesConfig;
+    /** Name of a top-level `shared` block; expanded away at load time, so nothing downstream sees it. */
+    use?: string;
     /** Set by site.ts on a route it generated (`site.<key>`); never declared in YAML. */
     generated?: string;
 }
+/** A named, reusable `request` and `response.headers` block a route selects with `use`. */
+export interface SharedBlock {
+    request?: RouteConfig['request'];
+    response?: RouteConfig['response'];
+}
 export interface ProjectDocument {
     version: '1';
     extensions?: Record<string, ExtensionDeclaration>;
@@ -196,6 +206,7 @@ export interface ProjectDocument {
     includes?: string[];
     policies?: PoliciesConfig;
     profiles?: Record<string, PolicyLayer>;
+    shared?: Record<string, SharedBlock>;
     site?: SiteConfig;
 }
 /** What config.ts returns: the entry document, the merged route table and the files it came from. */
@@ -394,6 +405,8 @@ export interface PlanInventoryEntry {
     sandbox?: boolean;
     /** The route's declared `sandboxReason`, when it has one. */
     sandboxReason?: string;
+    /** The route's declared `coveredElsewhere` audit waivers (method to reason), when it has any. */
+    coveredElsewhere?: Record<string, string>;
 }
 export interface TestPlan {
     inventory: PlanInventoryEntry[];

package/dist/types.js

@@ -55,7 +55,7 @@
                                                                                     
                                                                              
  
-                                                                                                                                                       
+                                                                                                                                                                          
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
                                                                                       
                                                                                                                        
@@ -83,17 +83,23 @@
                                                                                       
                                                                             
                          
+                                                                                                                 
+                                            
                                                                                        
                                                                             
                                                                       
                                                                                                      
                                                                                     
+                                                                                                       
+               
                                                                                        
                      
  
+/** A named, reusable `request` and `response.headers` block a route selects with `use`. */
+                                                                                                     
                                   
                                                                                                                           
-                                                                                       
+                                                                                                                             
  
 /** What config.ts returns: the entry document, the merged route table and the files it came from. */
                                                                                                                                                   
@@ -209,6 +215,8 @@
                     
                                                                
                          
+                                                                                                   
+                                            
  
                            
                                                                                                 

package/dist/typescript-authoring.js

@@ -7,7 +7,7 @@ import {stringify} from 'yaml';
 import {loadDocument} from './config.js';
 import {collectFunctionSources,routeFunctions} from './function-sources.js';
 import {authoringPath,authoringFile,readAuthoringFile,publishAuthoringProject} from './authoring-files.js';
-import {assert} from './errors.js';
+import {assert,ConfigError} from './errors.js';
 
                                                                                                                                   
 const emitted=(path        )=>path.replace(/\.ts$/,'.js');
@@ -22,7 +22,9 @@ const SANDBOX_MODULE_LIMIT=128,SANDBOX_MODULE_BYTE_LIMIT=1048576,SANDBOX_TOTAL_B
  * plugins, package resolution, subprocesses or guest code execution are used. */
 export async function buildTypeScriptProject(project        ,output        ,{dryRun=false}                              ={})                                 {
   const root=await realpath(project),loaded=await loadDocument(root),files=new Map                      (),modules=new Map               ();
-  const {default:ts}=await import('typescript');
+  const ts=await import('typescript').then(module=>module.default).catch(()=>{
+    throw new ConfigError('TypeScript authoring requires the optional typescript package (npm install --save-dev --save-exact typescript@6.0.3)');
+  });
   // Which trust levels a module has already been visited under, so a graph
   // reachable from both a sandboxed and a trusted route is validated under each
   // route's own rules exactly once instead of being refused outright. The
@@ -128,7 +130,7 @@ export async function buildTypeScriptProject(project        ,output        ,{dry
     for(const ref of [route.page,route.download])if(ref)await asset(ref.file);
     if(route.static)await directory(route.static.directory);
   }
-  for(const ref of [loaded.document.site?.favicon,loaded.document.site?.llms])if(ref)await asset(ref);
+  for(const ref of [loaded.document.site?.favicon,loaded.document.site?.llms,loaded.document.site?.notFound])if(ref)await asset(ref);
   // Request fixtures describe behavior the emitted project must keep, so they travel with it.
   try{await asset('tests/requests.json');}catch(error){if(!(error instanceof Error && 'code' in error && error.code==='ENOENT'))throw error;}
   // Flatten includes using the loader's duplicate-checked route table. Original