@zvk/game-bridge 0.1.0

package/dist/geometry/visibility.js

@@ -0,0 +1,128 @@
+import { point2, rect2 } from "./types.js";
+function assertInsets(insets) {
+    for (const [name, value] of Object.entries(insets)) {
+        if (!Number.isFinite(value) || value < 0)
+            throw new RangeError(`${name} inset must be finite and non-negative`);
+    }
+}
+function finiteMargins(margins) {
+    if (![margins.top, margins.right, margins.bottom, margins.left].every(Number.isFinite)) {
+        throw new RangeError("Visibility margins must be finite");
+    }
+}
+export function insetRect(rect, insets) {
+    assertInsets(insets);
+    const width = Math.max(0, rect.width - insets.left - insets.right);
+    const height = Math.max(0, rect.height - insets.top - insets.bottom);
+    const x = width === 0 ? rect.x + rect.width / 2 : rect.x + insets.left;
+    const y = height === 0 ? rect.y + rect.height / 2 : rect.y + insets.top;
+    return rect2("overlay", x, y, width, height);
+}
+export function expandRect(rect, margins) {
+    finiteMargins(margins);
+    const rawWidth = rect.width + margins.left + margins.right;
+    const rawHeight = rect.height + margins.top + margins.bottom;
+    const width = Math.max(0, rawWidth);
+    const height = Math.max(0, rawHeight);
+    return rect2("overlay", width === 0 ? rect.x + rect.width / 2 : rect.x - margins.left, height === 0 ? rect.y + rect.height / 2 : rect.y - margins.top, width, height);
+}
+export function containsPoint(rect, point) {
+    return point.x >= rect.x && point.y >= rect.y && point.x < rect.x + rect.width && point.y < rect.y + rect.height;
+}
+export function containsPointInConvexQuad(quad, point) {
+    const points = [quad.topLeft, quad.topRight, quad.bottomRight, quad.bottomLeft];
+    let sign = 0;
+    for (let index = 0; index < points.length; index += 1) {
+        const first = points[index];
+        const second = points[(index + 1) % points.length];
+        const cross = (second.x - first.x) * (point.y - first.y) - (second.y - first.y) * (point.x - first.x);
+        if (cross === 0)
+            continue;
+        const current = Math.sign(cross);
+        if (sign !== 0 && current !== sign)
+            return false;
+        sign = current;
+    }
+    return true;
+}
+export function intersectRects(left, right) {
+    const x = Math.max(left.x, right.x);
+    const y = Math.max(left.y, right.y);
+    const farX = Math.min(left.x + left.width, right.x + right.width);
+    const farY = Math.min(left.y + left.height, right.y + right.height);
+    return farX <= x || farY <= y ? null : rect2("overlay", x, y, farX - x, farY - y);
+}
+export function unionRects(left, right) {
+    const x = Math.min(left.x, right.x);
+    const y = Math.min(left.y, right.y);
+    return rect2("overlay", x, y, Math.max(left.x + left.width, right.x + right.width) - x, Math.max(left.y + left.height, right.y + right.height) - y);
+}
+export function clampPointToRect(point, rect) {
+    return point2("overlay", Math.min(Math.max(point.x, rect.x), rect.x + rect.width), Math.min(Math.max(point.y, rect.y), rect.y + rect.height));
+}
+function previousRepresentable(value) {
+    if (!Number.isFinite(value))
+        return value;
+    if (value === 0)
+        return -Number.MIN_VALUE;
+    const buffer = new ArrayBuffer(8);
+    const float = new Float64Array(buffer);
+    const bits = new BigUint64Array(buffer);
+    float[0] = value;
+    bits[0] = bits[0] + (value > 0 ? -1n : 1n);
+    return float[0];
+}
+export function clampPointToHalfOpenRect(point, rect) {
+    if (rect.width <= 0 || rect.height <= 0)
+        return point2("overlay", rect.x, rect.y);
+    return point2("overlay", Math.min(Math.max(point.x, rect.x), previousRepresentable(rect.x + rect.width)), Math.min(Math.max(point.y, rect.y), previousRepresentable(rect.y + rect.height)));
+}
+export function closestPointOnRectEdge(point, rect) {
+    const clamped = clampPointToRect(point, rect);
+    if (!containsPoint(rect, point))
+        return clamped;
+    const distances = [
+        { distance: point.y - rect.y, x: point.x, y: rect.y },
+        { distance: rect.x + rect.width - point.x, x: rect.x + rect.width, y: point.y },
+        { distance: rect.y + rect.height - point.y, x: point.x, y: rect.y + rect.height },
+        { distance: point.x - rect.x, x: rect.x, y: point.y },
+    ];
+    const closest = distances.reduce((best, candidate) => candidate.distance < best.distance ? candidate : best);
+    return point2("overlay", closest.x, closest.y);
+}
+export function intersectRayWithRect(origin, direction, rect) {
+    if (![origin.x, origin.y, direction.x, direction.y].every(Number.isFinite) || (direction.x === 0 && direction.y === 0))
+        return null;
+    const candidates = [];
+    const add = (distance, edge) => {
+        if (distance < 0 || !Number.isFinite(distance))
+            return;
+        const x = origin.x + direction.x * distance;
+        const y = origin.y + direction.y * distance;
+        if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
+            candidates.push({ point: point2("overlay", x, y), edge, distance });
+        }
+    };
+    if (direction.y !== 0) {
+        add((rect.y - origin.y) / direction.y, "top");
+        add((rect.y + rect.height - origin.y) / direction.y, "bottom");
+    }
+    if (direction.x !== 0) {
+        add((rect.x - origin.x) / direction.x, "left");
+        add((rect.x + rect.width - origin.x) / direction.x, "right");
+    }
+    candidates.sort((left, right) => left.distance - right.distance || left.edge.localeCompare(right.edge));
+    return candidates[0] ?? null;
+}
+export function overflowInsets(inner, outer) {
+    return {
+        top: Math.max(0, outer.y - inner.y),
+        right: Math.max(0, inner.x + inner.width - (outer.x + outer.width)),
+        bottom: Math.max(0, inner.y + inner.height - (outer.y + outer.height)),
+        left: Math.max(0, outer.x - inner.x),
+    };
+}
+export function overlapArea(left, right) {
+    const intersection = intersectRects(left, right);
+    return intersection === null ? 0 : intersection.width * intersection.height;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./core/channel.js";
+export * from "./core/coalesced-publisher.js";
+export * from "./core/game-bridge.js";
+export type { IntentDispatchResult, IntentEnvelope, IntentSink, } from "./core/intents.js";
+export { assertJsonValue } from "./core/serializable.js";
+export * from "./core/types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./core/channel.js";
+export * from "./core/coalesced-publisher.js";
+export * from "./core/game-bridge.js";
+export { assertJsonValue } from "./core/serializable.js";
+export * from "./core/types.js";

package/dist/phaser/index.d.ts

@@ -0,0 +1,187 @@
+import type { BridgePublishResult, BridgePublisher, GameBridgeDiagnostic, GameBridgeFrame, JsonValue } from "../index.js";
+import { type AffineTransform2D, type InverseProjectionResult, type OutsideProjectionPolicy, type Point2, type Rect2, type Size2, type WorldAnchorSnapshot } from "../geometry/index.js";
+import { type CanvasDomMetrics, type DomReferenceBox } from "../dom/index.js";
+export interface PhaserPointLike {
+    readonly x: number;
+    readonly y: number;
+}
+export interface PhaserTransformMatrixLike {
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+    readonly d: number;
+    readonly e: number;
+    readonly f: number;
+}
+export interface PhaserCameraLike {
+    readonly name?: string;
+    readonly id?: number;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly scrollX: number;
+    readonly scrollY: number;
+    readonly zoom?: number;
+    readonly zoomX?: number;
+    readonly zoomY?: number;
+    readonly rotation?: number;
+    readonly originX?: number;
+    readonly originY?: number;
+    readonly roundPixels?: boolean;
+    readonly visible?: boolean;
+    readonly inputEnabled?: boolean;
+    readonly matrix?: PhaserTransformMatrixLike;
+    readonly matrixCombined?: PhaserTransformMatrixLike;
+    readonly getWorldPoint: (x: number, y: number, output?: {
+        x: number;
+        y: number;
+    }) => PhaserPointLike;
+}
+export interface PhaserEventEmitterLike {
+    readonly on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    readonly once: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    readonly off: (event: string, listener: (...args: unknown[]) => void) => unknown;
+}
+export interface PhaserSizeLike {
+    readonly width: number;
+    readonly height: number;
+}
+export interface PhaserScaleManagerLike extends PhaserEventEmitterLike {
+    readonly gameSize: PhaserSizeLike;
+    readonly baseSize: PhaserSizeLike;
+    readonly displaySize: PhaserSizeLike;
+    readonly displayScale?: PhaserPointLike;
+    readonly scaleMode?: string | number;
+}
+export interface PhaserSceneLike {
+    readonly events: PhaserEventEmitterLike;
+    readonly game: {
+        readonly canvas: HTMLCanvasElement;
+    };
+    readonly scale: PhaserScaleManagerLike;
+}
+export interface PhaserBridgeError {
+    readonly code: "dom-unavailable" | "resize-observer-unavailable" | "scheduler-unavailable" | "camera-unavailable" | "camera-id-unavailable" | "canvas-disconnected" | "overlay-disconnected" | "zero-sized-surface" | "invalid-backing-size" | "non-finite-measurement" | "invalid-clock-id" | "non-finite-transform" | "non-invertible-transform" | "inconsistent-transform-snapshot" | "unsupported-camera-transform" | "unsupported-css-transform" | "duplicate-anchor-id" | "source-frame-regression" | "clock-mismatch" | "capture-callback-threw" | "destroyed";
+    readonly message: string;
+}
+export interface PhaserCameraProjectionSnapshot {
+    readonly cameraId: string;
+    readonly worldToCamera: AffineTransform2D<"world", "camera">;
+    readonly cameraViewport: Rect2<"game">;
+    readonly visible: boolean;
+    readonly roundPixels: boolean;
+    readonly matrixSource: "render-matrix" | "world-point-sampling";
+    readonly cameraEffectsIncluded: boolean;
+}
+export interface ReadPhaserCameraOptions {
+    readonly cameraId?: string;
+    readonly includeCameraEffects?: boolean;
+    readonly matrixSource?: "render-matrix" | "world-point-sampling";
+}
+export type ReadPhaserCameraResult = {
+    readonly ok: true;
+    readonly snapshot: PhaserCameraProjectionSnapshot;
+} | {
+    readonly ok: false;
+    readonly error: PhaserBridgeError;
+};
+export declare function readPhaserCameraProjection(camera: PhaserCameraLike, options?: ReadPhaserCameraOptions): ReadPhaserCameraResult;
+export interface PhaserSurfaceProjection {
+    readonly capturedAtMs: number;
+    readonly clockId: string;
+    readonly gameLogicalSize: Size2<"game">;
+    readonly gameViewportInBacking: Rect2<"backing">;
+    readonly canvasBackingSize: Size2<"backing">;
+    readonly gameToBacking: AffineTransform2D<"game", "backing">;
+    readonly dom: CanvasDomMetrics;
+    readonly scaleMode?: string | number;
+}
+export type PhaserSurfaceProjectionResult = {
+    readonly ok: true;
+    readonly surface: PhaserSurfaceProjection;
+} | {
+    readonly ok: false;
+    readonly error: PhaserBridgeError;
+};
+export interface ReadPhaserSurfaceOptions {
+    readonly scene: PhaserSceneLike;
+    readonly canvas?: HTMLCanvasElement;
+    readonly overlay: HTMLElement;
+    readonly overlayBox?: DomReferenceBox;
+    readonly capturedAtMs?: number;
+    readonly clockId?: string;
+}
+export declare function readPhaserSurfaceProjection(options: ReadPhaserSurfaceOptions): PhaserSurfaceProjectionResult;
+export interface PhaserWorldAnchor<TMetadata extends JsonValue = JsonValue> extends WorldAnchorSnapshot<TMetadata> {
+    readonly scrollFactor?: {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+export declare function clientPointToPhaserWorld(camera: PhaserCameraLike, surface: PhaserSurfaceProjection, point: Point2<"client">, options?: {
+    readonly outside?: OutsideProjectionPolicy;
+}): InverseProjectionResult;
+export interface CreatePhaserSceneBridgeOptions<TMetadata extends JsonValue = JsonValue> {
+    readonly scene: PhaserSceneLike;
+    readonly camera: PhaserCameraLike | (() => PhaserCameraLike | null);
+    readonly overlay: HTMLElement | (() => HTMLElement | null);
+    readonly publisher: BridgePublisher<GameBridgeFrame<TMetadata>>;
+    readonly readAnchors: () => readonly PhaserWorldAnchor<TMetadata>[];
+    readonly nextSourceFrameId?: () => number;
+    readonly clock?: {
+        readonly id: string;
+        readonly now: () => number;
+    };
+    readonly phase?: "render" | "postupdate" | "manual";
+    readonly inactivePolicy?: "retain" | "not-ready";
+    readonly onDiagnostic?: (diagnostic: GameBridgeDiagnostic) => void;
+}
+export type PhaserFrameCaptureResult = {
+    readonly status: "staged-ready" | "staged-not-ready" | "replaced-pending";
+    readonly sourceFrameId: number;
+    readonly diagnostics: readonly GameBridgeDiagnostic[];
+} | {
+    readonly status: "disconnected" | "destroyed";
+};
+export type PhaserFrameFlushResult = {
+    readonly status: "empty";
+} | BridgePublishResult;
+export type PhaserBridgeDisconnectResult = {
+    readonly status: "disconnected";
+    readonly publication: BridgePublishResult;
+} | {
+    readonly status: "already-disconnected";
+} | {
+    readonly status: "destroyed";
+};
+export type PhaserSceneBridgeDestroyResult = {
+    readonly status: "destroyed";
+    readonly publication?: BridgePublishResult;
+} | {
+    readonly status: "already-destroyed";
+};
+export interface PhaserSceneBridgeStatus {
+    readonly lifecycle: "connected" | "inactive" | "disconnected" | "destroyed";
+    readonly phase: "render" | "postupdate" | "manual";
+    readonly generation: number;
+    readonly lastSourceFrameId: number;
+    readonly pending: boolean;
+    readonly listenerCount: number;
+    readonly observerCount: number;
+}
+export interface PhaserSceneBridgeConnection {
+    readonly capture: () => PhaserFrameCaptureResult;
+    readonly flush: () => PhaserFrameFlushResult;
+    readonly disconnect: (reason?: string) => PhaserBridgeDisconnectResult;
+    readonly destroy: () => PhaserSceneBridgeDestroyResult;
+    readonly getStatus: () => PhaserSceneBridgeStatus;
+}
+export type CreatePhaserSceneBridgeResult = {
+    readonly ok: true;
+    readonly connection: PhaserSceneBridgeConnection;
+} | {
+    readonly ok: false;
+    readonly error: PhaserBridgeError;
+};
+export declare function createPhaserSceneBridge<TMetadata extends JsonValue>(options: CreatePhaserSceneBridgeOptions<TMetadata>): CreatePhaserSceneBridgeResult;

package/dist/phaser/index.js

@@ -0,0 +1,347 @@
+import { affineTransform, clientPoint, compileProjectionContext, composeTransforms, gamePoint, invertTransform, projectWorldAnchors, rect2, size2, transformPoint, translationTransform, } from "../geometry/index.js";
+import { measureGameSurface, observeGameSurface, } from "../dom/index.js";
+const phaserError = (code, message) => ({ ok: false, error: { code, message } });
+const finite = (...values) => values.every(Number.isFinite);
+export function readPhaserCameraProjection(camera, options = {}) {
+    const cameraId = options.cameraId?.trim() || camera.name?.trim() || (Number.isFinite(camera.id) ? `camera-${camera.id}` : "");
+    if (!cameraId)
+        return phaserError("camera-id-unavailable", "An explicit stable camera identity is required");
+    if (!finite(camera.x, camera.y, camera.width, camera.height) || camera.width < 0 || camera.height < 0)
+        return phaserError("non-finite-transform", "Camera viewport is invalid");
+    const source = options.matrixSource ?? ((camera.matrixCombined ?? camera.matrix) ? "render-matrix" : "world-point-sampling");
+    let worldToGame;
+    if (source === "render-matrix") {
+        const matrix = camera.matrixCombined ?? camera.matrix;
+        if (!matrix || !finite(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f))
+            return phaserError("unsupported-camera-transform", "A finite public render matrix is unavailable");
+        const scroll = translationTransform("world", "world", -camera.scrollX, -camera.scrollY);
+        worldToGame = composeTransforms(scroll, affineTransform("world", "game", matrix));
+    }
+    else {
+        try {
+            const origin = camera.getWorldPoint(camera.x, camera.y);
+            const x = camera.getWorldPoint(camera.x + 1, camera.y);
+            const y = camera.getWorldPoint(camera.x, camera.y + 1);
+            if (!finite(origin.x, origin.y, x.x, x.y, y.x, y.y))
+                return phaserError("non-finite-transform", "Camera world-point samples were non-finite");
+            const gameToWorld = affineTransform("game", "world", {
+                a: x.x - origin.x, b: x.y - origin.y, c: y.x - origin.x, d: y.y - origin.y,
+                e: origin.x - (x.x - origin.x) * camera.x - (y.x - origin.x) * camera.y,
+                f: origin.y - (x.y - origin.y) * camera.x - (y.y - origin.y) * camera.y,
+            });
+            const inverse = invertTransform(gameToWorld);
+            if (!inverse.ok)
+                return phaserError(inverse.error.code, "Camera world-point transform is not invertible");
+            worldToGame = inverse.value;
+        }
+        catch {
+            return phaserError("unsupported-camera-transform", "Camera world-point sampling failed");
+        }
+    }
+    const gameToCamera = translationTransform("game", "camera", -camera.x, -camera.y);
+    return {
+        ok: true,
+        snapshot: Object.freeze({
+            cameraId,
+            worldToCamera: Object.freeze(composeTransforms(worldToGame, gameToCamera)),
+            cameraViewport: Object.freeze(rect2("game", camera.x, camera.y, camera.width, camera.height)),
+            visible: camera.visible !== false,
+            roundPixels: camera.roundPixels === true,
+            matrixSource: source,
+            cameraEffectsIncluded: options.includeCameraEffects !== false,
+        }),
+    };
+}
+export function readPhaserSurfaceProjection(options) {
+    const canvas = options.canvas ?? options.scene.game.canvas;
+    const dom = measureGameSurface({
+        canvas,
+        overlay: options.overlay,
+        ...(options.overlayBox === undefined ? {} : { overlayBox: options.overlayBox }),
+        ...(options.capturedAtMs === undefined ? {} : { capturedAtMs: options.capturedAtMs }),
+        ...(options.clockId === undefined ? {} : { clockId: options.clockId }),
+    });
+    if (!dom.ok)
+        return phaserError(dom.error.code, dom.error.message);
+    const game = options.scene.scale.gameSize;
+    const base = options.scene.scale.baseSize;
+    if (!finite(game.width, game.height, base.width, base.height) || game.width <= 0 || game.height <= 0 || base.width <= 0 || base.height <= 0)
+        return phaserError("zero-sized-surface", "Phaser game or base size is zero or invalid");
+    const mode = options.scene.scale.scaleMode;
+    const uniformMode = mode === 3 || mode === 6 || (typeof mode === "string" && /^(FIT|EXPAND)$/i.test(mode));
+    const naturalScaleX = base.width / game.width;
+    const naturalScaleY = base.height / game.height;
+    const uniformScale = Math.min(naturalScaleX, naturalScaleY);
+    const scaleX = uniformMode ? uniformScale : naturalScaleX;
+    const scaleY = uniformMode ? uniformScale : naturalScaleY;
+    const viewportWidth = game.width * scaleX;
+    const viewportHeight = game.height * scaleY;
+    const viewportX = (canvas.width - viewportWidth) / 2;
+    const viewportY = (canvas.height - viewportHeight) / 2;
+    const gameToBacking = affineTransform("game", "backing", { a: scaleX, b: 0, c: 0, d: scaleY, e: viewportX, f: viewportY });
+    const surface = {
+        capturedAtMs: dom.metrics.capturedAtMs,
+        clockId: dom.metrics.clockId,
+        gameLogicalSize: size2("game", game.width, game.height),
+        gameViewportInBacking: rect2("backing", viewportX, viewportY, viewportWidth, viewportHeight),
+        canvasBackingSize: size2("backing", canvas.width, canvas.height),
+        gameToBacking,
+        dom: dom.metrics,
+        ...(options.scene.scale.scaleMode !== undefined ? { scaleMode: options.scene.scale.scaleMode } : {}),
+    };
+    return { ok: true, surface: Object.freeze(surface) };
+}
+export function clientPointToPhaserWorld(camera, surface, point, options = {}) {
+    const cssToClient = invertTransform(surface.dom.canvasCssToClient);
+    const backingToCss = invertTransform(surface.dom.backingToCanvasCss);
+    const gameToBacking = invertTransform(surface.gameToBacking);
+    if (!cssToClient.ok || !backingToCss.ok || !gameToBacking.ok)
+        return { ok: false, error: { code: "non-invertible-transform" } };
+    let game = transformPoint(gameToBacking.value, transformPoint(backingToCss.value, transformPoint(cssToClient.value, clientPoint(point.x, point.y))));
+    const viewport = { x: camera.x, y: camera.y, width: camera.width, height: camera.height };
+    const outside = game.x < viewport.x || game.y < viewport.y || game.x >= viewport.x + viewport.width || game.y >= viewport.y + viewport.height;
+    if (outside && (options.outside ?? "reject") === "reject")
+        return { ok: false, error: { code: "outside-camera" } };
+    let wasClamped = false;
+    if (outside && options.outside === "clamp-to-camera") {
+        game = gamePoint(Math.min(Math.max(game.x, viewport.x), Math.max(viewport.x, viewport.x + viewport.width - Number.EPSILON)), Math.min(Math.max(game.y, viewport.y), Math.max(viewport.y, viewport.y + viewport.height - Number.EPSILON)));
+        wasClamped = true;
+    }
+    try {
+        const world = camera.getWorldPoint(game.x, game.y);
+        if (!finite(world.x, world.y))
+            return { ok: false, error: { code: "invalid-point" } };
+        return { ok: true, worldPoint: { x: world.x, y: world.y }, gamePoint: game, wasClamped };
+    }
+    catch {
+        return { ok: false, error: { code: "invalid-point" } };
+    }
+}
+let connectorGeneration = 0;
+function diagnostic(code, message, capturedAtMs) {
+    return { code, severity: "error", message, ...(capturedAtMs === undefined ? {} : { capturedAtMs }) };
+}
+function geometryDiagnosticCode(code) {
+    switch (code) {
+        case "unsupported-protocol-version":
+        case "invalid-camera-id":
+        case "negative-dimension":
+        case "transform-space-mismatch":
+            return "inconsistent-transform-snapshot";
+        case "invalid-anchor-batch":
+            return "invalid-anchor";
+        default:
+            return code;
+    }
+}
+export function createPhaserSceneBridge(options) {
+    if (!options || typeof options !== "object")
+        throw new TypeError("Scene bridge options must be an object");
+    if (typeof options.readAnchors !== "function")
+        throw new TypeError("readAnchors must be a function");
+    if (typeof options.publisher?.publish !== "function")
+        throw new TypeError("publisher must be a bridge publisher");
+    if (options.nextSourceFrameId !== undefined && typeof options.nextSourceFrameId !== "function")
+        throw new TypeError("nextSourceFrameId must be a function");
+    if (options.onDiagnostic !== undefined && typeof options.onDiagnostic !== "function")
+        throw new TypeError("onDiagnostic must be a function");
+    const phase = options.phase ?? "render";
+    const clock = options.clock ?? (typeof performance !== "undefined" && typeof performance.now === "function"
+        ? { id: "performance", now: () => performance.now() }
+        : undefined);
+    if (!clock)
+        return phaserError("scheduler-unavailable", "A monotonic clock is unavailable");
+    if (!clock.id.trim())
+        return phaserError("invalid-clock-id", "Clock ID must be non-empty");
+    if (typeof clock.now !== "function")
+        throw new TypeError("clock.now must be a function");
+    let lifecycle = "connected";
+    const generation = ++connectorGeneration;
+    let lastSourceFrameId = 0;
+    let ownedSourceFrameId = 0;
+    let lastClock = -Infinity;
+    let pending;
+    let observer;
+    const listeners = [];
+    const report = (item) => {
+        try {
+            options.onDiagnostic?.(item);
+        }
+        catch (callbackError) {
+            queueMicrotask(() => { throw callbackError; });
+        }
+    };
+    const stageNotReady = (sourceFrameId, capturedAtMs, item) => {
+        const replaced = pending !== undefined;
+        report(item);
+        pending = Object.freeze({ protocolVersion: 1, sourceFrameId, capturedAtMs, clockId: clock.id, status: "not-ready", transform: null, anchors: [], diagnostics: [item] });
+        return { status: replaced ? "replaced-pending" : "staged-not-ready", sourceFrameId, diagnostics: [item] };
+    };
+    const nextId = () => {
+        if (options.nextSourceFrameId)
+            return options.nextSourceFrameId();
+        ownedSourceFrameId += 1;
+        return ownedSourceFrameId;
+    };
+    const resolveCamera = () => typeof options.camera === "function" ? options.camera() : options.camera;
+    const resolveOverlay = () => typeof options.overlay === "function" ? options.overlay() : options.overlay;
+    const capture = () => {
+        if (lifecycle === "destroyed")
+            return { status: "destroyed" };
+        if (lifecycle === "disconnected")
+            return { status: "disconnected" };
+        let sourceFrameId;
+        let capturedAtMs;
+        try {
+            sourceFrameId = nextId();
+            if (!Number.isSafeInteger(sourceFrameId) || sourceFrameId <= lastSourceFrameId) {
+                return stageNotReady(lastSourceFrameId, Number.isFinite(lastClock) ? lastClock : 0, diagnostic("source-frame-regression", "Source frame IDs must be increasing safe integers"));
+            }
+            capturedAtMs = clock.now();
+            if (!Number.isFinite(capturedAtMs) || capturedAtMs < lastClock) {
+                return stageNotReady(lastSourceFrameId, Number.isFinite(lastClock) ? lastClock : 0, diagnostic("clock-mismatch", "Clock values must be finite and nondecreasing"));
+            }
+            lastSourceFrameId = sourceFrameId;
+            lastClock = capturedAtMs;
+            const camera = resolveCamera();
+            if (!camera)
+                return stageNotReady(sourceFrameId, capturedAtMs, diagnostic("camera-unavailable", "The selected camera is unavailable", capturedAtMs));
+            const overlay = resolveOverlay();
+            if (!overlay)
+                return stageNotReady(sourceFrameId, capturedAtMs, diagnostic("overlay-disconnected", "The overlay is unavailable", capturedAtMs));
+            const cameraResult = readPhaserCameraProjection(camera);
+            if (!cameraResult.ok)
+                return stageNotReady(sourceFrameId, capturedAtMs, diagnostic(cameraResult.error.code, cameraResult.error.message, capturedAtMs));
+            const surfaceResult = readPhaserSurfaceProjection({ scene: options.scene, overlay, capturedAtMs, clockId: clock.id });
+            if (!surfaceResult.ok)
+                return stageNotReady(sourceFrameId, capturedAtMs, diagnostic(surfaceResult.error.code, surfaceResult.error.message, capturedAtMs));
+            const cameraToGame = translationTransform("camera", "game", cameraResult.snapshot.cameraViewport.x, cameraResult.snapshot.cameraViewport.y);
+            const dom = surfaceResult.surface.dom;
+            const transform = {
+                protocolVersion: 1,
+                cameraId: cameraResult.snapshot.cameraId,
+                capturedAtMs,
+                clockId: clock.id,
+                worldToCamera: cameraResult.snapshot.worldToCamera,
+                cameraToGame,
+                gameToBacking: surfaceResult.surface.gameToBacking,
+                backingToCanvasCss: dom.backingToCanvasCss,
+                canvasCssToClient: dom.canvasCssToClient,
+                clientToOverlay: dom.clientToOverlay,
+                cameraViewport: cameraResult.snapshot.cameraViewport,
+                gameLogicalSize: surfaceResult.surface.gameLogicalSize,
+                gameViewportInBacking: surfaceResult.surface.gameViewportInBacking,
+                canvasBackingSize: surfaceResult.surface.canvasBackingSize,
+                canvasCssSize: dom.canvasCssSize,
+                canvasContentClientRect: dom.canvasContentClientRect,
+                overlayClientRect: dom.overlayClientRect,
+                cameraVisible: cameraResult.snapshot.visible,
+                roundPixels: cameraResult.snapshot.roundPixels,
+            };
+            const compiled = compileProjectionContext(transform);
+            if (!compiled.ok)
+                return stageNotReady(sourceFrameId, capturedAtMs, diagnostic(geometryDiagnosticCode(compiled.error.code), compiled.error.message, capturedAtMs));
+            const inputs = options.readAnchors().map((anchor) => {
+                const factor = anchor.scrollFactor ?? { x: 1, y: 1 };
+                if (!finite(factor.x, factor.y))
+                    return anchor;
+                return {
+                    ...anchor,
+                    worldPoint: {
+                        x: anchor.worldPoint.x + camera.scrollX * (1 - factor.x),
+                        y: anchor.worldPoint.y + camera.scrollY * (1 - factor.y),
+                    },
+                };
+            });
+            const projected = projectWorldAnchors(compiled.context, inputs);
+            if (!projected.ok)
+                return stageNotReady(sourceFrameId, capturedAtMs, diagnostic(geometryDiagnosticCode(projected.error.code), projected.error.message, capturedAtMs));
+            const replaced = pending !== undefined;
+            pending = Object.freeze({ protocolVersion: 1, sourceFrameId, capturedAtMs, clockId: clock.id, status: "ready", transform: Object.freeze(transform), anchors: projected.anchors, diagnostics: projected.diagnostics });
+            return { status: replaced ? "replaced-pending" : "staged-ready", sourceFrameId, diagnostics: projected.diagnostics };
+        }
+        catch (caught) {
+            return stageNotReady(lastSourceFrameId, Number.isFinite(lastClock) ? lastClock : 0, diagnostic("capture-callback-threw", caught instanceof Error ? caught.message : "A capture callback threw"));
+        }
+    };
+    const flush = () => {
+        if (!pending)
+            return { status: "empty" };
+        const frame = pending;
+        pending = undefined;
+        return options.publisher.publish(frame);
+    };
+    const addListener = (emitter, event, listener) => {
+        emitter.on(event, listener);
+        listeners.push({ emitter, event, listener });
+    };
+    const removeRuntime = () => {
+        for (const item of listeners.splice(0))
+            item.emitter.off(item.event, item.listener);
+        observer?.disconnect();
+        observer = undefined;
+        pending = undefined;
+    };
+    const phaseHandler = () => { capture(); flush(); };
+    if (phase !== "manual")
+        addListener(options.scene.events, phase, phaseHandler);
+    addListener(options.scene.scale, "resize", () => { });
+    addListener(options.scene.events, "pause", () => { lifecycle = "inactive"; });
+    addListener(options.scene.events, "resume", () => { lifecycle = "connected"; capture(); flush(); });
+    addListener(options.scene.events, "sleep", () => {
+        lifecycle = "inactive";
+        if (options.inactivePolicy !== "retain") {
+            const item = diagnostic("camera-unavailable", "Scene is sleeping", Number.isFinite(lastClock) ? lastClock : 0);
+            stageNotReady(lastSourceFrameId, Number.isFinite(lastClock) ? lastClock : 0, item);
+            flush();
+        }
+    });
+    addListener(options.scene.events, "wake", () => { lifecycle = "connected"; capture(); flush(); });
+    const publishDisconnected = (reason) => options.publisher.publish({
+        protocolVersion: 1,
+        sourceFrameId: lastSourceFrameId,
+        capturedAtMs: Number.isFinite(lastClock) ? lastClock : 0,
+        clockId: Number.isFinite(lastClock) ? clock.id : "bridge-idle",
+        status: "disconnected",
+        transform: null,
+        anchors: [],
+        diagnostics: reason ? [diagnostic("destroyed", reason)] : [],
+    });
+    const disconnect = (reason) => {
+        if (lifecycle === "destroyed")
+            return { status: "destroyed" };
+        if (lifecycle === "disconnected")
+            return { status: "already-disconnected" };
+        lifecycle = "disconnected";
+        removeRuntime();
+        return { status: "disconnected", publication: publishDisconnected(reason) };
+    };
+    const destroy = () => {
+        if (lifecycle === "destroyed")
+            return { status: "already-destroyed" };
+        const disconnected = lifecycle === "disconnected" ? undefined : disconnect("scene bridge destroyed");
+        const publication = disconnected?.status === "disconnected" ? disconnected.publication : undefined;
+        lifecycle = "destroyed";
+        removeRuntime();
+        return { status: "destroyed", ...(publication ? { publication } : {}) };
+    };
+    addListener(options.scene.events, "shutdown", () => { disconnect("scene shutdown"); });
+    addListener(options.scene.events, "destroy", () => { destroy(); });
+    const initialOverlay = resolveOverlay();
+    if (initialOverlay) {
+        const observed = observeGameSurface({ canvas: options.scene.game.canvas, overlay: initialOverlay, onChange: () => { } });
+        if (!observed.ok) {
+            removeRuntime();
+            return phaserError(observed.error.code, observed.error.message);
+        }
+        observer = observed.observer;
+    }
+    const connection = {
+        capture,
+        flush,
+        disconnect,
+        destroy,
+        getStatus: () => ({ lifecycle, phase, generation, lastSourceFrameId, pending: pending !== undefined, listenerCount: listeners.length, observerCount: observer ? 1 : 0 }),
+    };
+    return { ok: true, connection };
+}