@cyberart-io/engine 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -255,7 +255,9 @@ type NormalizeFailure = {
 type NormalizeResult = NormalizeSuccess | NormalizeFailure;
 /**
  * `kind` on the input wins. Otherwise persistence types are intents, then
- * the second dotted segment of `type` if it is a known kind.
+ * 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;
@@ -281,11 +283,18 @@ 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;
 }
 
 /**
@@ -404,6 +413,8 @@ declare class IncompatibleCartStateError extends Error {
  *
  * 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";
@@ -428,6 +439,7 @@ type ScriptedAction = {
     type: 'asset';
     id: string;
     status: 'ready' | 'failed';
+    /** Optional structured failure or resolved resource. Envelope is unchanged. */
     detail?: unknown;
 });
 type DeterministicRuntimeOptions = {
@@ -460,6 +472,151 @@ type AppliedAction = {
  */
 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
@@ -497,6 +654,13 @@ type CreateRuntimeOptions = {
      * 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. */
@@ -558,72 +722,20 @@ 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;
 
-/**
- * Copyright (c) 2026 Aaron Boyarsky
- * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
- * See packages/engine/LICENSE
- *
- * CI / agent harness around production `createRuntime({ deterministic })`.
- * `installHeadlessCanvas` is test-only — do not call it from Player or kaleidoscope.
- */
-
-/** 1×1 PNG so `captureFrame(path)` writes a file that actually opens. */
-declare const HEADLESS_PNG_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
-declare const DEFAULT_HEADLESS_WIDTH = 320;
-declare const DEFAULT_HEADLESS_HEIGHT = 180;
-/**
- * Documented jsdom canvas install. Mutates `HTMLCanvasElement.prototype`.
- * Idempotent. Not for production playback.
- */
-declare function installHeadlessCanvas(): void;
-type HeadlessFrameError = {
-    error: unknown;
-    info: FrameErrorInfo;
-};
-type HeadlessInspect = {
-    state: unknown;
-    events: HostEvent[];
-    errors: HeadlessFrameError[];
-    replay: ReplayMetadata;
-    clock: ClockSnapshot;
-};
-type CreateHeadlessHarnessOptions<T = unknown> = {
-    cart: AnimationCart<T>;
-    seed?: CreateRuntimeOptions['seed'];
-    width?: number;
-    height?: number;
-    /** Virtual clock origin in ms. Default 0. */
-    origin?: number;
-    actions?: ScriptedAction[];
-    initialState?: Partial<T>;
-    gameManager?: unknown;
-    onEvent?: HostEventListener;
-    onError?: (error: unknown, info: FrameErrorInfo) => void;
-};
-type HeadlessHarness<T = unknown> = {
-    readonly runtime: CyberArtRuntime;
-    readonly container: HTMLElement;
-    readonly events: readonly HostEvent[];
-    readonly errors: readonly HeadlessFrameError[];
-    readonly cart: CartHandle;
-    step(frames?: number): Promise<void>;
-    advance(ms: number): Promise<void>;
-    schedule(action: ScriptedAction): void;
-    dispatch(event: HostEvent): void;
-    key(key: string): void;
-    /** Pointer-down at the next frame. Use `schedule` for move/up. Canvas pixels, not CSS. */
-    click(x: number, y: number): void;
-    inspect(): Promise<HeadlessInspect>;
-    captureFrame(path?: string): Promise<CartSnapshot>;
-    remount(options?: MountOptions<T>): CartHandle;
-    destroy(): void;
-};
-declare function createHeadlessHarness<T>(options: CreateHeadlessHarnessOptions<T>): HeadlessHarness<T>;
-
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -716,4 +828,660 @@ type EventRouter = {
 };
 declare function createEventRouter(options?: EventRouterOptions): EventRouter;
 
-export { ASSET_FAILED_EVENT, ASSET_READY_EVENT, type AnimationCart, type AnimationTiming, type AppliedAction, type AttachOptions, type AudioLibraryId, type AudioLibrarySpec, CYBERART_CANVAS_ATTR, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type Clock, type ClockSnapshot, type CreateHeadlessHarnessOptions, type CreateRuntimeOptions, type CyberArtRuntime, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, DEFAULT_MAX_HOPS, type DeterministicRuntimeOptions, type DimensionContext, EVENT_ENVELOPE_VERSION, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type FrameErrorInfo, HEADLESS_PNG_DATA_URL, type HeadlessFrameError, type HeadlessHarness, type HeadlessInspect, HostChannel, type HostEvent, type HostEventListener, type ImportCartStateExtras, IncompatibleCartStateError, KeyboardManager, type MountOptions, type NormalizeContext, type NormalizeResult, type PointerClick, PointerManager, type PublishExtras, REJECTED_EVENT_TYPE, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayMetadata, type ScriptedAction, type TokenData, type ValidateResult, type VirtualClock, attachCartStatePersistence, canonicalizeSeed, createEventRouter, createHeadlessHarness, createRuntime, createVirtualClock, createWallClock, describeReplayMismatch, inferEventKind, installHeadlessCanvas, matchEventPattern, normalizeEvent, registerCartStateHotkeys, resolveRuntimeSeed };
+/**
+ * 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;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Versioned, JSON-serializable capability manifest for a cart/module.
+ * Definition, parse, and host validation all return structured diagnostics
+ * instead of throwing.
+ */
+declare const CAPABILITY_MANIFEST_VERSION: 1;
+declare const CAPABILITY_PHASES: readonly ["loading", "ready", "error", "unsupported"];
+type CapabilityPhase = (typeof CAPABILITY_PHASES)[number];
+declare const CAPABILITY_MANAGERS: readonly ["keyboard", "pointer", "audio", "assets", "hostChannel"];
+type CapabilityManager = (typeof CAPABILITY_MANAGERS)[number];
+declare const CAPABILITY_ASSET_KINDS: readonly ["image", "audio", "font", "spritesheet"];
+type CapabilityAssetKind = (typeof CAPABILITY_ASSET_KINDS)[number];
+declare const CAPABILITY_INTEGRATIONS: readonly ["tone", "midi"];
+type CapabilityIntegration = (typeof CAPABILITY_INTEGRATIONS)[number];
+type CapabilityDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type CapabilityRuntime = {
+    minContractVersion: number;
+    features: string[];
+};
+type CapabilityAssetDeclarationSummary = {
+    id: string;
+    kind: CapabilityAssetKind;
+};
+type CapabilityAssetSummary = {
+    kinds: CapabilityAssetKind[];
+    declarations: CapabilityAssetDeclarationSummary[];
+};
+type CapabilityPermissions = {
+    emit: string[];
+    subscribe: string[];
+    authoritative?: boolean;
+};
+type CapabilityManifest = {
+    version: typeof CAPABILITY_MANIFEST_VERSION;
+    id: string;
+    runtime: CapabilityRuntime;
+    phases: CapabilityPhase[];
+    managers: CapabilityManager[];
+    assets: CapabilityAssetSummary;
+    acceptedEvents: string[];
+    emittedEvents: string[];
+    permissions: CapabilityPermissions;
+    integrations: CapabilityIntegration[];
+};
+type CapabilityManifestInput = {
+    version?: number;
+    id: string;
+    runtime: CapabilityRuntime;
+    phases: CapabilityPhase[];
+    managers: CapabilityManager[];
+    assets: CapabilityAssetSummary;
+    acceptedEvents: string[];
+    emittedEvents: string[];
+    permissions: CapabilityPermissions;
+    integrations: CapabilityIntegration[];
+};
+type HostCapabilities = {
+    contractVersion: number;
+    features: string[];
+    integrations: CapabilityIntegration[];
+    managers?: CapabilityManager[];
+    emit?: string[];
+    subscribe?: string[];
+};
+type DefineCapabilityManifestResult = {
+    ok: true;
+    manifest: CapabilityManifest;
+} | {
+    ok: false;
+    errors: CapabilityDiagnostic[];
+};
+type ValidateCapabilityManifestResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: CapabilityDiagnostic[];
+};
+declare function defineCapabilityManifest(input: unknown): DefineCapabilityManifestResult;
+declare function parseCapabilityManifest(json: string | unknown): DefineCapabilityManifestResult;
+declare function toJSON(manifest: CapabilityManifest): CapabilityManifest;
+declare function validateCapabilityManifest(manifest: CapabilityManifest, hostCapabilities: HostCapabilities): ValidateCapabilityManifestResult;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Shared normalized coordinate, anchor, and hit-region contract. Hosts and
+ * adapters may adopt this later; pixel `PresentationRegion` is unchanged.
+ *
+ * Coordinate spaces:
+ * - `normalized` — 0–1 of the **content** box (full intrinsic artwork, not letterbox).
+ * - `asset` — intrinsic content pixels (`contentWidth` × `contentHeight`).
+ * - `css` / `viewport` — layout pixels (`viewportWidth` × `viewportHeight`).
+ * - `canvas` — drawing-buffer pixels (`css * devicePixelRatio`). Pointers match
+ *   `PointerManager` / harness `click` when the buffer is the drawing canvas.
+ *
+ * Pointer helpers default to **canvas** space. Pass `{ space: 'css' }` for
+ * layout pixels. Round-trip: `ROUND_TRIP_TOLERANCE` (1e-6 normalized) or
+ * `ROUND_TRIP_TOLERANCE_CANVAS_PX` (0.5 canvas px).
+ */
+declare const GEOMETRY_CONTRACT_VERSION: 1;
+/** Maximum |Δ| in normalized units after canvas/css round-trip. */
+declare const ROUND_TRIP_TOLERANCE = 0.000001;
+/** Maximum |Δ| in canvas pixels after normalized round-trip. */
+declare const ROUND_TRIP_TOLERANCE_CANVAS_PX = 0.5;
+declare const COORDINATE_SPACES: readonly ["normalized", "asset", "canvas", "css", "viewport"];
+type CoordinateSpace = (typeof COORDINATE_SPACES)[number];
+type PointerSpace = 'canvas' | 'css';
+type PresentationFitMode = 'contain' | 'cover' | 'crop';
+declare const ANCHOR_ORIGINS: readonly ["center", "top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"];
+type AnchorOrigin = (typeof ANCHOR_ORIGINS)[number];
+type NormalizedPoint = {
+    x: number;
+    y: number;
+};
+type NormalizedRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type NormalizedPolygon = readonly NormalizedPoint[];
+type PixelPoint = {
+    x: number;
+    y: number;
+};
+type PixelRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type GeometryPadding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Insets from the content edges in normalized units (0–1). */
+type GeometrySafeArea = GeometryPadding;
+type GeometryAnchor = {
+    id: string;
+    point: NormalizedPoint;
+    origin?: AnchorOrigin;
+};
+type GeometryHitbox = {
+    id: string;
+    rect?: NormalizedRect;
+    polygon?: NormalizedPolygon;
+};
+type GeometryDocument = {
+    version: typeof GEOMETRY_CONTRACT_VERSION;
+    landmarks: GeometryAnchor[];
+    regions: GeometryHitbox[];
+    padding?: GeometryPadding;
+    safeArea?: GeometrySafeArea;
+};
+type CreatePresentationLayoutInput = {
+    contentWidth: number;
+    contentHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    mode: PresentationFitMode;
+    /** Canvas buffer pixels per CSS pixel. Default 1. */
+    devicePixelRatio?: number;
+};
+type PresentationLayout = {
+    mode: PresentationFitMode;
+    contentWidth: number;
+    contentHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    /** Content → CSS pixels. */
+    scale: number;
+    /** Letterbox (positive) or crop (negative) offset of content origin in CSS. */
+    offsetX: number;
+    offsetY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    /** Visible slice of the content box in normalized space. */
+    visibleNormalizedRect: NormalizedRect;
+};
+type GeometryDiagnostic = {
+    code: 'out-of-bounds' | 'overlap' | 'duplicate-id' | 'invalid-shape' | 'version-mismatch';
+    id?: string;
+    detail: string;
+    with?: string;
+};
+type GeometryValidation = {
+    ok: boolean;
+    diagnostics: GeometryDiagnostic[];
+};
+type LandmarkRegisterResult = {
+    ok: true;
+    landmark: GeometryAnchor;
+} | {
+    ok: false;
+    error: 'duplicate-id';
+    id: string;
+};
+type LandmarkRegistry = {
+    register(landmark: GeometryAnchor): LandmarkRegisterResult;
+    get(id: string): GeometryAnchor | undefined;
+    list(): GeometryAnchor[];
+};
+type DebugDrawCall = {
+    method: string;
+    id?: string;
+    args: unknown[];
+};
+type GeometryDebugContext = {
+    fillStyle?: string;
+    strokeStyle?: string;
+    font?: string;
+    fillRect?(x: number, y: number, w: number, h: number): void;
+    strokeRect?(x: number, y: number, w: number, h: number): void;
+    fillText?(text: string, x: number, y: number): void;
+    beginPath?(): void;
+    moveTo?(x: number, y: number): void;
+    lineTo?(x: number, y: number): void;
+    closePath?(): void;
+    stroke?(): void;
+    fill?(): void;
+};
+declare function pointFromOrigin(origin: AnchorOrigin): NormalizedPoint;
+declare function createPresentationLayout(input: CreatePresentationLayoutInput): PresentationLayout;
+declare function normalizedToAsset(point: NormalizedPoint, layout: PresentationLayout): PixelPoint;
+declare function assetToNormalized(point: PixelPoint, layout: PresentationLayout): NormalizedPoint;
+declare function normalizedToCss(point: NormalizedPoint, layout: PresentationLayout): PixelPoint;
+declare function cssToNormalized(point: PixelPoint, layout: PresentationLayout): NormalizedPoint;
+declare function cssToCanvas(point: PixelPoint, layout: PresentationLayout): PixelPoint;
+declare function canvasToCss(point: PixelPoint, layout: PresentationLayout): PixelPoint;
+declare function normalizedToCanvas(point: NormalizedPoint, layout: PresentationLayout): PixelPoint;
+declare function canvasToNormalized(point: PixelPoint, layout: PresentationLayout): NormalizedPoint;
+declare function rectToCss(rect: NormalizedRect, layout: PresentationLayout): PixelRect;
+declare function rectToCanvas(rect: NormalizedRect, layout: PresentationLayout): PixelRect;
+/**
+ * Pointer is in **canvas** pixels unless `{ space: 'css' }` is passed.
+ * Returns the first region whose rect or polygon contains the point, in
+ * document order.
+ */
+declare function pointerToRegion(pointer: PixelPoint, layout: PresentationLayout, doc: GeometryDocument, options?: {
+    space?: PointerSpace;
+}): GeometryHitbox | undefined;
+/** Visible CSS (viewport) rectangle for a region; polygons use their AABB. */
+declare function regionToViewport(region: GeometryHitbox, layout: PresentationLayout): PixelRect | undefined;
+declare function createLandmarkRegistry(initial?: readonly GeometryAnchor[]): LandmarkRegistry;
+declare function validateGeometry(doc: GeometryDocument): GeometryValidation;
+/**
+ * Draws labeled region rects and reports validation failures as extra labels.
+ * Tests may pass a stub that records `fillRect` / `strokeRect` / `fillText`.
+ */
+declare function drawGeometryDebug(ctx: GeometryDebugContext, layout: PresentationLayout, doc: GeometryDocument, diagnostics?: readonly GeometryDiagnostic[]): DebugDrawCall[];
+declare function serializeGeometry(doc: GeometryDocument): string;
+declare function parseGeometry(json: string): GeometryDocument;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * First-class multi-cart runtime group. Creates production `createRuntime`
+ * instances, attaches each mailbox to one shared `createEventRouter`, and
+ * locksteps a deterministic clock. Carts never receive the router object.
+ */
+
+declare const DEFAULT_GROUP_WIDTH = 320;
+declare const DEFAULT_GROUP_HEIGHT = 180;
+type RuntimeGroupKind = 'render' | 'calculation';
+/**
+ * Optional capability-shaped attach hints. Explicit participant `emit` /
+ * `subscribe` / `authoritative` win. Do not import the capability manifest
+ * module from this file.
+ */
+type RuntimeGroupCapability = {
+    emit?: string[];
+    subscribe?: string[];
+    authoritative?: boolean;
+};
+type RuntimeGroupFrameError = {
+    error: unknown;
+    info: FrameErrorInfo;
+};
+type RuntimeGroupParticipantConfig<T = unknown> = {
+    id: string;
+    cart: AnimationCart<T>;
+    /** Rendered surface vs calculation cart (still a real `AnimationCart`). */
+    kind?: RuntimeGroupKind;
+    seed?: CreateRuntimeOptions['seed'];
+    container?: HTMLElement;
+    width?: number;
+    height?: number;
+    initialState?: Partial<T>;
+    gameManager?: unknown;
+    onEvent?: HostEventListener;
+    emit?: string[];
+    subscribe?: string[];
+    authoritative?: boolean;
+    capability?: RuntimeGroupCapability;
+};
+type CreateRuntimeGroupOptions = {
+    participants: RuntimeGroupParticipantConfig[];
+    /** Shared virtual-clock origin (ms). Default 0. */
+    origin?: number;
+    width?: number;
+    height?: number;
+    validate?: EventRouterOptions['validate'];
+    createId?: () => string;
+    now?: () => number;
+    /** Extra router options. Group injects shared `createId` / `now` unless set here. */
+    router?: EventRouterOptions;
+};
+type RuntimeGroupParticipantInspect = {
+    state: unknown;
+    events: HostEvent[];
+    errors: RuntimeGroupFrameError[];
+    kind: RuntimeGroupKind;
+    clock: ClockSnapshot;
+};
+type RuntimeGroupDiagnostics = {
+    paused: boolean;
+    participantIds: string[];
+    clocks: Record<string, ClockSnapshot>;
+    rejections: unknown[];
+};
+type RuntimeGroupInspect = {
+    participants: Record<string, RuntimeGroupParticipantInspect>;
+    trace: EventEnvelope[];
+    diagnostics: RuntimeGroupDiagnostics;
+};
+type RuntimeGroupParticipantHandle = {
+    readonly id: string;
+    readonly kind: RuntimeGroupKind;
+    readonly runtime: CyberArtRuntime;
+    readonly container: HTMLElement;
+    readonly events: readonly HostEvent[];
+    readonly errors: readonly RuntimeGroupFrameError[];
+    get cart(): CartHandle;
+};
+type RuntimeGroup = {
+    readonly router: EventRouter;
+    readonly origin: number;
+    readonly paused: boolean;
+    participant(id: string): RuntimeGroupParticipantHandle;
+    step(frames?: number): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reset(): void;
+    dispatch(participantId: string, event: HostEvent): void;
+    publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
+    inspect(): Promise<RuntimeGroupInspect>;
+    destroy(): void;
+};
+declare function createRuntimeGroup(options: CreateRuntimeGroupOptions): RuntimeGroup;
+
+export { ANCHOR_ORIGINS, ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, type AnchorOrigin, 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, CAPABILITY_ASSET_KINDS, CAPABILITY_INTEGRATIONS, CAPABILITY_MANAGERS, CAPABILITY_MANIFEST_VERSION, CAPABILITY_PHASES, COORDINATE_SPACES, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CapabilityAssetDeclarationSummary, type CapabilityAssetKind, type CapabilityAssetSummary, type CapabilityDiagnostic, type CapabilityIntegration, type CapabilityManager, type CapabilityManifest, type CapabilityManifestInput, type CapabilityPermissions, type CapabilityPhase, type CapabilityRuntime, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type Clock, type ClockSnapshot, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CoordinateSpace, type CreateAssetPreloaderOptions, type CreatePresentationLayoutInput, type CreatePresentationTimelineOptions, type CreateRuntimeGroupOptions, 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_GROUP_HEIGHT, DEFAULT_GROUP_WIDTH, DEFAULT_MAX_HOPS, type DebugDrawCall, type DefineCapabilityManifestResult, 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, GEOMETRY_CONTRACT_VERSION, type GeometryAnchor, type GeometryDebugContext, type GeometryDiagnostic, type GeometryDocument, type GeometryHitbox, type GeometryPadding, type GeometrySafeArea, type GeometryValidation, type HostCapabilities, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, KeyboardManager, type LandmarkRegisterResult, type LandmarkRegistry, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, type NormalizedPoint, type NormalizedPolygon, type NormalizedRect, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PixelPoint, type PixelRect, type PlayCueResult, type PointerClick, PointerManager, type PointerSpace, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationFitMode, type PresentationLayout, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REJECTED_EVENT_TYPE, ROUND_TRIP_TOLERANCE, ROUND_TRIP_TOLERANCE_CANVAS_PX, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayMetadata, type ResolvedAsset, type RuntimeGroup, type RuntimeGroupCapability, type RuntimeGroupDiagnostics, type RuntimeGroupFrameError, type RuntimeGroupInspect, type RuntimeGroupKind, type RuntimeGroupParticipantConfig, type RuntimeGroupParticipantHandle, type RuntimeGroupParticipantInspect, SILENT_ASSET_FALLBACK_REF, type SchemaCompatibility, type ScriptedAction, type TokenData, type ValidateCapabilityManifestResult, type ValidateResult, type VirtualClock, applyCueEasing, assetStatusEvent, assetToNormalized, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, canvasToCss, canvasToNormalized, toJSON as capabilityManifestToJSON, comparePayloadSchemas, createAssetFailure, createAssetPreloader, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createLandmarkRegistry, createPresentationLayout, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createRuntime, createRuntimeGroup, createVirtualClock, createWallClock, cssToCanvas, cssToNormalized, defineCapabilityManifest, defineDiagnostic, defineIntent, defineStateEvent, deriveAttachOptions, describeReplayMismatch, drawGeometryDebug, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isCueLifecycleType, isPresentationModel, isPresentationPhase, kindSegmentInType, matchEventPattern, mountPresentationAdapter, normalizeEvent, normalizedToAsset, normalizedToCanvas, normalizedToCss, parseCapabilityManifest, parseGeometry, pointFromOrigin, pointerToRegion, rectToCanvas, rectToCss, regionToViewport, registerCartStateHotkeys, resolveRuntimeSeed, rewriteHostedAssetRef, serializeGeometry, validateCapabilityManifest, validateGeometry, verifyAttachOptions };