@cyberart-io/engine 0.0.3 → 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";
@@ -1119,4 +1153,798 @@ declare function isCueLifecycleType(value: unknown): value is CueLifecycleType;
 declare function applyCueEasing(t: number, easing: CueEasing): number;
 declare function createPresentationTimeline(options?: CreatePresentationTimelineOptions): PresentationTimeline;
 
-export { ASSET_FAILED_EVENT, ASSET_FAILURE_CODES, ASSET_KINDS, ASSET_READY_EVENT, type AnimationCart, type AnimationTiming, type AppliedAction, type AssetCorsMode, type AssetDeclaration, type AssetFailure, type AssetFailureCode, type AssetItemStatus, type AssetKind, type AssetPreloadSnapshot, type AssetPreloader, type AssetProvenance, type AssetResolveRequest, type AssetResolver, type AssetRuntimeOptions, type AttachOptions, type AttachPresentationAdapterOptions, type AudioLibraryId, type AudioLibrarySpec, CUE_CANCELLED_EVENT, CUE_COMPLETED_EVENT, CUE_LIFECYCLE_EVENTS, CUE_REPLACED_EVENT, CUE_STARTED_EVENT, CYBERART_CANVAS_ATTR, type CartHandle, type CartSnapshot, type CartStateBundle, type CartStateHotkeyOptions, type CartStateMessageHandler, type CartStatePersister, type Clock, type ClockSnapshot, type ContractDiagnostic, type ContractFieldType, type ContractRegistry, type CreateAssetPreloaderOptions, type CreatePresentationTimelineOptions, type CreateRuntimeOptions, type CueDuplicatePolicy, type CueEasing, type CueLifecycleEvent, type CueLifecycleType, type CuePhase, type CueReducedMotionPolicy, type CueRepeatPolicy, type CueSpec, type CueTimelineSnapshot, type CueView, type CyberArtRuntime, DEFAULT_MAX_HOPS, type DefineContractResult, type DeterministicRuntimeOptions, type DimensionContext, EVENT_ENVELOPE_VERSION, type EventContract, type EventContractManifest, type EventEnvelope, type EventInput, type EventKind, type EventRouter, type EventRouterOptions, type FixtureAssetCatalog, type FixtureAssetRecord, type FrameErrorInfo, HostChannel, type HostEvent, type HostEventListener, type HostedAssetResolverOptions, INVALID_PRESENTATION_MODEL_MESSAGE, type ImportCartStateExtras, IncompatibleCartStateError, type InferredPayload, KeyboardManager, type MountOptions, type MountPresentationAdapterOptions, type NormalizeContext, type NormalizeResult, PRESENTATION_ADAPTER_VERSION, PRESENTATION_MODEL_EVENT, PRESENTATION_PHASES, PRESENTATION_SUBSCRIBE_PATTERNS, PRESENTATION_UNSUPPORTED_EVENT, type PayloadFieldSpec, type PayloadSchema, type PayloadValidation, type PlayCueResult, type PointerClick, PointerManager, type PresentationAdapter, type PresentationAdapterTarget, type PresentationCartState, type PresentationModel, type PresentationPhase, type PresentationRegion, type PresentationTimeline, type PresentationView, type PublishExtras, REJECTED_EVENT_TYPE, Random, type RandomState, type RejectionPayload, type RejectionReason, type ReplayMetadata, type ResolvedAsset, SILENT_ASSET_FALLBACK_REF, type SchemaCompatibility, type ScriptedAction, type TokenData, type ValidateResult, type VirtualClock, applyCueEasing, assetStatusEvent, attachCartStatePersistence, attachPresentationAdapter, canonicalizeSeed, comparePayloadSchemas, createAssetFailure, createAssetPreloader, createContractRegistry, createEventRouter, createFixtureAssetResolver, createHostedAssetResolver, createPresentationModelEvent, createPresentationTimeline, createReferencePresentationCart, createRuntime, createVirtualClock, createWallClock, defineDiagnostic, defineIntent, defineStateEvent, deriveAttachOptions, describeReplayMismatch, familyPatternForType, inferEventKind, isAssetFailure, isAssetFailureCode, isAssetKind, isCueLifecycleType, isPresentationModel, isPresentationPhase, kindSegmentInType, matchEventPattern, mountPresentationAdapter, normalizeEvent, registerCartStateHotkeys, resolveRuntimeSeed, rewriteHostedAssetRef, verifyAttachOptions };
+/**
+ * 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];
+type CapabilityDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type CapabilityRuntime = {
+    minContractVersion: number;
+    features: string[];
+};
+type CapabilityAssetDeclarationSummary = {
+    id: string;
+    kind: CapabilityAssetKind;
+};
+type CapabilityAssetSummary = {
+    kinds: CapabilityAssetKind[];
+    declarations: CapabilityAssetDeclarationSummary[];
+};
+type CapabilityPermissions = {
+    emit: string[];
+    subscribe: string[];
+    authoritative?: boolean;
+};
+/** 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;
+    runtime: CapabilityRuntime;
+    phases: CapabilityPhase[];
+    managers: CapabilityManager[];
+    assets: CapabilityAssetSummary;
+    acceptedEvents: string[];
+    emittedEvents: string[];
+    permissions: CapabilityPermissions;
+    integrations: CapabilityIntegration[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
+};
+type CapabilityManifestInput = {
+    version?: number;
+    id: string;
+    runtime: CapabilityRuntime;
+    phases: CapabilityPhase[];
+    managers: CapabilityManager[];
+    assets: CapabilityAssetSummary;
+    acceptedEvents: string[];
+    emittedEvents: string[];
+    permissions: CapabilityPermissions;
+    integrations: CapabilityIntegration[];
+    surface?: CapabilitySurfaceRequirements;
+    layers?: CapabilityLayerRequirements;
+};
+type HostCapabilities = {
+    contractVersion: number;
+    features: string[];
+    integrations: CapabilityIntegration[];
+    managers?: CapabilityManager[];
+    emit?: string[];
+    subscribe?: string[];
+    surface?: CapabilitySurfaceRequirements & {
+        clearPolicy?: CapabilityClearPolicy | CapabilityClearPolicy[];
+    };
+    layers?: CapabilityLayerRequirements;
+};
+type DefineCapabilityManifestResult = {
+    ok: true;
+    manifest: CapabilityManifest;
+} | {
+    ok: false;
+    errors: CapabilityDiagnostic[];
+};
+type ValidateCapabilityManifestResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: CapabilityDiagnostic[];
+};
+declare function defineCapabilityManifest(input: unknown): DefineCapabilityManifestResult;
+declare function parseCapabilityManifest(json: string | unknown): DefineCapabilityManifestResult;
+declare function toJSON(manifest: CapabilityManifest): CapabilityManifest;
+declare function validateCapabilityManifest(manifest: CapabilityManifest, hostCapabilities: HostCapabilities): ValidateCapabilityManifestResult;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Shared normalized coordinate, anchor, and hit-region contract. Hosts and
+ * adapters may adopt this later; pixel `PresentationRegion` is unchanged.
+ *
+ * Coordinate spaces:
+ * - `normalized` — 0–1 of the **content** box (full intrinsic artwork, not letterbox).
+ * - `asset` — intrinsic content pixels (`contentWidth` × `contentHeight`).
+ * - `css` / `viewport` — layout pixels (`viewportWidth` × `viewportHeight`).
+ * - `canvas` — drawing-buffer pixels (`css * devicePixelRatio`). Pointers match
+ *   `PointerManager` / harness `click` when the buffer is the drawing canvas.
+ *
+ * Pointer helpers default to **canvas** space. Pass `{ space: 'css' }` for
+ * layout pixels. Round-trip: `ROUND_TRIP_TOLERANCE` (1e-6 normalized) or
+ * `ROUND_TRIP_TOLERANCE_CANVAS_PX` (0.5 canvas px).
+ */
+declare const GEOMETRY_CONTRACT_VERSION: 1;
+/** Maximum |Δ| in normalized units after canvas/css round-trip. */
+declare const ROUND_TRIP_TOLERANCE = 0.000001;
+/** Maximum |Δ| in canvas pixels after normalized round-trip. */
+declare const ROUND_TRIP_TOLERANCE_CANVAS_PX = 0.5;
+declare const COORDINATE_SPACES: readonly ["normalized", "asset", "canvas", "css", "viewport"];
+type CoordinateSpace = (typeof COORDINATE_SPACES)[number];
+type PointerSpace = 'canvas' | 'css';
+type PresentationFitMode = 'contain' | 'cover' | 'crop';
+declare const ANCHOR_ORIGINS: readonly ["center", "top-left", "top-right", "bottom-left", "bottom-right", "top", "bottom", "left", "right"];
+type AnchorOrigin = (typeof ANCHOR_ORIGINS)[number];
+type NormalizedPoint = {
+    x: number;
+    y: number;
+};
+type NormalizedRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type NormalizedPolygon = readonly NormalizedPoint[];
+type PixelPoint = {
+    x: number;
+    y: number;
+};
+type PixelRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type GeometryPadding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Insets from the content edges in normalized units (0–1). */
+type GeometrySafeArea = GeometryPadding;
+type GeometryAnchor = {
+    id: string;
+    point: NormalizedPoint;
+    origin?: AnchorOrigin;
+};
+type GeometryHitbox = {
+    id: string;
+    rect?: NormalizedRect;
+    polygon?: NormalizedPolygon;
+};
+type GeometryDocument = {
+    version: typeof GEOMETRY_CONTRACT_VERSION;
+    landmarks: GeometryAnchor[];
+    regions: GeometryHitbox[];
+    padding?: GeometryPadding;
+    safeArea?: GeometrySafeArea;
+};
+type CreatePresentationLayoutInput = {
+    contentWidth: number;
+    contentHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    mode: PresentationFitMode;
+    /** Canvas buffer pixels per CSS pixel. Default 1. */
+    devicePixelRatio?: number;
+};
+type PresentationLayout = {
+    mode: PresentationFitMode;
+    contentWidth: number;
+    contentHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    /** Content → CSS pixels. */
+    scale: number;
+    /** Letterbox (positive) or crop (negative) offset of content origin in CSS. */
+    offsetX: number;
+    offsetY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    /** Visible slice of the content box in normalized space. */
+    visibleNormalizedRect: NormalizedRect;
+};
+type GeometryDiagnostic = {
+    code: 'out-of-bounds' | 'overlap' | 'duplicate-id' | 'invalid-shape' | 'version-mismatch';
+    id?: string;
+    detail: string;
+    with?: string;
+};
+type GeometryValidation = {
+    ok: boolean;
+    diagnostics: GeometryDiagnostic[];
+};
+type LandmarkRegisterResult = {
+    ok: true;
+    landmark: GeometryAnchor;
+} | {
+    ok: false;
+    error: 'duplicate-id';
+    id: string;
+};
+type LandmarkRegistry = {
+    register(landmark: GeometryAnchor): LandmarkRegisterResult;
+    get(id: string): GeometryAnchor | undefined;
+    list(): GeometryAnchor[];
+};
+type DebugDrawCall = {
+    method: string;
+    id?: string;
+    args: unknown[];
+};
+type GeometryDebugContext = {
+    fillStyle?: string;
+    strokeStyle?: string;
+    font?: string;
+    fillRect?(x: number, y: number, w: number, h: number): void;
+    strokeRect?(x: number, y: number, w: number, h: number): void;
+    fillText?(text: string, x: number, y: number): void;
+    beginPath?(): void;
+    moveTo?(x: number, y: number): void;
+    lineTo?(x: number, y: number): void;
+    closePath?(): void;
+    stroke?(): void;
+    fill?(): void;
+};
+declare function pointFromOrigin(origin: AnchorOrigin): NormalizedPoint;
+declare function createPresentationLayout(input: CreatePresentationLayoutInput): PresentationLayout;
+declare function normalizedToAsset(point: NormalizedPoint, layout: PresentationLayout): PixelPoint;
+declare function assetToNormalized(point: PixelPoint, layout: PresentationLayout): NormalizedPoint;
+declare function normalizedToCss(point: NormalizedPoint, layout: PresentationLayout): PixelPoint;
+declare function cssToNormalized(point: PixelPoint, layout: PresentationLayout): NormalizedPoint;
+declare function cssToCanvas(point: PixelPoint, layout: PresentationLayout): PixelPoint;
+declare function canvasToCss(point: PixelPoint, layout: PresentationLayout): PixelPoint;
+declare function normalizedToCanvas(point: NormalizedPoint, layout: PresentationLayout): PixelPoint;
+declare function canvasToNormalized(point: PixelPoint, layout: PresentationLayout): NormalizedPoint;
+declare function rectToCss(rect: NormalizedRect, layout: PresentationLayout): PixelRect;
+declare function rectToCanvas(rect: NormalizedRect, layout: PresentationLayout): PixelRect;
+/**
+ * Pointer is in **canvas** pixels unless `{ space: 'css' }` is passed.
+ * Returns the first region whose rect or polygon contains the point, in
+ * document order.
+ */
+declare function pointerToRegion(pointer: PixelPoint, layout: PresentationLayout, doc: GeometryDocument, options?: {
+    space?: PointerSpace;
+}): GeometryHitbox | undefined;
+/** Visible CSS (viewport) rectangle for a region; polygons use their AABB. */
+declare function regionToViewport(region: GeometryHitbox, layout: PresentationLayout): PixelRect | undefined;
+declare function createLandmarkRegistry(initial?: readonly GeometryAnchor[]): LandmarkRegistry;
+declare function validateGeometry(doc: GeometryDocument): GeometryValidation;
+/**
+ * Draws labeled region rects and reports validation failures as extra labels.
+ * Tests may pass a stub that records `fillRect` / `strokeRect` / `fillText`.
+ */
+declare function drawGeometryDebug(ctx: GeometryDebugContext, layout: PresentationLayout, doc: GeometryDocument, diagnostics?: readonly GeometryDiagnostic[]): DebugDrawCall[];
+declare function serializeGeometry(doc: GeometryDocument): string;
+declare function parseGeometry(json: string): GeometryDocument;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * First-class multi-cart runtime group. Creates production `createRuntime`
+ * instances, attaches each mailbox to one shared `createEventRouter`, and
+ * locksteps a deterministic clock. Carts never receive the router object.
+ */
+
+declare const DEFAULT_GROUP_WIDTH = 320;
+declare const DEFAULT_GROUP_HEIGHT = 180;
+type RuntimeGroupKind = 'render' | 'calculation';
+/**
+ * Optional capability-shaped attach hints. Explicit participant `emit` /
+ * `subscribe` / `authoritative` win. Do not import the capability manifest
+ * module from this file.
+ */
+type RuntimeGroupCapability = {
+    emit?: string[];
+    subscribe?: string[];
+    authoritative?: boolean;
+};
+type RuntimeGroupFrameError = {
+    error: unknown;
+    info: FrameErrorInfo;
+};
+type RuntimeGroupParticipantConfig<T = unknown> = {
+    id: string;
+    cart: AnimationCart<T>;
+    /** Rendered surface vs calculation cart (still a real `AnimationCart`). */
+    kind?: RuntimeGroupKind;
+    seed?: CreateRuntimeOptions['seed'];
+    container?: HTMLElement;
+    width?: number;
+    height?: number;
+    initialState?: Partial<T>;
+    gameManager?: unknown;
+    onEvent?: HostEventListener;
+    emit?: string[];
+    subscribe?: string[];
+    authoritative?: boolean;
+    capability?: RuntimeGroupCapability;
+};
+type CreateRuntimeGroupOptions = {
+    participants: RuntimeGroupParticipantConfig[];
+    /** Shared virtual-clock origin (ms). Default 0. */
+    origin?: number;
+    width?: number;
+    height?: number;
+    validate?: EventRouterOptions['validate'];
+    createId?: () => string;
+    now?: () => number;
+    /** Extra router options. Group injects shared `createId` / `now` unless set here. */
+    router?: EventRouterOptions;
+    /** Bound on the accepted-event trace (oldest dropped). Default 1024. */
+    maxTrace?: number;
+};
+type RuntimeGroupParticipantInspect = {
+    state: unknown;
+    events: HostEvent[];
+    errors: RuntimeGroupFrameError[];
+    kind: RuntimeGroupKind;
+    clock: ClockSnapshot;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
+};
+type RuntimeGroupDiagnostics = {
+    paused: boolean;
+    participantIds: string[];
+    clocks: Record<string, ClockSnapshot>;
+    rejections: unknown[];
+};
+type RuntimeGroupInspect = {
+    participants: Record<string, RuntimeGroupParticipantInspect>;
+    trace: EventEnvelope[];
+    diagnostics: RuntimeGroupDiagnostics;
+};
+type RuntimeGroupParticipantHandle = {
+    readonly id: string;
+    readonly kind: RuntimeGroupKind;
+    readonly runtime: CyberArtRuntime;
+    readonly container: HTMLElement;
+    readonly events: readonly HostEvent[];
+    readonly errors: readonly RuntimeGroupFrameError[];
+    get cart(): CartHandle;
+};
+type RuntimeGroup = {
+    readonly router: EventRouter;
+    readonly origin: number;
+    readonly paused: boolean;
+    participant(id: string): RuntimeGroupParticipantHandle;
+    step(frames?: number): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reset(): void;
+    /** 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;
+
+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 };