@cyberart-io/engine 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -43,6 +43,23 @@ type TokenData = {
     /** Same idea for Arweave-typed external assets. We don't currently use it. */
     preferredArweaveGateway?: string;
 };
+/**
+ * Canonical token hash for `Random` / Art Blocks.
+ *
+ * A full 64-hex hash (optional `0x`) is returned unchanged aside from a
+ * lowercase `0x` prefix — this is the kaleidoscope / Art Blocks path.
+ * Any other seed (including the Adventure Kit example `42`) is mixed into
+ * a 64-hex hash so `Random` always sees the same shape.
+ */
+declare function canonicalizeSeed(seed: string | number): string;
+/**
+ * Seed policy for `createRuntime`.
+ *
+ * Live kaleidoscope / Art Blocks must keep a caller-supplied 64-hex hash (and
+ * a short `?hash=` string as `0x…`, not remixed). Deterministic mode and
+ * numeric seeds such as `42` go through `canonicalizeSeed`.
+ */
+declare function resolveRuntimeSeed(seed: string | number, mode: 'live' | 'deterministic'): string;
 
 /**
  * Copyright (c) 2026 Aaron Boyarsky
@@ -50,11 +67,29 @@ type TokenData = {
  * See packages/engine/LICENSE
  */
 
+type Sfc32Regs = {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+};
+/** Snapshot of the dual sfc32 generators after warmup (or after `setState`). */
+type RandomState = {
+    seed: string;
+    useA: boolean;
+    prngA: Sfc32Regs;
+    prngB: Sfc32Regs;
+};
 declare class Random {
+    readonly seed: string;
     private useA;
     private prngA;
     private prngB;
+    private genA;
+    private genB;
     constructor(tokenData: TokenData);
+    getState(): RandomState;
+    setState(state: RandomState): void;
     r_zero_one(): number;
     dec(min?: number, max?: number): number;
     int(min: number, max?: number): number;
@@ -86,12 +121,18 @@ type KeypressHandler = () => void;
 declare class KeyboardManager {
     private actionMap;
     private debugMode;
+    private listening;
     constructor(debugMode?: boolean, captureKeyboard?: boolean);
     /**
      * When a key is pressed, check if there's a corresponding action, and execute it.
      * @param e
      */
     checkKeypress({ key }: KeyboardEvent): void;
+    /**
+     * Inject a key without a DOM event. Deterministic hosts call this at a
+     * chosen frame instead of listening on `window`.
+     */
+    inject(key: string): void;
     /**
      * Register a certain action to be performed when a given key is pressed.
      * @param key
@@ -116,22 +157,112 @@ type PointerClick = {
     x: number;
     y: number;
 };
+type PointerManagerOptions = {
+    /**
+     * When false, do not attach canvas pointer listeners. Deterministic mode
+     * injects coordinates instead of reading the live pointer.
+     */
+    listen?: boolean;
+};
 declare class PointerManager {
     x: number;
     y: number;
     isDown: boolean;
     private clicks;
     private canvas;
-    constructor(canvas: HTMLCanvasElement);
+    private listening;
+    constructor(canvas: HTMLCanvasElement, options?: PointerManagerOptions);
     private toCanvasCoords;
     private onPointerDown;
     private onPointerMove;
     private onPointerUp;
     hasClick(): boolean;
     consumeClick(): PointerClick | null;
+    /**
+     * Inject a pointer sample in canvas pixel space. Deterministic hosts call
+     * this at a chosen frame instead of waiting on DOM pointer events.
+     */
+    inject(kind: 'down' | 'move' | 'up', x: number, y: number): void;
     destroy(): void;
 }
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Versioned envelope for routed host ↔ cart events. Unattached HostChannel
+ * mailboxes still accept thin `{ type, payload }` events; this module is the
+ * schema the EventRouter normalizes to.
+ */
+declare const EVENT_ENVELOPE_VERSION: 1;
+type EventKind = 'intent' | 'state' | 'diagnostic';
+type RejectionReason = 'malformed' | 'unauthorized' | 'host-rejected' | 'rate-limited' | 'loop-detected' | 'storm-detected' | 'unknown-target' | 'not-subscribed' | 'hop-limit';
+declare const REJECTED_EVENT_TYPE = "cyberart.diagnostic.rejected";
+/** Remaining hops on a new root event; each caused follow-up decrements by 1. */
+declare const DEFAULT_MAX_HOPS = 8;
+type EventEnvelope = {
+    schemaVersion: typeof EVENT_ENVELOPE_VERSION;
+    type: string;
+    kind: EventKind;
+    source: string;
+    target?: string;
+    id: string;
+    correlationId: string;
+    causationId?: string;
+    seq: number;
+    hops: number;
+    idempotencyKey?: string;
+    payload?: unknown;
+};
+type EventInput = {
+    type: string;
+    payload?: unknown;
+    schemaVersion?: number;
+    kind?: EventKind;
+    source?: string;
+    target?: string;
+    id?: string;
+    correlationId?: string;
+    causationId?: string;
+    seq?: number;
+    hops?: number;
+    idempotencyKey?: string;
+};
+type RejectionPayload = {
+    reason: RejectionReason;
+    detail?: string;
+    eventType: string;
+    source: string;
+};
+type NormalizeContext = {
+    source: string;
+    createId: () => string;
+    seq: number;
+    causationId?: string;
+    maxHops?: number;
+    parentHops?: number;
+};
+type NormalizeSuccess = {
+    ok: true;
+    envelope: EventEnvelope;
+};
+type NormalizeFailure = {
+    ok: false;
+    reason: 'malformed';
+    detail: string;
+};
+type NormalizeResult = NormalizeSuccess | NormalizeFailure;
+/**
+ * `kind` on the input wins. Otherwise persistence types are intents, then
+ * the first dotted segment that is `intent` | `state` | `diagnostic`.
+ * `adventure.presentation.*` does not infer a kind (the presentation segment
+ * is not one); put the kind in the name, e.g. `adventure.presentation.intent.*`.
+ */
+declare function inferEventKind(input: EventInput): EventKind | undefined;
+declare function matchEventPattern(pattern: string, type: string): boolean;
+declare function normalizeEvent(input: EventInput, context: NormalizeContext): NormalizeResult;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -142,22 +273,49 @@ declare class PointerManager {
  * `emit`ted by the cart and forwarded to host `onEvent` listeners.
  *
  * Carts that never mention this object behave as they do today.
+ *
+ * Routed traffic is a full EventEnvelope; thin `{ type, payload }` remains
+ * valid on an unattached mailbox. Extra envelope fields are optional here.
  */
-type HostEvent = {
-    type: string;
-    payload?: unknown;
-};
+
+type HostEvent = EventInput;
 type HostEventListener = (event: HostEvent) => void;
 declare class HostChannel {
     private inbound;
     private listeners;
+    private closed;
     dispatch(event: HostEvent): void;
     consume(): HostEvent[];
     emit(event: HostEvent): void;
     onEvent(listener: HostEventListener): () => void;
+    /** Drop queued inbound events. Does not remove `onEvent` listeners. */
+    clearInbound(): void;
+    /** Drop inbound events and listeners. Runtime teardown; not cart unload. */
     clear(): void;
+    /** Permanent close. Further dispatch / emit / consume / onEvent throw. */
+    close(): void;
+    private requireOpen;
 }
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Time source for animation. Production uses the wall clock (`performance.now`);
+ * deterministic mode uses a host-advanced virtual clock so replays do not
+ * depend on rAF, `setTimeout`, or wall time.
+ */
+type Clock = {
+    now(): number;
+};
+type VirtualClock = Clock & {
+    set(ms: number): void;
+    advance(ms: number): void;
+};
+declare function createWallClock(): Clock;
+declare function createVirtualClock(origin?: number): VirtualClock;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -248,6 +406,217 @@ declare class IncompatibleCartStateError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host-controlled time, input, and asset completion for deterministic replays.
+ * Production kaleidoscope / Art Blocks playback does not enable this mode.
+ * Logical asset URLs are resolved by the host preloader (`assetResolver.ts`);
+ * this module only times `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` delivery.
+ */
+
+declare const ASSET_READY_EVENT = "cyberart.asset.ready";
+declare const ASSET_FAILED_EVENT = "cyberart.asset.failed";
+type PointerKind = 'down' | 'move' | 'up';
+type ScriptedAction = {
+    atFrame: number;
+} & ({
+    type: 'pointer';
+    pointer: {
+        kind: PointerKind;
+        x: number;
+        y: number;
+    };
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'event';
+    event: HostEvent;
+} | {
+    type: 'asset';
+    id: string;
+    status: 'ready' | 'failed';
+    /** Optional structured failure or resolved resource. Envelope is unchanged. */
+    detail?: unknown;
+});
+type DeterministicRuntimeOptions = {
+    /** Virtual clock origin in ms. Default 0. */
+    origin?: number;
+    /** Actions applied at the start of `atFrame`, before `update`. */
+    actions?: ScriptedAction[];
+};
+type ClockSnapshot = {
+    now: number;
+    framesElapsed: number;
+    frameRate: number;
+};
+type ReplayMetadata = {
+    seed: string;
+    clock: ClockSnapshot;
+    rng: RandomState;
+    actions: ScriptedAction[];
+    applied: AppliedAction[];
+    events: HostEvent[];
+    state: unknown;
+};
+type AppliedAction = {
+    frame: number;
+    action: ScriptedAction;
+};
+/**
+ * Compare two replay captures. Empty array means identical; otherwise each
+ * string names the first disagreement on that field.
+ */
+declare function describeReplayMismatch(a: ReplayMetadata, b: ReplayMetadata): string[];
+
+declare const ASSET_KINDS: readonly ["image", "audio", "font", "spritesheet"];
+type AssetKind = (typeof ASSET_KINDS)[number];
+declare const ASSET_FAILURE_CODES: readonly ["timeout", "cors", "not-found", "invalid", "aborted", "resolver"];
+type AssetFailureCode = (typeof ASSET_FAILURE_CODES)[number];
+type AssetCorsMode = 'anonymous' | 'use-credentials' | 'omit';
+/** Logical silent placeholder. Carts/hosts may treat it as “no media”. */
+declare const SILENT_ASSET_FALLBACK_REF = "cyberart:fallback/silent";
+type AssetProvenance = {
+    readonly [key: string]: string | number | boolean | null | undefined;
+};
+type AssetDeclaration = {
+    /** Cache key and `ASSET_*_EVENT` payload `id`. */
+    id: string;
+    /** Logical URI: `https://…`, `moltazine:post/<id>#fragment`, `world:asset/…`, `library:…`. */
+    ref: string;
+    type: AssetKind;
+    integrity?: string;
+    provenance?: AssetProvenance;
+    /** Per-asset timeout. Ignored when wall-clock timeouts are off (deterministic). */
+    timeoutMs?: number;
+    /**
+     * `'silent'` synthesizes `SILENT_ASSET_FALLBACK_REF`. A string is another
+     * logical ref of the same type. A declaration is resolved as-is.
+     */
+    fallback?: 'silent' | string | AssetDeclaration;
+};
+type AssetResolveRequest = {
+    id: string;
+    ref: string;
+    type: AssetKind;
+    integrity?: string;
+    provenance?: AssetProvenance;
+};
+type ResolvedAsset = {
+    id: string;
+    ref: string;
+    type: AssetKind;
+    url: string;
+    integrity?: string;
+    provenance?: AssetProvenance;
+    cors?: AssetCorsMode;
+    usedFallback?: boolean;
+    /** When true, `dispose` / `forget` call `URL.revokeObjectURL`. */
+    managed?: boolean;
+};
+type AssetFailure = {
+    id: string;
+    ref: string;
+    code: AssetFailureCode;
+    message: string;
+};
+type AssetItemStatus = {
+    state: 'pending';
+} | {
+    state: 'loading';
+} | {
+    state: 'ready';
+    resource: ResolvedAsset;
+    failure?: AssetFailure;
+} | {
+    state: 'failed';
+    failure: AssetFailure;
+};
+type AssetPreloadSnapshot = {
+    total: number;
+    pending: number;
+    ready: number;
+    failed: number;
+    fallbacks: number;
+    items: Record<string, AssetItemStatus>;
+    failures: AssetFailure[];
+};
+type AssetResolver = {
+    resolve(request: AssetResolveRequest, signal?: AbortSignal): Promise<ResolvedAsset>;
+};
+type CreateAssetPreloaderOptions = {
+    resolver: AssetResolver;
+    timeoutMs?: number;
+    /**
+     * Dispatch `ASSET_READY_EVENT` / `ASSET_FAILED_EVENT` as loads settle.
+     * Default true. Deterministic runtimes pass false so scripted `asset`
+     * actions own delivery timing.
+     */
+    emitEvents?: boolean;
+    /**
+     * Apply `timeoutMs` with `setTimeout`. Default true. Deterministic
+     * runtimes pass false so tests do not wait on wall-clock fetch.
+     */
+    wallClockTimeout?: boolean;
+    dispatch?: (event: HostEvent) => void;
+};
+type AssetRuntimeOptions = {
+    resolver: AssetResolver;
+    timeoutMs?: number;
+    emitEvents?: boolean;
+};
+type AssetPreloader = {
+    preload(declarations: readonly AssetDeclaration[]): Promise<AssetPreloadSnapshot>;
+    get(id: string): ResolvedAsset | undefined;
+    getProgress(): AssetPreloadSnapshot;
+    onProgress(listener: (snapshot: AssetPreloadSnapshot) => void): () => void;
+    abort(id?: string): void;
+    forget(id?: string): void;
+    dispose(): void;
+};
+type FixtureAssetRecord = {
+    url: string;
+    integrity?: string;
+    cors?: AssetCorsMode;
+    provenance?: AssetProvenance;
+} | {
+    error: AssetFailureCode;
+    message?: string;
+};
+type FixtureAssetCatalog = Readonly<Record<string, FixtureAssetRecord>>;
+type HostedAssetResolverOptions = {
+    /** Prefix for rewritten logical refs. `http(s)` / `data:` / `blob:` pass through. */
+    cdnBase: string;
+    /** Authored refs that fail with a structured code. No network. */
+    failures?: Readonly<Record<string, AssetFailureCode | {
+        code: AssetFailureCode;
+        message?: string;
+    }>>;
+};
+declare function isAssetKind(value: unknown): value is AssetKind;
+declare function isAssetFailureCode(value: unknown): value is AssetFailureCode;
+declare function isAssetFailure(value: unknown): value is AssetFailure;
+declare function createAssetFailure(input: {
+    id: string;
+    ref: string;
+    code: AssetFailureCode;
+    message?: string;
+}): AssetFailure;
+declare function assetStatusEvent(status: 'ready' | 'failed', payload: {
+    id: string;
+    ref?: string;
+    resource?: ResolvedAsset;
+    failure?: AssetFailure;
+}): HostEvent;
+/** Map a logical ref through a hosted CDN prefix. Ordinary URLs are unchanged. */
+declare function rewriteHostedAssetRef(ref: string, cdnBase: string): string;
+declare function createFixtureAssetResolver(catalog: FixtureAssetCatalog): AssetResolver;
+declare function createHostedAssetResolver(options: HostedAssetResolverOptions): AssetResolver;
+declare function createAssetPreloader(options: CreateAssetPreloaderOptions): AssetPreloader;
+
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -262,11 +631,16 @@ type FrameErrorInfo = {
 type CreateRuntimeOptions = {
     /** Required mount point. The runtime creates or adopts a canvas inside this element. */
     container: HTMLElement;
-    /** Optional token hash (`0x` + 64 hex). Instance-local; does not clobber an existing global cache. */
-    seed?: string;
+    /**
+     * Token hash (`0x` + 64 hex) or any seed mixed into one. Instance-local;
+     * does not clobber an existing global cache. Kaleidoscope / Art Blocks
+     * pass the platform hash unchanged.
+     */
+    seed?: string | number;
     /**
      * When true, the cart listens for window keydown (full-page players).
      * Defaults to false so an embed does not steal keys from the host.
+     * Ignored when `deterministic` is set — input is injected per frame.
      */
     captureKeyboard?: boolean;
     /**
@@ -274,6 +648,19 @@ type CreateRuntimeOptions = {
      * (click can beat idle prebuild). After mount, `cart.metadata.audio` wins.
      */
     audio?: AudioLibrarySpec;
+    /**
+     * Host-controlled time, input, and asset events. Production playback
+     * (kaleidoscope locally and `build:art`) leaves this unset so rAF and the
+     * token hash drive the piece as they do today.
+     */
+    deterministic?: boolean | DeterministicRuntimeOptions;
+    /**
+     * Host-pluggable asset resolver/preloader. Carts request logical refs;
+     * the host maps them to loadable URLs or blobs. Leave unset when unused.
+     * In deterministic mode, preload does not dispatch `ASSET_*` events —
+     * scripted `{ type: 'asset' }` actions own delivery timing.
+     */
+    assets?: AssetRuntimeOptions;
 };
 type MountOptions<T = unknown> = {
     /** Boot overrides passed as `customState` into `getDefaultState`. Not a live-state replay. */
@@ -310,6 +697,18 @@ type CartHandle = {
     peekExportedFramebuffer(): ImageData | null;
     peekSeed(): string | undefined;
     isGenerative(): boolean;
+    /**
+     * Run `frames` ticks on the virtual clock. Requires `deterministic`.
+     * Does not use rAF; live kaleidoscope playback never calls this.
+     */
+    step(frames?: number): Promise<void>;
+    /** Run the frames that span `ms` at the cart frame rate. Requires `deterministic`. */
+    advance(ms: number): Promise<void>;
+    /** Queue a scripted input/asset/host event for a future frame. */
+    schedule(action: ScriptedAction): void;
+    getClock(): ClockSnapshot;
+    getRandomState(): RandomState;
+    getReplayMetadata(): Promise<ReplayMetadata>;
     readonly canvas: HTMLCanvasElement | undefined;
     paused: boolean;
     readonly tokenData: TokenData;
@@ -323,6 +722,16 @@ type CyberArtRuntime = {
     unlockAudio(): Promise<void>;
     destroy(): void;
     readonly tokenData: TokenData;
+    /**
+     * This runtime's mailbox. Attach it to `createEventRouter` from the host;
+     * carts never receive the router. Survives cart remount; `destroy()` clears it.
+     */
+    readonly hostChannel: HostChannel;
+    /**
+     * Preloader for this runtime. Undefined when `assets` was omitted.
+     * Survives cart remount; `destroy()` disposes it.
+     */
+    readonly assets: AssetPreloader | undefined;
     onError?: (error: unknown, info: FrameErrorInfo) => void;
 };
 declare function createRuntime(options: CreateRuntimeOptions): CyberArtRuntime;
@@ -374,4 +783,340 @@ type CartStateHotkeyOptions = {
  */
 declare function registerCartStateHotkeys(keyboardManager: KeyboardManager, hostChannel: HostChannel, options?: CartStateHotkeyOptions): void;
 
-export { type AnimationCart, type AnimationTiming, type AudioLibraryId, type AudioLibrarySpec, CYBERART_CANVAS_ATTR, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type CreateRuntimeOptions, type CyberArtRuntime, type DimensionContext, type FrameErrorInfo, HostChannel, type HostEvent, type HostEventListener, type ImportCartStateExtras, IncompatibleCartStateError, KeyboardManager, type MountOptions, type PointerClick, PointerManager, Random, type TokenData, attachCartStatePersistence, createRuntime, registerCartStateHotkeys };
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Host-side event router. Carts keep a dumb HostChannel mailbox; the host
+ * attaches those channels here so events are permissioned, budgeted, and
+ * loop-checked before they reach another cart. Carts never receive this
+ * object.
+ */
+
+type ValidateResult = true | {
+    reason: 'host-rejected';
+    detail?: string;
+};
+type AttachOptions = {
+    emit?: string[];
+    subscribe?: string[];
+    authoritative?: boolean;
+};
+type EventRouterOptions = {
+    validate?: (event: EventEnvelope) => ValidateResult;
+    createId?: () => string;
+    now?: () => number;
+    hostSource?: string;
+    maxPerTurn?: number;
+    maxPerWindow?: number;
+    windowMs?: number;
+    maxCausationDepth?: number;
+    maxHops?: number;
+    maxCorrelationPerTurn?: number;
+    maxIndex?: number;
+};
+type PublishExtras = {
+    cause?: EventEnvelope;
+};
+type EventRouter = {
+    attach(id: string, channel: HostChannel, options?: AttachOptions): void;
+    detach(id: string): void;
+    publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
+    subscribe(patterns: string[], listener: (event: EventEnvelope) => void): () => void;
+    turn(): void;
+};
+declare function createEventRouter(options?: EventRouterOptions): EventRouter;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * One contract definition drives TypeScript payload types, runtime
+ * validation, router permission checks, and machine-readable manifests.
+ * Kind must appear as a dotted segment of `type` so names like
+ * `adventure.presentation.cue.started` fail at definition time instead of
+ * silently inferring a bogus kind.
+ */
+
+type ContractFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+type PayloadFieldSpec = {
+    type: ContractFieldType;
+    optional?: boolean;
+};
+type PayloadSchema = {
+    /** Payload schema version. Bump on any field change. */
+    version: number;
+    fields: Record<string, PayloadFieldSpec>;
+};
+type ContractDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type EventContractManifest = {
+    type: string;
+    kind: EventKind;
+    version: number;
+    fields: Record<string, {
+        type: ContractFieldType;
+        optional: boolean;
+    }>;
+    emitPattern: string;
+    subscribePattern: string;
+};
+type PayloadValidation = {
+    ok: true;
+    payload: unknown;
+} | {
+    ok: false;
+    errors: ContractDiagnostic[];
+};
+type EventContract = {
+    type: string;
+    kind: EventKind;
+    payloadSchema: PayloadSchema;
+    emitPattern: string;
+    subscribePattern: string;
+    toManifest(): EventContractManifest;
+    validatePayload(payload: unknown): PayloadValidation;
+};
+type DefineContractResult = {
+    ok: true;
+    contract: EventContract;
+} | {
+    ok: false;
+    errors: ContractDiagnostic[];
+};
+type SchemaCompatibility = 'identical' | 'backward-compatible' | 'breaking';
+type FieldTs<T extends ContractFieldType> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'array' ? unknown[] : Record<string, unknown>;
+type OptionalFieldKeys<S extends PayloadSchema> = {
+    [K in keyof S['fields']]: S['fields'][K] extends {
+        optional: true;
+    } ? K : never;
+}[keyof S['fields']];
+type RequiredFieldKeys<S extends PayloadSchema> = Exclude<keyof S['fields'], OptionalFieldKeys<S>>;
+type InferredPayload<S extends PayloadSchema> = {
+    [K in RequiredFieldKeys<S>]: FieldTs<S['fields'][K]['type']>;
+} & {
+    [K in OptionalFieldKeys<S>]?: FieldTs<S['fields'][K]['type']>;
+};
+/** First dotted segment that is `intent` | `state` | `diagnostic`. */
+declare function kindSegmentInType(type: string): EventKind | undefined;
+declare function familyPatternForType(type: string): string;
+declare function defineIntent(type: string, schema: PayloadSchema): DefineContractResult;
+declare function defineStateEvent(type: string, schema: PayloadSchema): DefineContractResult;
+declare function defineDiagnostic(type: string, schema: PayloadSchema): DefineContractResult;
+declare function comparePayloadSchemas(from: PayloadSchema, to: PayloadSchema): SchemaCompatibility;
+declare function deriveAttachOptions(contracts: EventContract[], role: 'cart' | 'authoritative'): AttachOptions;
+declare function verifyAttachOptions(options: AttachOptions, contracts: EventContract[]): {
+    ok: true;
+} | {
+    ok: false;
+    errors: ContractDiagnostic[];
+};
+type ContractRegistry = {
+    get(type: string): EventContract | undefined;
+    manifest(): EventContractManifest[];
+    validateEnvelope(event: EventEnvelope): PayloadValidation;
+    asRouterValidate(event: EventEnvelope): ValidateResult;
+};
+declare function createContractRegistry(contracts: EventContract[]): ContractRegistry;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Versioned presentation-adapter contract. Hosts own canonical state and
+ * push a render model; Cyberart presents it and emits interaction intents.
+ * Adventure Kit concepts stay in the host.
+ */
+
+declare const PRESENTATION_ADAPTER_VERSION: 1;
+/** Host → cart render model. Kind is `state`. */
+declare const PRESENTATION_MODEL_EVENT = "presentation.state.model";
+/**
+ * Cart → host when a model cannot be presented. Kind is `intent` so a
+ * non-authoritative cart can emit it through the router.
+ */
+declare const PRESENTATION_UNSUPPORTED_EVENT = "presentation.intent.unsupported";
+declare const PRESENTATION_PHASES: readonly ["loading", "ready", "error", "unsupported"];
+type PresentationPhase = (typeof PRESENTATION_PHASES)[number];
+/**
+ * Recommended router `subscribe` for a presentation cart. Intent type names
+ * are host-owned (`adventure.intent.*`); do not put domain objects in `target`.
+ */
+declare const PRESENTATION_SUBSCRIBE_PATTERNS: readonly ["presentation.state.*", "cyberart.diagnostic.rejected"];
+declare const INVALID_PRESENTATION_MODEL_MESSAGE = "Presentation adapter: model is invalid or not JSON-serializable";
+type PresentationRegion = {
+    id: string;
+    /** Drawing-space pixels — same space as `PointerManager` / harness `click`. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Emitted on click while `phase === 'ready'`. Prefer `*.intent.*` type names. */
+    intent: EventInput;
+};
+type PresentationView = {
+    background?: string;
+    title?: string;
+    regions?: readonly PresentationRegion[];
+};
+type PresentationModel<TView = PresentationView> = {
+    contractVersion: typeof PRESENTATION_ADAPTER_VERSION;
+    phase: PresentationPhase;
+    /** Host-owned render model. The engine does not interpret domain fields. */
+    view?: TView;
+    /** Machine-readable when `phase` is `loading` | `error` | `unsupported`. */
+    reason?: string;
+};
+type PresentationCartState<TView = PresentationView> = {
+    model: PresentationModel<TView>;
+};
+type PresentationAdapterTarget = {
+    dispatch(event: HostEvent): void;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    destroy(): void;
+    readonly paused?: boolean;
+};
+type PresentationAdapter<TView = PresentationView, TTarget extends PresentationAdapterTarget = PresentationAdapterTarget> = {
+    readonly version: typeof PRESENTATION_ADAPTER_VERSION;
+    readonly target: TTarget;
+    /** Last model this session presented (or the boot model). A copy — mutating it does not update the cart. */
+    readonly model: PresentationModel<TView>;
+    readonly phase: PresentationPhase;
+    readonly paused: boolean;
+    present(model: PresentationModel<TView>): void;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    /** Point at a new handle after `runtime.mount` / `harness.remount`. */
+    retarget(target: TTarget): void;
+    destroy(): void;
+};
+type AttachPresentationAdapterOptions<TView = PresentationView> = {
+    model?: PresentationModel<TView>;
+    /**
+     * Dispatch `model` onto the mailbox. Default `true` when `model` is set,
+     * `false` otherwise (leave the cart's current state alone).
+     */
+    present?: boolean;
+};
+type MountPresentationAdapterOptions<TView = PresentationView> = {
+    cart?: AnimationCart<PresentationCartState<TView>>;
+    onEvent?: HostEventListener;
+    model?: PresentationModel<TView>;
+    initialState?: MountOptions<PresentationCartState<TView>>['initialState'];
+};
+declare function isPresentationPhase(value: unknown): value is PresentationPhase;
+declare function isPresentationModel(value: unknown): value is PresentationModel;
+declare function createPresentationModelEvent<TView = PresentationView>(model: PresentationModel<TView>, extras?: Pick<EventInput, 'correlationId' | 'causationId' | 'idempotencyKey'>): EventInput;
+/**
+ * Minimal presentation cart. Hit-tests `view.regions` while `phase === 'ready'`.
+ * Hosts with a custom view shape may pass their own cart to `mountPresentationAdapter`.
+ * `title` is inspectable state; only `background` is painted.
+ */
+declare function createReferencePresentationCart<TView = PresentationView>(): AnimationCart<PresentationCartState<TView>>;
+declare function attachPresentationAdapter<TView = PresentationView, TTarget extends PresentationAdapterTarget = PresentationAdapterTarget>(target: TTarget, options?: AttachPresentationAdapterOptions<TView>): PresentationAdapter<TView, TTarget>;
+/** Mount a presentation cart and return the host-facing adapter. */
+declare function mountPresentationAdapter<TView = PresentationView>(runtime: CyberArtRuntime, options?: MountPresentationAdapterOptions<TView>): PresentationAdapter<TView, CartHandle>;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Deterministic presentation cue / timeline. Carts step this with a frame
+ * index; there are no wall-clock timers. Lifecycle event type names are
+ * stable for later contract registries.
+ */
+declare const CUE_STARTED_EVENT: "cue.started";
+declare const CUE_COMPLETED_EVENT: "cue.completed";
+declare const CUE_CANCELLED_EVENT: "cue.cancelled";
+declare const CUE_REPLACED_EVENT: "cue.replaced";
+declare const CUE_LIFECYCLE_EVENTS: readonly ["cue.started", "cue.completed", "cue.cancelled", "cue.replaced"];
+type CueLifecycleType = (typeof CUE_LIFECYCLE_EVENTS)[number];
+type CueEasing = 'linear' | 'ease-out';
+type CueDuplicatePolicy = 'ignore' | 'replace' | 'reject';
+type CueRepeatPolicy = {
+    count: number;
+} | {
+    forever: true;
+};
+type CueReducedMotionPolicy = 'skip' | 'complete' | {
+    durationFrames: number;
+};
+type CueSpec = {
+    name: string;
+    idempotencyKey: string;
+    /** Frame when the cue is eligible to start (before delay). Default: play frame. */
+    startFrame?: number;
+    durationFrames: number;
+    delayFrames?: number;
+    easing?: CueEasing;
+    repeat?: CueRepeatPolicy;
+    /**
+     * When the timeline is in reduced-motion mode: skip (complete immediately),
+     * complete (same), or a shorter duration. Default `complete`.
+     */
+    reducedMotion?: CueReducedMotionPolicy;
+    onDuplicate?: CueDuplicatePolicy;
+};
+type CuePhase = 'scheduled' | 'active' | 'completed' | 'cancelled';
+type CueView = {
+    name: string;
+    idempotencyKey: string;
+    phase: CuePhase;
+    startFrame: number;
+    durationFrames: number;
+    delayFrames: number;
+    easing: CueEasing;
+    progress: number;
+    repeatIndex: number;
+};
+type CueLifecycleEvent = {
+    type: CueLifecycleType;
+    atFrame: number;
+    name: string;
+    idempotencyKey: string;
+    progress: number;
+};
+type CueTimelineSnapshot = {
+    frame: number;
+    reducedMotion: boolean;
+    cues: CueView[];
+    events: CueLifecycleEvent[];
+};
+type PlayCueResult = {
+    ok: true;
+    cue: CueView;
+} | {
+    ok: false;
+    reason: 'duplicate' | 'invalid';
+    detail: string;
+};
+type CreatePresentationTimelineOptions = {
+    /** Host-controlled reduced-motion / reduced-sensory flag. Not a CSS query. */
+    reducedMotion?: boolean;
+    originFrame?: number;
+};
+type PresentationTimeline = {
+    play(spec: CueSpec): PlayCueResult;
+    step(frames?: number): CueLifecycleEvent[];
+    cancel(idempotencyKey: string): boolean;
+    reset(): void;
+    snapshot(): CueTimelineSnapshot;
+    get(idempotencyKey: string): CueView | undefined;
+    readonly frame: number;
+    readonly reducedMotion: boolean;
+};
+declare function isCueLifecycleType(value: unknown): value is CueLifecycleType;
+declare function applyCueEasing(t: number, easing: CueEasing): number;
+declare function createPresentationTimeline(options?: CreatePresentationTimelineOptions): PresentationTimeline;
+
+export { ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, type AnimationCart, type AnimationTiming, type AppliedAction, type AssetCorsMode, type AssetDeclaration, type AssetFailure, type AssetFailureCode, type AssetItemStatus, type AssetKind, type AssetPreloadSnapshot, type AssetPreloader, type AssetProvenance, type AssetResolveRequest, type AssetResolver, type AssetRuntimeOptions, type AttachOptions, type AttachPresentationAdapterOptions, type AudioLibraryId, type AudioLibrarySpec, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type Clock, type ClockSnapshot, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CreateAssetPreloaderOptions, type CreatePresentationTimelineOptions, type CreateRuntimeOptions, type CueDuplicatePolicy, type CueEasing, type CueLifecycleEvent, type CueLifecycleType, type CuePhase, type CueReducedMotionPolicy, type CueRepeatPolicy, type CueSpec, type CueTimelineSnapshot, type CueView, type CyberArtRuntime, DEFAULT_MAX_HOPS, type DefineContractResult, type DeterministicRuntimeOptions, type DimensionContext, EVENT_ENVELOPE_VERSION, type EventContract, type EventContractManifest, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type FixtureAssetCatalog, type FixtureAssetRecord, type FrameErrorInfo, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, KeyboardManager, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PlayCueResult, type PointerClick, PointerManager, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REJECTED_EVENT_TYPE, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayMetadata, type ResolvedAsset, SILENT_ASSET_FALLBACK_REF, type SchemaCompatibility, type ScriptedAction, type TokenData, type ValidateResult, type VirtualClock, applyCueEasing, assetStatusEvent, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, comparePayloadSchemas, createAssetFailure, createAssetPreloader, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createRuntime, createVirtualClock, createWallClock, defineDiagnostic, defineIntent, defineStateEvent, deriveAttachOptions, describeReplayMismatch, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isCueLifecycleType, isPresentationModel, isPresentationPhase, kindSegmentInType, matchEventPattern, mountPresentationAdapter, normalizeEvent, registerCartStateHotkeys, resolveRuntimeSeed, rewriteHostedAssetRef, verifyAttachOptions };