@cyberart-io/engine 0.0.4 → 0.0.5

package/dist/headless.d.ts

@@ -177,6 +177,7 @@ declare class PointerManager {
  */
 declare const EVENT_ENVELOPE_VERSION: 1;
 type EventKind = 'intent' | 'state' | 'diagnostic';
+type RejectionReason = 'malformed' | 'unauthorized' | 'host-rejected' | 'rate-limited' | 'loop-detected' | 'storm-detected' | 'unknown-target' | 'not-subscribed' | 'hop-limit';
 type EventEnvelope = {
     schemaVersion: typeof EVENT_ENVELOPE_VERSION;
     type: string;
@@ -592,72 +593,6 @@ type CyberArtRuntime = {
     onError?: (error: unknown, info: FrameErrorInfo) => void;
 };
 
-/**
- * Copyright (c) 2026 Aaron Boyarsky
- * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
- * See packages/engine/LICENSE
- *
- * CI / agent harness around production `createRuntime({ deterministic })`.
- * `installHeadlessCanvas` is test-only — do not call it from Player or kaleidoscope.
- */
-
-/** 1×1 PNG so `captureFrame(path)` writes a file that actually opens. */
-declare const HEADLESS_PNG_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
-declare const DEFAULT_HEADLESS_WIDTH = 320;
-declare const DEFAULT_HEADLESS_HEIGHT = 180;
-/**
- * Documented jsdom canvas install. Mutates `HTMLCanvasElement.prototype`.
- * Idempotent. Not for production playback.
- */
-declare function installHeadlessCanvas(): void;
-type HeadlessFrameError = {
-    error: unknown;
-    info: FrameErrorInfo;
-};
-type HeadlessInspect = {
-    state: unknown;
-    events: HostEvent[];
-    errors: HeadlessFrameError[];
-    replay: ReplayMetadata;
-    clock: ClockSnapshot;
-};
-type CreateHeadlessHarnessOptions<T = unknown> = {
-    cart: AnimationCart<T>;
-    seed?: CreateRuntimeOptions['seed'];
-    width?: number;
-    height?: number;
-    /** Virtual clock origin in ms. Default 0. */
-    origin?: number;
-    actions?: ScriptedAction[];
-    initialState?: Partial<T>;
-    gameManager?: unknown;
-    onEvent?: HostEventListener;
-    onError?: (error: unknown, info: FrameErrorInfo) => void;
-};
-type HeadlessHarness<T = unknown> = {
-    readonly runtime: CyberArtRuntime;
-    readonly container: HTMLElement;
-    readonly events: readonly HostEvent[];
-    readonly errors: readonly HeadlessFrameError[];
-    readonly cart: CartHandle;
-    step(frames?: number): Promise<void>;
-    advance(ms: number): Promise<void>;
-    schedule(action: ScriptedAction): void;
-    dispatch(event: HostEvent): void;
-    start(): Promise<void>;
-    pause(): void;
-    resume(): void;
-    readonly paused: boolean;
-    key(key: string): void;
-    /** Pointer-down at the next frame. Use `schedule` for move/up. Canvas pixels, not CSS. */
-    click(x: number, y: number): void;
-    inspect(): Promise<HeadlessInspect>;
-    captureFrame(path?: string): Promise<CartSnapshot>;
-    remount(options?: MountOptions<T>): CartHandle;
-    destroy(): void;
-};
-declare function createHeadlessHarness<T>(options: CreateHeadlessHarnessOptions<T>): HeadlessHarness<T>;
-
 /**
  * Copyright (c) 2026 Aaron Boyarsky
  * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
@@ -690,15 +625,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;
 };
 
@@ -755,6 +724,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;
@@ -762,6 +733,9 @@ type RuntimeGroupParticipantInspect = {
     errors: RuntimeGroupFrameError[];
     kind: RuntimeGroupKind;
     clock: ClockSnapshot;
+    emit: string[];
+    subscribe: string[];
+    authoritative: boolean;
 };
 type RuntimeGroupDiagnostics = {
     paused: boolean;
@@ -792,14 +766,470 @@ 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 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 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;
+};
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Deterministic software Canvas2D for jsdom / CI. Integer pixel coverage
+ * (pixel-center samples, nearest-neighbor images, no antialiasing). No
+ * Math.random. Unsupported operations throw HeadlessUnsupportedOperationError
+ * instead of no-op.
+ */
+declare class HeadlessUnsupportedOperationError extends Error {
+    readonly operation: string;
+    name: string;
+    constructor(operation: string, detail?: string);
+}
+type GlyphAtlas = {
+    cellWidth: number;
+    cellHeight: number;
+    /** Packed 0/1 coverage, `cellWidth * cellHeight` bits per glyph, row-major. */
+    glyphs: Record<string, Uint8Array>;
+};
+type HeadlessImageFixture = {
+    readonly __headlessImage: true;
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+type HeadlessCanvas2DSettings = {
+    alpha?: boolean;
+    glyphAtlas?: GlyphAtlas;
+};
+declare class HeadlessSurface {
+    readonly canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+    readonly alpha: boolean;
+    pixels: Uint8ClampedArray;
+    glyphAtlas: GlyphAtlas;
+    context: CanvasRenderingContext2D | null;
+    onDeviceReset: (() => void) | null;
+    constructor(canvas: HTMLCanvasElement, width: number, height: number, settings: HeadlessCanvas2DSettings);
+    resize(width: number, height: number, clear?: boolean): void;
+    fillOpaqueBlack(): void;
+}
+declare function createImageFixture(width: number, height: number, data?: Uint8ClampedArray): HeadlessImageFixture;
+declare function setDefaultGlyphAtlas(atlas: GlyphAtlas | undefined): void;
+declare function getHeadlessSurface(canvas: HTMLCanvasElement): HeadlessSurface | undefined;
+declare function attachHeadlessCanvas2D(canvas: HTMLCanvasElement, settings?: HeadlessCanvas2DSettings): CanvasRenderingContext2D;
+declare function makeImageData(data: Uint8ClampedArray, width: number, height: number): ImageData;
+declare function createDefaultGlyphAtlas(): GlyphAtlas;
+declare function encodePng(width: number, height: number, pixels: Uint8ClampedArray | Uint8Array): Uint8Array;
+declare function encodePngDataUrl(width: number, height: number, pixels: Uint8ClampedArray | Uint8Array): string;
+declare function decodePng(bytes: Uint8Array): ImageData;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * CI / agent harness around production `createRuntime({ deterministic })`.
+ * `installHeadlessCanvas` is test-only — do not call it from Player or kaleidoscope.
+ */
+
+/** 1×1 PNG fallback when `toDataURL` runs before a 2D context is attached. */
+declare const HEADLESS_PNG_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+declare const DEFAULT_HEADLESS_WIDTH = 320;
+declare const DEFAULT_HEADLESS_HEIGHT = 180;
+type InstallHeadlessCanvasOptions = {
+    glyphAtlas?: GlyphAtlas;
+};
+/**
+ * Documented jsdom canvas install. Mutates `HTMLCanvasElement.prototype`.
+ * Idempotent. Not for production playback. Software Canvas2D pixels flow
+ * through `getContext` / `toDataURL` so `cart.snapshot()` is the real frame.
+ */
+declare function installHeadlessCanvas(options?: InstallHeadlessCanvasOptions): void;
+type HeadlessFrameError = {
+    error: unknown;
+    info: FrameErrorInfo;
+};
+type HeadlessInspect = {
+    state: unknown;
+    events: HostEvent[];
+    errors: HeadlessFrameError[];
+    replay: ReplayMetadata;
+    clock: ClockSnapshot;
+};
+type CreateHeadlessHarnessOptions<T = unknown> = {
+    cart: AnimationCart<T>;
+    seed?: CreateRuntimeOptions['seed'];
+    width?: number;
+    height?: number;
+    /** Virtual clock origin in ms. Default 0. */
+    origin?: number;
+    actions?: ScriptedAction[];
+    initialState?: Partial<T>;
+    gameManager?: unknown;
+    onEvent?: HostEventListener;
+    onError?: (error: unknown, info: FrameErrorInfo) => void;
+};
+type HeadlessHarness<T = unknown> = {
+    readonly runtime: CyberArtRuntime;
+    readonly container: HTMLElement;
+    readonly events: readonly HostEvent[];
+    readonly errors: readonly HeadlessFrameError[];
+    readonly cart: CartHandle;
+    step(frames?: number): Promise<void>;
+    advance(ms: number): Promise<void>;
+    schedule(action: ScriptedAction): void;
+    dispatch(event: HostEvent): void;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+    key(key: string): void;
+    /** Pointer-down at the next frame. Use `schedule` for move/up. Canvas pixels, not CSS. */
+    click(x: number, y: number): void;
+    inspect(): Promise<HeadlessInspect>;
+    captureFrame(path?: string): Promise<CartSnapshot>;
+    remount(options?: MountOptions<T>): CartHandle;
+    destroy(): void;
+};
+declare function createHeadlessHarness<T>(options: CreateHeadlessHarnessOptions<T>): HeadlessHarness<T>;
+
+declare const UPDATE_GOLDEN_ENV = "CYBERART_UPDATE_GOLDEN";
+type VisualCompareOptions = {
+    /** Max per-channel absolute delta (0 = exact). */
+    tolerance?: number;
+    /** Max allowed differing pixels after tolerance. */
+    maxDifferingPixels?: number;
+    /**
+     * When set, a pixel matches if weighted RGB distance <= this value.
+     * Weights are 0.299 / 0.587 / 0.114 (documented luma).
+     */
+    perceptualThreshold?: number;
+    /** Alpha channel max delta. Defaults to `tolerance` (including when perceptual RGB is used). */
+    alphaTolerance?: number;
+    /** Force golden-update behavior regardless of env. */
+    updateGolden?: boolean;
+};
+type VisualArtifacts = {
+    expectedPng: Uint8Array;
+    actualPng: Uint8Array;
+    diffPng: Uint8Array;
+    expectedDataUrl: string;
+    actualDataUrl: string;
+    diffDataUrl: string;
+    differingPixels: number;
+};
+type VisualCompareResult = {
+    match: boolean;
+    differingPixels: number;
+    width: number;
+    height: number;
+    artifacts: VisualArtifacts;
+    updatedGolden: boolean;
+};
+declare function shouldUpdateGolden(env?: {
+    [key: string]: string | undefined;
+} | undefined): boolean;
+declare function imageDataFromPngDataUrl(dataUrl: string): ImageData;
+declare function compareImageData(actual: ImageData, expected: ImageData, options?: VisualCompareOptions): VisualCompareResult;
+declare function assertPixelsEqual(actual: ImageData, expected: ImageData, options?: VisualCompareOptions): VisualCompareResult;
+declare function assertPngDataUrlsEqual(actualDataUrl: string, expectedDataUrl: string, options?: VisualCompareOptions): VisualCompareResult;
+type VisualArtifactPaths = {
+    expectedPath: string;
+    actualPath: string;
+    diffPath: string;
+};
+/**
+ * Node-only. Writes expected.png / actual.png / diff.png under `dir`.
+ * Uses a dynamic `node:fs/promises` import so the browser runtime graph stays clean.
+ */
+declare function writeVisualArtifacts(dir: string, artifacts: VisualArtifacts, names?: {
+    expected?: string;
+    actual?: string;
+    diff?: string;
+}): Promise<VisualArtifactPaths>;
+
 type CreateHeadlessMultiCartHarnessOptions = CreateRuntimeGroupOptions;
 type HeadlessMultiCartHarness = RuntimeGroup;
 declare function createHeadlessMultiCartHarness(options: CreateHeadlessMultiCartHarnessOptions): HeadlessMultiCartHarness;
 
-export { type CreateHeadlessHarnessOptions, type CreateHeadlessMultiCartHarnessOptions, DEFAULT_HEADLESS_HEIGHT, DEFAULT_HEADLESS_WIDTH, HEADLESS_PNG_DATA_URL, type HeadlessFrameError, type HeadlessHarness, type HeadlessInspect, type HeadlessMultiCartHarness, createHeadlessHarness, createHeadlessMultiCartHarness, installHeadlessCanvas };
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * One contract definition drives TypeScript payload types, runtime
+ * validation, router permission checks, and machine-readable manifests.
+ * Kind must appear as a dotted segment of `type` so names like
+ * `host.presentation.cue.started` fail at definition time instead of
+ * silently inferring a bogus kind.
+ */
+
+type ContractFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+type PayloadFieldSpec = {
+    type: ContractFieldType;
+    optional?: boolean;
+};
+type PayloadSchema = {
+    /** Payload schema version. Bump on any field change. */
+    version: number;
+    fields: Record<string, PayloadFieldSpec>;
+};
+type ContractDiagnostic = {
+    code: string;
+    detail: string;
+    path?: string;
+};
+type EventContractManifest = {
+    type: string;
+    kind: EventKind;
+    version: number;
+    fields: Record<string, {
+        type: ContractFieldType;
+        optional: boolean;
+    }>;
+    emitPattern: string;
+    subscribePattern: string;
+};
+type PayloadValidation = {
+    ok: true;
+    payload: unknown;
+} | {
+    ok: false;
+    errors: ContractDiagnostic[];
+};
+type EventContract = {
+    type: string;
+    kind: EventKind;
+    payloadSchema: PayloadSchema;
+    emitPattern: string;
+    subscribePattern: string;
+    toManifest(): EventContractManifest;
+    validatePayload(payload: unknown): PayloadValidation;
+};
+type ContractRegistry = {
+    get(type: string): EventContract | undefined;
+    manifest(): EventContractManifest[];
+    validateEnvelope(event: EventEnvelope): PayloadValidation;
+    asRouterValidate(event: EventEnvelope): ValidateResult;
+};
+
+declare const REPLAY_INSPECTOR_SCHEMA_VERSION: 1;
+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;
+}>;
+
+/**
+ * Copyright (c) 2026 Aaron Boyarsky
+ * SPDX-License-Identifier: LicenseRef-CyberArt-Engine
+ * See packages/engine/LICENSE
+ *
+ * Node/jsdom test helpers. Import from `@cyberart-io/engine/headless`.
+ * Production carts and browser hosts must import `@cyberart-io/engine` instead
+ * so Vite never walks `node:fs/promises`.
+ */
+
+type WriteComposedFrameResult = ComposedFrame & {
+    path?: string;
+};
+/**
+ * Headless composition-order capture. `captureComposedFrame()` stays on the
+ * compositor (browser-safe). This helper writes PNG bytes when a path is given.
+ */
+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 GlyphAtlas, HEADLESS_PNG_DATA_URL, 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 WriteComposedFrameResult, assertPixelsEqual, assertPngDataUrlsEqual, attachHeadlessCanvas2D, compareImageData, compareReplayTraces, createDefaultGlyphAtlas, createHeadlessHarness, createHeadlessMultiCartHarness, createImageFixture, createReplayInspector, decodePng, encodePng, encodePngDataUrl, getHeadlessSurface, imageDataFromPngDataUrl, installHeadlessCanvas, makeImageData, replayExportedTrace, setDefaultGlyphAtlas, shouldUpdateGolden, writeComposedFrame, writeVisualArtifacts };