@zvk/game-bridge

@zvk/game-bridge is a headless boundary between browser-game runtimes and DOM UI. It owns immutable channels, typed UI intents, exact affine projection, lifecycle diagnostics, and optional DOM, React, and structurally typed Phaser adapters. The game continues to own simulation, entity selection, camera policy, rendering, persistence, and action semantics.

bun add @zvk/game-bridge
# Add React and/or Phaser only when importing their adapter subpaths.

Local ZVK consumers may use file:/Users/brandon/Programming/zvk/packages/game-bridge plus a matching override. Release proof uses npm pack and installs that immutable tarball into an isolated consumer fixture.

Choose the owner subpath

| Import | Use it for | | --- | --- | | @zvk/game-bridge | Channels, independent state/frame lanes, intents, diagnostics | | @zvk/game-bridge/geometry | Branded affine transforms, visibility, inverse projection, placement | | @zvk/game-bridge/dom | Canvas/overlay measurement and observation | | @zvk/game-bridge/react | React 18.3/19 external-store bindings | | @zvk/game-bridge/phaser | Explicit-camera Phaser 3.90 capture and lifecycle | | @zvk/game-bridge/test-utils | Typed frames, anchors, fake Phaser surfaces, lifecycle assertions |

Two lanes

The lower-frequency state lane carries app-defined HUD/menu data. The high-frequency frame lane atomically carries one transform and its app-selected projected anchors. Publishing one lane never notifies subscribers to the other.

import { createGameBridge } from "@zvk/game-bridge";

const { bridge, producer } = createGameBridge({
  initialState: { score: 0 },
  serverState: { score: 0 },
  onIntent: ({ intent }) => runtime.dispatch(intent),
});

producer.state.publish({ score: 1 });
const stop = bridge.state.subscribe(() => render(bridge.state.getSnapshot()));
bridge.intents.dispatch({ type: "menu.close" });
stop();

For a world overlay, join a projected anchor ID from bridge.frame to semantic state from bridge.state, then map anchor.overlayPoint into an app component or @zvk/game-ui surface. The packages integrate through plain data and do not depend on each other.

Create scene connectors after the DOM and camera exist. Destroy connectors during scene shutdown, then destroy the whole bridge during application shutdown. Treat not-ready, disconnected, and destroyed frames as having no usable world anchors.

The root and geometry imports need no optional peers or browser globals. React uses a fixed server snapshot; DOM and Phaser work begins only when their factories are called. Package code returns discriminated failures and never logs implicitly.

Read the checked guides for installation and lifecycle, core contracts, geometry and inverse input, DOM measurement, React and SSR, Phaser lifecycle, test fixtures, and migration.

Maintainer verification

bun run --filter @zvk/game-bridge preflight
bun run verify:game-bridge:promotion

The promotion gate runs package preflight, npm readiness, and the tarball-installed web-game-template consumer canary. It records producer and consumer Git state plus tarball version/hash and command results.

Non-goals

This is not an engine, ECS, simulation store, renderer, UI kit, event bus, entity registry, persistence layer, or networking system. It publishes only app-selected plain-data anchors and app-defined intents.