@cyberart-io/engine 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -48,7 +48,7 @@ type TokenData = {
  *
  * A full 64-hex hash (optional `0x`) is returned unchanged aside from a
  * lowercase `0x` prefix — this is the kaleidoscope / Art Blocks path.
- * Any other seed (including the Adventure Kit example `42`) is mixed into
+ * Any other seed (including the numeric example `42`) is mixed into
  * a 64-hex hash so `Random` always sees the same shape.
  */
 declare function canonicalizeSeed(seed: string | number): string;
@@ -256,8 +256,8 @@ type NormalizeResult = NormalizeSuccess | NormalizeFailure;
 /**
  * `kind` on the input wins. Otherwise persistence types are intents, then
  * the first dotted segment that is `intent` | `state` | `diagnostic`.
- * `adventure.presentation.*` does not infer a kind (the presentation segment
- * is not one); put the kind in the name, e.g. `adventure.presentation.intent.*`.
+ * `host.presentation.*` does not infer a kind (the presentation segment
+ * is not one); put the kind in the name, e.g. `host.presentation.intent.*`.
  */
 declare function inferEventKind(input: EventInput): EventKind | undefined;
 declare function matchEventPattern(pattern: string, type: string): boolean;
@@ -815,15 +815,49 @@ type EventRouterOptions = {
     maxHops?: number;
     maxCorrelationPerTurn?: number;
     maxIndex?: number;
+    /** Bound on the decision trace (oldest dropped). Default 256. */
+    maxDecisions?: number;
 };
 type PublishExtras = {
     cause?: EventEnvelope;
 };
+type RouterParticipantInspect = {
+    id: string;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
+};
+type RouterDecisionOutcome = 'accepted' | 'rejected' | 'duplicate';
+type RouterDecisionReason = RejectionReason | 'duplicate';
+type RouterDecision = {
+    outcome: RouterDecisionOutcome;
+    reason?: RouterDecisionReason;
+    detail?: string;
+    source: string;
+    type: string;
+    kind?: EventKind;
+    envelopeId?: string;
+    priorEnvelopeId?: string;
+    target?: string;
+    deliveredTo: string[];
+    hops?: number;
+    seq?: number;
+    correlationId?: string;
+    causationId?: string;
+    idempotencyKey?: string;
+    schemaVersion?: number;
+    payload?: unknown;
+    turn: number;
+    time: number;
+};
 type EventRouter = {
     attach(id: string, channel: HostChannel, options?: AttachOptions): void;
     detach(id: string): void;
     publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
     subscribe(patterns: string[], listener: (event: EventEnvelope) => void): () => void;
+    subscribeDecision(listener: (decision: RouterDecision) => void): () => void;
+    inspectParticipants(): RouterParticipantInspect[];
+    inspectDecisions(): RouterDecision[];
     turn(): void;
 };
 declare function createEventRouter(options?: EventRouterOptions): EventRouter;
@@ -836,7 +870,7 @@ declare function createEventRouter(options?: EventRouterOptions): EventRouter;
  * One contract definition drives TypeScript payload types, runtime
  * validation, router permission checks, and machine-readable manifests.
  * Kind must appear as a dotted segment of `type` so names like
- * `adventure.presentation.cue.started` fail at definition time instead of
+ * `host.presentation.cue.started` fail at definition time instead of
  * silently inferring a bogus kind.
  */
 
@@ -931,7 +965,7 @@ declare function createContractRegistry(contracts: EventContract[]): ContractReg
  *
  * Versioned presentation-adapter contract. Hosts own canonical state and
  * push a render model; Cyberart presents it and emits interaction intents.
- * Adventure Kit concepts stay in the host.
+ * Host domain concepts stay in the host.
  */
 
 declare const PRESENTATION_ADAPTER_VERSION: 1;
@@ -946,7 +980,7 @@ declare const PRESENTATION_PHASES: readonly ["loading", "ready", "error", "unsup
 type PresentationPhase = (typeof PRESENTATION_PHASES)[number];
 /**
  * Recommended router `subscribe` for a presentation cart. Intent type names
- * are host-owned (`adventure.intent.*`); do not put domain objects in `target`.
+ * are host-owned (`host.intent.*`); do not put domain objects in `target`.
  */
 declare const PRESENTATION_SUBSCRIBE_PATTERNS: readonly ["presentation.state.*", "cyberart.diagnostic.rejected"];
 declare const INVALID_PRESENTATION_MODEL_MESSAGE = "Presentation adapter: model is invalid or not JSON-serializable";
@@ -1137,6 +1171,10 @@ declare const CAPABILITY_ASSET_KINDS: readonly ["image", "audio", "font", "sprit
 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];
 type CapabilityDiagnostic = {
     code: string;
     detail: string;
@@ -1159,6 +1197,16 @@ type CapabilityPermissions = {
     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[];
+};
 type CapabilityManifest = {
     version: typeof CAPABILITY_MANIFEST_VERSION;
     id: string;
@@ -1170,6 +1218,8 @@ type CapabilityManifest = {
     emittedEvents: string[];
     permissions: CapabilityPermissions;
     integrations: CapabilityIntegration[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
 };
 type CapabilityManifestInput = {
     version?: number;
@@ -1182,6 +1232,8 @@ type CapabilityManifestInput = {
     emittedEvents: string[];
     permissions: CapabilityPermissions;
     integrations: CapabilityIntegration[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
 };
 type HostCapabilities = {
     contractVersion: number;
@@ -1190,6 +1242,10 @@ type HostCapabilities = {
     managers?: CapabilityManager[];
     emit?: string[];
     subscribe?: string[];
+    surface?: CapabilitySurfaceRequirements & {
+        clearPolicy?: CapabilityClearPolicy | CapabilityClearPolicy[];
+    };
+    layers?: CapabilityLayerRequirements;
 };
 type DefineCapabilityManifestResult = {
     ok: true;
@@ -1440,6 +1496,8 @@ type CreateRuntimeGroupOptions = {
     now?: () => number;
     /** Extra router options. Group injects shared `createId` / `now` unless set here. */
     router?: EventRouterOptions;
+    /** Bound on the accepted-event trace (oldest dropped). Default 1024. */
+    maxTrace?: number;
 };
 type RuntimeGroupParticipantInspect = {
     state: unknown;
@@ -1447,6 +1505,9 @@ type RuntimeGroupParticipantInspect = {
     errors: RuntimeGroupFrameError[];
     kind: RuntimeGroupKind;
     clock: ClockSnapshot;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
 };
 type RuntimeGroupDiagnostics = {
     paused: boolean;
@@ -1477,11 +1538,413 @@ type RuntimeGroup = {
     pause(): void;
     resume(): void;
     reset(): void;
+    /** Shared viewport. Sets each container and canvas buffer size. Does not clear sibling pixels on detach. */
+    resize(width: number, height: number): void;
+    /** Tear down one participant without destroying the group or blanking siblings. */
+    detach(id: string): void;
     dispatch(participantId: string, event: HostEvent): void;
     publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
+    inspectParticipants(): Array<RouterParticipantInspect & {
+        kind: RuntimeGroupKind;
+    }>;
     inspect(): Promise<RuntimeGroupInspect>;
     destroy(): void;
 };
 declare function createRuntimeGroup(options: CreateRuntimeGroupOptions): RuntimeGroup;
 
-export { ANCHOR_ORIGINS, ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, type AnchorOrigin, type AnimationCart, type AnimationTiming, type AppliedAction, type AssetCorsMode, type AssetDeclaration, type AssetFailure, type AssetFailureCode, type AssetItemStatus, type AssetKind, type AssetPreloadSnapshot, type AssetPreloader, type AssetProvenance, type AssetResolveRequest, type AssetResolver, type AssetRuntimeOptions, type AttachOptions, type AttachPresentationAdapterOptions, type AudioLibraryId, type AudioLibrarySpec, CAPABILITY_ASSET_KINDS, CAPABILITY_INTEGRATIONS, CAPABILITY_MANAGERS, CAPABILITY_MANIFEST_VERSION, CAPABILITY_PHASES, COORDINATE_SPACES, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CapabilityAssetDeclarationSummary, type CapabilityAssetKind, type CapabilityAssetSummary, type CapabilityDiagnostic, type CapabilityIntegration, type CapabilityManager, type CapabilityManifest, type CapabilityManifestInput, type CapabilityPermissions, type CapabilityPhase, type CapabilityRuntime, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type Clock, type ClockSnapshot, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CoordinateSpace, type CreateAssetPreloaderOptions, type CreatePresentationLayoutInput, type CreatePresentationTimelineOptions, type CreateRuntimeGroupOptions, type CreateRuntimeOptions, type CueDuplicatePolicy, type CueEasing, type CueLifecycleEvent, type CueLifecycleType, type CuePhase, type CueReducedMotionPolicy, type CueRepeatPolicy, type CueSpec, type CueTimelineSnapshot, type CueView, type CyberArtRuntime, DEFAULT_GROUP_HEIGHT, DEFAULT_GROUP_WIDTH, DEFAULT_MAX_HOPS, type DebugDrawCall, type DefineCapabilityManifestResult, type DefineContractResult, type DeterministicRuntimeOptions, type DimensionContext, EVENT_ENVELOPE_VERSION, type EventContract, type EventContractManifest, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type FixtureAssetCatalog, type FixtureAssetRecord, type FrameErrorInfo, GEOMETRY_CONTRACT_VERSION, type GeometryAnchor, type GeometryDebugContext, type GeometryDiagnostic, type GeometryDocument, type GeometryHitbox, type GeometryPadding, type GeometrySafeArea, type GeometryValidation, type HostCapabilities, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, KeyboardManager, type LandmarkRegisterResult, type LandmarkRegistry, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, type NormalizedPoint, type NormalizedPolygon, type NormalizedRect, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PixelPoint, type PixelRect, type PlayCueResult, type PointerClick, PointerManager, type PointerSpace, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationFitMode, type PresentationLayout, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REJECTED_EVENT_TYPE, ROUND_TRIP_TOLERANCE, ROUND_TRIP_TOLERANCE_CANVAS_PX, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayMetadata, type ResolvedAsset, type RuntimeGroup, type RuntimeGroupCapability, type RuntimeGroupDiagnostics, type RuntimeGroupFrameError, type RuntimeGroupInspect, type RuntimeGroupKind, type RuntimeGroupParticipantConfig, type RuntimeGroupParticipantHandle, type RuntimeGroupParticipantInspect, SILENT_ASSET_FALLBACK_REF, type SchemaCompatibility, type ScriptedAction, type TokenData, type ValidateCapabilityManifestResult, type ValidateResult, type VirtualClock, applyCueEasing, assetStatusEvent, assetToNormalized, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, canvasToCss, canvasToNormalized, toJSON as capabilityManifestToJSON, comparePayloadSchemas, createAssetFailure, createAssetPreloader, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createLandmarkRegistry, createPresentationLayout, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createRuntime, createRuntimeGroup, createVirtualClock, createWallClock, cssToCanvas, cssToNormalized, defineCapabilityManifest, defineDiagnostic, defineIntent, defineStateEvent, deriveAttachOptions, describeReplayMismatch, drawGeometryDebug, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isCueLifecycleType, isPresentationModel, isPresentationPhase, kindSegmentInType, matchEventPattern, mountPresentationAdapter, normalizeEvent, normalizedToAsset, normalizedToCanvas, normalizedToCss, parseCapabilityManifest, parseGeometry, pointFromOrigin, pointerToRegion, rectToCanvas, rectToCss, regionToViewport, registerCartStateHotkeys, resolveRuntimeSeed, rewriteHostedAssetRef, serializeGeometry, validateCapabilityManifest, validateGeometry, verifyAttachOptions };
+declare const REPLAY_INSPECTOR_SCHEMA_VERSION: 1;
+declare const DEFAULT_MAX_INSPECTOR_RECORDS = 512;
+declare const REDACTED_VALUE = "[REDACTED]";
+type ReplayTraceFilter = {
+    types?: string[];
+    sources?: string[];
+    outcomes?: RouterDecisionOutcome[];
+    correlationId?: string;
+};
+type CreateReplayInspectorOptions = {
+    redactedKeys?: string[];
+    maxRecords?: number;
+    /** Optional contracts so records can include payload schema version. */
+    registry?: Pick<ContractRegistry, 'get'>;
+};
+type InspectorRecord = {
+    index: number;
+    turn: number;
+    time: number;
+    outcome: RouterDecisionOutcome;
+    reason?: RouterDecisionReason;
+    detail?: string;
+    source: string;
+    target?: string;
+    type: string;
+    kind?: EventKind;
+    envelopeId?: string;
+    priorEnvelopeId?: string;
+    correlationId?: string;
+    causationId?: string;
+    hops?: number;
+    seq?: number;
+    idempotencyKey?: string;
+    schemaVersion?: number;
+    payloadSchemaVersion?: number;
+    deliveredTo: string[];
+    payload?: unknown;
+};
+type CausationTreeNode = {
+    envelopeId?: string;
+    type: string;
+    source: string;
+    outcome: RouterDecisionOutcome;
+    reason?: RouterDecisionReason;
+    children: CausationTreeNode[];
+};
+type ReplayParticipantSummary = {
+    id: string;
+    kind?: RuntimeGroupKind;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
+    seed?: string;
+    clock?: ClockSnapshot;
+    state?: unknown;
+    errorCount: number;
+    lastError?: string;
+};
+type ReplayInspectorReport = {
+    schemaVersion: typeof REPLAY_INSPECTOR_SCHEMA_VERSION;
+    participants: ReplayParticipantSummary[];
+    records: InspectorRecord[];
+    trees: CausationTreeNode[];
+    dropped: number;
+};
+type ReplayTapeAction = {
+    kind: 'publish';
+    event: EventInput;
+    extras?: PublishExtras;
+} | {
+    kind: 'dispatch';
+    participantId: string;
+    event: HostEvent;
+} | {
+    kind: 'step';
+    frames: number;
+} | {
+    kind: 'asset';
+    participantId: string;
+    event: HostEvent;
+};
+type ReplayInspectorExport = {
+    schemaVersion: typeof REPLAY_INSPECTOR_SCHEMA_VERSION;
+    origin: number;
+    redactedKeys: string[];
+    participants: ReplayParticipantSummary[];
+    tape: ReplayTapeAction[];
+    records: InspectorRecord[];
+    snapshots: Record<string, unknown>;
+};
+type ReplayCompareResult = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+type BoundReplaySession = {
+    publish(event: EventInput, extras?: PublishExtras): EventEnvelope | undefined;
+    dispatch(participantId: string, event: HostEvent): void;
+    step(frames?: number): Promise<void>;
+    report(): Promise<ReplayInspectorReport>;
+    exportTrace(filter?: ReplayTraceFilter): Promise<ReplayInspectorExport>;
+    unbind(): void;
+};
+type ReplayInspector = {
+    watchRouter(router: EventRouter): () => void;
+    bind(group: RuntimeGroup): BoundReplaySession;
+    importTrace(exported: ReplayInspectorExport | string): void;
+    exportTrace(filter?: ReplayTraceFilter): ReplayInspectorExport;
+    report(filter?: ReplayTraceFilter): ReplayInspectorReport;
+    causationTree(correlationId?: string): CausationTreeNode[];
+    records(): InspectorRecord[];
+    reset(): void;
+    destroy(): void;
+};
+declare function compareReplayTraces(expected: InspectorRecord[], actual: InspectorRecord[]): ReplayCompareResult;
+declare function createReplayInspector(options?: CreateReplayInspectorOptions): ReplayInspector;
+declare function replayExportedTrace(exported: ReplayInspectorExport, group: RuntimeGroup, options?: CreateReplayInspectorOptions): Promise<{
+    inspector: ReplayInspector;
+    report: ReplayInspectorReport;
+}>;
+
+declare const COMPOSITOR_BLEND_MODES: readonly ["source-over", "screen"];
+type CompositorBlendMode = (typeof COMPOSITOR_BLEND_MODES)[number];
+declare const COMPOSITOR_CLEAR_POLICIES: readonly ["transparent", "opaque"];
+type CompositorClearPolicy = (typeof COMPOSITOR_CLEAR_POLICIES)[number];
+type CompositorPointerEvents = 'auto' | 'none';
+type CompositorClip = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type CompositorLayerConfig = {
+    id: string;
+    order: number;
+    visible?: boolean;
+    opacity?: number;
+    blend?: CompositorBlendMode;
+    clip?: CompositorClip;
+    pointerEvents?: CompositorPointerEvents;
+    clearPolicy?: CompositorClearPolicy;
+};
+type CompositorLayerInspect = {
+    id: string;
+    order: number;
+    visible: boolean;
+    opacity: number;
+    blend: CompositorBlendMode;
+    clip: CompositorClip | null;
+    pointerEvents: CompositorPointerEvents;
+    clearPolicy: CompositorClearPolicy;
+};
+type CompositorHostOptions = {
+    /** Back-layer pixels. Scaled nearest-neighbor to the compositor viewport. */
+    image?: ImageData;
+    /** Opaque CSS `#rgb` / `#rrggbb` fill when `image` is omitted. */
+    color?: string;
+};
+type CreateCompositorOptions = {
+    group: RuntimeGroup;
+    layers: CompositorLayerConfig[];
+    width?: number;
+    height?: number;
+    dpr?: number;
+    host?: CompositorHostOptions;
+    /**
+     * Host surface clear. Default `transparent` — never fill black.
+     * Per-layer `clearPolicy: 'transparent'` knocks out RGB 0,0,0 backing
+     * pixels so opaque cart canvases can stack over a host image.
+     */
+    clearPolicy?: CompositorClearPolicy;
+    /**
+     * When true (default), compose into a compositor-owned canvas.
+     * When false, require `target` and draw there.
+     */
+    offscreen?: boolean;
+    target?: HTMLCanvasElement;
+};
+type ComposedFrame = {
+    imageData: ImageData;
+    pngDataUrl: string;
+    width: number;
+    height: number;
+    declaredOrder: CompositorLayerInspect[];
+};
+type CompositorInspect = {
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    clearPolicy: CompositorClearPolicy;
+    layers: CompositorLayerInspect[];
+    declaredOrder: string[];
+};
+type Compositor = {
+    readonly canvas: HTMLCanvasElement;
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+    compose(): ImageData;
+    captureComposedFrame(): ComposedFrame;
+    /**
+     * Shared CSS viewport. Updates group canvas buffer size (`width * dpr`).
+     * Layer order/blend survive. Carts that cache layout from `DimensionContext`
+     * need `group.reset()` (or remount) so they rebuild at the new size.
+     */
+    resize(width: number, height: number, dpr?: number): void;
+    setLayer(id: string, patch: Partial<Omit<CompositorLayerConfig, 'id'>>): void;
+    layer(id: string): CompositorLayerInspect;
+    layers(): CompositorLayerInspect[];
+    pointerTarget(x: number, y: number): string | undefined;
+    unmountLayer(id: string): void;
+    inspect(): CompositorInspect;
+    destroy(): void;
+};
+declare function createCompositor(options: CreateCompositorOptions): Compositor;
+
+/**
+ * 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.
+ */
+
+declare const DEFAULT_BROWSER_VIEWPORT: {
+    readonly width: 320;
+    readonly height: 180;
+    readonly deviceScaleFactor: 1;
+};
+type BrowserInputModality = 'pointer' | 'keyboard' | 'touch';
+type BrowserViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+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;
+};
+type BrowserReproductionMetadata = {
+    seed: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    reducedMotion: boolean;
+    inputModality: BrowserInputModality;
+    actions: BrowserHarnessAction[];
+};
+type BrowserCompositorConfig = Omit<CreateCompositorOptions, 'group' | 'width' | 'height' | 'dpr'>;
+type BrowserHarnessMountContext = {
+    root: HTMLElement;
+    layout: PresentationLayout;
+    reducedMotion: boolean;
+    inputModality: BrowserInputModality;
+    placeRegion(id: string, element: HTMLElement): PixelRect | undefined;
+};
+type BrowserHarnessRuntimeContext = BrowserHarnessMountContext & {
+    group: RuntimeGroup | undefined;
+    compositor: Compositor | undefined;
+    publish(event: EventInput): EventEnvelope | undefined;
+};
+type BrowserHostSession = {
+    participants?: RuntimeGroupParticipantConfig[];
+    compositor?: BrowserCompositorConfig;
+    hostState?: () => unknown;
+    ready?: (ctx: BrowserHarnessRuntimeContext) => void;
+    relayout?: (ctx: BrowserHarnessRuntimeContext) => void;
+    destroy?: () => void;
+};
+type CreateBrowserHarnessOptions = {
+    seed?: string;
+    viewport?: BrowserViewport;
+    reducedMotion?: boolean;
+    inputModality?: BrowserInputModality;
+    origin?: number;
+    createId?: () => string;
+    geometry?: GeometryDocument;
+    contentWidth?: number;
+    contentHeight?: number;
+    fit?: PresentationFitMode;
+    mount?: (ctx: BrowserHarnessMountContext) => BrowserHostSession | void;
+};
+type BrowserHarnessInspect = {
+    host: unknown;
+    layout: PresentationLayout;
+    events: EventEnvelope[];
+    participantEvents: Record<string, HostEvent[]>;
+    state: Record<string, unknown>;
+    focus: BrowserA11ySnapshot['focus'];
+    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[];
+    goto(url?: string): void;
+    setViewport(width: number, height: number, dpr?: number): 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;
+};
+declare function createBrowserHarness(options?: CreateBrowserHarnessOptions): BrowserHarness;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Playwright-shaped adapter over `createBrowserHarness`. Same method names as
+ * a Playwright `Page` (`goto`, `setViewportSize`, `click`, `screenshot`) so CI
+ * can swap engines later without `@playwright/test` as an engine dependency.
+ */
+
+type PlaywrightCompatibleViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+};
+type PlaywrightCompatibleAdapter = {
+    goto(url?: string): Promise<void>;
+    setViewportSize(viewport: PlaywrightCompatibleViewport): Promise<void>;
+    click(selector: string): Promise<void>;
+    screenshot(): Promise<BrowserHarnessScreenshot>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    locator(selector: string): {
+        click(): Promise<void>;
+        focus(): Promise<void>;
+    };
+    close(): Promise<void>;
+};
+declare function createPlaywrightCompatibleAdapter(harness: BrowserHarness): PlaywrightCompatibleAdapter;
+
+export { ANCHOR_ORIGINS, ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, type AnchorOrigin, type AnimationCart, type AnimationTiming, type AppliedAction, type AssetCorsMode, type AssetDeclaration, type AssetFailure, type AssetFailureCode, type AssetItemStatus, type AssetKind, type AssetPreloadSnapshot, type AssetPreloader, type AssetProvenance, type AssetResolveRequest, type AssetResolver, type AssetRuntimeOptions, type AttachOptions, type AttachPresentationAdapterOptions, type AudioLibraryId, type AudioLibrarySpec, type BoundReplaySession, type BrowserA11ySnapshot, type BrowserCompositorConfig, type BrowserHarness, type BrowserHarnessAction, type BrowserHarnessInspect, type BrowserHarnessMountContext, type BrowserHarnessRuntimeContext, type BrowserHarnessScreenshot, type BrowserHostSession, type BrowserInputModality, type BrowserReproductionMetadata, type BrowserViewport, CAPABILITY_ASSET_KINDS, CAPABILITY_BLEND_MODES, CAPABILITY_CLEAR_POLICIES, CAPABILITY_INTEGRATIONS, CAPABILITY_MANAGERS, CAPABILITY_MANIFEST_VERSION, CAPABILITY_PHASES, COMPOSITOR_BLEND_MODES, COMPOSITOR_CLEAR_POLICIES, COORDINATE_SPACES, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CapabilityAssetDeclarationSummary, type CapabilityAssetKind, type CapabilityAssetSummary, type CapabilityBlendMode, type CapabilityClearPolicy, type CapabilityDiagnostic, type CapabilityIntegration, type CapabilityLayerRequirements, type CapabilityManager, type CapabilityManifest, type CapabilityManifestInput, type CapabilityPermissions, type CapabilityPhase, type CapabilityRuntime, type CapabilitySurfaceRequirements, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type CausationTreeNode, type Clock, type ClockSnapshot, type ComposedFrame, type Compositor, type CompositorBlendMode, type CompositorClearPolicy, type CompositorClip, type CompositorHostOptions, type CompositorInspect, type CompositorLayerConfig, type CompositorLayerInspect, type CompositorPointerEvents, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CoordinateSpace, type CreateAssetPreloaderOptions, type CreateBrowserHarnessOptions, type CreateCompositorOptions, type CreatePresentationLayoutInput, type CreatePresentationTimelineOptions, type CreateReplayInspectorOptions, type CreateRuntimeGroupOptions, type CreateRuntimeOptions, type CueDuplicatePolicy, type CueEasing, type CueLifecycleEvent, type CueLifecycleType, type CuePhase, type CueReducedMotionPolicy, type CueRepeatPolicy, type CueSpec, type CueTimelineSnapshot, type CueView, type CyberArtRuntime, DEFAULT_BROWSER_VIEWPORT, DEFAULT_GROUP_HEIGHT, DEFAULT_GROUP_WIDTH, DEFAULT_MAX_HOPS, DEFAULT_MAX_INSPECTOR_RECORDS, type DebugDrawCall, type DefineCapabilityManifestResult, type DefineContractResult, type DeterministicRuntimeOptions, type DimensionContext, EVENT_ENVELOPE_VERSION, type EventContract, type EventContractManifest, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type FixtureAssetCatalog, type FixtureAssetRecord, type FrameErrorInfo, GEOMETRY_CONTRACT_VERSION, type GeometryAnchor, type GeometryDebugContext, type GeometryDiagnostic, type GeometryDocument, type GeometryHitbox, type GeometryPadding, type GeometrySafeArea, type GeometryValidation, type HostCapabilities, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, type InspectorRecord, KeyboardManager, type LandmarkRegisterResult, type LandmarkRegistry, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, type NormalizedPoint, type NormalizedPolygon, type NormalizedRect, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PixelPoint, type PixelRect, type PlayCueResult, type PlaywrightCompatibleAdapter, type PlaywrightCompatibleViewport, type PointerClick, PointerManager, type PointerSpace, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationFitMode, type PresentationLayout, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REDACTED_VALUE, REJECTED_EVENT_TYPE, REPLAY_INSPECTOR_SCHEMA_VERSION, ROUND_TRIP_TOLERANCE, ROUND_TRIP_TOLERANCE_CANVAS_PX, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayCompareResult, type ReplayInspector, type ReplayInspectorExport, type ReplayInspectorReport, type ReplayMetadata, type ReplayParticipantSummary, type ReplayTapeAction, type ReplayTraceFilter, type ResolvedAsset, type RouterDecision, type RouterDecisionOutcome, type RouterDecisionReason, type RouterParticipantInspect, type RuntimeGroup, type RuntimeGroupCapability, type RuntimeGroupDiagnostics, type RuntimeGroupFrameError, type RuntimeGroupInspect, type RuntimeGroupKind, type RuntimeGroupParticipantConfig, type RuntimeGroupParticipantHandle, type RuntimeGroupParticipantInspect, SILENT_ASSET_FALLBACK_REF, type SchemaCompatibility, type ScriptedAction, type TokenData, type ValidateCapabilityManifestResult, type ValidateResult, type VirtualClock, applyCueEasing, assetStatusEvent, assetToNormalized, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, canvasToCss, canvasToNormalized, toJSON as capabilityManifestToJSON, comparePayloadSchemas, compareReplayTraces, createAssetFailure, createAssetPreloader, createBrowserHarness, createCompositor, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createLandmarkRegistry, createPlaywrightCompatibleAdapter, createPresentationLayout, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createReplayInspector, createRuntime, createRuntimeGroup, createVirtualClock, createWallClock, cssToCanvas, cssToNormalized, defineCapabilityManifest, defineDiagnostic, defineIntent, defineStateEvent, deriveAttachOptions, describeReplayMismatch, drawGeometryDebug, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isCueLifecycleType, isPresentationModel, isPresentationPhase, kindSegmentInType, matchEventPattern, mountPresentationAdapter, normalizeEvent, normalizedToAsset, normalizedToCanvas, normalizedToCss, parseCapabilityManifest, parseGeometry, pointFromOrigin, pointerToRegion, rectToCanvas, rectToCss, regionToViewport, registerCartStateHotkeys, replayExportedTrace, resolveRuntimeSeed, rewriteHostedAssetRef, serializeGeometry, validateCapabilityManifest, validateGeometry, verifyAttachOptions };