@zvk/game-bridge 0.1.0

package/dist/react/index.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentType, type ReactNode } from "react";
+import type { BridgeEquality, BridgeReader, GameBridge, GameBridgeFrame, JsonValue } from "../index.js";
+import type { ProjectedWorldAnchor } from "../geometry/index.js";
+export declare function useBridgeSnapshot<TSnapshot>(reader: BridgeReader<TSnapshot>): TSnapshot;
+export declare function useBridgeSelector<TSnapshot, TSelected>(reader: BridgeReader<TSnapshot>, selector: (snapshot: TSnapshot) => TSelected, equals?: BridgeEquality<TSelected>): TSelected;
+export interface GameBridgeReactBindings<TState, TIntent extends JsonValue, TAnchorMetadata extends JsonValue> {
+    readonly Provider: ComponentType<{
+        readonly bridge: GameBridge<TState, TIntent, TAnchorMetadata>;
+        readonly children?: ReactNode;
+    }>;
+    readonly useBridge: () => GameBridge<TState, TIntent, TAnchorMetadata>;
+    readonly useStateSnapshot: () => TState;
+    readonly useFrameSnapshot: () => GameBridgeFrame<TAnchorMetadata>;
+    readonly useStateSelector: <TSelected>(selector: (snapshot: TState) => TSelected, equals?: BridgeEquality<TSelected>) => TSelected;
+    readonly useFrameSelector: <TSelected>(selector: (snapshot: GameBridgeFrame<TAnchorMetadata>) => TSelected, equals?: BridgeEquality<TSelected>) => TSelected;
+    readonly useProjectedAnchor: (id: string) => ProjectedWorldAnchor<TAnchorMetadata> | null;
+}
+export declare function createGameBridgeReactBindings<TState, TIntent extends JsonValue, TAnchorMetadata extends JsonValue = JsonValue>(options?: {
+    readonly displayName?: string;
+}): GameBridgeReactBindings<TState, TIntent, TAnchorMetadata>;

package/dist/react/index.js

@@ -0,0 +1,47 @@
+"use client";
+import { createContext, createElement, useCallback, useContext, useRef, useSyncExternalStore, } from "react";
+export function useBridgeSnapshot(reader) {
+    return useSyncExternalStore(reader.subscribe, reader.getSnapshot, reader.getServerSnapshot);
+}
+export function useBridgeSelector(reader, selector, equals = Object.is) {
+    const selectorRef = useRef(selector);
+    const equalsRef = useRef(equals);
+    selectorRef.current = selector;
+    equalsRef.current = equals;
+    const cacheRef = useRef(undefined);
+    const getSelected = useCallback((getSnapshot) => {
+        const source = getSnapshot();
+        const selected = selectorRef.current(source);
+        const cached = cacheRef.current;
+        if (cached && cached.source === source && selectorRef.current === selector)
+            return cached.selected;
+        if (cached && equalsRef.current(cached.selected, selected)) {
+            cacheRef.current = { source, selected: cached.selected };
+            return cached.selected;
+        }
+        cacheRef.current = { source, selected };
+        return selected;
+    }, [reader, selector]);
+    const getSnapshot = useCallback(() => getSelected(reader.getSnapshot), [getSelected, reader]);
+    const getServerSnapshot = useCallback(() => getSelected(reader.getServerSnapshot), [getSelected, reader]);
+    return useSyncExternalStore(reader.subscribe, getSnapshot, getServerSnapshot);
+}
+export function createGameBridgeReactBindings(options) {
+    const displayName = options?.displayName?.trim() || "GameBridge";
+    const Context = createContext(null);
+    Context.displayName = `${displayName}Context`;
+    const Provider = ({ bridge, children }) => createElement(Context.Provider, { value: bridge }, children);
+    Provider.displayName = `${displayName}Provider`;
+    const useBridge = () => {
+        const bridge = useContext(Context);
+        if (!bridge)
+            throw new Error(`${displayName} context is missing; render ${displayName}Provider above this hook`);
+        return bridge;
+    };
+    const useStateSnapshot = () => useBridgeSnapshot(useBridge().state);
+    const useFrameSnapshot = () => useBridgeSnapshot(useBridge().frame);
+    const useStateSelector = (selector, equals) => useBridgeSelector(useBridge().state, selector, equals);
+    const useFrameSelector = (selector, equals) => useBridgeSelector(useBridge().frame, selector, equals);
+    const useProjectedAnchor = (id) => useFrameSelector((frame) => frame.anchors.find((anchor) => anchor.id === id) ?? null, Object.is);
+    return { Provider, useBridge, useStateSnapshot, useFrameSnapshot, useStateSelector, useFrameSelector, useProjectedAnchor };
+}

package/dist/test-utils/assertions.d.ts

@@ -0,0 +1,2 @@
+export { assertJsonValue, isJsonValue } from "../core/serializable.js";
+export declare function assertApproximatelyEqual(actual: number, expected: number, epsilon?: number): void;

package/dist/test-utils/assertions.js

@@ -0,0 +1,9 @@
+export { assertJsonValue, isJsonValue } from "../core/serializable.js";
+export function assertApproximatelyEqual(actual, expected, epsilon = 1e-9) {
+    if (!Number.isFinite(epsilon) || epsilon < 0) {
+        throw new RangeError("epsilon must be finite and non-negative");
+    }
+    if (!Number.isFinite(actual) || !Number.isFinite(expected) || Math.abs(actual - expected) > epsilon) {
+        throw new Error(`Expected finite numbers to be within ${epsilon}`);
+    }
+}

package/dist/test-utils/fixtures.d.ts

@@ -0,0 +1,7 @@
+import type { BridgeReader } from "../core/channel.js";
+export interface BridgeNotificationRecorder<TSnapshot> {
+    readonly snapshots: readonly TSnapshot[];
+    readonly revisions: readonly number[];
+    readonly unsubscribe: () => void;
+}
+export declare function recordBridgeNotifications<TSnapshot>(reader: BridgeReader<TSnapshot>): BridgeNotificationRecorder<TSnapshot>;

package/dist/test-utils/fixtures.js

@@ -0,0 +1,9 @@
+export function recordBridgeNotifications(reader) {
+    const snapshots = [];
+    const revisions = [];
+    const unsubscribe = reader.subscribe(() => {
+        snapshots.push(reader.getSnapshot());
+        revisions.push(reader.getRevision());
+    });
+    return { snapshots, revisions, unsubscribe };
+}

package/dist/test-utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./assertions.js";
+export * from "./fixtures.js";
+export * from "./manual-scheduler.js";

package/dist/test-utils/index.js

@@ -0,0 +1,3 @@
+export * from "./assertions.js";
+export * from "./fixtures.js";
+export * from "./manual-scheduler.js";

package/dist/test-utils/manual-scheduler.d.ts

@@ -0,0 +1,10 @@
+import type { BridgeScheduler } from "../core/coalesced-publisher.js";
+export interface ManualBridgeScheduler extends BridgeScheduler<number> {
+    readonly flushNext: () => boolean;
+    readonly flushAll: () => number;
+    readonly getPendingCount: () => number;
+    readonly getRequestedCount: () => number;
+    readonly getCancelledCount: () => number;
+    readonly capture: (handle: number) => (() => void) | undefined;
+}
+export declare function createManualBridgeScheduler(): ManualBridgeScheduler;

package/dist/test-utils/manual-scheduler.js

@@ -0,0 +1,43 @@
+export function createManualBridgeScheduler() {
+    let nextHandle = 1;
+    let requestedCount = 0;
+    let cancelledCount = 0;
+    const callbacks = new Map();
+    const captured = new Map();
+    return {
+        request: (callback) => {
+            const handle = nextHandle;
+            nextHandle += 1;
+            requestedCount += 1;
+            callbacks.set(handle, callback);
+            captured.set(handle, callback);
+            return handle;
+        },
+        cancel: (handle) => {
+            if (callbacks.delete(handle))
+                cancelledCount += 1;
+        },
+        flushNext: () => {
+            const entry = callbacks.entries().next().value;
+            if (entry === undefined)
+                return false;
+            callbacks.delete(entry[0]);
+            entry[1]();
+            return true;
+        },
+        flushAll: () => {
+            let count = 0;
+            while (callbacks.size > 0) {
+                const entry = callbacks.entries().next().value;
+                callbacks.delete(entry[0]);
+                entry[1]();
+                count += 1;
+            }
+            return count;
+        },
+        getPendingCount: () => callbacks.size,
+        getRequestedCount: () => requestedCount,
+        getCancelledCount: () => cancelledCount,
+        capture: (handle) => captured.get(handle),
+    };
+}

package/docs/content/core-contracts.md

@@ -0,0 +1,5 @@
+# Core Contracts
+
+A channel separates a read-only `BridgeReader` from a write-only `BridgePublisher`. Snapshots keep reference identity until an accepted publication, server snapshots stay fixed, listeners use stable iteration, reentrant publications drain FIFO, and close is idempotent.
+
+`createGameBridge` composes independent app-state and atomic frame channels with a synchronous typed intent sink. Destroy clears anchors through a terminal frame before closing channels. Production paths do not clone or stringify snapshots; use test utilities to assert JSON compatibility.

package/docs/content/dom.md

@@ -0,0 +1,5 @@
+# DOM Adapter
+
+`measureGameSurface` reads canvas backing size, the bitmap content box, and a selected overlay reference box. It returns typed failures for missing DOM, disconnected or zero-sized surfaces, invalid measurements, and unsupported transforms.
+
+`observeGameSurface` coalesces resize, scroll, visual viewport, and fullscreen changes. Disconnect removes observers, listeners, and scheduled work. Importing the module performs no measurement.

package/docs/content/errors-and-performance.md

@@ -0,0 +1,5 @@
+# Errors and Performance
+
+Expected runtime failures are discriminated results and bounded diagnostics; package code never logs implicitly. Invalid points and anchors are isolated where safe, while duplicate IDs or invalid transforms reject the current frame.
+
+Projection is constant time per point after compilation and linear per selected batch. Frame staging is latest-value-wins with one notification per scheduling boundary. Avoid deep equality, cloning, stringification, and unbounded diagnostic history in frame producers. Keep DOM-selected anchors small; treat batches above 128 as an application review threshold rather than a package error.

package/docs/content/geometry.md

@@ -0,0 +1,5 @@
+# Geometry
+
+Coordinate brands distinguish world, camera, logical game, canvas backing, canvas CSS, client, overlay, and normalized values. The forward affine chain is compiled once and inverted once, then reused for point and anchor projection.
+
+Visibility uses half-open bounds and reports camera, canvas, and overlay membership separately. Canvas backing-to-CSS scale comes from measured dimensions rather than global DPR. Inverse projection supports reject, allow, and camera-clamp policies. Placement ranks overflow, exclusion overlap, and fallback order deterministically.

package/docs/content/index.md

@@ -0,0 +1,5 @@
+# Game Bridge
+
+Choose the root for immutable channels, the state/frame bridge, intents, and diagnostics. Choose `geometry` for pure affine math; `dom`, `react`, and `phaser` only at those runtime boundaries; and `test-utils` only in tests. Applications own gameplay and presentation.
+
+Public imports are `@zvk/game-bridge`, `/geometry`, `/dom`, `/react`, `/phaser`, and `/test-utils`.

package/docs/content/migration.md

@@ -0,0 +1,5 @@
+# Migration
+
+Create one bridge at the application boundary, preserve app-owned selectors and action types, and migrate one selected overlay. Compare old and new projection in tests, then replace the adopted local external-store hook and transform math with public subpaths.
+
+Verify pan, zoom, rotation, viewport offset, CSS scale, resize, pointer mapping, and scene restart. Remove the old adopted path only after parity. Rollback restores that narrow seam; no save or simulation schema must change.

package/docs/content/phaser.md

@@ -0,0 +1,5 @@
+# Phaser Adapter
+
+The Phaser subpath accepts a small structural camera, scale, scene, and emitter surface and performs no runtime Phaser import. Version 0.1 proves Phaser `^3.90.0`; other major lines are not claimed until the same real-browser contract passes.
+
+Select one camera explicitly. Capture at the render boundary, sample only app-selected anchors, and publish transform plus anchors atomically. Temporary capture failures clear anchors with `not-ready`; shutdown publishes `disconnected`; stale generation callbacks cannot publish after cleanup.

package/docs/content/react.md

@@ -0,0 +1,5 @@
+# React Adapter
+
+`useBridgeSnapshot` delegates to `useSyncExternalStore` with the reader's fixed server snapshot. `useBridgeSelector` preserves selected reference identity when equality succeeds. `createGameBridgeReactBindings` creates an explicit app-typed provider and hooks without a package singleton.
+
+Create matching server/client initial snapshots, begin runtime capture after mount, and destroy runtime connectors before destroying the bridge. Strict Mode must settle to one subscription.

package/docs/examples/react-phaser-overlay.tsx

@@ -0,0 +1,14 @@
+import { createGameBridge } from "@zvk/game-bridge";
+import { createGameBridgeReactBindings } from "@zvk/game-bridge/react";
+
+type State = { readonly labelById: Readonly<Record<string, string>> };
+type Intent = { readonly type: "marker.select"; readonly id: string };
+
+export const created = createGameBridge<State, Intent>({ initialState: { labelById: {} } });
+export const bindings = createGameBridgeReactBindings<State, Intent>({ displayName: "ExampleBridge" });
+
+export function MarkerList() {
+  const frame = bindings.useFrameSnapshot();
+  const labels = bindings.useStateSelector((state) => state.labelById);
+  return <>{frame.anchors.map((anchor) => <span key={anchor.id}>{labels[anchor.id]}</span>)}</>;
+}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@zvk/game-bridge",
+  "version": "0.1.0",
+  "description": "Typed snapshots, coordinate transforms, and optional React and Phaser adapters for browser-game UI bridges.",
+  "private": false,
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brandon-schabel/zvk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./geometry": {
+      "types": "./dist/geometry/index.d.ts",
+      "import": "./dist/geometry/index.js",
+      "default": "./dist/geometry/index.js"
+    },
+    "./dom": {
+      "types": "./dist/dom/index.d.ts",
+      "import": "./dist/dom/index.js",
+      "default": "./dist/dom/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    },
+    "./phaser": {
+      "types": "./dist/phaser/index.d.ts",
+      "import": "./dist/phaser/index.js",
+      "default": "./dist/phaser/index.js"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils/index.d.ts",
+      "import": "./dist/test-utils/index.js",
+      "default": "./dist/test-utils/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "bun run scripts/clean.mjs",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build": "bun run clean && bun run build:types",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run src --maxWorkers=2",
+    "test:ssr": "vitest run tests/ssr --environment node",
+    "test:exports": "vitest run tests/exports --environment node",
+    "test:types": "tsd",
+    "test:docs-examples": "bun run build && vitest run tests/docs-examples --environment jsdom",
+    "test:browser": "bun run build && playwright test --config playwright.config.ts",
+    "test:packed-consumer": "bun run build && bun run scripts/check-packed-consumer.mjs",
+    "benchmark:geometry": "bun run build && bun run scripts/benchmark-geometry.mjs",
+    "docs:lint": "bun run scripts/lint-docs.mjs",
+    "validate:exports": "bun run scripts/validate-exports.mjs",
+    "validate:source-policy": "bun run scripts/validate-source-policy.mjs",
+    "tarball:inspect": "bun run scripts/check-tarball.mjs",
+    "pack:dry": "bun pm pack --dry-run",
+    "preflight": "bun run build && bun run typecheck && bun run test && bun run test:ssr && bun run test:types && bun run test:exports && bun run test:docs-examples && bun run test:browser && bun run test:packed-consumer && bun run docs:lint && bun run validate:exports && bun run validate:source-policy && bun run tarball:inspect && bun run pack:dry",
+    "preflight:ci": "bun run build && bun run typecheck && bun run test && bun run test:ssr && bun run test:types && bun run test:exports && bun run test:docs-examples && bun run test:browser && bun run test:packed-consumer && bun run docs:lint && bun run validate:exports && bun run validate:source-policy && bun run tarball:inspect && bun run pack:dry"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "phaser": "^3.90.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "phaser": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^28.1.0",
+    "phaser": "^3.90.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsd": "^0.33.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8"
+  },
+  "tsd": {
+    "directory": "tests/types"
+  }
+}