@cyberart-io/engine 0.0.8 → 0.0.10

package/dist/headless.d.ts

@@ -440,9 +440,17 @@ type SnapshotIntegrity = {
     alg: string;
     hash: string;
 };
+type SnapshotSignatureRef = {
+    id: string;
+    alg: string;
+};
 type SnapshotProvenance = {
     source?: string;
     integrity?: SnapshotIntegrity;
+    publisher?: string;
+    version?: string;
+    signature?: SnapshotSignatureRef;
+    grants?: string[];
 };
 type SnapshotEnvelope = {
     schemaVersion: typeof SNAPSHOT_SCHEMA_VERSION;
@@ -472,7 +480,7 @@ type ExportSnapshotOptions = {
 
 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"];
+declare const ASSET_FAILURE_CODES: readonly ["timeout", "cors", "not-found", "invalid", "aborted", "resolver", "undeclared", "hash-mismatch", "unsigned"];
 type AssetFailureCode = (typeof ASSET_FAILURE_CODES)[number];
 type AssetCorsMode = 'anonymous' | 'use-credentials' | 'omit';
 type AssetProvenance = {
@@ -926,10 +934,14 @@ type RuntimeGroupParticipantInspect = {
     emit: string[];
     subscribe: string[];
     authoritative: boolean;
+    /** True when the group skips this slot on `step` (portal parent suspend). */
+    suspended: boolean;
 };
 type RuntimeGroupDiagnostics = {
     paused: boolean;
     participantIds: string[];
+    /** Participants skipped by `step` until `resumeParticipant`. Sorted. */
+    suspendedIds: string[];
     clocks: Record<string, ClockSnapshot>;
     rejections: unknown[];
 };
@@ -961,6 +973,13 @@ type RuntimeGroup = {
     resize(width: number, height: number): void;
     /** Tear down one participant without destroying the group or blanking siblings. */
     detach(id: string): void;
+    /**
+     * Pause this cart's live loop and skip it on group `step`. Snapshot-safe
+     * state is retained. Used by portal lifecycle; does not pause siblings.
+     */
+    suspendParticipant(id: string): void;
+    resumeParticipant(id: string): void;
+    isParticipantSuspended(id: string): boolean;
     dispatch(participantId: string, event: HostEvent): void;
     publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
     inspectParticipants(): Array<RouterParticipantInspect & {
@@ -1425,6 +1444,183 @@ declare function replayExportedTrace(exported: ReplayInspectorExport, group: Run
     report: ReplayInspectorReport;
 }>;
 
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Content-selection and presentation-decision traces. Hosts record why a
+ * binding, revision, asset, sequence, or fallback won. Reuses CYB-65
+ * redaction, bounded retention, and correlation ids. There is no Player UI.
+ */
+
+declare const SELECTION_TRACE_SCHEMA_VERSION: 1;
+declare const DEFAULT_MAX_SELECTION_RECORDS = 512;
+declare const SELECTION_REASON_CODES: readonly ["binding-conflict", "asset-failure", "revision-rollback", "sequence-interruption", "text-only-fallback"];
+type SelectionReasonCode = (typeof SELECTION_REASON_CODES)[number];
+declare const SELECTION_DECISION_KINDS: readonly ["state-projection", "binding", "content-revision", "staging", "asset", "sequence", "presentation", "snapshot"];
+type SelectionDecisionKind = (typeof SELECTION_DECISION_KINDS)[number];
+declare const SELECTION_TRACE_SENSITIVE_KEYS: readonly ["prompt", "credentials", "credential", "authorization", "apiKey", "secret", "privatePrompt", "signedUrl", "signedURL", "signed_url", "presignedUrl", "password"];
+declare function isSelectionReasonCode(value: unknown): value is SelectionReasonCode;
+declare function isSelectionDecisionKind(value: unknown): value is SelectionDecisionKind;
+type SelectionBindingEvaluation = {
+    bindingId: string;
+    priority: number;
+    predicateResult: boolean;
+    winner?: boolean;
+    rejectedReason?: string;
+};
+type SelectionContentIdentity = {
+    contentId: string;
+    revision: string;
+    manifestVersion?: number;
+    source?: string;
+    publisher?: string;
+    hashes?: Record<string, string>;
+};
+type SelectionStagingOutcome = 'validated' | 'rejected' | 'cache-hit' | 'cache-miss' | 'superseded' | 'rollback' | 'retained';
+type SelectionStagingResult = {
+    outcome: SelectionStagingOutcome;
+    cache?: 'hit' | 'miss';
+    detail?: string;
+};
+type SelectionAssetResolution = {
+    logicalRef: string;
+    resolver?: string;
+    adapter?: string;
+    mediaHash?: string;
+    ready: boolean;
+    failure?: string;
+    fallback?: string | null;
+};
+type SelectionSequenceDecision = {
+    sequenceId: string;
+    invocationId: string;
+    stepId?: string | null;
+    track?: string | null;
+    decision: 'play' | 'skip' | 'interrupt' | 'replay' | 'complete';
+    capabilityFallback?: string | null;
+};
+type SelectionPresentationDecision = {
+    layerId?: string;
+    variant?: string;
+    regionId?: string;
+    maskRevision?: string | number;
+    blend?: string;
+    hitTest?: boolean;
+    caption?: string | null;
+    audioIntent?: string | null;
+};
+type SelectionSnapshotProvenance = {
+    revision?: string | number | null;
+    schemaVersion?: number;
+    seed?: string;
+};
+type SelectionDecisionInput = {
+    kind: SelectionDecisionKind;
+    reason: SelectionReasonCode | string;
+    summary: string;
+    turn?: number;
+    time?: number;
+    correlationId?: string;
+    causationId?: string;
+    envelopeId?: string;
+    initiatingEventType?: string;
+    projectionRevision?: string | number;
+    projection?: unknown;
+    hostState?: unknown;
+    bindings?: readonly SelectionBindingEvaluation[];
+    winningBindingId?: string | null;
+    rejectedBindingIds?: readonly string[];
+    defaultFallback?: boolean;
+    requestedContent?: SelectionContentIdentity;
+    activatedContent?: SelectionContentIdentity | null;
+    staging?: SelectionStagingResult;
+    lastKnownGood?: SelectionContentIdentity | null;
+    asset?: SelectionAssetResolution;
+    sequence?: SelectionSequenceDecision;
+    presentation?: SelectionPresentationDecision;
+    snapshot?: SelectionSnapshotProvenance;
+};
+type SelectionDecisionRecord = {
+    index: number;
+    kind: SelectionDecisionKind;
+    reason: string;
+    summary: string;
+    turn?: number;
+    time?: number;
+    correlationId?: string;
+    causationId?: string;
+    envelopeId?: string;
+    initiatingEventType?: string;
+    projectionRevision?: string | number;
+    projection?: unknown;
+    bindings?: SelectionBindingEvaluation[];
+    winningBindingId?: string | null;
+    rejectedBindingIds?: string[];
+    defaultFallback?: boolean;
+    requestedContent?: SelectionContentIdentity;
+    activatedContent?: SelectionContentIdentity | null;
+    staging?: SelectionStagingResult;
+    lastKnownGood?: SelectionContentIdentity | null;
+    asset?: SelectionAssetResolution;
+    sequence?: SelectionSequenceDecision;
+    presentation?: SelectionPresentationDecision;
+    snapshot?: SelectionSnapshotProvenance;
+};
+type SelectionTraceFilter = {
+    kinds?: readonly SelectionDecisionKind[];
+    reasons?: readonly string[];
+    correlationId?: string;
+    causationId?: string;
+    envelopeId?: string;
+    contentId?: string;
+    sequenceId?: string;
+};
+type CreateSelectionTraceOptions = {
+    redactedKeys?: readonly string[];
+    maxRecords?: number;
+    sampleRate?: number;
+    /** Safe host-projection field names. All other projection/hostState keys redact. */
+    projectionWhitelist?: readonly string[];
+    inspector?: Pick<ReplayInspector, 'records'>;
+};
+type SelectionTraceExport = {
+    schemaVersion: typeof SELECTION_TRACE_SCHEMA_VERSION;
+    redactedKeys: string[];
+    projectionWhitelist: string[];
+    dropped: number;
+    sampledOut: number;
+    records: SelectionDecisionRecord[];
+    inspectorRecords: InspectorRecord[];
+    snapshotRevision?: string | number | null;
+    snapshotSchemaVersion?: number;
+    snapshotSeed?: string;
+};
+type SelectionTraceReport = {
+    schemaVersion: typeof SELECTION_TRACE_SCHEMA_VERSION;
+    records: SelectionDecisionRecord[];
+    dropped: number;
+    sampledOut: number;
+};
+type SelectionTrace = {
+    recordSelectionDecision(input: SelectionDecisionInput): SelectionDecisionRecord | null;
+    records(filter?: SelectionTraceFilter): SelectionDecisionRecord[];
+    query(filter?: SelectionTraceFilter): SelectionDecisionRecord[];
+    chain(correlationId: string): SelectionDecisionRecord[];
+    exportTrace(filter?: SelectionTraceFilter): SelectionTraceExport;
+    importTrace(exported: SelectionTraceExport | string): void;
+    report(filter?: SelectionTraceFilter): SelectionTraceReport;
+    setSnapshotProvenance(meta: SelectionSnapshotProvenance): void;
+    reset(): void;
+    destroy(): void;
+};
+declare function recordSelectionDecision(trace: SelectionTrace, input: SelectionDecisionInput): SelectionDecisionRecord | null;
+declare function attachSelectionTrace<T extends object>(bundle: T, trace: SelectionTraceExport | null): T & {
+    selectionTrace: SelectionTraceExport | null;
+};
+declare function createSelectionTrace(options?: CreateSelectionTraceOptions): SelectionTrace;
+
 type CueEasing = 'linear' | 'ease-out';
 type CueDuplicatePolicy = 'ignore' | 'replace' | 'reject';
 type CueRepeatPolicy = {
@@ -1482,6 +1678,7 @@ type PlayCueResult = {
  */
 
 declare const AUDIO_CUE_EVENTS: readonly ["audio.cue.scheduled", "audio.cue.started", "audio.cue.skipped", "audio.cue.failed"];
+declare const AUDIO_CUE_SNAPSHOT_SCHEMA_VERSION: 1;
 type AudioCueEventType = (typeof AUDIO_CUE_EVENTS)[number];
 type AudioCueSkipReason = 'reduced-sensory' | 'muted' | 'unauthorized';
 type AudioCueFailReason = 'asset-failed' | 'torn-down' | 'invalid';
@@ -1499,6 +1696,8 @@ type AudioCueView = CueView & {
     participantId?: string;
     priority: number;
     audioPhase: 'scheduled' | 'started' | 'skipped' | 'failed' | 'completed';
+    /** Original play spec; omitted when the cue was not repeating. */
+    repeat?: CueRepeatPolicy;
 };
 type AudioCueEvent = {
     type: AudioCueEventType;
@@ -1512,11 +1711,28 @@ type AudioCueEvent = {
     progress: number;
 };
 type AudioCueTimelineSnapshot = {
+    schemaVersion: typeof AUDIO_CUE_SNAPSHOT_SCHEMA_VERSION;
     frame: number;
     reducedSensory: boolean;
     cues: AudioCueView[];
     events: AudioCueEvent[];
 };
+type HeadlessAudioAdapterSnapshot = AudioCueTimelineSnapshot & {
+    unlock: AudioUnlockStatus;
+    muted: boolean;
+};
+type AudioCueDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type RestoreAudioCueResult = {
+    ok: true;
+    snapshot: AudioCueTimelineSnapshot;
+} | {
+    ok: false;
+    errors: AudioCueDiagnostic[];
+};
 type PlayAudioCueResult = {
     ok: true;
     cue: AudioCueView;
@@ -1531,8 +1747,15 @@ type AudioCueTimeline = {
     cancel(idempotencyKey: string): boolean;
     reset(): void;
     snapshot(): AudioCueTimelineSnapshot;
+    restore(input: unknown): RestoreAudioCueResult;
     get(idempotencyKey: string): AudioCueView | undefined;
     dispose(): void;
+    /**
+     * Updates skip-playback for future cue starts. Already-started cues
+     * continue; scheduled cues that have not started yet use the new flag
+     * when they start.
+     */
+    setReducedSensory(value: boolean): void;
     readonly frame: number;
     readonly reducedSensory: boolean;
 };
@@ -1543,12 +1766,13 @@ type HeadlessAudioAdapter = {
     play(spec: AudioCueSpec): PlayAudioCueResult;
     step(frames?: number): AudioCueEvent[];
     handleHostEvent(event: HostEvent): void;
-    snapshot(): AudioCueTimelineSnapshot & {
-        unlock: AudioUnlockStatus;
-        muted: boolean;
-    };
+    snapshot(): HeadlessAudioAdapterSnapshot;
+    restore(input: unknown): RestoreAudioCueResult;
     destroy(): void;
+    setReducedSensory(value: boolean): void;
+    readonly reducedSensory: boolean;
 };
+declare function parseAudioCueSnapshot(input: unknown): RestoreAudioCueResult;
 declare function createHeadlessAudioAdapter(options?: {
     reducedSensory?: boolean;
     originFrame?: number;
@@ -1697,9 +1921,15 @@ type VisualLayerController = {
     inspect(): VisualLayerInspect[];
     captureComposedFrame(): ComposedFrame;
     destroy(): void;
+    /**
+     * Updates the host flag used by future `play()` calls. In-flight
+     * transitions keep the durations they were compiled with.
+     */
+    setReducedMotion(value: boolean): void;
     readonly frame: number;
     readonly sceneId: string | null;
     readonly compositor: Compositor;
+    readonly reducedMotion: boolean;
 };
 type VisualLayerCapture = {
     frame: ComposedFrame;
@@ -1713,47 +1943,2402 @@ declare function createVisualLayerController(options: CreateVisualLayerControlle
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
  * See packages/engine/LICENSE
  *
- * Cart-agnostic update/render frame benchmark for CI and agent workflows.
- * Prefer this over ad-hoc vitest probes when evaluating hash / trait cost.
+ * 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;
+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 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 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 FrameBenchmarkOptions = {
-    /** Measured frames after warmup. Default 30. */
-    frames?: number;
-    /** Discarded frames before measurement. Default 5. */
-    warmupFrames?: number;
-    /** Simulated frame advance in ms. Default 1000/60. */
-    frameStepMs?: number;
-    width?: number;
-    height?: number;
-    tokenId?: string;
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Cart-published named semantic regions (mask / polygon / depth) in normalized
+ * space. The host drives hover/focus/selected and supplies a11y names/roles.
+ * Geometry, blend, and hit-test policy stay with the cart. Snapshot JSON is
+ * hostState-safe. Headless inspect does not require a DOM overlay.
+ */
+
+declare const SEMANTIC_LAYER_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const SEMANTIC_GEOMETRY_KINDS: readonly ["mask", "polygon", "rect", "depth"];
+type SemanticGeometryKind = (typeof SEMANTIC_GEOMETRY_KINDS)[number];
+declare const SEMANTIC_HIT_TEST_POLICIES: readonly ["pass-through", "absorb", "exclusive", "depth-ordered"];
+type SemanticHitTestPolicy = (typeof SEMANTIC_HIT_TEST_POLICIES)[number];
+declare const SEMANTIC_APPEARANCE_KEYS: readonly ["idle", "hover", "focus", "selected"];
+type SemanticAppearanceKey = (typeof SEMANTIC_APPEARANCE_KEYS)[number];
+type SemanticRegionState = {
+    hover: boolean;
+    focus: boolean;
+    selected: boolean;
+};
+type SemanticRegionA11y = {
+    name: string;
+    role: string;
+};
+type SemanticMaskGrid = {
+    width: number;
+    height: number;
+    /** Row-major coverage in [0, 1]. Length must be width * height. */
+    alpha: readonly number[];
+    /** Where the grid maps in normalized space. Default full content box. */
+    bounds?: NormalizedRect;
+};
+type SemanticRegionGeometry = {
+    mask?: SemanticMaskGrid;
+    polygon?: NormalizedPolygon;
+    rect?: NormalizedRect;
+    /** Higher values are closer to the viewer. Default 0. */
+    depth?: number;
+};
+type SemanticRegionVisual = {
+    opacity?: number;
+    blend?: CompositorBlendMode;
+    /** Visual-layer version applied when `visualLayerId` is set. */
+    version?: string;
+};
+type SemanticRegionVisuals = Partial<Record<SemanticAppearanceKey, SemanticRegionVisual>>;
+type SemanticRegionDeclaration = {
+    id: string;
+    geometry: SemanticRegionGeometry;
+    hitTest?: SemanticHitTestPolicy;
+    blend?: CompositorBlendMode;
+    order?: number;
+    compositorLayerId?: string;
+    visualLayerId?: string;
+    visuals?: SemanticRegionVisuals;
+    initialState?: Partial<SemanticRegionState>;
+};
+type SemanticRegionInspect = {
+    id: string;
+    geometryKinds: SemanticGeometryKind[];
+    hitTest: SemanticHitTestPolicy;
+    blend: CompositorBlendMode;
+    order: number;
+    depth: number;
+    state: SemanticRegionState;
+    appearance: SemanticAppearanceKey;
+    a11y: SemanticRegionA11y | null;
+    visual: SemanticRegionVisual;
+};
+type SemanticPublishedRegion = {
+    id: string;
+    geometryKinds: SemanticGeometryKind[];
+    a11y: SemanticRegionA11y | null;
+};
+type SemanticRegionSnapshotRow = {
+    id: string;
+    geometry: SemanticRegionGeometry;
+    hitTest: SemanticHitTestPolicy;
+    blend: CompositorBlendMode;
+    order: number;
+    compositorLayerId: string | null;
+    visualLayerId: string | null;
+    visuals: SemanticRegionVisuals;
+    state: SemanticRegionState;
+    a11y: SemanticRegionA11y | null;
+};
+type SemanticLayerControllerSnapshot = {
+    schemaVersion: typeof SEMANTIC_LAYER_SNAPSHOT_SCHEMA_VERSION;
+    frame: number;
+    regions: SemanticRegionSnapshotRow[];
+};
+type RestoreSemanticLayerResult = {
+    ok: true;
+    snapshot: SemanticLayerControllerSnapshot;
+} | {
+    ok: false;
+    errors: string[];
+};
+type CreateSemanticLayerControllerOptions = {
+    regions: readonly SemanticRegionDeclaration[];
+    compositor?: Compositor;
+    visualLayers?: VisualLayerController;
+    originFrame?: number;
+};
+type SemanticLayerController = {
+    list(): SemanticRegionInspect[];
+    inspect(): SemanticRegionInspect[];
+    inspectPublished(): SemanticPublishedRegion[];
+    get(id: string): SemanticRegionInspect | undefined;
+    geometryOf(id: string): SemanticRegionGeometry | undefined;
+    setRegionState(id: string, state: Partial<SemanticRegionState>): void;
+    setRegionA11y(id: string, a11y: SemanticRegionA11y | null): void;
+    hitTest(point: NormalizedPoint): SemanticRegionInspect | undefined;
+    hitTestAll(point: NormalizedPoint): SemanticRegionInspect[];
+    snapshot(): SemanticLayerControllerSnapshot;
+    restore(input: unknown): RestoreSemanticLayerResult;
+    destroy(): void;
+    readonly frame: number;
+};
+declare function createSemanticLayerController(options: CreateSemanticLayerControllerOptions): SemanticLayerController;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Cross-modal presentation sequences. One frame-stepped clock coordinates
+ * audio, captions, semantic-region state, visual layers, and typed cues.
+ * Authored content is JSON-serializable: no callbacks, no ambient host access.
+ * Dialogue graphs and game rules stay with the host.
+ */
+
+declare const PRESENTATION_SEQUENCE_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const PRESENTATION_SEQUENCE_EVENTS: readonly ["presentation.sequence.state.requested", "presentation.sequence.state.preloading", "presentation.sequence.state.ready", "presentation.sequence.state.started", "presentation.sequence.state.step-started", "presentation.sequence.state.step-completed", "presentation.sequence.state.skipped", "presentation.sequence.state.interrupted", "presentation.sequence.state.failed", "presentation.sequence.state.completed", "presentation.sequence.diagnostic.lifecycle"];
+type PresentationSequenceEventType = (typeof PRESENTATION_SEQUENCE_EVENTS)[number];
+declare const PRESENTATION_TRACK_KINDS: readonly ["audio", "caption", "semantic-region", "visual-layer", "cue"];
+type PresentationTrackKind = (typeof PRESENTATION_TRACK_KINDS)[number];
+declare const PRESENTATION_INTERRUPTION_POLICIES: readonly ["replace", "queue", "reject", "ignore"];
+type PresentationInterruptionPolicy = (typeof PRESENTATION_INTERRUPTION_POLICIES)[number];
+declare const PRESENTATION_COMPLETION_RULES: readonly ["duration", "immediate"];
+type PresentationCompletionRule = (typeof PRESENTATION_COMPLETION_RULES)[number];
+declare const PRESENTATION_AUDIO_CAPABILITY_STATUSES: readonly ["unavailable", "failed", "unauthorized", "muted"];
+type PresentationAudioCapabilityStatus = (typeof PRESENTATION_AUDIO_CAPABILITY_STATUSES)[number];
+declare const PRESENTATION_INVOCATION_PHASES: readonly ["requested", "preloading", "ready", "playing", "paused", "skipped", "interrupted", "failed", "completed"];
+type PresentationInvocationPhase = (typeof PRESENTATION_INVOCATION_PHASES)[number];
+type PresentationSequenceDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type PresentationStepTiming = {
+    kind: 'absolute';
+    atFrame: number;
+} | {
+    kind: 'relative';
+    afterStepId?: string;
+    delayFrames?: number;
+} | {
+    kind: 'simultaneous';
+    withStepId: string;
+    order?: number;
+    delayFrames?: number;
+};
+type PresentationStepEffect = {
+    kind: 'audio';
+    assetBinding: string;
+    channelBinding?: string;
+} | {
+    kind: 'caption';
+    textBinding: string;
+    visible: boolean;
+} | {
+    kind: 'semantic-region';
+    regionBinding: string;
+    state: Partial<Pick<SemanticRegionState, 'hover' | 'focus' | 'selected'>>;
+} | {
+    kind: 'visual-layer';
+    layerBinding: string;
+    transition: Extract<VisualLayerTransitionKind, 'show' | 'hide'>;
+    versionBinding?: string;
+} | {
+    kind: 'cue';
+    name: string;
+    easing?: CueEasing;
+};
+type PresentationStepDefinition = {
+    id: string;
+    timing: PresentationStepTiming;
+    durationFrames: number;
+    delayFrames?: number;
+    completion?: PresentationCompletionRule;
+    effect: PresentationStepEffect;
+    restoreOnComplete?: boolean;
+    reducedMotion?: CueReducedMotionPolicy;
+    reducedSensory?: 'keep' | 'skip-audio' | 'complete';
+};
+type PresentationTrackDefinition = {
+    id: string;
+    kind: PresentationTrackKind;
+    steps: readonly PresentationStepDefinition[];
+};
+type PresentationFallbackWhen = {
+    capability: 'audio';
+    status: PresentationAudioCapabilityStatus;
+};
+type PresentationFallbackDefinition = {
+    id: string;
+    when: PresentationFallbackWhen;
+    omitTrackIds?: readonly string[];
+};
+type PresentationSequenceDefinition = {
+    id: string;
+    tracks: readonly PresentationTrackDefinition[];
+    interruptionPolicy?: PresentationInterruptionPolicy;
+    fallbacks?: readonly PresentationFallbackDefinition[];
+};
+type PresentationSequenceBindings = {
+    assets?: Record<string, string>;
+    captions?: Record<string, string>;
+    regions?: Record<string, string>;
+    layers?: Record<string, string>;
+    versions?: Record<string, string>;
+    channels?: Record<string, string>;
+};
+type PlaySequenceOptions = {
+    invocationId: string;
+    idempotencyKey?: string;
+    bindings?: PresentationSequenceBindings;
+};
+type DefinePresentationSequenceResult = {
+    ok: true;
+    sequence: PresentationSequenceDefinition;
+} | {
+    ok: false;
+    errors: PresentationSequenceDiagnostic[];
+};
+type PlaySequenceResult = {
+    ok: true;
+    invocation: PresentationInvocationView;
+} | {
+    ok: false;
+    reason: 'unknown-sequence' | 'invalid' | 'busy' | 'duplicate';
+    detail: string;
+};
+type RestorePresentationSequenceResult = {
+    ok: true;
+    snapshot: PresentationSequenceSnapshot;
+} | {
+    ok: false;
+    errors: PresentationSequenceDiagnostic[];
+};
+type PresentationSequenceEvent = {
+    type: PresentationSequenceEventType;
+    atFrame: number;
+    sequenceId: string;
+    invocationId: string;
+    idempotencyKey: string;
+    stepId?: string;
+    fallbackId?: string;
+    reason?: string;
+};
+type PresentationCaptionView = {
+    id: string;
+    text: string;
+    visible: boolean;
+};
+type PresentationCueIntent = {
+    sequenceId: string;
+    stepId: string;
+    trackId: string;
+    kind: PresentationTrackKind;
+    startFrame: number;
+    durationFrames: number;
+    order: number;
+    effect: PresentationStepEffect;
+};
+type PresentationInvocationView = {
+    sequenceId: string;
+    invocationId: string;
+    idempotencyKey: string;
+    phase: PresentationInvocationPhase;
+    playhead: number;
+    startedAtFrame: number;
+    completedStepIds: string[];
+    activeStepIds: string[];
+    selectedFallbackId: string | null;
+    /** Reduced-motion flag used to compile this invocation's step durations. */
+    compiledReducedMotion: boolean;
+};
+type PresentationSequenceSnapshot = {
+    schemaVersion: typeof PRESENTATION_SEQUENCE_SNAPSHOT_SCHEMA_VERSION;
+    frame: number;
+    reducedMotion: boolean;
+    reducedSensory: boolean;
+    paused: boolean;
+    active: PresentationInvocationView | null;
+    queue: PresentationSequenceSnapshotQueued[];
+    captions: PresentationCaptionView[];
+    events: PresentationSequenceEvent[];
+    bindings: PresentationSequenceBindings | null;
+};
+type PresentationSequenceSnapshotQueued = {
+    sequenceId: string;
+    invocationId: string;
+    idempotencyKey: string;
+    bindings: PresentationSequenceBindings;
+};
+type PresentationSequenceInspect = {
+    frame: number;
+    paused: boolean;
+    reducedMotion: boolean;
+    reducedSensory: boolean;
+    active: PresentationInvocationView | null;
+    queue: PresentationInvocationView[];
+    captions: PresentationCaptionView[];
+    cueIntent: PresentationCueIntent[];
+};
+type CreatePresentationSequencePlayerOptions = {
+    originFrame?: number;
+    reducedMotion?: boolean;
+    reducedSensory?: boolean;
+    audio?: AudioCueTimeline | HeadlessAudioAdapter;
+    semantic?: SemanticLayerController;
+    visual?: VisualLayerController;
+    sequences?: readonly PresentationSequenceDefinition[];
+};
+type PresentationSequencePlayer = {
+    define(input: PresentationSequenceDefinition): DefinePresentationSequenceResult;
+    playSequence(sequenceId: string, options: PlaySequenceOptions): PlaySequenceResult;
+    skip(invocationId?: string): boolean;
+    replay(invocationId?: string): PlaySequenceResult;
+    pause(): boolean;
+    resume(): boolean;
+    cancel(invocationId?: string): boolean;
+    step(frames?: number): PresentationSequenceEvent[];
+    snapshot(): PresentationSequenceSnapshot;
+    restore(input: unknown): RestorePresentationSequenceResult;
+    inspect(): PresentationSequenceInspect;
+    inspectCueIntent(sequenceId: string, options?: {
+        fallbackId?: string;
+    }): PresentationCueIntent[];
+    get(sequenceId: string): PresentationSequenceDefinition | undefined;
+    destroy(): void;
     /**
-     * Mutate state after `getDefaultState` (e.g. skip Tone init in jsdom by
-     * setting `audioContextStarted = true`).
+     * Updates the host flag used by future `playSequence` / cue-intent
+     * compilation. The active invocation **continues** with the durations it
+     * was compiled with. Queued plays that have not started yet use the new
+     * policy when they start.
      */
-    prepareState?: (state: unknown, featureState: unknown) => void;
-    /** Optional stub drawing context; defaults to a no-op `putImageData`. */
-    drawingContext?: CanvasRenderingContext2D;
-};
-type FrameBenchmarkResult = {
-    frames: number;
-    updateAvgMs: number;
-    renderAvgMs: number;
-    totalAvgMs: number;
-    updateMaxMs: number;
-    renderMaxMs: number;
-    estFps: number;
-    updatePct: number;
-    renderPct: number;
+    setReducedMotion(value: boolean): void;
+    readonly frame: number;
+    readonly reducedMotion: boolean;
+    readonly reducedSensory: boolean;
 };
+declare function presentationSequenceEventContracts(): EventContract[];
+declare function definePresentationSequence(input: unknown): DefinePresentationSequenceResult;
+declare function createPresentationSequencePlayer(options?: CreatePresentationSequencePlayerOptions): PresentationSequencePlayer;
+
 /**
- * Run a cart's update/render loop headlessly and report average / max phase
- * timings. Does not start audio or mount a live AnimationManager — suitable
- * for jsdom vitest and agent hash probes.
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Declarative projection of host-authoritative state into presentation
+ * resources. The host reducer stays the owner; this module evaluates a
+ * bounded, JSON-serializable binding manifest and applies one coherent
+ * presentation revision (or the declared fail-closed defaults).
  */
-declare function benchmarkCartFrames<T, TFeatureState = undefined>(cart: AnimationCart<T, TFeatureState>, hash: string, rawParams: number[], options?: FrameBenchmarkOptions): FrameBenchmarkResult;
-/** Round timing fields for stable console / snapshot logging. */
-declare function formatFrameBenchmarkResult(result: FrameBenchmarkResult, digits?: number): Record<string, number>;
+
+declare const PRESENTATION_BINDING_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const PRESENTATION_BINDING_MANIFEST_VERSION: 1;
+declare const PRESENTATION_BINDING_APPLIED_EVENT: "presentation.binding.state.applied";
+declare const PRESENTATION_BINDING_ERROR_CODES: readonly ["invalid-manifest", "invalid-schema", "invalid-version", "invalid-id", "unknown-field", "unknown-resource", "unknown-selector", "duplicate-id", "duplicate-priority", "uncovered-default", "impossible-target", "callbacks-forbidden", "invalid-predicate", "invalid-projection", "invalid-snapshot", "destroyed"];
+type PresentationBindingErrorCode = (typeof PRESENTATION_BINDING_ERROR_CODES)[number];
+type PresentationBindingDiagnostic = {
+    code: PresentationBindingErrorCode | string;
+    detail: string;
+    path?: string;
+};
+type JsonPrimitive = string | number | boolean | null;
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+type PresentationPredicate = {
+    path: string;
+    eq: JsonPrimitive;
+} | {
+    path: string;
+    neq: JsonPrimitive;
+} | {
+    path: string;
+    present: boolean;
+} | {
+    selector: string;
+} | {
+    all: PresentationPredicate[];
+} | {
+    any: PresentationPredicate[];
+} | {
+    not: PresentationPredicate;
+};
+type PresentationBindingTarget = {
+    kind: 'visual-layer';
+    layerId: string;
+    version: string;
+    transition?: Extract<VisualLayerTransitionKind, 'show' | 'hide' | 'replace'>;
+} | {
+    kind: 'presence';
+    entityId: string;
+    present: boolean;
+    regionId?: string;
+} | {
+    kind: 'prop';
+    propId: string;
+    visible: boolean;
+    layerId?: string;
+} | {
+    kind: 'semantic-region';
+    regionId: string;
+    state?: Partial<Pick<SemanticRegionState, 'hover' | 'focus' | 'selected'>>;
+    hitTestEnabled?: boolean;
+} | {
+    kind: 'hotspot';
+    hotspotId: string;
+    enabled: boolean;
+    regionId?: string;
+} | {
+    kind: 'sequence';
+    sequenceId: string;
+    play?: boolean;
+} | {
+    kind: 'asset';
+    bindingId: string;
+    assetId: string;
+};
+type PresentationBinding = {
+    id: string;
+    priority: number;
+    when: PresentationPredicate;
+    targets: readonly PresentationBindingTarget[];
+};
+type PresentationBindingResources = {
+    layers?: readonly string[];
+    versions?: Readonly<Record<string, readonly string[]>>;
+    regions?: readonly string[];
+    sequences?: readonly string[];
+    hotspots?: readonly string[];
+    entities?: readonly string[];
+    props?: readonly string[];
+    assets?: readonly string[];
+};
+type PresentationBindingManifest = {
+    id: string;
+    schemaVersion: typeof PRESENTATION_BINDING_MANIFEST_VERSION;
+    bindings: readonly PresentationBinding[];
+    defaults: readonly PresentationBindingTarget[];
+    resources?: PresentationBindingResources;
+};
+type DefinePresentationBindingsResult = {
+    ok: true;
+    manifest: PresentationBindingManifest;
+} | {
+    ok: false;
+    errors: PresentationBindingDiagnostic[];
+};
+type PresentationBindingSelector = (projection: JsonObject) => boolean;
+type PresentationBindingConsidered = {
+    bindingId: string;
+    predicateResult: boolean;
+    detail?: string;
+};
+type PresentationBindingRejected = {
+    bindingId: string;
+    targetKey: string;
+    reason: 'lower-priority' | 'predicate-false';
+};
+type PresentationBindingFallback = {
+    targetKey: string;
+    reason: 'uncovered-default' | 'missing-state' | 'invalid-projection';
+};
+type PresentationBindingExplanation = {
+    considered: PresentationBindingConsidered[];
+    winners: Record<string, {
+        bindingId: string | null;
+        target: PresentationBindingTarget;
+    }>;
+    rejected: PresentationBindingRejected[];
+    fallbacks: PresentationBindingFallback[];
+    fallbackReason: 'missing-state' | 'invalid-projection' | null;
+};
+type PresentationBindingEvaluation = {
+    selectedBindingIds: string[];
+    targets: PresentationBindingTarget[];
+    usedFallback: boolean;
+    fallbackReason: 'missing-state' | 'invalid-projection' | null;
+    explanation: PresentationBindingExplanation;
+};
+type HostPresentationOverride = {
+    labels?: Record<string, string | Pick<SemanticRegionA11y, 'name' | 'role'>>;
+    reducedSensory?: boolean;
+    reducedMotion?: boolean;
+};
+type PresentationBindingInspect = {
+    revision: string | number | null;
+    selectedBindingIds: string[];
+    layers: Record<string, string>;
+    presence: Record<string, boolean>;
+    props: Record<string, boolean>;
+    regions: Record<string, Partial<SemanticRegionState> & {
+        hitTestEnabled?: boolean;
+    }>;
+    hotspots: Record<string, boolean>;
+    sequences: Record<string, 'playing' | 'idle'>;
+    assets: Record<string, string>;
+    override: HostPresentationOverride | null;
+    usedFallback: boolean;
+    fallbackReason: 'missing-state' | 'invalid-projection' | null;
+    explanation: PresentationBindingExplanation | null;
+};
+type PresentationBindingSnapshot = {
+    schemaVersion: typeof PRESENTATION_BINDING_SNAPSHOT_SCHEMA_VERSION;
+    manifestId: string;
+    projectionRevision: string | number | null;
+    selectedBindingIds: string[];
+    targets: PresentationBindingTarget[];
+    usedFallback: boolean;
+    fallbackReason: 'missing-state' | 'invalid-projection' | null;
+    override: HostPresentationOverride | null;
+};
+type ApplyPresentationBindingsResult = {
+    ok: true;
+    revision: string | number;
+    selectedBindingIds: string[];
+    usedFallback: boolean;
+    fallbackReason: 'missing-state' | 'invalid-projection' | null;
+    explanation: PresentationBindingExplanation;
+    inspect: PresentationBindingInspect;
+} | {
+    ok: false;
+    errors: PresentationBindingDiagnostic[];
+    inspect: PresentationBindingInspect;
+};
+type RestorePresentationBindingsResult = {
+    ok: true;
+    snapshot: PresentationBindingSnapshot;
+} | {
+    ok: false;
+    errors: PresentationBindingDiagnostic[];
+};
+type CreatePresentationBindingRuntimeOptions = {
+    manifest: PresentationBindingManifest | unknown;
+    visual?: VisualLayerController;
+    semantic?: SemanticLayerController;
+    sequences?: PresentationSequencePlayer;
+    selectors?: Readonly<Record<string, PresentationBindingSelector>>;
+    router?: Pick<EventRouter, 'publish'>;
+    onEvent?: (event: EventInput) => void;
+};
+type PresentationBindingRuntime = {
+    apply(projection: unknown, options?: {
+        revision?: string | number;
+    }): ApplyPresentationBindingsResult;
+    setOverride(override: HostPresentationOverride | null): void;
+    evaluate(projection: unknown): PresentationBindingEvaluation;
+    inspect(): PresentationBindingInspect;
+    snapshot(): PresentationBindingSnapshot;
+    restore(input: unknown): RestorePresentationBindingsResult;
+    destroy(): void;
+    readonly manifest: PresentationBindingManifest;
+};
+declare function presentationBindingEventContracts(): EventContract[];
+declare function definePresentationBindings(input: unknown): DefinePresentationBindingsResult;
+declare function evaluatePresentationBindings(manifest: PresentationBindingManifest, projection: unknown, selectors?: Readonly<Record<string, PresentationBindingSelector>>): PresentationBindingEvaluation;
+declare function createPresentationBindingRuntime(options: CreatePresentationBindingRuntimeOptions): PresentationBindingRuntime;
+
+/**
+ * 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];
+declare const CAPABILITY_BLEND_MODES: readonly ["source-over", "screen"];
+type CapabilityBlendMode = (typeof CAPABILITY_BLEND_MODES)[number];
+declare const CAPABILITY_CLEAR_POLICIES: readonly ["transparent", "opaque"];
+type CapabilityClearPolicy = (typeof CAPABILITY_CLEAR_POLICIES)[number];
+declare const CAPABILITY_CART_KINDS: readonly ["render", "calculation"];
+type CapabilityCartKind = (typeof CAPABILITY_CART_KINDS)[number];
+/** Device/host grants a remote cart may request. Omitted on existing manifests. */
+declare const CAPABILITY_DEVICE_GRANTS: readonly ["audio", "controller", "network", "persistence", "fullscreen"];
+type CapabilityDeviceGrant = (typeof CAPABILITY_DEVICE_GRANTS)[number];
+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;
+};
+/** Optional surface requirements. Omitted on existing manifests. */
+type CapabilitySurfaceRequirements = {
+    alpha?: boolean;
+    clearPolicy?: CapabilityClearPolicy;
+};
+/** Optional compositor/layer requirements. Omitted on existing manifests. */
+type CapabilityLayerRequirements = {
+    compositor?: boolean;
+    blend?: CapabilityBlendMode[];
+};
+/** Optional executable-module refs. Omitted on existing manifests. */
+type CapabilityModuleRef = {
+    id: string;
+    version: string;
+};
+type CapabilityModuleRequirements = {
+    refs?: CapabilityModuleRef[];
+};
+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[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
+    /** Omitted means `'render'`. `'calculation'` carts have no surface. */
+    kind?: CapabilityCartKind;
+    /** Optional device grants (CYB-74). Omitted on existing manifests. */
+    grants?: CapabilityDeviceGrant[];
+};
+type HostCapabilities = {
+    contractVersion: number;
+    features: string[];
+    integrations: CapabilityIntegration[];
+    managers?: CapabilityManager[];
+    emit?: string[];
+    subscribe?: string[];
+    surface?: CapabilitySurfaceRequirements & {
+        clearPolicy?: CapabilityClearPolicy | CapabilityClearPolicy[];
+    };
+    layers?: CapabilityLayerRequirements;
+    modules?: CapabilityModuleRequirements;
+    /** Cart kinds this host can run. Omitted: kind is not checked. */
+    kinds?: CapabilityCartKind[];
+    /**
+     * Device grants this host is willing to give. Omitted is treated as an
+     * empty set (deny-by-default) when the cart listed `grants`.
+     */
+    grants?: CapabilityDeviceGrant[];
+};
+
+type ExecutableModuleRef = {
+    id: string;
+    version: string;
+};
+type ExecutableModuleCapabilities = {
+    readonly [key: string]: unknown;
+};
+type ExecutableModuleInvokeContext = {
+    signal: AbortSignal;
+    turn: number;
+};
+type ExecutableModuleInstance = {
+    invoke(input: unknown, context: ExecutableModuleInvokeContext): unknown | Promise<unknown>;
+    destroy?: () => void;
+};
+type ExecutableModuleFactory = (capabilities: ExecutableModuleCapabilities) => ExecutableModuleInstance;
+type ExecutableModuleRegistration = {
+    id: string;
+    version: string;
+    create: ExecutableModuleFactory;
+    capabilities?: ExecutableModuleCapabilities;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Signed, versioned remote-cart manifests. HMAC signatures, declared-asset
+ * loads, and deny-by-default host grants. Trusted factories only — no eval.
+ */
+
+declare const REMOTE_CART_MANIFEST_VERSION: 1;
+declare const REMOTE_CART_SIGNATURE_ALG: "hmac-sha256";
+declare const HOST_GRANT_SNAPSHOT_SCHEMA_VERSION: 1;
+type RemoteCartGrant = CapabilityDeviceGrant;
+declare const REMOTE_CART_ERROR_CODES: readonly ["invalid-json", "invalid-manifest", "invalid-version", "invalid-signature", "unknown-publisher", "unknown-key", "undeclared-asset", "hash-mismatch", "unsigned-bytes", "capability-denied", "destroyed", "load-failed"];
+type RemoteCartErrorCode = (typeof REMOTE_CART_ERROR_CODES)[number];
+type RemoteCartDiagnostic = {
+    code: RemoteCartErrorCode | string;
+    detail: string;
+    path?: string;
+};
+type RemoteCartAsset = {
+    id: string;
+    kind: AssetKind;
+    url: string;
+    hash: string;
+    alg: 'sha256';
+};
+type RemoteCartManifestBody = {
+    version: typeof REMOTE_CART_MANIFEST_VERSION;
+    id: string;
+    cartVersion: string;
+    publisher: string;
+    assets: RemoteCartAsset[];
+    requestedGrants: RemoteCartGrant[];
+    module?: ExecutableModuleRef;
+    capabilities?: CapabilityManifest;
+};
+type RemoteCartSignature = {
+    alg: typeof REMOTE_CART_SIGNATURE_ALG;
+    keyId: string;
+    mac: string;
+};
+type SignedRemoteCartManifest = {
+    body: RemoteCartManifestBody;
+    signature: RemoteCartSignature;
+};
+type HostGrantSnapshot = {
+    schemaVersion: typeof HOST_GRANT_SNAPSHOT_SCHEMA_VERSION;
+    grants: RemoteCartGrant[];
+};
+type HostGrantRestoreResult = {
+    ok: true;
+    grants: RemoteCartGrant[];
+} | {
+    ok: false;
+    errors: RemoteCartDiagnostic[];
+};
+type HostGrantSet = {
+    grant(capability: RemoteCartGrant): HostGrantRestoreResult;
+    revoke(capability: RemoteCartGrant): HostGrantRestoreResult;
+    has(capability: RemoteCartGrant): boolean;
+    list(): RemoteCartGrant[];
+    inspect(): HostGrantSnapshot;
+    restore(input: unknown): HostGrantRestoreResult;
+};
+type RemoteCartNetworkApi = {
+    fetch(url: string): Promise<Uint8Array>;
+};
+type RemoteCartStorageApi = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+};
+type RemoteCartDeviceApi = {
+    request(): {
+        ok: true;
+    };
+};
+type RemoteCartCapabilityBag = ExecutableModuleCapabilities & {
+    grants: readonly RemoteCartGrant[];
+    network: RemoteCartNetworkApi;
+    storage: RemoteCartStorageApi;
+    audio: RemoteCartDeviceApi;
+    controller: RemoteCartDeviceApi;
+    fullscreen: RemoteCartDeviceApi;
+};
+type RemoteCartInspect = {
+    id: string;
+    cartVersion: string;
+    publisher: string;
+    signature: {
+        id: string;
+        alg: string;
+    };
+    requestedGrants: RemoteCartGrant[];
+    grants: RemoteCartGrant[];
+    assets: Array<{
+        id: string;
+        url: string;
+        hash: string;
+    }>;
+    loaded: boolean;
+    destroyed: boolean;
+    diagnostics: RemoteCartDiagnostic[];
+};
+type RemoteCartSandbox = {
+    listRequestedGrants(): RemoteCartGrant[];
+    grants: HostGrantSet;
+    loadAssets(): Promise<{
+        ok: true;
+        snapshot: AssetPreloadSnapshot;
+    } | {
+        ok: false;
+        errors: RemoteCartDiagnostic[];
+    }>;
+    capabilities(): RemoteCartCapabilityBag | {
+        ok: false;
+        errors: RemoteCartDiagnostic[];
+    };
+    inspect(): RemoteCartInspect;
+    snapshotProvenance(): SnapshotProvenance;
+    destroy(): void;
+};
+type CreateRemoteCartSandboxOptions = {
+    manifest: SignedRemoteCartManifest;
+    /** Host HMAC secrets keyed by `signature.keyId`. Sandbox re-verifies before load. */
+    keys: Readonly<Record<string, string>>;
+    grants?: Iterable<RemoteCartGrant>;
+    bytesByUrl: Readonly<Record<string, Uint8Array>>;
+    modules?: readonly ExecutableModuleRegistration[];
+};
+declare function createHostGrantSet(initial?: Iterable<RemoteCartGrant>): HostGrantSet;
+declare function createRemoteCartSandbox(options: CreateRemoteCartSandboxOptions): RemoteCartSandbox;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Universal portal/experience lifecycle: enter another cart exclusively,
+ * suspend the parent, transfer host grants, return a versioned outcome.
+ * Cabinet, painting, and other host metaphors are the same primitive.
+ */
+
+declare const PORTAL_LIFECYCLE_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const PORTAL_OUTCOME_SCHEMA_VERSION: 1;
+declare const PORTAL_METAPHORS: readonly ["cabinet", "painting", "dream", "wormhole", "book", "nested-world"];
+type PortalMetaphor = (typeof PORTAL_METAPHORS)[number];
+declare const PORTAL_OUTCOME_KINDS: readonly ["completed", "aborted"];
+type PortalOutcomeKind = (typeof PORTAL_OUTCOME_KINDS)[number];
+/** Exclusive device grants transferred for the child's lifetime. */
+declare const PORTAL_EXCLUSIVE_GRANTS: readonly ["audio", "controller", "fullscreen"];
+type PortalExclusiveGrant = (typeof PORTAL_EXCLUSIVE_GRANTS)[number];
+declare const PORTAL_ENTERED_EVENT = "portal.lifecycle.entered";
+declare const PORTAL_EXITED_EVENT = "portal.lifecycle.exited";
+declare const PORTAL_ABORTED_EVENT = "portal.lifecycle.aborted";
+declare const PORTAL_LIFECYCLE_EVENTS: readonly ["portal.lifecycle.entered", "portal.lifecycle.exited", "portal.lifecycle.aborted"];
+type PortalLifecycleEventType = (typeof PORTAL_LIFECYCLE_EVENTS)[number];
+type PortalDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type PortalOutcome = {
+    schemaVersion: typeof PORTAL_OUTCOME_SCHEMA_VERSION;
+    kind: PortalOutcomeKind;
+    payload?: unknown;
+};
+type PortalCartDeclaration = {
+    id: string;
+    /** Cart ids this cart may enter. */
+    targets: readonly string[];
+    acceptedOutcomeSchemaVersion?: number;
+    emittedOutcomeSchemaVersion?: number;
+};
+type PortalEnterRequest = {
+    from: string;
+    to: string;
+    metaphor?: PortalMetaphor;
+    seed?: string;
+    clock?: number;
+    /** Extra grants to give the child (exclusive ones are transferred from parent). */
+    grants?: readonly CapabilityDeviceGrant[];
+    state?: unknown;
+    persistence?: unknown;
+};
+type PortalFrameInspect = {
+    id: string;
+    parentId: string;
+    childId: string;
+    metaphor: PortalMetaphor;
+    seed: string | null;
+    clock: number | null;
+    parentState: unknown;
+    parentGrants: CapabilityDeviceGrant[];
+    /** Live child grants after transfer + extras. */
+    childGrants: CapabilityDeviceGrant[];
+    /** Child grants before enter, used to restore and revert extras. */
+    childGrantsBefore: CapabilityDeviceGrant[];
+    extraChildGrants: CapabilityDeviceGrant[];
+    persistence: unknown;
+    transferred: PortalExclusiveGrant[];
+    enterCue: typeof PORTAL_ENTERED_EVENT;
+    exitCue: typeof PORTAL_EXITED_EVENT | typeof PORTAL_ABORTED_EVENT | null;
+};
+type PortalLifecycleSnapshot = {
+    schemaVersion: typeof PORTAL_LIFECYCLE_SNAPSHOT_SCHEMA_VERSION;
+    activeId: string | null;
+    stack: PortalFrameInspect[];
+    lastOutcome: PortalOutcome | null;
+    cues: PortalLifecycleEventType[];
+};
+type PortalInspect = {
+    destroyed: boolean;
+    activeId: string | null;
+    stack: PortalFrameInspect[];
+    lastOutcome: PortalOutcome | null;
+    cues: PortalLifecycleEventType[];
+    grants: Record<string, CapabilityDeviceGrant[]>;
+};
+type PortalMutationResult = {
+    ok: true;
+    inspect: PortalInspect;
+    outcome?: PortalOutcome;
+} | {
+    ok: false;
+    errors: PortalDiagnostic[];
+};
+type RestorePortalResult = {
+    ok: true;
+    snapshot: PortalLifecycleSnapshot;
+} | {
+    ok: false;
+    errors: PortalDiagnostic[];
+};
+type CreatePortalLifecycleOptions = {
+    group?: RuntimeGroup;
+    /** Per-participant grant sets. Missing ids get an empty HostGrantSet. */
+    grants?: Readonly<Record<string, HostGrantSet>>;
+    audioBroker?: AudioBroker;
+    declarations?: readonly PortalCartDeclaration[];
+    rootId?: string;
+    maxDepth?: number;
+    createId?: () => string;
+};
+type PortalLifecycle = {
+    enter(request: PortalEnterRequest): PortalMutationResult;
+    exit(payload?: unknown): PortalMutationResult;
+    abort(payload?: unknown): PortalMutationResult;
+    stack(): PortalFrameInspect[];
+    activeId(): string | null;
+    inspect(): PortalInspect;
+    snapshot(): PortalLifecycleSnapshot;
+    restore(input: unknown): RestorePortalResult;
+    grantsOf(participantId: string): HostGrantSet;
+    destroy(): void;
+};
+/**
+ * Same `enter` / `exit` / `abort` as the session. Metaphor is fixed so cabinet
+ * and painting hosts share lifecycle code.
+ */
+declare function cabinetPortal(portal: PortalLifecycle): {
+    enter: (request: Omit<PortalEnterRequest, 'metaphor'>) => PortalMutationResult;
+    exit: (payload?: unknown) => PortalMutationResult;
+    abort: (payload?: unknown) => PortalMutationResult;
+};
+declare function paintingPortal(portal: PortalLifecycle): {
+    enter: (request: Omit<PortalEnterRequest, 'metaphor'>) => PortalMutationResult;
+    exit: (payload?: unknown) => PortalMutationResult;
+    abort: (payload?: unknown) => PortalMutationResult;
+};
+declare function createPortalLifecycle(options?: CreatePortalLifecycleOptions): PortalLifecycle;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Durable asynchronous job orchestration: lifecycle, persistence, worker
+ * boundary, evaluator feedback, and host-owned apply. Wall-clock completion
+ * never mutates authoritative host state.
+ */
+
+declare const JOB_ORCHESTRATION_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const JOB_RESULT_REF_SCHEMA_VERSION: 1;
+declare const JOB_STATES: readonly ["queued", "claimed", "awaiting-evaluation", "retry-scheduled", "ready", "applied", "failed", "canceled", "superseded"];
+type JobState = (typeof JOB_STATES)[number];
+declare const JOB_RETRYABILITY: readonly ["retryable", "permanent", "unknown"];
+type JobRetryability = (typeof JOB_RETRYABILITY)[number];
+declare const JOB_EVALUATOR_DECISIONS: readonly ["accept", "reject", "revise"];
+type JobEvaluatorDecision = (typeof JOB_EVALUATOR_DECISIONS)[number];
+declare const JOB_LIFECYCLE_EVENTS: readonly ["job.intent.submitted", "job.state.queued", "job.state.claimed", "job.state.progress", "job.state.awaiting-evaluation", "job.state.retry-scheduled", "job.state.ready", "job.state.applied", "job.state.failed", "job.state.canceled", "job.state.superseded", "job.diagnostic.lifecycle"];
+type JobLifecycleEventType = (typeof JOB_LIFECYCLE_EVENTS)[number];
+type JobDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type JobResultRef = {
+    schemaVersion: typeof JOB_RESULT_REF_SCHEMA_VERSION;
+    kind: string;
+    uri: string;
+    contentType?: string;
+    bytes?: number;
+};
+type JobRetryPolicy = {
+    maxAttempts: number;
+    backoffMs: readonly number[];
+    retryableCodes: readonly string[];
+};
+type JobFallback = {
+    reasonCode: string;
+    resultRef?: JobResultRef;
+};
+type JobDefinition = {
+    id: string;
+    version: number;
+    requestSchema: PayloadSchema;
+    resultKind: string;
+    retry: JobRetryPolicy;
+    timeoutMs: number;
+    leaseMs: number;
+    fallback: JobFallback;
+};
+type JobProgress = {
+    value: number;
+    stage: string;
+    message?: string;
+};
+type JobFailureRecord = {
+    attempt: number;
+    code: string;
+    retryability: JobRetryability;
+    at: number;
+    detail?: string;
+};
+type JobEvaluatorRecord = {
+    decision: JobEvaluatorDecision;
+    at: number;
+    correction?: string;
+};
+type JobRecord = {
+    jobId: string;
+    definitionId: string;
+    definitionVersion: number;
+    idempotencyKey: string;
+    state: JobState;
+    request: unknown;
+    resultRef: JobResultRef | null;
+    progress: JobProgress;
+    attempt: number;
+    failureHistory: JobFailureRecord[];
+    evaluatorHistory: JobEvaluatorRecord[];
+    correlationId: string;
+    causationId?: string;
+    workerId: string | null;
+    leaseUntil: number | null;
+    createdAt: number;
+    updatedAt: number;
+    timeoutAt: number;
+    nextRetryAt: number | null;
+    supersededBy: string | null;
+    fallbackApplied: boolean;
+    fallback?: JobFallback;
+};
+type JobCoordinatorSnapshot = {
+    schemaVersion: typeof JOB_ORCHESTRATION_SNAPSHOT_SCHEMA_VERSION;
+    jobs: JobRecord[];
+    hostAcceptedJobIds: string[];
+};
+type JobInspect = {
+    destroyed: boolean;
+    jobs: JobRecord[];
+    events: JobLifecycleEventType[];
+};
+type JobMutationResult = {
+    ok: true;
+    job: JobRecord;
+} | {
+    ok: false;
+    errors: JobDiagnostic[];
+};
+type RestoreJobResult = {
+    ok: true;
+    snapshot: JobCoordinatorSnapshot;
+} | {
+    ok: false;
+    errors: JobDiagnostic[];
+};
+type JobSubmitRequest = {
+    definitionId: string;
+    idempotencyKey: string;
+    request: unknown;
+    correlationId: string;
+    causationId?: string;
+    supersedeJobId?: string;
+};
+type JobPersistenceAdapter = {
+    save(job: JobRecord): void;
+    get(jobId: string): JobRecord | undefined;
+    getByIdempotencyKey(key: string): JobRecord | undefined;
+    list(): JobRecord[];
+    replaceAll(jobs: JobRecord[]): void;
+};
+type JobWorkRequest = {
+    jobId: string;
+    workerId: string;
+    definitionId: string;
+    request: unknown;
+    attempt: number;
+};
+type JobWorkerCallbacks = {
+    reportProgress(jobId: string, progress: JobProgress): JobMutationResult;
+    complete(jobId: string, resultRef: JobResultRef): JobMutationResult;
+    fail(jobId: string, failure: {
+        code: string;
+        retryability: JobRetryability;
+        detail?: string;
+    }): JobMutationResult;
+    heartbeat(jobId: string): JobMutationResult;
+};
+type JobWorkerAdapter = {
+    bind(callbacks: JobWorkerCallbacks): void;
+    start(work: JobWorkRequest): void;
+    cancel?(jobId: string): void;
+};
+type HeadlessJobWorker = JobWorkerAdapter & {
+    complete(jobId: string, resultRef: JobResultRef): JobMutationResult;
+    fail(jobId: string, failure: {
+        code: string;
+        retryability: JobRetryability;
+        detail?: string;
+    }): JobMutationResult;
+    started(): string[];
+};
+type CreateJobCoordinatorOptions = {
+    definitions: readonly JobDefinition[];
+    persistence?: JobPersistenceAdapter;
+    worker?: JobWorkerAdapter;
+    router?: Pick<EventRouter, 'publish'>;
+    now?: () => number;
+    createId?: () => string;
+    maxCorrectionChars?: number;
+    maxFailureHistory?: number;
+};
+type JobCoordinator = {
+    submit(request: JobSubmitRequest): JobMutationResult;
+    claim(workerId: string): JobMutationResult;
+    reportProgress(jobId: string, progress: JobProgress): JobMutationResult;
+    heartbeat(jobId: string): JobMutationResult;
+    complete(jobId: string, resultRef: JobResultRef): JobMutationResult;
+    fail(jobId: string, failure: {
+        code: string;
+        retryability: JobRetryability;
+        detail?: string;
+    }): JobMutationResult;
+    evaluate(jobId: string, decision: JobEvaluatorDecision, correction?: string): JobMutationResult;
+    cancel(jobId: string): JobMutationResult;
+    recoverStale(): JobRecord[];
+    tick(): JobRecord[];
+    /** Host policy gate. Ready jobs become applied; never called from worker complete. */
+    accept(jobId: string): JobMutationResult;
+    get(jobId: string): JobRecord | undefined;
+    getByIdempotencyKey(key: string): JobRecord | undefined;
+    inspect(): JobInspect;
+    snapshot(): JobCoordinatorSnapshot;
+    restore(input: unknown): RestoreJobResult;
+    exportTrace(): {
+        jobs: unknown[];
+        events: JobLifecycleEventType[];
+    };
+    destroy(): void;
+};
+declare function jobEventContracts(): EventContract[];
+declare function createMemoryJobPersistence(): JobPersistenceAdapter;
+declare function createHeadlessJobWorker(): HeadlessJobWorker;
+declare function createJobCoordinator(options: CreateJobCoordinatorOptions): JobCoordinator;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Step-by-step snapshot migrations. The original object is never mutated.
+ * Hosts own persistence; this registry only transforms envelopes in memory.
+ */
+
+type SnapshotMigration = {
+    from: number;
+    to: number;
+    migrate: (snapshot: unknown) => unknown;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Optional spatial world graph: nodes, edges, discovery projections, entity
+ * transit, and host-owned path policy. Semantic time and story rules stay
+ * with the host. No economy, combat, quest, or narrative.
+ */
+
+declare const WORLD_GRAPH_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const WORLD_NODE_KINDS: readonly ["room", "region", "landmark", "frontier"];
+type WorldNodeKind = (typeof WORLD_NODE_KINDS)[number];
+declare const WORLD_MAP_LAYERS: readonly ["local", "regional"];
+type WorldMapLayer = (typeof WORLD_MAP_LAYERS)[number];
+declare const WORLD_EDGE_VISIBILITIES: readonly ["canonical", "discoverable", "hidden"];
+type WorldEdgeVisibility = (typeof WORLD_EDGE_VISIBILITIES)[number];
+declare const WORLD_EDGE_ACCESS: readonly ["open", "locked", "disabled"];
+type WorldEdgeAccess = (typeof WORLD_EDGE_ACCESS)[number];
+declare const WORLD_ENTITY_KINDS: readonly ["character", "party"];
+type WorldEntityKind = (typeof WORLD_ENTITY_KINDS)[number];
+declare const WORLD_ENTITY_STATUSES: readonly ["available", "busy", "traveling"];
+type WorldEntityStatus = (typeof WORLD_ENTITY_STATUSES)[number];
+declare const WORLD_GRAPH_EVENTS: readonly ["world.graph.state.node-added", "world.graph.state.edge-added", "world.graph.state.discovered", "world.graph.state.transit", "world.graph.diagnostic.lifecycle"];
+type WorldGraphEventType = (typeof WORLD_GRAPH_EVENTS)[number];
+type WorldGraphDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type WorldNode = {
+    id: string;
+    version: number;
+    kind: WorldNodeKind;
+    mapLayer: WorldMapLayer;
+    frontier?: boolean;
+    metadata?: Record<string, unknown>;
+};
+type WorldEdge = {
+    id: string;
+    version: number;
+    from: string;
+    to: string;
+    directed: boolean;
+    kind: string;
+    visibility: WorldEdgeVisibility;
+    access: WorldEdgeAccess;
+    requirements?: Record<string, unknown>;
+    cost?: Record<string, number>;
+    metadata?: Record<string, unknown>;
+};
+type WorldTransit = {
+    originNodeId: string;
+    destinationNodeId: string;
+    routeEdgeIds: readonly string[];
+    departedAt: number;
+    expectedArrival: number;
+};
+type WorldEntity = {
+    id: string;
+    kind: WorldEntityKind;
+    status: WorldEntityStatus;
+    locationNodeId: string | null;
+    transit: WorldTransit | null;
+    metadata?: Record<string, unknown>;
+};
+type WorldObserverDiscovery = {
+    observerId: string;
+    nodeIds: readonly string[];
+    edgeIds: readonly string[];
+};
+type WorldGraphSnapshot = {
+    schemaVersion: typeof WORLD_GRAPH_SNAPSHOT_SCHEMA_VERSION;
+    graphId: string;
+    nodes: WorldNode[];
+    edges: WorldEdge[];
+    entities: WorldEntity[];
+    discovery: WorldObserverDiscovery[];
+};
+type WorldGraphProjection = {
+    kind: 'canonical' | 'known' | 'local' | 'regional';
+    observerId?: string;
+    focusNodeId?: string;
+    nodes: WorldNode[];
+    edges: WorldEdge[];
+    frontiers: WorldNode[];
+    entities: WorldEntity[];
+};
+type WorldPathStep = {
+    edgeId: string;
+    from: string;
+    to: string;
+    cost: number;
+};
+type WorldPath = {
+    from: string;
+    to: string;
+    nodeIds: string[];
+    steps: WorldPathStep[];
+    totalCost: number;
+};
+type WorldTraversalContext = {
+    semanticTime: number;
+    observerId?: string;
+    hostState?: unknown;
+};
+type WorldTraversalPolicy = {
+    canTraverse(edge: WorldEdge, from: string, to: string, ctx: WorldTraversalContext): boolean;
+    cost(edge: WorldEdge, from: string, to: string, ctx: WorldTraversalContext): number;
+};
+type WorldQueryBounds = {
+    maxVisits?: number;
+};
+type WorldGraphInspect = {
+    destroyed: boolean;
+    graphId: string;
+    nodeCount: number;
+    edgeCount: number;
+    entityCount: number;
+    observerCount: number;
+    events: WorldGraphEventType[];
+};
+type WorldMutationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: WorldGraphDiagnostic[];
+};
+type RestoreWorldGraphResult = {
+    ok: true;
+    snapshot: WorldGraphSnapshot;
+} | {
+    ok: false;
+    errors: WorldGraphDiagnostic[];
+};
+type WorldPathResult = {
+    ok: true;
+    path: WorldPath;
+} | {
+    ok: false;
+    errors: WorldGraphDiagnostic[];
+};
+type WorldReachabilityResult = {
+    nodeIds: string[];
+};
+type WorldGraphPatch = {
+    nodes?: readonly WorldNode[];
+    edges?: readonly WorldEdge[];
+};
+type CreateWorldGraphOptions = {
+    graphId?: string;
+    migrations?: readonly SnapshotMigration[];
+    router?: Pick<EventRouter, 'publish'>;
+    source?: string;
+    maxPathVisits?: number;
+};
+type WorldGraph = {
+    addNode(node: WorldNode): WorldMutationResult;
+    addEdge(edge: WorldEdge): WorldMutationResult;
+    applyPatch(patch: WorldGraphPatch): WorldMutationResult;
+    removeNode(nodeId: string): WorldMutationResult;
+    removeEdge(edgeId: string): WorldMutationResult;
+    setEdgeAccess(edgeId: string, access: WorldEdgeAccess): WorldMutationResult;
+    discover(observerId: string, known: {
+        nodeIds?: readonly string[];
+        edgeIds?: readonly string[];
+    }): WorldMutationResult;
+    upsertEntity(entity: WorldEntity): WorldMutationResult;
+    startTransit(entityId: string, transit: WorldTransit, status?: Exclude<WorldEntityStatus, 'available'>): WorldMutationResult;
+    completeTransit(entityId: string, semanticTime: number): WorldMutationResult;
+    setEntityStatus(entityId: string, status: WorldEntityStatus): WorldMutationResult;
+    getNode(nodeId: string): WorldNode | undefined;
+    getEdge(edgeId: string): WorldEdge | undefined;
+    getEntity(entityId: string): WorldEntity | undefined;
+    projectCanonical(): WorldGraphProjection;
+    projectKnown(observerId: string): WorldGraphProjection;
+    projectLocal(observerId: string, focusNodeId: string, hops?: number): WorldGraphProjection;
+    projectRegional(observerId: string): WorldGraphProjection;
+    findPath(from: string, to: string, policy: WorldTraversalPolicy, ctx: WorldTraversalContext, bounds?: WorldQueryBounds): WorldPathResult;
+    reachable(from: string, policy: WorldTraversalPolicy, ctx: WorldTraversalContext, bounds?: WorldQueryBounds): WorldReachabilityResult;
+    inspect(): WorldGraphInspect;
+    snapshot(): WorldGraphSnapshot;
+    restore(input: unknown): RestoreWorldGraphResult;
+    events(): readonly EventInput[];
+    destroy(): void;
+};
+declare function worldGraphEventContracts(): EventContract[];
+declare function createWorldGraph(options?: CreateWorldGraphOptions): WorldGraph;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Transactional world-patch validation and atomic application. A generated
+ * result becomes one world revision or none — never a half-installed world.
+ * Cyberart is not the host's database of record.
+ */
+
+declare const WORLD_PATCH_SCHEMA_VERSION: 1;
+declare const WORLD_PATCH_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const WORLD_PATCH_OPS: readonly ["add", "replace", "revise", "remove", "tombstone", "link", "unlink"];
+type WorldPatchOp = (typeof WORLD_PATCH_OPS)[number];
+declare const WORLD_PATCH_ACCEPTED_EVENT: "world.patch.state.accepted";
+declare const WORLD_PATCH_EVENTS: readonly ["world.patch.state.accepted", "world.patch.state.rejected", "world.patch.state.superseded", "world.patch.diagnostic.lifecycle"];
+type WorldPatchEventType = (typeof WORLD_PATCH_EVENTS)[number];
+declare const WORLD_PATCH_ERROR_CODES: readonly ["invalid-schema", "unknown-field", "unknown-op", "missing-field", "missing-ref", "referential-integrity", "stale-base", "precondition-failed", "asset-unavailable", "content-unavailable", "binding-unavailable", "cycle", "over-limit", "idempotency-conflict", "superseded", "invalid-snapshot", "invalid-version", "destroyed", "domain", "capability-denied", "schema-mismatch", "identity-required", "identity-absent", "entity-revision", "entity-hash", "duplicate-id", "graph-apply-failed", "publish-failed"];
+type WorldPatchErrorCode = (typeof WORLD_PATCH_ERROR_CODES)[number];
+type WorldPatchDiagnostic = {
+    code: WorldPatchErrorCode | string;
+    detail: string;
+    path?: string;
+    expectedRevision?: number;
+    actualRevision?: number;
+};
+type WorldPatchProvenance = {
+    producer: string;
+    jobId?: string;
+    contentRevisions?: string[];
+};
+type WorldPatchRefs = {
+    contentId?: string;
+    contentRevision?: string;
+    binding?: string;
+    asset?: string;
+    identity?: string;
+};
+type WorldPatchOperation = {
+    op: WorldPatchOp;
+    kind: string;
+    id: string;
+    order?: number;
+    value?: unknown;
+    from?: string;
+    to?: string;
+    refs?: WorldPatchRefs;
+};
+type WorldPatchPrecondition = {
+    type: 'base-revision';
+    revision: number;
+} | {
+    type: 'entity-revision';
+    kind: string;
+    id: string;
+    revision: number;
+} | {
+    type: 'entity-hash';
+    kind: string;
+    id: string;
+    hash: string;
+} | {
+    type: 'identity-required';
+    kind: string;
+    id: string;
+} | {
+    type: 'identity-absent';
+    kind: string;
+    id: string;
+} | {
+    type: 'capability';
+    name: string;
+} | {
+    type: 'schema';
+    schemaVersion: number;
+};
+type WorldPatch = {
+    patchId: string;
+    schemaVersion: typeof WORLD_PATCH_SCHEMA_VERSION;
+    baseRevision: number;
+    idempotencyKey: string;
+    preconditions?: WorldPatchPrecondition[];
+    operations: WorldPatchOperation[];
+    provenance: WorldPatchProvenance;
+    supersedes?: string;
+};
+type WorldEntityRecord = {
+    kind: string;
+    id: string;
+    revision: number;
+    hash: string;
+    value: unknown;
+    tombstoned: boolean;
+    refs?: WorldPatchRefs;
+};
+type WorldLinkRecord = {
+    id: string;
+    kind: string;
+    from: string;
+    to: string;
+    value?: unknown;
+};
+type WorldAcceptedPatch = {
+    patchId: string;
+    idempotencyKey: string;
+    revision: number;
+    provenance: WorldPatchProvenance;
+    supersededBy?: string;
+};
+type WorldRevisionState = {
+    revision: number;
+    entities: WorldEntityRecord[];
+    links: WorldLinkRecord[];
+    accepted: WorldAcceptedPatch[];
+};
+type WorldIdentityChange = {
+    op: WorldPatchOp;
+    kind: string;
+    id: string;
+};
+type WorldPatchAuditRecord = {
+    outcome: 'accepted' | 'rejected' | 'superseded';
+    patchId: string;
+    idempotencyKey: string;
+    at: number;
+    oldRevision: number;
+    newRevision: number;
+    reasonCodes: string[];
+    changedIdentities: WorldIdentityChange[];
+    provenance: WorldPatchProvenance | Record<string, unknown>;
+    patch: unknown;
+};
+type WorldPatchSnapshot = {
+    schemaVersion: typeof WORLD_PATCH_SNAPSHOT_SCHEMA_VERSION;
+    world: WorldRevisionState;
+    audit: WorldPatchAuditRecord[];
+    graph?: WorldGraphSnapshot;
+};
+type WorldPatchInspect = {
+    destroyed: boolean;
+    revision: number;
+    entities: WorldEntityRecord[];
+    links: WorldLinkRecord[];
+    acceptedPatchIds: string[];
+    events: WorldPatchEventType[];
+    lastRejection: WorldPatchDiagnostic[] | null;
+};
+type WorldPatchDryRunResult = {
+    ok: true;
+    previewRevision: number;
+    changedIdentities: WorldIdentityChange[];
+    diagnostics: WorldPatchDiagnostic[];
+} | {
+    ok: false;
+    errors: WorldPatchDiagnostic[];
+};
+type WorldPatchCommitResult = {
+    ok: true;
+    patchId: string;
+    oldRevision: number;
+    newRevision: number;
+    changedIdentities: WorldIdentityChange[];
+    idempotent?: boolean;
+    inspect: WorldPatchInspect;
+} | {
+    ok: false;
+    errors: WorldPatchDiagnostic[];
+    inspect: WorldPatchInspect;
+};
+type RestoreWorldPatchResult = {
+    ok: true;
+    snapshot: WorldPatchSnapshot;
+} | {
+    ok: false;
+    errors: WorldPatchDiagnostic[];
+};
+type WorldPersistenceTransaction = {
+    applyWorldRevision(next: WorldRevisionState): void;
+    commit(): void;
+    rollback(): void;
+};
+type WorldPatchAcceptedPayload = {
+    patchId: string;
+    oldRevision: number;
+    newRevision: number;
+    changedIdentities: WorldIdentityChange[];
+    producer: string;
+    jobId?: string;
+    contentRevisions?: string[];
+};
+type WorldPersistenceAdapter = {
+    begin(): WorldPersistenceTransaction;
+    current(): WorldRevisionState;
+    publish?(payload: WorldPatchAcceptedPayload): void;
+};
+type WorldPatchLimits = {
+    maxOperations?: number;
+    maxDiagnostics?: number;
+    maxEntities?: number;
+    maxBytes?: number;
+};
+type WorldPatchContentAvailability = {
+    hasRevision?(contentId: string, revision: string): boolean;
+    available?: ReadonlyArray<{
+        contentId?: string;
+        revision: string;
+    }>;
+};
+type WorldPatchBindingAvailability = {
+    listedIds?: readonly string[];
+};
+type WorldPatchAssetAvailability = {
+    availableIds?: readonly string[];
+};
+type WorldPatchGraphPolicy = {
+    allowCycles?: boolean;
+    detectCycle?(preview: WorldRevisionState): boolean;
+};
+type WorldPatchDomainValidator = (ctx: {
+    patch: WorldPatch;
+    current: WorldRevisionState;
+    preview: WorldRevisionState;
+}) => WorldPatchDiagnostic[];
+type CreateWorldPatchApplierOptions = {
+    persistence?: WorldPersistenceAdapter;
+    graph?: WorldGraph;
+    content?: WorldPatchContentAvailability;
+    bindings?: WorldPatchBindingAvailability;
+    assets?: WorldPatchAssetAvailability;
+    now?: () => number;
+    limits?: WorldPatchLimits;
+    redact?: readonly string[];
+    router?: Pick<EventRouter, 'publish'>;
+    onEvent?: (event: EventInput) => void;
+    domainValidators?: readonly WorldPatchDomainValidator[];
+    capabilities?: readonly string[];
+    graphPolicy?: WorldPatchGraphPolicy;
+    source?: string;
+};
+type WorldPatchApplier = {
+    dryRun(patch: unknown): WorldPatchDryRunResult;
+    commit(patch: unknown): WorldPatchCommitResult;
+    inspect(): WorldPatchInspect;
+    snapshot(): WorldPatchSnapshot;
+    restore(input: unknown): RestoreWorldPatchResult;
+    audit(options?: {
+        redact?: boolean;
+    }): WorldPatchAuditRecord[];
+    events(): readonly EventInput[];
+    destroy(): void;
+};
+declare function worldPatchEventContracts(): EventContract[];
+declare function createMemoryWorldPersistence(): WorldPersistenceAdapter;
+declare function createWorldPatchApplier(options?: CreateWorldPatchApplierOptions): WorldPatchApplier;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Atomic external content-revision activation. Adapters discover and load
+ * revision catalogs; the activator stages every declared asset, then commits
+ * one complete bundle (or keeps the last known good). Consumers never see a
+ * mixed old/new scene.
+ */
+
+declare const CONTENT_REVISION_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const CONTENT_REVISION_MANIFEST_VERSION: 1;
+declare const CONTENT_REVISION_ACTIVATED_EVENT: "content.revision.state.activated";
+declare const CONTENT_REVISION_EVENTS: readonly ["content.revision.state.discovered", "content.revision.state.staging", "content.revision.state.validated", "content.revision.state.rejected", "content.revision.state.activated", "content.revision.state.rolled-back", "content.revision.state.superseded", "content.revision.diagnostic.lifecycle"];
+type ContentRevisionEventType = (typeof CONTENT_REVISION_EVENTS)[number];
+declare const CONTENT_REVISION_ERROR_CODES: readonly ["invalid-manifest", "invalid-schema", "invalid-version", "invalid-snapshot", "unknown-revision", "unknown-adapter", "hash-mismatch", "capability-denied", "pinned", "staging-failed", "activation-failed", "health-check-failed", "stale-health-check", "superseded", "destroyed", "adapter-missing", "asset-failed", "unsigned"];
+type ContentRevisionErrorCode = (typeof CONTENT_REVISION_ERROR_CODES)[number];
+type ContentRevisionDiagnostic = {
+    code: ContentRevisionErrorCode | string;
+    detail: string;
+    path?: string;
+};
+type ContentRevisionAssetDecl = {
+    id: string;
+    kind: AssetKind;
+    url: string;
+    hash: string;
+    alg: 'sha256';
+    optional?: boolean;
+    fallback?: {
+        id: string;
+        kind: AssetKind;
+        url: string;
+        hash: string;
+        alg: 'sha256';
+    };
+};
+type ContentRevisionCatalog = {
+    contentId: string;
+    revision: string;
+    manifestVersion: typeof CONTENT_REVISION_MANIFEST_VERSION;
+    publisher: string;
+    source: string;
+    adapterId: string;
+    assets: ContentRevisionAssetDecl[];
+    requestedGrants?: RemoteCartGrant[];
+    capabilities?: CapabilityManifest;
+    signature?: {
+        id: string;
+        alg: string;
+    };
+};
+type ContentRevisionDescriptor = {
+    contentId: string;
+    revision: string;
+    adapterId: string;
+    publisher: string;
+    source: string;
+};
+type ContentRevisionResource = {
+    id: string;
+    kind: AssetKind;
+    ref: string;
+    hash: string;
+    url: string;
+    optional: boolean;
+    usedFallback: boolean;
+};
+type ContentRevisionBundle = {
+    bundleId: string;
+    contentId: string;
+    revision: string;
+    manifestVersion: typeof CONTENT_REVISION_MANIFEST_VERSION;
+    publisher: string;
+    source: string;
+    adapterId: string;
+    signature?: {
+        id: string;
+        alg: string;
+    };
+    resources: Record<string, ContentRevisionResource>;
+};
+type ContentRevisionStagingView = {
+    contentId: string;
+    revision: string;
+    adapterId: string;
+    bundleId: string;
+};
+type ContentRevisionInspect = {
+    destroyed: boolean;
+    pinned: boolean;
+    active: ContentRevisionBundle | null;
+    lastKnownGood: ContentRevisionBundle | null;
+    staging: ContentRevisionStagingView | null;
+    events: ContentRevisionEventType[];
+    lastRejection: ContentRevisionDiagnostic[] | null;
+};
+type ContentRevisionSnapshot = {
+    schemaVersion: typeof CONTENT_REVISION_SNAPSHOT_SCHEMA_VERSION;
+    pinned: boolean;
+    active: ContentRevisionBundle | null;
+    lastKnownGood: ContentRevisionBundle | null;
+    previous: ContentRevisionBundle | null;
+};
+type ContentRevisionMutationResult = {
+    ok: true;
+    bundle: ContentRevisionBundle | null;
+    idempotent?: boolean;
+} | {
+    ok: false;
+    errors: ContentRevisionDiagnostic[];
+};
+type RestoreContentRevisionResult = {
+    ok: true;
+    snapshot: ContentRevisionSnapshot;
+} | {
+    ok: false;
+    errors: ContentRevisionDiagnostic[];
+};
+type ActivateContentRevisionRequest = {
+    contentId: string;
+    revision?: string;
+    adapterId?: string;
+};
+type ContentRevisionFetchBytes = (url: string, signal?: AbortSignal) => Promise<Uint8Array | undefined>;
+type ContentRegistryAdapter = {
+    readonly id: string;
+    hasRevision(contentId: string, revision: string): boolean;
+    discover(contentId: string): Promise<ContentRevisionDescriptor | undefined>;
+    loadRevision(contentId: string, revision: string, signal?: AbortSignal): Promise<{
+        ok: true;
+        catalog: ContentRevisionCatalog;
+    } | {
+        ok: false;
+        errors: ContentRevisionDiagnostic[];
+    }>;
+    fetchBytes: ContentRevisionFetchBytes;
+};
+type CreateStaticContentAdapterOptions = {
+    id?: string;
+    revisions: readonly ContentRevisionCatalog[];
+    bytesByUrl: Readonly<Record<string, Uint8Array>>;
+    fetchBytes?: ContentRevisionFetchBytes;
+};
+type CreateRemoteContentAdapterOptions = {
+    id?: string;
+    fetch: (url: string, signal?: AbortSignal) => Promise<unknown>;
+    keys: Readonly<Record<string, string>>;
+    bytesByUrl?: Readonly<Record<string, Uint8Array>>;
+    fetchBytes?: ContentRevisionFetchBytes;
+    catalogUrl?: (contentId: string, revision?: string) => string;
+    known?: ReadonlyArray<{
+        contentId: string;
+        revision: string;
+    }>;
+};
+type ContentRevisionHealthCheck = (bundle: ContentRevisionBundle) => boolean | Promise<boolean>;
+type CreateContentRevisionActivatorOptions = {
+    adapters: readonly ContentRegistryAdapter[];
+    pin?: boolean;
+    grants?: HostGrantSet;
+    hostCapabilities?: HostCapabilities;
+    healthCheck?: ContentRevisionHealthCheck;
+    router?: Pick<EventRouter, 'publish'>;
+    onEvent?: (event: EventInput) => void;
+};
+type ContentRevisionActivator = {
+    pin(frozen?: boolean): void;
+    unpin(): void;
+    isPinned(): boolean;
+    discover(contentId: string, adapterId?: string): Promise<ContentRevisionDescriptor | undefined>;
+    activate(request: ActivateContentRevisionRequest): Promise<ContentRevisionMutationResult>;
+    rollback(): ContentRevisionMutationResult;
+    inspect(): ContentRevisionInspect;
+    activeBundle(): ContentRevisionBundle | null;
+    snapshot(): ContentRevisionSnapshot;
+    restore(input: unknown): RestoreContentRevisionResult;
+    provenance(): SnapshotProvenance | undefined;
+    destroy(): void;
+};
+declare function contentRevisionEventContracts(): EventContract[];
+declare function createStaticContentAdapter(options: CreateStaticContentAdapterOptions): ContentRegistryAdapter;
+declare function createRemoteContentAdapter(options: CreateRemoteContentAdapterOptions): ContentRegistryAdapter;
+declare function createContentRevisionActivator(options: CreateContentRevisionActivatorOptions): ContentRevisionActivator;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Cart-agnostic update/render frame benchmark for CI and agent workflows.
+ * Prefer this over ad-hoc vitest probes when evaluating hash / trait cost.
+ */
+
+type FrameBenchmarkOptions = {
+    /** Measured frames after warmup. Default 30. */
+    frames?: number;
+    /** Discarded frames before measurement. Default 5. */
+    warmupFrames?: number;
+    /** Simulated frame advance in ms. Default 1000/60. */
+    frameStepMs?: number;
+    width?: number;
+    height?: number;
+    tokenId?: string;
+    /**
+     * Mutate state after `getDefaultState` (e.g. skip Tone init in jsdom by
+     * setting `audioContextStarted = true`).
+     */
+    prepareState?: (state: unknown, featureState: unknown) => void;
+    /** Optional stub drawing context; defaults to a no-op `putImageData`. */
+    drawingContext?: CanvasRenderingContext2D;
+};
+type FrameBenchmarkResult = {
+    frames: number;
+    updateAvgMs: number;
+    renderAvgMs: number;
+    totalAvgMs: number;
+    updateMaxMs: number;
+    renderMaxMs: number;
+    estFps: number;
+    updatePct: number;
+    renderPct: number;
+};
+/**
+ * Run a cart's update/render loop headlessly and report average / max phase
+ * timings. Does not start audio or mount a live AnimationManager — suitable
+ * for jsdom vitest and agent hash probes.
+ */
+declare function benchmarkCartFrames<T, TFeatureState = undefined>(cart: AnimationCart<T, TFeatureState>, hash: string, rawParams: number[], options?: FrameBenchmarkOptions): FrameBenchmarkResult;
+/** Round timing fields for stable console / snapshot logging. */
+declare function formatFrameBenchmarkResult(result: FrameBenchmarkResult, digits?: number): Record<string, number>;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Opt-in DOM/browser host harness. Mounts a caller-supplied host into a
+ * viewport, optionally wires a runtime group and compositor, and dispatches
+ * pointer/keyboard through layout coordinates. Does not import Node built-ins
+ * and does not encode host-product event types or fixtures.
+ */
+
+type BrowserInputModality = 'pointer' | 'keyboard' | 'touch';
+type BrowserHarnessAction = {
+    type: 'viewport';
+    width: number;
+    height: number;
+    dpr: number;
+} | {
+    type: 'click';
+    x: number;
+    y: number;
+    selector?: string;
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'step';
+    frames: number;
+} | {
+    type: 'advance';
+    ms: number;
+} | {
+    type: 'reducedMotion';
+    value: boolean;
+} | {
+    type: 'inputModality';
+    value: BrowserInputModality;
+};
+type BrowserHarnessScreenshot = {
+    imageData: ImageData | null;
+    pngDataUrl: string | null;
+    html: string;
+    declaredOrder: string[];
+};
+type BrowserA11ySnapshot = {
+    focus: {
+        tag: string;
+        id: string;
+        role: string | null;
+        name: string;
+    };
+    live: string;
+    html: string;
+    publishedRegions: Array<{
+        id: string;
+        geometryKinds: string[];
+        name: string | null;
+        role: string | null;
+    }>;
+};
+type BrowserReproductionMetadata = {
+    seed: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    reducedMotion: boolean;
+    inputModality: BrowserInputModality;
+    actions: BrowserHarnessAction[];
+};
+type BrowserHarnessInspect = {
+    host: unknown;
+    layout: PresentationLayout;
+    events: EventEnvelope[];
+    participantEvents: Record<string, HostEvent[]>;
+    state: Record<string, unknown>;
+    focus: BrowserA11ySnapshot['focus'];
+    publishedRegions: BrowserA11ySnapshot['publishedRegions'];
+    scrollTop: number;
+    clock: {
+        framesElapsed: number;
+    };
+};
+type BrowserHarness = {
+    readonly root: HTMLElement;
+    readonly group: RuntimeGroup | undefined;
+    readonly compositor: Compositor | undefined;
+    readonly layout: PresentationLayout;
+    readonly events: readonly EventEnvelope[];
+    readonly geometry: GeometryDocument | undefined;
+    goto(url?: string): void;
+    setViewport(width: number, height: number, dpr?: number): void;
+    setGeometry(next?: GeometryDocument): void;
+    setReducedMotion(value: boolean): void;
+    setInputModality(value: BrowserInputModality): void;
+    click(selectorOrX: string | number, y?: number): void;
+    key(key: string): void;
+    focus(selector: string): void;
+    step(frames?: number): Promise<void>;
+    advance(ms: number): Promise<void>;
+    screenshot(): BrowserHarnessScreenshot;
+    accessibilitySnapshot(): BrowserA11ySnapshot;
+    inspect(): Promise<BrowserHarnessInspect>;
+    reproduction(): BrowserReproductionMetadata;
+    captureComposedFrame(): ComposedFrame;
+    destroy(): void;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * End-to-end production composition scenario harness. Composes the real
+ * browser host, runtime group, compositor, visual/semantic layers, bindings,
+ * sequences, headless audio, optional host-owned audio observation, snapshots,
+ * and replay inspector. Does not introduce a second runtime. Authored
+ * scenarios are JSON-serializable.
+ */
+
+declare const PRODUCTION_SCENARIO_SCHEMA_VERSION: 1;
+declare const PRODUCTION_SCENARIO_SNAPSHOT_SCHEMA_VERSION: 1;
+declare const PRODUCTION_SCENARIO_BOUNDARIES: readonly ["input", "reducer", "routing", "binding", "cue", "pixels", "caption", "audio", "save-replay"];
+type ProductionScenarioBoundary = (typeof PRODUCTION_SCENARIO_BOUNDARIES)[number];
+declare const PRODUCTION_SCENARIO_ERROR_CODES: readonly ["invalid-scenario", "invalid-schema", "unknown-field", "missing-field", "callbacks-forbidden", "missing-participant", "missing-layer", "destroyed", "assertion-failed", "invalid-host-audio", "invalid-audio-sidecar", "unsupported-preference", "invalid-geometry", "ambiguous-geometry", "stale-geometry"];
+type ProductionScenarioErrorCode = (typeof PRODUCTION_SCENARIO_ERROR_CODES)[number];
+declare const HOST_OWNED_AUDIO_EVENT_KINDS: readonly ["invoked", "completed", "failed", "skipped", "fallback"];
+type HostOwnedAudioEventKind = (typeof HOST_OWNED_AUDIO_EVENT_KINDS)[number];
+declare const PRODUCTION_SCENARIO_VIEWPORT_PRESETS: readonly ["desktop", "mobile"];
+type ProductionScenarioViewportPreset = (typeof PRODUCTION_SCENARIO_VIEWPORT_PRESETS)[number];
+declare const DEFAULT_PRODUCTION_SCENARIO_VIEWPORTS: {
+    readonly desktop: {
+        readonly width: 64;
+        readonly height: 48;
+        readonly deviceScaleFactor: 1;
+    };
+    readonly mobile: {
+        readonly width: 48;
+        readonly height: 64;
+        readonly deviceScaleFactor: 2;
+    };
+};
+type ProductionScenarioDiagnostic = {
+    code: ProductionScenarioErrorCode | string;
+    detail: string;
+    path?: string;
+    boundary?: ProductionScenarioBoundary;
+};
+type ProductionScenarioRequired = {
+    participants: readonly string[];
+    layers: readonly string[];
+};
+type ProductionScenarioMatrix = {
+    viewport?: ProductionScenarioViewportPreset;
+    width?: number;
+    height?: number;
+    dpr?: number;
+    reducedMotion?: boolean;
+    mute?: boolean;
+    failedAssetIds?: readonly string[];
+    fallback?: boolean;
+    inputModality?: BrowserInputModality;
+};
+type ProductionScenarioStep = {
+    type: 'click';
+    selector?: string;
+    x?: number;
+    y?: number;
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'focus';
+    selector: string;
+} | {
+    type: 'step';
+    frames: number;
+} | {
+    type: 'viewport';
+    kind?: ProductionScenarioViewportPreset;
+    width?: number;
+    height?: number;
+    dpr?: number;
+} | {
+    type: 'reducedMotion';
+    value: boolean;
+} | {
+    type: 'mute';
+    value: boolean;
+} | {
+    type: 'failAsset';
+    assetId: string;
+} | {
+    type: 'save';
+} | {
+    type: 'reload';
+} | {
+    type: 'replay';
+};
+type ProductionScenarioDefinition = {
+    id: string;
+    schemaVersion: typeof PRODUCTION_SCENARIO_SCHEMA_VERSION;
+    seed: string;
+    required: ProductionScenarioRequired;
+    matrix?: ProductionScenarioMatrix;
+    steps?: readonly ProductionScenarioStep[];
+};
+type DefineProductionScenarioResult = {
+    ok: true;
+    scenario: ProductionScenarioDefinition;
+} | {
+    ok: false;
+    errors: ProductionScenarioDiagnostic[];
+};
+type ProductionScenarioReduceResult = {
+    accepted: boolean;
+    state: JsonObject;
+    reason?: string;
+    playSequence?: string;
+};
+type ProductionScenarioControl = {
+    id: string;
+    name?: string;
+    role?: string;
+};
+type ProductionScenarioInputSurface = {
+    controls: readonly ProductionScenarioControl[];
+    geometry: GeometryDocument;
+};
+type ProductionScenarioHost = {
+    initialState: JsonObject;
+    reduce(state: JsonObject, intent: EventInput): ProductionScenarioReduceResult;
+    project?(state: JsonObject): JsonObject;
+    /**
+     * Host-generic projection of the active input surface. After an accepted
+     * reduce (and on reload) the runner rebuilds visible/focusable controls and
+     * the geometry document from this result. Omit to keep construction-time
+     * geometry and controls.
+     */
+    projectInputSurface?(state: JsonObject): ProductionScenarioInputSurface;
+};
+type HostOwnedAudioEvent = {
+    kind: HostOwnedAudioEventKind;
+    atFrame?: number;
+    name?: string;
+    caption?: string;
+    assetId?: string;
+    reason?: string;
+    id?: string;
+    correlationId?: string;
+    causationId?: string;
+};
+type HostOwnedAudioSnapshot = {
+    events: readonly HostOwnedAudioEvent[];
+    captions?: readonly string[];
+    muted?: boolean;
+};
+/**
+ * Host-owned audio/presentation observer. The host already drives the
+ * controller; the runner only snapshots evidence. Generic: no dialogue
+ * product semantics. At least one of `snapshot` or `collect` is required.
+ */
+type HostOwnedAudioObserver = {
+    snapshot?(): HostOwnedAudioSnapshot;
+    collect?(): HostOwnedAudioSnapshot;
+    inspect?(): unknown;
+};
+type ProductionScenarioLocalization = {
+    boundary: ProductionScenarioBoundary;
+    code: ProductionScenarioErrorCode;
+    detail: string;
+};
+declare const REDUCED_MOTION_ACTIVE_SEQUENCE_POLICY: "continue";
+type ReducedMotionActiveSequencePolicy = typeof REDUCED_MOTION_ACTIVE_SEQUENCE_POLICY;
+declare const REDUCED_MOTION_PARTICIPANT_IDS: readonly ["browser", "visual", "sequence", "audio", "semantic"];
+type ReducedMotionParticipantId = (typeof REDUCED_MOTION_PARTICIPANT_IDS)[number];
+type ReducedMotionParticipantReport = {
+    id: ReducedMotionParticipantId;
+    applied: boolean;
+    reducedMotion?: boolean;
+    reducedSensory?: boolean;
+    reason?: string;
+};
+type ReducedMotionPropagation = {
+    from: boolean;
+    to: boolean;
+    activeSequencePolicy: ReducedMotionActiveSequencePolicy;
+    participants: ReducedMotionParticipantReport[];
+};
+type ProductionScenarioObservation = {
+    inputDispatched: boolean;
+    inputTarget?: string;
+    reducerAccepted?: boolean;
+    reducerRejected?: boolean;
+    reducerReason?: string;
+    routedTypes: string[];
+    rejected: boolean;
+    selectedBindingIds: string[];
+    sequenceId?: string | null;
+    sequencePhase?: string | null;
+    captions: string[];
+    declaredOrder: string[];
+    requiredParticipantsPresent: boolean;
+    requiredLayersPresent: boolean;
+    missingParticipants: string[];
+    missingLayers: string[];
+    audioInvoked: boolean;
+    audioFailed: boolean;
+    muted: boolean;
+    replayMatch?: boolean;
+    snapshotOk?: boolean;
+    audioRestoreOk?: boolean;
+    reducedMotion?: boolean;
+    reducedMotionPropagation?: ReducedMotionPropagation | null;
+    activeControlIds: string[];
+};
+type ProductionScenarioExpectation = {
+    inputDispatched?: boolean;
+    reducerAccepted?: boolean;
+    reducerRejected?: boolean;
+    routedTypes?: readonly string[];
+    selectedBindingIds?: readonly string[];
+    sequenceId?: string;
+    captions?: readonly string[];
+    requiredParticipantsPresent?: boolean;
+    requiredLayersPresent?: boolean;
+    audioInvoked?: boolean;
+    audioFailed?: boolean;
+    replayMatch?: boolean;
+    snapshotOk?: boolean;
+    audioRestoreOk?: boolean;
+};
+type ProductionScenarioEvidenceBundle = {
+    schemaVersion: typeof PRODUCTION_SCENARIO_SNAPSHOT_SCHEMA_VERSION;
+    scenarioId: string;
+    seed: string;
+    matrix: Required<Pick<ProductionScenarioMatrix, 'viewport' | 'width' | 'height' | 'dpr'>> & ProductionScenarioMatrix;
+    hashes: {
+        pixels: string;
+        semantic: string;
+        a11y: string;
+        trace: string;
+        snapshot: string;
+        assets: string;
+    };
+    revisions: {
+        world: string | number | null;
+        bindings: string | number | null;
+        snapshot: number;
+    };
+    traces: {
+        envelopes: EventEnvelope[];
+        inspector: InspectorRecord[];
+        audio: AudioCueEvent[];
+        hostAudio: HostOwnedAudioEvent[];
+        actions: ProductionScenarioStep[];
+    };
+    screenshot: {
+        pngDataUrl: string | null;
+        declaredOrder: string[];
+        width: number;
+        height: number;
+    };
+    semantic: SemanticPublishedRegion[];
+    a11y: BrowserA11ySnapshot;
+    firstBrokenBoundary: ProductionScenarioBoundary | null;
+    localization: ProductionScenarioLocalization | null;
+    participants: string[];
+    layers: string[];
+    observation: ProductionScenarioObservation;
+    selectionTrace?: SelectionTraceExport | null;
+};
+type CreateProductionScenarioRunnerOptions = {
+    scenario: ProductionScenarioDefinition | unknown;
+    participants: RuntimeGroupParticipantConfig[];
+    compositorLayers: CompositorLayerConfig[];
+    visualLayers?: readonly VisualLayerDeclaration[];
+    visualSources?: Readonly<Record<string, ImageData>>;
+    semanticRegions?: readonly SemanticRegionDeclaration[];
+    sequences?: readonly PresentationSequenceDefinition[];
+    bindings?: PresentationBindingManifest | unknown;
+    geometry?: GeometryDocument;
+    host: ProductionScenarioHost;
+    /**
+     * Optional host-owned audio observer. When supplied, the runner records
+     * invocation / completion / failure / skip / fallback evidence from this
+     * adapter without requiring a presentation sequence for the same beat.
+     * Invalid adapters fail closed at boundary `audio`.
+     */
+    hostAudio?: HostOwnedAudioObserver;
+    sequenceBindings?: Readonly<Record<string, PresentationSequenceBindings>>;
+    contentWidth?: number;
+    contentHeight?: number;
+    origin?: number;
+    createId?: () => string;
+    mapClick?: (hotspotId: string) => EventInput;
+    mapKey?: (key: string) => EventInput | undefined;
+    router?: Pick<EventRouter, 'publish'>;
+};
+type ProductionScenarioRunner = {
+    readonly scenario: ProductionScenarioDefinition;
+    readonly harness: BrowserHarness;
+    readonly audio: HeadlessAudioAdapter;
+    readonly inspector: ReplayInspector;
+    goto(): void;
+    click(selectorOrX: string | number, y?: number): void;
+    key(key: string): void;
+    focus(selector: string): void;
+    setViewport(width: number, height: number, dpr?: number): void;
+    setReducedMotion(value: boolean): void;
+    mute(value?: boolean): void;
+    failAsset(assetId: string): void;
+    step(frames?: number): Promise<void>;
+    applyHostIntent(intent: EventInput): ProductionScenarioReduceResult;
+    playSequence(sequenceId: string, invocationId?: string): void;
+    publish(event: EventInput): EventEnvelope | undefined;
+    save(): SnapshotEnvelope;
+    reload(snapshot?: SnapshotEnvelope): void;
+    replay(): Promise<ReplayCompareResult>;
+    run(steps?: readonly ProductionScenarioStep[]): Promise<ProductionScenarioEvidenceBundle>;
+    captureEvidence(expected?: ProductionScenarioExpectation): ProductionScenarioEvidenceBundle;
+    inspect(): {
+        host: JsonObject;
+        lastDecision: ProductionScenarioReduceResult | null;
+        bindings: ReturnType<PresentationBindingRuntime['inspect']> | null;
+        sequences: ReturnType<PresentationSequencePlayer['inspect']> | null;
+        visual: ReturnType<VisualLayerController['inspect']> | null;
+        semantic: ReturnType<SemanticLayerController['inspect']> | null;
+        audio: ReturnType<HeadlessAudioAdapter['snapshot']>;
+        hostAudio: HostOwnedAudioSnapshot | null;
+        participants: string[];
+        layers: string[];
+        composition: ProductionScenarioLocalization | null;
+        reducedMotion: boolean;
+        reducedMotionPropagation: ReducedMotionPropagation | null;
+        inputSurface: {
+            controlIds: string[];
+            geometry: GeometryDocument | null;
+        };
+    };
+    destroy(): void;
+};
+declare function productionScenarioEventContracts(): EventContract[];
+declare function isHostOwnedAudioEventKind(value: unknown): value is HostOwnedAudioEventKind;
+declare function defineProductionScenario(input: unknown): DefineProductionScenarioResult;
+declare function fnv1aHex(data: string | Uint8Array): string;
+declare function localizeProductionScenarioFailure(observed: ProductionScenarioObservation, expected?: ProductionScenarioExpectation): ProductionScenarioLocalization | null;
+declare function createProductionScenarioRunner(options: CreateProductionScenarioRunnerOptions): ProductionScenarioRunner;
 
 /**
  * Copyright (c) 2026 Aaron Boyarsky
@@ -1775,4 +4360,4 @@ type WriteComposedFrameResult = ComposedFrame & {
  */
 declare function writeComposedFrame(compositor: Compositor, path?: string): Promise<WriteComposedFrameResult>;
 
-export { type BoundReplaySession, type CausationTreeNode, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateReplayInspectorOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, type FrameBenchmarkOptions, type FrameBenchmarkResult, type GlyphAtlas, HEADLESS_PNG_DATA_URL, type HeadlessAudioAdapter, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type InspectorRecord, type InstallHeadlessCanvasOptions, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, benchmarkCartFrames, captureVisualLayers, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, createVisualLayerController, decodePng, encodePng, encodePngDataUrl, formatFrameBenchmarkResult, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };
+export { AUDIO_CUE_SNAPSHOT_SCHEMA_VERSION, type AudioCueDiagnostic, type BoundReplaySession, CONTENT_REVISION_ACTIVATED_EVENT, CONTENT_REVISION_SNAPSHOT_SCHEMA_VERSION, type CausationTreeNode, type ContentRevisionActivator, type ContentRevisionBundle, type ContentRevisionInspect, type ContentRevisionSnapshot, type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, type CreateProductionScenarioRunnerOptions, type CreateReplayInspectorOptions, type CreateSelectionTraceOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, DEFAULT_MAX_SELECTION_RECORDS, DEFAULT_PRODUCTION_SCENARIO_VIEWPORTS, type FrameBenchmarkOptions, type FrameBenchmarkResult, type GlyphAtlas, HEADLESS_PNG_DATA_URL, HOST_OWNED_AUDIO_EVENT_KINDS, type HeadlessAudioAdapter, type HeadlessAudioAdapterSnapshot, type HeadlessCanvas2DSettings, type HeadlessFrameError, type HeadlessHarness, type HeadlessImageFixture, type HeadlessInspect, type HeadlessJobWorker, type HeadlessMultiCartHarness, HeadlessUnsupportedOperationError, type HostGrantSet, type HostOwnedAudioEvent, type HostOwnedAudioEventKind, type HostOwnedAudioObserver, type HostOwnedAudioSnapshot, type InspectorRecord, type InstallHeadlessCanvasOptions, type JobCoordinator, type JobCoordinatorSnapshot, type JobInspect, PRESENTATION_BINDING_APPLIED_EVENT, PRESENTATION_BINDING_SNAPSHOT_SCHEMA_VERSION, PRODUCTION_SCENARIO_BOUNDARIES, PRODUCTION_SCENARIO_SCHEMA_VERSION, PRODUCTION_SCENARIO_SNAPSHOT_SCHEMA_VERSION, type PortalInspect, type PortalLifecycle, type PortalLifecycleSnapshot, type PresentationBindingInspect, type PresentationBindingManifest, type PresentationBindingRuntime, type PresentationBindingSnapshot, type PresentationSequenceDefinition, type PresentationSequenceInspect, type PresentationSequencePlayer, type PresentationSequenceSnapshot, type ProductionScenarioControl, type ProductionScenarioDefinition, type ProductionScenarioEvidenceBundle, type ProductionScenarioExpectation, type ProductionScenarioHost, type ProductionScenarioInputSurface, type ProductionScenarioLocalization, type ProductionScenarioObservation, type ProductionScenarioRunner, REDUCED_MOTION_ACTIVE_SEQUENCE_POLICY, REDUCED_MOTION_PARTICIPANT_IDS, type ReducedMotionActiveSequencePolicy, type ReducedMotionParticipantId, type ReducedMotionParticipantReport, type ReducedMotionPropagation, type RemoteCartInspect, type RemoteCartSandbox, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, type RestoreAudioCueResult, SELECTION_DECISION_KINDS, SELECTION_REASON_CODES, SELECTION_TRACE_SCHEMA_VERSION, SELECTION_TRACE_SENSITIVE_KEYS, type SelectionAssetResolution, type SelectionBindingEvaluation, type SelectionContentIdentity, type SelectionDecisionInput, type SelectionDecisionKind, type SelectionDecisionRecord, type SelectionPresentationDecision, type SelectionReasonCode, type SelectionSequenceDecision, type SelectionSnapshotProvenance, type SelectionStagingOutcome, type SelectionStagingResult, type SelectionTrace, type SelectionTraceExport, type SelectionTraceFilter, type SelectionTraceReport, type SemanticLayerController, type SemanticPublishedRegion, type SemanticRegionInspect, UPDATE_GOLDEN_ENV, type VisualArtifactPaths, type VisualArtifacts, type VisualCompareOptions, type VisualCompareResult, type VisualLayerCapture, type VisualLayerController, type VisualLayerInspect, WORLD_PATCH_ACCEPTED_EVENT, WORLD_PATCH_SNAPSHOT_SCHEMA_VERSION, type WorldGraph, type WorldGraphInspect, type WorldGraphProjection, type WorldGraphSnapshot, type WorldPatchApplier, type WorldPatchInspect, type WorldPatchSnapshot, type WorldPersistenceAdapter, type WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, attachSelectionTrace, benchmarkCartFrames, cabinetPortal, captureVisualLayers, compareImageData, compareReplayTraces, contentRevisionEventContracts, createContentRevisionActivator, createDefaultGlyphAtlas, createHeadlessAudioAdapter, createHeadlessHarness, createHeadlessJobWorker, createHeadlessMultiCartHarness, createHostGrantSet, createImageFixture, createJobCoordinator, createMemoryJobPersistence, createMemoryWorldPersistence, createPortalLifecycle, createPresentationBindingRuntime, createPresentationSequencePlayer, createProductionScenarioRunner, createRemoteCartSandbox, createRemoteContentAdapter, createReplayInspector, createSelectionTrace, createSemanticLayerController, createStaticContentAdapter, createVisualLayerController, createWorldGraph, createWorldPatchApplier, decodePng, definePresentationBindings, definePresentationSequence, defineProductionScenario, encodePng, encodePngDataUrl, evaluatePresentationBindings, fnv1aHex, formatFrameBenchmarkResult, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, isHostOwnedAudioEventKind, isSelectionDecisionKind, isSelectionReasonCode, jobEventContracts, localizeProductionScenarioFailure, makeImageData, paintingPortal, parseAudioCueSnapshot, presentationBindingEventContracts, presentationSequenceEventContracts, productionScenarioEventContracts, recordSelectionDecision, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, worldGraphEventContracts, worldPatchEventContracts, writeComposedFrame, writeVisualArtifacts };