@vgai/engine 0.5.0 → 0.5.2

package/dist/manifest/schema.js

@@ -1,394 +0,0 @@
-// T3.1 slice 1 — the game manifest schema (`vgai.game.json`).
-//
-// This is the serialized form of the Game's root list
-// (docs/GAME-ROOT-DESIGN.md §1, D6) — see docs/GAME-MANIFEST-DESIGN.md §3 for
-// the adjudicated field list this file implements exactly. `load.ts` is this
-// schema's runtime reader (T4.1 policy): it parses via this schema, then
-// layers the cross-field checks and default resolution §3/§5 describe. Every
-// field below has a `.describe()` (repo policy — powers
-// `scripts/generate-schema.ts` and the T4.1 schema-walk coverage test).
-//
-// Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
-// (inferred type) convention used throughout `scene/schema/` — the design
-// doc's §3 sketch names the bare consts (`Tier`, `IngestStrategy`,
-// `AdapterRoot`) without the `Schema` suffix; that sketch is explicitly a
-// "Zod sketch" the doc tells implementers to adapt to real code style
-// ("mirror the style in scene/schema/scene-file.ts" per CLAUDE.md), so the
-// schema consts here are suffixed and the bare names are reserved for the
-// inferred types, matching every other schema file in the repo.
-//
-// Adapter surface values mirror `AdapterSurface` in
-// `packages/engine/src/runtime/game.ts` (`'threejs' | 'pixijs' | 'react'`)
-// by value, not by import. The adapter remains the sole root discriminator.
-import { z } from 'zod';
-/**
- * Current on-disk `vgai.game.json` format. Exported so editor/server
- * compatibility checks do not duplicate the schema's literal value.
- */
-export const GAME_MANIFEST_VERSION = 2;
-// ---------------------------------------------------------------------------
-// Ingest capture strategy (world2d today; the general vocabulary D6/§4 names)
-// ---------------------------------------------------------------------------
-export const IngestStrategySchema = z.enum([
-    'shared', // game imports host-served ESM three — full in-realm capture
-    'deduped', // game source built by OUR pipeline, bundler dedupe — full capture
-    'iframe-reachable', // prebuilt bundle in iframe, three reachable — cross-realm capture
-    'opaque-embed', // prebuilt bundle, nothing reachable — host lifecycle only
-]);
-// ---------------------------------------------------------------------------
-// Capability tier — one ordered enum, declared per delivery context (§4)
-// ---------------------------------------------------------------------------
-export const TierSchema = z.enum([
-    'first-party', // vgai-native root: full editor, full loop control
-    'shared', // = IngestStrategy 'shared' rung
-    'deduped', // = IngestStrategy 'deduped' rung
-    'iframe-reachable', // = IngestStrategy 'iframe-reachable' rung
-    'opaque-embed', // = IngestStrategy 'opaque-embed' rung
-    'unsupported', // this root does not function in this delivery context
-]);
-// ---------------------------------------------------------------------------
-// Root adapter identity. The adapter is the sole discriminator: a root never
-// repeats its rendering substrate in a sibling `kind` field. Module and ingest
-// adapters carry the surface their adapter contract exposes because the host
-// must allocate a layer before the module has mounted.
-// ---------------------------------------------------------------------------
-export const RootAdapterSchema = z
-    .union([
-    z.enum(['threejs', 'pixijs', 'react']),
-    z
-        .object({
-        module: z
-            .string()
-            .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
-        surface: z
-            .enum(['threejs', 'pixijs', 'react'])
-            .describe('Native surface exposed by this custom adapter contract'),
-    })
-        .strict(),
-    z
-        .object({
-        surface: z
-            .enum(['threejs', 'pixijs', 'react'])
-            .describe('Native surface captured from the unmodified game'),
-        ingest: z
-            .object({
-            strategy: IngestStrategySchema.describe('Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier'),
-            entryHtml: z
-                .string()
-                .optional()
-                .describe('Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, ' +
-                'docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through ' +
-                'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
-                'introspection), for both pixijs and threejs roots. Legal but NOT wired to a ' +
-                'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
-                'instead, the wired reachable route).'),
-            assets: z
-                .record(z.string(), z.string())
-                .optional()
-                .describe('Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)'),
-            domStubs: z
-                .array(z.string())
-                .optional()
-                .describe('DOM API stub ids this ingested game requires to run headlessly/in-realm'),
-            captureTimeoutMs: z
-                .number()
-                .optional()
-                .describe('Max time to wait for in-realm/cross-realm capture before failing loudly'),
-            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — the six
-            // iframe-reachable-multi mount fields (`ingest-iframe-2d.ts`'s
-            // `IframeReachableMultiOpts`), legal ONLY when `strategy` is
-            // 'iframe-reachable' (enforced by the `.superRefine` below).
-            bundleUrl: z
-                .string()
-                .optional()
-                .describe('Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
-                'mount route (iframe-reachable only), for BOTH pixijs (Track P, ' +
-                "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, " +
-                'docs/WAVE4-FTUE-HARDENING-DESIGN.md, ' +
-                "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
-                'PRECONDITION: the bundle must externalize its root`s own runtime as a bare, ' +
-                'un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` ' +
-                'does this for you) so it resolves through the iframe importmap to the HOST ' +
-                'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
-                'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
-                'entryHtml is required when strategy is iframe-reachable.'),
-            baseHref: z
-                .string()
-                .optional()
-                .describe("Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only)."),
-            assetBaseUrl: z
-                .string()
-                .optional()
-                .describe("Host-side basePath forced onto the trapped runtime's own asset resolution — " +
-                "pixi's `Assets.init` for a pixijs root, three's " +
-                '`DefaultLoadingManager.setURLModifier` for a threejs root (D-W1) — absolute, or ' +
-                "root-relative (resolved against the editor page's own origin at mount time, " +
-                'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
-                '(iframe-reachable only — a document.write iframe keeps the parent window.location).'),
-            extraDeps: z
-                .array(z.string())
-                .optional()
-                .describe("Bare specifiers of this root's externalized deps beyond its own runtime " +
-                "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
-                'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
-                'carries data, not code); an unregistered specifier falls back to the open ' +
-                "project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served " +
-                'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
-                '(iframe-reachable only).'),
-            pixiModuleUrl: z
-                .string()
-                .optional()
-                .describe('PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
-                "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
-                'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
-                'version skew) (iframe-reachable only). Declaring this on a `kind: "threejs"` ' +
-                'root is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
-                'not-supported error at resolve — three has no version-skew mount this wave (D-W7, ' +
-                'docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly ' +
-                'parked, no consumer exists).'),
-            bodyHtml: z
-                .string()
-                .optional()
-                .describe('HTML injected into the iframe body before the game script boots (e.g. a ' +
-                '`<div id="game-root">` the game expects to find) (iframe-reachable only).'),
-        })
-            .describe('Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
-            'own external folder)')
-            .superRefine((ingest, ctx) => {
-            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2/D-P4): the six
-            // iframe-reachable-multi fields only make sense for the
-            // iframe-reachable-multi mount — reject them under any other
-            // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
-            const iframeOnlyFields = [
-                ['bundleUrl', ingest.bundleUrl !== undefined],
-                ['baseHref', ingest.baseHref !== undefined],
-                ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
-                ['extraDeps', ingest.extraDeps !== undefined],
-                ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
-                ['bodyHtml', ingest.bodyHtml !== undefined],
-            ];
-            if (ingest.strategy !== 'iframe-reachable') {
-                for (const [key, present] of iframeOnlyFields) {
-                    if (present) {
-                        ctx.addIssue({
-                            code: z.ZodIssueCode.custom,
-                            message: `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
-                                `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
-                                "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
-                                '(pixijs: ingest-iframe-2d.ts IframeReachableMultiOpts; threejs, D-W1: ' +
-                                'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
-                                'meaning under any other strategy.',
-                            path: [key],
-                        });
-                    }
-                }
-                return;
-            }
-            const hasBundleUrl = ingest.bundleUrl !== undefined;
-            const hasEntryHtml = ingest.entryHtml !== undefined;
-            if (hasBundleUrl === hasEntryHtml) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
-                        'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
-                        `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
-                    path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
-                });
-            }
-        }),
-    })
-        .strict(),
-])
-    .describe("Root adapter identity: built-in 'threejs'/'pixijs'/'react', a custom " +
-    '{ module, surface } adapter, or an { ingest, surface } adapter for an unmodified game');
-// ---------------------------------------------------------------------------
-// Root entry
-// ---------------------------------------------------------------------------
-export const AdapterRootSchema = z
-    .object({
-    id: z
-        .string()
-        .describe('Unique id for this root within the manifest (enforced-unique, D-V6 — GameManifestSchema.roots rejects duplicates)'),
-    description: z
-        .string()
-        .optional()
-        .describe("Optional one-line description of this root's game/content (e.g. an ingested game's " +
-        "blurb — the manifest-native replacement for a registry entry's description field)"),
-    adapter: RootAdapterSchema.describe("This root's adapter and sole rendering/lifecycle discriminator"),
-    scene: z
-        .string()
-        .optional()
-        .describe('.vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)'),
-    entry: z
-        .string()
-        .optional()
-        .describe("Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)"),
-    zOrder: z
-        .number()
-        .int()
-        .default(0)
-        .describe('Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order'),
-    pausable: z
-        .boolean()
-        .default(true)
-        .describe('Whether play-mode pause/step applies to this root'),
-    loop: z
-        .enum(['gated', 'self-driven'])
-        .default('gated')
-        .describe('gated: host-driven loop (default). self-driven: this root drives its own loop ' +
-        '(the "composited, unsynchronized" tier) — an axis independent of capability tier'),
-    capabilities: z
-        .object({
-        local: TierSchema.optional().describe('Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)'),
-        hosted: TierSchema.optional().describe('Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)'),
-    })
-        .optional()
-        .describe("Per-delivery-context capability tier declarations (§4). Declaring above the adapter's " +
-        'ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.'),
-})
-    .strict();
-// ---------------------------------------------------------------------------
-// Game manifest (vgai.game.json)
-// ---------------------------------------------------------------------------
-export const GameManifestSchema = z
-    .object({
-    $schema: z
-        .string()
-        .optional()
-        .describe('Optional JSON Schema URI for editor autocomplete and validation'),
-    manifestVersion: z
-        .literal(GAME_MANIFEST_VERSION)
-        .describe('Manifest file format version (v2 clean roots)'),
-    name: z.string().describe('Game display name'),
-    appId: z
-        .string()
-        .optional()
-        .describe('Stable reverse-domain application id used by packaged targets'),
-    editorPort: z
-        .number()
-        .int()
-        .min(1024)
-        .max(65535)
-        .optional()
-        .describe('Stable preferred local editor port; launchers may fall forward when occupied'),
-    version: z.string().describe("The game's own version (used for orphan detection)"),
-    engine: z
-        .object({
-        version: z
-            .string()
-            .describe('Exact @vgai/engine semver this game was scaffolded/last upgraded against — an ' +
-            'identity pin, not a range'),
-    })
-        .describe('Engine version pin'),
-    roots: z
-        .array(AdapterRootSchema)
-        .min(1)
-        .superRefine((roots, ctx) => {
-        // D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md §1G debt,
-        // docs/MULTI-WORLD-DESIGN.md §1G): root ids are described as unique
-        // above but that was describe-only at the SCHEMA level — only
-        // load.ts's loader-level cross-field check caught a collision, so
-        // any OTHER consumer of this schema (the generated JSON Schema,
-        // editor tooling) saw duplicate ids as legal. Enforced HERE instead,
-        // naming every colliding id (not just the first found) — overlay
-        // files are keyed by root id (`.vgai/overlays/<id>.json`), so a
-        // silently-permitted duplicate would have two roots silently share
-        // one overlay.
-        const counts = new Map();
-        for (const root of roots)
-            counts.set(root.id, (counts.get(root.id) ?? 0) + 1);
-        const duplicates = [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
-        if (duplicates.length === 0)
-            return;
-        const idsText = duplicates.map((id) => `"${id}"`).join(', ');
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: duplicates.length === 1
-                ? `Game manifest: duplicate root id ${idsText} — root ids must be unique across the manifest (enforced-unique).`
-                : `Game manifest: duplicate root ids: ${idsText} — root ids must be unique across the manifest (enforced-unique).`,
-        });
-    })
-        .describe("The Game's explicit, non-empty adapter-root composition. There is no implicit root."),
-    authoring: z
-        .object({
-        hierarchy: z
-            .object({
-            rootLabels: z
-                .record(z.string(), z.string())
-                .optional()
-                .describe('Optional editor labels keyed by adapter-root id'),
-            groups: z
-                .array(z.object({
-                id: z.string().describe('Unique editor-only group id'),
-                label: z.string().describe('Editor-only group label'),
-                roots: z
-                    .array(z.string())
-                    .min(1)
-                    .describe('Adapter-root ids shown under this editor-only group'),
-            }))
-                .optional()
-                .describe('Optional editor-only hierarchy groups'),
-        })
-            .optional()
-            .describe('Editor projection for native adapter roots'),
-    })
-        .optional()
-        .describe('Editor-only authoring metadata; never runtime ownership'),
-    server: z
-        .object({
-        room: z.string().describe('Colyseus room name'),
-        module: z
-            .string()
-            .optional()
-            .describe('Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap'),
-    })
-        .optional()
-        .describe('Multiplayer server config (Colyseus), if this game registers a room'),
-    resolution: z
-        .object({
-        width: z.number().describe('Canvas width in pixels'),
-        height: z.number().describe('Canvas height in pixels'),
-    })
-        .optional()
-        .describe('Canvas resolution'),
-    debug: z
-        .object({
-        allowInProduction: z
-            .boolean()
-            .describe('Allow the ?vgai-debug=1 introspection bridge and debug-command invocation in ' +
-            'production builds. Default false: the bridge only installs in dev builds. The ' +
-            'runtime reader is the debug-bridge installer (D18).'),
-    })
-        .optional()
-        .describe('Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs ' +
-        'window.__vgai outside dev builds.'),
-    determinism: z
-        .object({
-        seededRandom: z
-            .boolean()
-            .describe('Declares that ALL gameplay RNG in this project flows through ctx.random (the ' +
-            'named-stream seeded PRNG, docs/D15-DETERMINISM-DESIGN.md) rather than raw ' +
-            'Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: ' +
-            'the boot-time seeding reader (mount-manifest.ts seeds ctx.random from ' +
-            'defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the ' +
-            'gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this ' +
-            "project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase " +
-            'trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay ' +
-            'frame, never throws). Default false: an undeclared project gets no determinism ' +
-            'contract at all (that IS the opt-out — no dead field, per the T4.1 policy).'),
-        defaultSeed: z
-            .number()
-            .int()
-            .optional()
-            .describe('The seed ctx.random boots from when seededRandom is true, unless overridden by ' +
-            '?vgai-seed=<int> (the query param always wins over this manifest default) or an ' +
-            'even higher-precedence explicit config value a host passes directly. Optional — ' +
-            "omit to fall back to the runtime's own fixed default seed."),
-    })
-        .optional()
-        .describe('Seeded-RNG determinism contract (D15, docs/D15-DETERMINISM-DESIGN.md) — governs ' +
-        'whether ctx.random is boot-seeded from a reproducible seed and whether the ' +
-        'gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.'),
-})
-    .strict()
-    .describe('Game manifest (vgai.game.json) — the complete v2 project configuration');

package/dist/physics/collision-system.d.ts

@@ -1,41 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-/**
- * Collision event handler.
- * Called with the two collider handles and whether contact started or stopped.
- */
-export type CollisionHandler = (handleA: number, handleB: number, started: boolean) => void;
-/**
- * Drains the Rapier event queue each frame and dispatches collision events.
- *
- * Usage:
- *   const collisions = createCollisionSystem(rapierWorld, eventQueue);
- *   collisions.onCollision((a, b, started) => { ... });
- *   // In physics phase: rapierWorld.step(eventQueue);
- *   // In postPhysics: collisions.drain();
- */
-export declare function createCollisionSystem(rapierWorld: RAPIER.World, eventQueue: RAPIER.EventQueue): {
-    /** Register a collision handler. */
-    onCollision(handler: CollisionHandler): void;
-    /** Remove a collision handler. */
-    offCollision(handler: CollisionHandler): void;
-    /**
-     * Drain the event queue and dispatch collision events.
-     * Call this in POST_PHYSICS phase, after rapierWorld.step(eventQueue).
-     *
-     * Events are buffered first, then handlers run *after* the drain callback
-     * returns. This is required: a handler that calls back into the Rapier world
-     * (e.g. trigger dispatch resolving a collider, or an `onTriggerEnter` that
-     * spawns/removes a body) would otherwise re-enter Rapier while it is still
-     * borrowed by `drainCollisionEvents`, throwing "recursive use of an object
-     * ... unsafe aliasing in rust".
-     */
-    drain(): void;
-    /**
-     * Look up the rigid body handle that owns a collider handle.
-     * To resolve a collider directly to its Object3D entity, use the physics
-     * registry's `getByColliderHandle` reverse index instead.
-     */
-    getBodyHandleFromCollider(colliderHandle: number): number | undefined;
-};
-export type CollisionSystem = ReturnType<typeof createCollisionSystem>;
-//# sourceMappingURL=collision-system.d.ts.map

package/dist/physics/collision-system.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"collision-system.d.ts","sourceRoot":"","sources":["../../src/physics/collision-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAE5F;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU;IAI1F,oCAAoC;yBACf,gBAAgB;IAIrC,kCAAkC;0BACZ,gBAAgB;IAKtC;;;;;;;;;;OAUG;;IAkBH;;;;OAIG;8CACuC,MAAM,GAAG,MAAM,GAAG,SAAS;EAQxE;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/physics/collision-system.js

@@ -1,64 +0,0 @@
-/**
- * Drains the Rapier event queue each frame and dispatches collision events.
- *
- * Usage:
- *   const collisions = createCollisionSystem(rapierWorld, eventQueue);
- *   collisions.onCollision((a, b, started) => { ... });
- *   // In physics phase: rapierWorld.step(eventQueue);
- *   // In postPhysics: collisions.drain();
- */
-export function createCollisionSystem(rapierWorld, eventQueue) {
-    const handlers = [];
-    return {
-        /** Register a collision handler. */
-        onCollision(handler) {
-            handlers.push(handler);
-        },
-        /** Remove a collision handler. */
-        offCollision(handler) {
-            const idx = handlers.indexOf(handler);
-            if (idx !== -1)
-                handlers.splice(idx, 1);
-        },
-        /**
-         * Drain the event queue and dispatch collision events.
-         * Call this in POST_PHYSICS phase, after rapierWorld.step(eventQueue).
-         *
-         * Events are buffered first, then handlers run *after* the drain callback
-         * returns. This is required: a handler that calls back into the Rapier world
-         * (e.g. trigger dispatch resolving a collider, or an `onTriggerEnter` that
-         * spawns/removes a body) would otherwise re-enter Rapier while it is still
-         * borrowed by `drainCollisionEvents`, throwing "recursive use of an object
-         * ... unsafe aliasing in rust".
-         */
-        drain() {
-            const events = [];
-            eventQueue.drainCollisionEvents((handle1, handle2, started) => {
-                events.push([handle1, handle2, started]);
-            });
-            eventQueue.drainContactForceEvents((_event) => {
-                // Contact force events available for advanced use.
-                // Game code can subscribe to these by extending this system.
-            });
-            for (const [handle1, handle2, started] of events) {
-                for (let i = 0; i < handlers.length; i++) {
-                    handlers[i](handle1, handle2, started);
-                }
-            }
-        },
-        /**
-         * Look up the rigid body handle that owns a collider handle.
-         * To resolve a collider directly to its Object3D entity, use the physics
-         * registry's `getByColliderHandle` reverse index instead.
-         */
-        getBodyHandleFromCollider(colliderHandle) {
-            const collider = rapierWorld.getCollider(colliderHandle);
-            if (!collider)
-                return undefined;
-            const body = collider.parent();
-            if (!body)
-                return undefined;
-            return body.handle;
-        },
-    };
-}

package/dist/physics/physics-registry.d.ts

@@ -1,45 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import type * as THREE from 'three';
-/** The Rapier handles owned by a single Object3D entity. */
-export interface PhysicsRefs {
-    body: RAPIER.RigidBody;
-    collider: RAPIER.Collider;
-}
-/**
- * Maps Three.js Object3Ds to their Rapier bodies/colliders, and Rapier collider
- * handles back to Object3Ds.
- *
- * Replaces the old bitecs RigidBodyRef/ColliderRef SoA components. Two indexes:
- *  - `Object3D → {body, collider}` for the postPhysics transform writer and for
- *    GameComponents/editor to reach an entity's physics.
- *  - `colliderHandle → Object3D` reverse index for collision/trigger dispatch
- *    (Rapier collision events report collider handles).
- */
-export declare function createPhysicsRegistry(): {
-    /** Register an Object3D's body + collider, indexing both directions. */
-    add(object3D: THREE.Object3D, body: RAPIER.RigidBody, collider: RAPIER.Collider): void;
-    /** Get the physics refs for an Object3D, if any. */
-    get(object3D: THREE.Object3D): PhysicsRefs | undefined;
-    /** Resolve a Rapier collider handle to the Object3D that owns it. */
-    getByColliderHandle(handle: number): THREE.Object3D | undefined;
-    /**
-     * Register a callback fired synchronously, just before an entry is torn
-     * down, for every `remove()` call (both indexes are still intact at call
-     * time). Used by trigger-dispatch (T1.12d) to flush any pending
-     * `onTriggerExit` for a sensor overlap involving this object before the
-     * collider handle becomes unresolvable — otherwise an entity despawned
-     * between the physical exit and the next `collisions.drain()` silently
-     * drops the exit callback on its still-live overlap partner.
-     */
-    onRemove(listener: (object3D: THREE.Object3D, refs: PhysicsRefs) => void): void;
-    /** Remove an Object3D's entry from both indexes. */
-    remove(object3D: THREE.Object3D): void;
-    /** Iterate every (Object3D, refs) pair — used by the transform writer. */
-    entries(): IterableIterator<[THREE.Object3D, PhysicsRefs]>;
-    /** Number of registered physics entities. */
-    readonly size: number;
-    /** Clear both indexes (does not free Rapier bodies). */
-    clear(): void;
-};
-export type PhysicsRegistry = ReturnType<typeof createPhysicsRegistry>;
-//# sourceMappingURL=physics-registry.d.ts.map

package/dist/physics/physics-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"physics-registry.d.ts","sourceRoot":"","sources":["../../src/physics/physics-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB;IAMjC,wEAAwE;kBAC1D,KAAK,CAAC,QAAQ,QAAQ,MAAM,CAAC,SAAS,YAAY,MAAM,CAAC,QAAQ,GAAG,IAAI;IAKtF,oDAAoD;kBACtC,KAAK,CAAC,QAAQ,GAAG,WAAW,GAAG,SAAS;IAItD,qEAAqE;gCACzC,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,SAAS;IAI/D;;;;;;;;OAQG;uBACgB,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAI/E,oDAAoD;qBACnC,KAAK,CAAC,QAAQ,GAAG,IAAI;IAStC,0EAA0E;eAC/D,gBAAgB,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAI1D,6CAA6C;mBACjC,MAAM;IAIlB,wDAAwD;aAC/C,IAAI;EAKhB;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/physics/physics-registry.js

@@ -1,65 +0,0 @@
-/**
- * Maps Three.js Object3Ds to their Rapier bodies/colliders, and Rapier collider
- * handles back to Object3Ds.
- *
- * Replaces the old bitecs RigidBodyRef/ColliderRef SoA components. Two indexes:
- *  - `Object3D → {body, collider}` for the postPhysics transform writer and for
- *    GameComponents/editor to reach an entity's physics.
- *  - `colliderHandle → Object3D` reverse index for collision/trigger dispatch
- *    (Rapier collision events report collider handles).
- */
-export function createPhysicsRegistry() {
-    const byObject = new Map();
-    const byColliderHandle = new Map();
-    const removeListeners = [];
-    return {
-        /** Register an Object3D's body + collider, indexing both directions. */
-        add(object3D, body, collider) {
-            byObject.set(object3D, { body, collider });
-            byColliderHandle.set(collider.handle, object3D);
-        },
-        /** Get the physics refs for an Object3D, if any. */
-        get(object3D) {
-            return byObject.get(object3D);
-        },
-        /** Resolve a Rapier collider handle to the Object3D that owns it. */
-        getByColliderHandle(handle) {
-            return byColliderHandle.get(handle);
-        },
-        /**
-         * Register a callback fired synchronously, just before an entry is torn
-         * down, for every `remove()` call (both indexes are still intact at call
-         * time). Used by trigger-dispatch (T1.12d) to flush any pending
-         * `onTriggerExit` for a sensor overlap involving this object before the
-         * collider handle becomes unresolvable — otherwise an entity despawned
-         * between the physical exit and the next `collisions.drain()` silently
-         * drops the exit callback on its still-live overlap partner.
-         */
-        onRemove(listener) {
-            removeListeners.push(listener);
-        },
-        /** Remove an Object3D's entry from both indexes. */
-        remove(object3D) {
-            const refs = byObject.get(object3D);
-            if (refs) {
-                for (const listener of removeListeners)
-                    listener(object3D, refs);
-                byColliderHandle.delete(refs.collider.handle);
-            }
-            byObject.delete(object3D);
-        },
-        /** Iterate every (Object3D, refs) pair — used by the transform writer. */
-        entries() {
-            return byObject.entries();
-        },
-        /** Number of registered physics entities. */
-        get size() {
-            return byObject.size;
-        },
-        /** Clear both indexes (does not free Rapier bodies). */
-        clear() {
-            byObject.clear();
-            byColliderHandle.clear();
-        },
-    };
-}

package/dist/physics/transform-writer.d.ts

@@ -1,16 +0,0 @@
-import * as THREE from 'three';
-import type { PhysicsRegistry } from './physics-registry';
-/**
- * Build the single postPhysics transform writer.
- *
- * Replaces the old three-step path (physicsSyncSystem → ECS Position/Rotation →
- * vnode-manager.syncTransforms). Rapier always reports world-space transforms, so
- * for objects parented under something other than the scene root we convert the
- * body's world position/rotation into the parent's local space (P1.5) — the old
- * vnode path wrote world transforms as local and mis-placed parented children.
- *
- * Scale is left untouched: Rapier carries no scale, so the Object3D keeps its
- * authored local scale.
- */
-export declare function createTransformWriter(physics: PhysicsRegistry, sceneRoot: THREE.Object3D): () => void;
-//# sourceMappingURL=transform-writer.d.ts.map

package/dist/physics/transform-writer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transform-writer.d.ts","sourceRoot":"","sources":["../../src/physics/transform-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAM1D;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,SACpD,IAAI,CAoBxC"}