@cyberart-io/engine 0.0.2 → 0.0.3

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,295 @@ 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;
+
+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 };