@vgai/engine 0.5.2 → 0.5.3

package/src/{scene/schema → asset-formats}/instances.ts

@@ -2,12 +2,16 @@ import { z } from 'zod';
 
 /**
  * `.instances.json` — a declarative, authored-data instance-transform asset
- * (F3, docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Referenced by `mesh.instances`
- * as a bare array of 10-number tuples, one per instance, each
- * `[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ]`. The
- * scene loader fetches+parses this file and renders it as one
- * `THREE.InstancedMesh` (one draw call) — bulk transform data is referenced
- * as an asset, never inlined into the vscn (keeps vscn thin — gate G4).
+ * (F3). Referenced by `mesh.instances` as a bare array of 10-number tuples,
+ * one per instance, each `[posX,posY,posZ, quatX,quatY,quatZ,quatW,
+ * scaleX,scaleY,scaleZ]`. The scene loader fetches+parses this file and
+ * renders it as one `THREE.InstancedMesh` (one draw call) — bulk transform
+ * data is referenced as an asset, never inlined into the referencing
+ * document (gate G4).
+ *
+ * WO-8: the document that referenced it was `.vscn.json`, and that format is
+ * deleted. `.instances.json` survives as a FETCHED-ASSET format with its own
+ * `parseInstancesFile` — nothing in the shipped tree references one today.
  */
 export const InstancesFileSchema = z
   .array(

package/src/{scene/schema → asset-formats}/light.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-const SceneLightBase = z.object({
+const LightDescriptorBase = z.object({
   type: z.enum(['directional', 'point', 'spot', 'hemisphere', 'area']).describe('Light type'),
   color: z.string().optional().describe('Light color as CSS hex string'),
   intensity: z
@@ -42,12 +42,9 @@ const SceneLightBase = z.object({
     ),
 });
 
-export const SceneLightSchema = SceneLightBase.refine(
+export const LightDescriptorSchema = LightDescriptorBase.refine(
   (l) => l.type !== 'spot' || l.angle === undefined || l.angle > 0,
   { message: 'Spot light angle must be positive' },
 ).describe('Light source configuration');
 
-/** Partial schema for prefab instance overrides (type not required). */
-export const SceneLightOverrideSchema = SceneLightBase.partial();
-
-export type SceneLight = z.infer<typeof SceneLightSchema>;
+export type LightDescriptor = z.infer<typeof LightDescriptorSchema>;

package/src/{scene/schema → asset-formats}/material.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-const SceneMaterialObjectSchema = z
+const MaterialDescriptorObjectSchema = z
   .object({
     type: z.enum(['standard', 'physical', 'basic', 'toon']).describe('Material shading model'),
     color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
@@ -86,21 +86,18 @@ const SceneMaterialObjectSchema = z
   })
   .strict();
 
-export const SceneMaterialSchema = SceneMaterialObjectSchema.describe(
+export const MaterialDescriptorSchema = MaterialDescriptorObjectSchema.describe(
   'Material appearance properties',
 );
 
-/** Partial schema for prefab instance overrides (type not required). */
-export const SceneMaterialOverrideSchema = SceneMaterialObjectSchema.partial();
-
-export type SceneMaterial = z.infer<typeof SceneMaterialSchema>;
+export type MaterialDescriptor = z.infer<typeof MaterialDescriptorSchema>;
 
 /** .mat.json file format for shared/reusable material assets. */
 export const MaterialFileSchema = z
   .object({
     version: z.number().describe('File format version'),
     name: z.string().describe('Human-readable material name'),
-    material: SceneMaterialSchema.describe('Material definition'),
+    material: MaterialDescriptorSchema.describe('Material definition'),
   })
   .describe('Shared material asset file (.mat.json)');
 

package/src/{scene/schema → asset-formats}/mesh.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-const SceneMeshBase = z
+const MeshDescriptorBase = z
   .object({
     type: z
       .enum(['box', 'sphere', 'plane', 'cylinder', 'capsule', 'gltf', 'splat'])
@@ -37,7 +37,7 @@ const SceneMeshBase = z
         'Path to an instance-transform asset (.instances.json: an array of ' +
           '[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples). Renders one ' +
           'THREE.InstancedMesh (one draw call). Bulk transform data is referenced as an asset, ' +
-          'never inlined — keeps vscn thin.',
+          'never inlined — keeps the document thin.',
       ),
     lod: z
       .array(
@@ -66,7 +66,7 @@ const SceneMeshBase = z
   })
   .strict();
 
-export const SceneMeshSchema = SceneMeshBase.refine(
+export const MeshDescriptorSchema = MeshDescriptorBase.refine(
   (m) => (m.type !== 'gltf' && m.type !== 'splat') || m.src != null,
   {
     message: "External render asset requires 'src' field",
@@ -88,7 +88,4 @@ export const SceneMeshSchema = SceneMeshBase.refine(
   })
   .describe('Mesh geometry definition');
 
-/** Partial schema for prefab instance overrides (type not required). */
-export const SceneMeshOverrideSchema = SceneMeshBase.partial();
-
-export type SceneMesh = z.infer<typeof SceneMeshSchema>;
+export type MeshDescriptor = z.infer<typeof MeshDescriptorSchema>;

package/src/asset-formats/parse.ts

@@ -0,0 +1,39 @@
+import { AssetParseError } from '../asset-parse-error';
+import type { InstancesFile } from './instances';
+import { InstancesFileSchema } from './instances';
+import type { MaterialFile } from './material';
+import { MaterialFileSchema } from './material';
+
+// The error class itself is format-neutral and lives in
+// `engine/src/asset-parse-error.ts` (the input-map loader raises it too).
+// Re-exported here so callers have one import for parse + error.
+export { AssetParseError };
+
+/**
+ * Parse a `.mat.json` shared material asset (T4.6). There is no version-range
+ * gate for this format — `MaterialFileSchema`'s `version` field is RESERVED
+ * (see `schema-consumption-map.ts`).
+ *
+ * Formerly `@engine/scene/parse`'s `parseMaterialFile`; moved here when WO-8
+ * deleted the `.vscn` scene format that module was named for.
+ */
+export function parseMaterialFile(json: unknown, filePath?: string): MaterialFile {
+  const result = MaterialFileSchema.safeParse(json);
+  if (!result.success) {
+    throw new AssetParseError(result.error.issues, filePath);
+  }
+  return result.data;
+}
+
+/**
+ * Parse a `.instances.json` instance-transform asset (F3). Mirrors
+ * `parseMaterialFile` exactly — no version-range gate (the format is a bare
+ * tuple array, no `version` field).
+ */
+export function parseInstancesFile(json: unknown, filePath?: string): InstancesFile {
+  const result = InstancesFileSchema.safeParse(json);
+  if (!result.success) {
+    throw new AssetParseError(result.error.issues, filePath);
+  }
+  return result.data;
+}

package/src/{scene/schema → asset-formats}/particles.ts

@@ -320,9 +320,9 @@ const BurstSchema = z
   })
   .describe('Timed particle burst');
 
-// --- Top-level SceneParticles ---
+// --- Top-level ParticlesDescriptor ---
 
-export const SceneParticlesSchema = z
+export const ParticlesDescriptorSchema = z
   .object({
     // Lifecycle
     autoDestroy: z
@@ -392,7 +392,4 @@ export const SceneParticlesSchema = z
   })
   .describe('Particle system configuration');
 
-/** Partial schema for prefab instance overrides. */
-export const SceneParticlesOverrideSchema = SceneParticlesSchema.partial();
-
-export type SceneParticles = z.infer<typeof SceneParticlesSchema>;
+export type ParticlesDescriptor = z.infer<typeof ParticlesDescriptorSchema>;

package/src/{scene/schema/environment.ts → asset-formats/render-env.ts}

@@ -1,45 +1,18 @@
+/**
+ * Render settings — the tone-mapping / post-processing / render-feature scope
+ * the engine's renderer setup reads (`setup/setup-renderer.ts`).
+ *
+ * This used to be the `environment` block of the retired `.vscn.json` scene
+ * format (WO-8). The format is gone; these three scopes stayed because
+ * `setup-renderer.ts` genuinely reads every field and builds the
+ * postprocessing chain from them. Everything that was `.vscn`-only (`skybox`,
+ * `fog`, `ambient`, `background`, `envMapIntensity`, `navigation`, `physics`)
+ * went with the format.
+ */
 import { z } from 'zod';
-import { buildRenderingZod } from '../../render/render-features';
+import { buildRenderingZod } from '../render/render-features';
 
-export const SceneNavigationSchema = z
-  .object({
-    cellSize: z
-      .number()
-      .optional()
-      .describe('Navmesh voxel cell size (smaller = more detail, slower bake)'),
-    cellHeight: z.number().optional().describe('Navmesh voxel cell height'),
-    walkableSlopeAngle: z
-      .number()
-      .optional()
-      .describe('Maximum slope angle (degrees) agents can walk on'),
-    walkableHeight: z
-      .number()
-      .optional()
-      .describe('Minimum ceiling height for walkable areas (in voxels)'),
-    walkableClimb: z
-      .number()
-      .optional()
-      .describe('Maximum step height agents can climb (in voxels)'),
-    walkableRadius: z.number().optional().describe('Agent radius for navmesh erosion (in voxels)'),
-    maxEdgeLen: z.number().optional().describe('Maximum contour edge length in the navmesh'),
-    maxSimplificationError: z
-      .number()
-      .optional()
-      .describe('Maximum deviation for navmesh edge simplification'),
-    minRegionArea: z
-      .number()
-      .optional()
-      .describe('Minimum region area — smaller regions are removed'),
-    mergeRegionArea: z
-      .number()
-      .optional()
-      .describe('Regions smaller than this are merged with neighbors'),
-  })
-  .describe('Recast navigation mesh bake parameters');
-
-export type SceneNavigation = z.infer<typeof SceneNavigationSchema>;
-
-export const SceneToneMappingSchema = z
+export const ToneMappingDescriptorSchema = z
   .object({
     mode: z
       .enum(['none', 'linear', 'reinhard', 'cineon', 'aces', 'agx'])
@@ -49,9 +22,9 @@ export const SceneToneMappingSchema = z
   })
   .describe('Tone mapping configuration');
 
-export type SceneToneMapping = z.infer<typeof SceneToneMappingSchema>;
+export type ToneMappingDescriptor = z.infer<typeof ToneMappingDescriptorSchema>;
 
-export const ScenePostProcessingSchema = z
+export const PostProcessingDescriptorSchema = z
   .object({
     // ── Bloom & Vignette ──────────────────────────────────────────────────
     bloom: z
@@ -329,56 +302,20 @@ export const ScenePostProcessingSchema = z
   })
   .describe('Post-processing effects');
 
-export type ScenePostProcessing = z.infer<typeof ScenePostProcessingSchema>;
+export type PostProcessingDescriptor = z.infer<typeof PostProcessingDescriptorSchema>;
 
-export const ScenePhysicsSettingsSchema = z
+export const RenderEnvironmentSchema = z
   .object({
-    collisionLayers: z
-      .array(z.string())
-      .optional()
-      .describe('Named collision layers (up to 16). Index = bit position in collision bitmasks'),
-  })
-  .describe('Physics world settings');
-
-export type ScenePhysicsSettings = z.infer<typeof ScenePhysicsSettingsSchema>;
-
-export const SceneEnvironmentSchema = z
-  .object({
-    background: z.string().optional().describe('Background color as CSS hex string'),
-    ambient: z
-      .object({
-        color: z.string().describe('Ambient light color'),
-        intensity: z.number().describe('Ambient light intensity'),
-      })
-      .optional()
-      .describe('Global ambient light'),
-    fog: z
-      .object({
-        type: z.enum(['linear', 'exponential']).describe('Fog falloff type'),
-        color: z.string().describe('Fog color'),
-        near: z.number().optional().describe('Fog start distance (linear only)'),
-        far: z.number().optional().describe('Fog end distance (linear only)'),
-        density: z.number().optional().describe('Fog density (exponential only)'),
-      })
-      .optional()
-      .describe('Distance fog settings'),
-    skybox: z.string().optional().describe('Path to HDR/EXR skybox environment map'),
-    envMapIntensity: z
-      .number()
-      .optional()
-      .describe('Environment map reflection intensity multiplier'),
-    toneMapping: SceneToneMappingSchema.optional().describe('Tone mapping configuration'),
-    postProcessing: ScenePostProcessingSchema.optional().describe(
-      'Post-processing effects (bloom, vignette)',
+    toneMapping: ToneMappingDescriptorSchema.optional().describe('Tone mapping configuration'),
+    postProcessing: PostProcessingDescriptorSchema.optional().describe(
+      'Post-processing effects (bloom, vignette, SSAO, SSR, ...)',
     ),
-    navigation: SceneNavigationSchema.optional().describe('Navigation mesh bake settings'),
-    physics: ScenePhysicsSettingsSchema.optional().describe('Physics world settings'),
     rendering: buildRenderingZod()
       .optional()
       .describe(
-        'Scene-level render feature toggles (auto-batching, culling, LOD, shadows, etc.). Omit a field to inherit the engine default. Derived from the render-feature registry.',
+        'Render feature toggles (auto-batching, culling, LOD, shadows, etc.). Omit a field to inherit the engine default. Derived from the render-feature registry.',
       ),
   })
-  .describe('Scene-level environment and rendering settings');
+  .describe('Renderer-level settings read by setup/setup-renderer.ts');
 
-export type SceneEnvironment = z.infer<typeof SceneEnvironmentSchema>;
+export type RenderEnvironment = z.infer<typeof RenderEnvironmentSchema>;

package/src/{scene/schema → asset-formats}/tuples.ts

@@ -18,4 +18,4 @@ export const TransformSchema = z
   })
   .describe('Local transform relative to parent entity');
 
-export type SceneTransform = z.infer<typeof TransformSchema>;
+export type Transform = z.infer<typeof TransformSchema>;

package/src/{scene/asset-loaders.ts → asset-loaders.ts}

@@ -25,9 +25,9 @@
 import type { SplatMesh } from '@sparkjsdev/spark';
 import * as THREE from 'three';
 import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
-import { gltfLoader, resolveUrl, textureLoader } from '../loader';
-import { SceneParseError } from './parse';
-import { setUserData } from './user-data';
+import { AssetParseError } from './asset-parse-error';
+import { setUserData } from './ecs/user-data';
+import { gltfLoader, resolveUrl, textureLoader } from './loader';
 
 const textureCache = new Map<string, THREE.Texture>();
 const gltfCache = new Map<
@@ -146,9 +146,8 @@ export async function loadSplat(url: string, providedBytes?: Uint8Array): Promis
 
 /**
  * Resolve a single named node inside an already-loaded glTF scene graph (F4,
- * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md `mesh.node`). Pure and headlessly
- * testable — no fetch, no cache lookups; callers pass the `scene` they already
- * got from {@link loadGLTF}.
+ * `mesh.node`). Pure and headlessly testable — no fetch, no cache lookups;
+ * callers pass the `scene` they already got from {@link loadGLTF}.
  *
  * The returned node is the SAME object (and shares the SAME geometry) as
  * found in `scene` — nothing is cloned or copied out. `scene` is already a
@@ -158,7 +157,7 @@ export async function loadSplat(url: string, providedBytes?: Uint8Array): Promis
  * Atomic-subtree guard: a `SkinnedMesh` cannot be lifted out of its armature
  * (its skeleton/bind matrices reference sibling bone nodes elsewhere in the
  * hierarchy), so resolving a node that IS a SkinnedMesh, or that CONTAINS one,
- * throws a loud `SceneParseError` instead of silently producing broken skinning.
+ * throws a loud `AssetParseError` instead of silently producing broken skinning.
  */
 export function resolveGltfNode(
   scene: THREE.Object3D,
@@ -167,7 +166,7 @@ export function resolveGltfNode(
 ): THREE.Object3D {
   const node = scene.getObjectByName(nodeName);
   if (!node) {
-    throw new SceneParseError(
+    throw new AssetParseError(
       [
         {
           code: 'custom',
@@ -187,7 +186,7 @@ export function resolveGltfNode(
     });
   }
   if (containsSkinned) {
-    throw new SceneParseError(
+    throw new AssetParseError(
       [
         {
           code: 'custom',

package/src/asset-parse-error.ts

@@ -0,0 +1,33 @@
+/**
+ * The GENERIC fetched-asset parse error.
+ *
+ * Every authored asset format the engine validates at fetch time throws this
+ * when Zod rejects the payload, naming the offending file (T4.6). It lives
+ * here — beside `loader.ts`/`assets.ts` — rather than inside a format module so
+ * every caller (the `.mat.json` parser, the input-map loader in
+ * `input/input-manager.ts`) does not have to reach into the format half for
+ * it.
+ *
+ * It was called `SceneParseError` until WO-9 task #6. The extraction that gave
+ * this file its name deliberately deferred the class rename ("extraction, not
+ * redesign"); with `.vscn` gone the old name described nothing — a `.mat.json`
+ * or `.inputmap.json` failure is not a scene failure — so the class and its
+ * message header now say `asset`.
+ */
+
+import type { ZodIssue } from 'zod';
+
+export class AssetParseError extends Error {
+  readonly issues: ZodIssue[];
+  /** The offending file's path/URL, when the caller knows it (T4.6). */
+  readonly filePath?: string | undefined;
+
+  constructor(issues: ZodIssue[], filePath?: string) {
+    const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+    const header = filePath ? `Asset validation failed (${filePath}):` : 'Asset validation failed:';
+    super(`${header}\n${msg}`);
+    this.name = 'AssetParseError';
+    this.issues = issues;
+    this.filePath = filePath;
+  }
+}

package/src/{scene/asset-registry.ts → asset-registry.ts}

@@ -6,7 +6,7 @@
  */
 
 import * as THREE from 'three';
-import { resolveUrl } from '../loader';
+import { resolveUrl } from './loader';
 
 export interface ImportCorrection {
   /** Uniform scale factor applied to the GLTF clone before entity transform. */

package/src/assets.ts

@@ -34,7 +34,7 @@ export function createAssetCache(): AssetCache {
   // Use the shared, DRACO-wired GLTFLoader (A2 / CB2) — no second loader instance.
   // This cache keeps the parsed source GLTFResult (load/get semantics for gameplay
   // code); it does NOT clone. Callers that need disposal-safe clones use
-  // scene/asset-loaders `loadGLTF`, which clones + tags `__sharedGeometry`.
+  // asset-loaders `loadGLTF`, which clones + tags `__sharedGeometry`.
 
   function load<T = unknown>(url: string): Promise<T> {
     const existing = cache.get(url);

package/src/audio/wav-encode.ts

@@ -1,13 +1,13 @@
 /**
- * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
- * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
- * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
- * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
- * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
- * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
- * a browser render-mode page (`runtime/render-audio-control.ts`) and in
- * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
- * no Playwright needed).
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half).
+ * This module takes already-rendered Float32 channel data (e.g.
+ * `AudioBuffer.getChannelData(n)` from a `Tone.Offline` render,
+ * `audio/tone-offline-render.ts`) and produces a standard little-endian,
+ * 16-bit-PCM, interleaved RIFF/WAVE file as raw bytes — no
+ * `AudioBuffer`/`AudioContext` dependency, so this runs equally in a browser
+ * render-mode page (`runtime/render-audio-control.ts`) and in plain Node (this
+ * module's own `packages/engine/test/audio/wav-encode.test.ts`, no Playwright
+ * needed).
  *
  * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
  * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg

package/src/canvas-react/engine-bridge.ts

@@ -0,0 +1,59 @@
+/**
+ * `@engine/canvas-react` — the React context that carries a canvas world's
+ * engine runtime into its `@pixi/react` tree: the world's `GameContext`, read
+ * with {@link useGameContext}.
+ *
+ * The bridge value is built by `createPixiReactAdapter`'s `mount()`
+ * (./pixi-react-adapter.tsx), whose `update(dt)` runs this world's phases under
+ * the HOST loop — so registered systems tick in engine phase order, pause
+ * included (no update while the world is frozen).
+ *
+ * Behavior in a canvas world is components + hooks: `useGameContext` reaches
+ * engine services, `@pixi/react`'s own `useTick` is the per-frame hook, and
+ * `useApplication` is the door to the live `Application`.
+ */
+
+import { createContext, useContext } from 'react';
+import type { GameContext } from '../runtime/types';
+
+export interface EngineBridgeValue {
+  /** This root's `GameContext` — `input`, `debug`, `random`, `clock`, `game`,
+   *  `roots`, `systems`, `registerSystemAdapter`. Present so ordinary
+   *  components can reach engine services with a HOOK (see
+   *  {@link useGameContext}). */
+  readonly ctx?: GameContext | undefined;
+}
+
+export const EngineBridge = createContext<EngineBridgeValue | null>(null);
+
+/**
+ * This canvas root's `GameContext`, for use inside any component in the tree.
+ *
+ * An ordinary component does what a model would write:
+ *
+ * ```tsx
+ * function Player({ speed = 220 }) {
+ *   const { input } = useGameContext();
+ *   const ref = useRef<Sprite>(null);
+ *   useTick(({ deltaMS }) => {
+ *     if (input.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
+ *   });
+ *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
+ * }
+ * ```
+ *
+ * Throws when called outside a canvas root mounted by
+ * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
+ * `null` would surface as a mystery `undefined` deep in a tick callback.
+ */
+export function useGameContext(): GameContext {
+  const bridge = useContext(EngineBridge);
+  if (!bridge?.ctx) {
+    throw new Error(
+      'useGameContext(): no engine root context. This hook only works inside a canvas ' +
+        'root mounted by createPixiReactAdapter (@engine/canvas-react) — check that the ' +
+        'component is rendered inside your world entry, not in a standalone <Application>.',
+    );
+  }
+  return bridge.ctx;
+}

package/src/canvas-react/index.ts

@@ -0,0 +1,50 @@
+/**
+ * canvas-react — the `@pixi/react` lane for vgai's canvas surface
+ * (`@engine/canvas-react`).
+ *
+ * The canvas surface is source-as-truth: a canvas root's document IS its
+ * TSX world file, exactly as a three root's document is its R3F source. This
+ * module is the peer of `world3d-react/` — same seam, same shape, Pixi instead
+ * of three — and the peer of `pixi/`, which holds what the host needs to mount
+ * and inspect a PixiJS game it did NOT write.
+ *
+ * The engine CORE never imports this (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
+ * allowed react-importing entry alongside `react/` and `world3d-react/`, and
+ * core files may not import it), so a three-only bundle never pays for react
+ * or the Pixi reconciler.
+ *
+ * Surface:
+ *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
+ *    a first-party `surface: "canvas"` root under the host's gated loop.
+ *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
+ *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
+ *    render a container the game already owns, and place a spawn in the
+ *    display tree ahead of the commit that renders it.
+ *  - `useGameContext()` — this root's `GameContext` (`input`, `debug`,
+ *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
+ *    Behavior in a canvas world is components + hooks, never a class under a
+ *    string key.
+ *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
+ *    adopters building their own bridge.
+ *
+ * The Pixi runtime itself is NOT re-exported here. A component reaches the live
+ * `Application` (and therefore `stage`, `renderer`, `ticker`) with
+ * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
+ * assets with Pixi's own `Assets` — the library's API, not a second one.
+ */
+
+export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
+export { adoptNow, PixiPrimitive, type PixiPrimitiveProps } from './pixi-primitive';
+export {
+  type CreatePixiReactAdapterOptions,
+  createPixiReactAdapter,
+} from './pixi-react-adapter';
+export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
+export {
+  type CanvasRootContextOptions,
+  type CanvasRootRuntime,
+  createCanvasRootContext,
+  DEFAULT_INPUT_MAP_PATH,
+} from './world-context';