@vgai/engine 0.5.2 → 0.5.3

package/src/world2d/schema/entity2d.ts

@@ -1,163 +0,0 @@
-import { z } from 'zod';
-import { Physics2DSchema } from './physics2d';
-import { SpriteSchema, Text2DSchema } from './sprite';
-import { TilemapSchema } from './tilemap';
-import { Transform2DSchema, Vec2Schema } from './tuples2d';
-
-/** Component data: same shape as the 3D ComponentsSchema (scalars + scalar arrays). */
-const ComponentScalarSchema = z.union([z.number(), z.string(), z.boolean()]);
-const ComponentValueSchema = z.union([
-  ComponentScalarSchema,
-  z.array(z.number()),
-  z.array(z.string()),
-  z.array(z.boolean()),
-]);
-const ComponentDataSchema = z.record(z.string(), ComponentValueSchema);
-const ComponentsSchema = z.record(z.string(), ComponentDataSchema);
-
-/**
- * A world2d entity — the 2D analog of the 3D `SceneEntity`. The SAME engine model
- * (named components validated against a registry, a tree of children) reused; the
- * sections (`sprite`/`text`/`physics2d`/`transform2d`) name engine-owned data, NOT
- * `PIXI.Sprite`. `surface` defaults to 'world2d' for entities in a Scene2D file.
- */
-const Entity2DBase = z.object({
-  id: z.string().optional().describe('Unique entity ID. Auto-generated if omitted'),
-  name: z.string().describe('Human-readable entity name (shown in hierarchy panel)'),
-  surface: z
-    .enum(['world2d', 'world3d'])
-    .optional()
-    .describe(
-      "Render surface that instantiates this entity. Default 'world2d' in a Scene2D file. The " +
-        "'world3d' value is REJECTED at parse (T4.1): declared but has no runtime reader — " +
-        "authoring surface: 'world3d' throws. Do not author it ('world2d', the default, is fine).",
-    ),
-  visible: z.boolean().optional().describe('Whether the entity and its children are rendered'),
-  locked: z
-    .boolean()
-    .optional()
-    .describe('Prevent selection and editing in the native 2D scene editor'),
-  tags: z
-    .array(z.string())
-    .optional()
-    .describe(
-      'Arbitrary string tags for runtime queries. REJECTED at parse (T4.1): declared but has no ' +
-        'runtime reader — authoring this field throws. Do not author.',
-    ),
-  transform2d: Transform2DSchema.optional().describe('Local 2D transform relative to parent'),
-  pivot: Vec2Schema.optional().describe('Local-space pivot point [x, y]'),
-  sprite: SpriteSchema.optional().describe('2D sprite appearance'),
-  text: Text2DSchema.optional().describe('World-space text label'),
-  tilemap: TilemapSchema.optional().describe('2D tilemap (CompositeTilemap)'),
-  physics2d: Physics2DSchema.optional().describe('2D physics rigid body + collider'),
-  components: ComponentsSchema.optional().describe(
-    'User-defined components (validated against the world2d component registry)',
-  ),
-});
-
-export type Entity2D = z.infer<typeof Entity2DBase> & {
-  children?: Entity2D[] | undefined;
-};
-
-export const Entity2DSchema: z.ZodType<Entity2D> = z.lazy(() =>
-  Entity2DBase.extend({
-    children: z.array(Entity2DSchema).optional().describe('Child entities'),
-  })
-    // T4.1: two fields are authored/typed but have no runtime reader in
-    // `scene2d-loader.ts`'s `spawn()` (unlike their 3D `SceneEntity` siblings,
-    // which ARE read — `scene-query.ts` for `tags`):
-    //   - `tags` — never copied onto userData; no 2D equivalent of scene-query.ts.
-    //   - `surface: 'world3d'` — spawn() always instantiates as world2d
-    //     regardless of this field's value, so a 'world3d' entity is silently
-    //     spawned into the 2D world anyway. ('world2d', the default, is a
-    //     harmless no-op and is not flagged.)
-    // Loud load errors until readers exist — see T4.1.
-    .superRefine((entity, ctx) => {
-      if (entity.tags !== undefined) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message:
-            `world2d entity "${entity.name}": \`tags\` is authored but not implemented — ` +
-            'no 2D equivalent of scene-query.ts reads it yet. See T4.1.',
-          path: ['tags'],
-        });
-      }
-      if (entity.surface === 'world3d') {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message:
-            `world2d entity "${entity.name}": \`surface: 'world3d'\` is authored but not ` +
-            'implemented — spawn() always instantiates entities as world2d regardless of this ' +
-            'field, so a world3d entity would be silently spawned into the 2D world. See T4.1.',
-          path: ['surface'],
-        });
-      }
-    }),
-) as z.ZodType<Entity2D>;
-
-/** A world2d scene file — the 2D analog of `.vscn.json` (`.scn2d.json`). */
-export const Scene2DSchema = z
-  .object({
-    version: z.number().optional().describe('Scene format version'),
-    name: z
-      .string()
-      .optional()
-      .describe('Scene name shown in the native 2D document hierarchy and inspector'),
-    surface: z.literal('world2d').optional().describe("Render surface. Always 'world2d'"),
-    gravity: Vec2Schema.optional().describe(
-      'World gravity [x, y] in px/s^2. Default [0, 9.8 * pixelsPerMeter] ([0, 980] at the default scale)',
-    ),
-    pixelsPerMeter: z
-      .number()
-      .positive()
-      .optional()
-      .describe(
-        'Authored pixels per physics meter. Configures native Rapier World.lengthUnit and scales default gravity. Default 100',
-      ),
-    background: z.string().optional().describe("Background color hex string. Default '#10101a'"),
-    entities: z.array(Entity2DSchema).describe('Root entities of the world2d scene'),
-  })
-  // Duplicate authored ids are rejected at the document boundary so source
-  // history and editor selection always address one stable native Container.
-  .superRefine((scene, ctx) => {
-    const authoredIds = new Map<string, Array<string | number>>();
-    const visit = (entities: Entity2D[], parentPath: Array<string | number>): void => {
-      entities.forEach((entity, index) => {
-        const entityPath = [...parentPath, index];
-        if (entity.id !== undefined) {
-          const idPath = [...entityPath, 'id'];
-          const firstPath = authoredIds.get(entity.id);
-          if (firstPath) {
-            ctx.addIssue({
-              code: z.ZodIssueCode.custom,
-              message:
-                `Duplicate world2d entity id "${entity.id}"; first authored at ` +
-                firstPath.join('.'),
-              path: idPath,
-            });
-          } else {
-            authoredIds.set(entity.id, idPath);
-          }
-        }
-        if (entity.children) visit(entity.children, [...entityPath, 'children']);
-      });
-    };
-    visit(scene.entities, ['entities']);
-  })
-  .describe('A world2d scene (PixiJS render surface)');
-
-export type Scene2DFile = z.infer<typeof Scene2DSchema>;
-
-/** A copy-on-instantiate reusable native 2D entity subtree. This is a
- * separate format from Three's `.prefab.json`: its root is an `Entity2D`, and
- * insertion assigns fresh scene identities instead of creating a linked
- * override layer. */
-export const Entity2DAssetSchema = z
-  .object({
-    version: z.literal(1).describe('2D entity asset format version'),
-    name: z.string().describe('Reusable 2D entity asset display name'),
-    root: Entity2DSchema.describe('Native Entity2D subtree copied into a Scene2D document'),
-  })
-  .describe('A reusable native 2D entity asset (.entity2d.json)');
-
-export type Entity2DAsset = z.infer<typeof Entity2DAssetSchema>;

package/src/world2d/schema/physics2d.ts

@@ -1,64 +0,0 @@
-import { z } from 'zod';
-import { Vec2Schema } from './tuples2d';
-
-/** A single 2D collider shape (Rapier 2D). Cuboid takes 2 half-extents; ball a radius. */
-export const Collider2DSchema = z
-  .discriminatedUnion('shape', [
-    z.object({
-      shape: z.literal('cuboid').describe('Box collider aligned to the rigid-body rotation'),
-      halfExtents: Vec2Schema.describe('Half-width and half-height [hx, hy] in pixels'),
-    }),
-    z.object({
-      shape: z.literal('ball').describe('Circle collider'),
-      radius: z.number().describe('Radius in pixels'),
-    }),
-    z.object({
-      shape: z.literal('capsule').describe('Capsule collider (vertical)'),
-      halfHeight: z.number().describe('Half the straight segment length'),
-      radius: z.number().describe('Cap radius'),
-    }),
-  ])
-  .describe('2D collider shape (Rapier 2D)');
-
-export type SceneCollider2D = z.infer<typeof Collider2DSchema>;
-
-/**
- * `physics2d` authored section — engine-owned 2D physics data, instantiated as a
- * Rapier 2D RigidBody + Collider. The world2d analog of the 3D `physics` section.
- */
-export const Physics2DSchema = z
-  .object({
-    bodyType: z
-      .enum(['dynamic', 'fixed', 'kinematicVelocity', 'kinematicPosition'])
-      .describe(
-        'Rapier 2D rigid-body type. A body of any type nested below a dynamic or kinematic ' +
-          'body is rejected: Rapier has no parent/child body relationship. Nesting below a ' +
-          'fixed or physics-less transformed parent is supported for fixed bodies. Dynamic ' +
-          'and kinematic bodies additionally require a conformal parent chain (uniform scale ' +
-          'plus rotation/reflection), because later body rotation cannot round-trip through ' +
-          'non-uniform parent scale without shearing the Pixi visual.',
-      ),
-    collider: Collider2DSchema.describe(
-      'Collider shape attached to the body. Its pose and dimensions use the composed parent ' +
-        'transform at spawn. Cuboids support non-uniform scale; ball/capsule colliders reject ' +
-        'non-uniform scale because Rapier cannot represent an ellipse.',
-    ),
-    sensor: z
-      .boolean()
-      .optional()
-      .describe(
-        'If true, a sensor (trigger) collider — overlaps fire onTriggerEnter/Exit, no solid response',
-      ),
-    density: z.number().optional().describe('Collider density (drives mass). Default 1'),
-    friction: z.number().optional().describe('Coefficient of friction. Default 0.5'),
-    restitution: z.number().optional().describe('Bounciness 0..1. Default 0'),
-    linearDamping: z.number().optional().describe('Linear velocity damping. Default 0'),
-    gravityScale: z.number().optional().describe('Per-body gravity multiplier. Default 1'),
-    lockRotations: z
-      .boolean()
-      .optional()
-      .describe('Lock the body so it cannot rotate. Default false'),
-  })
-  .describe('2D physics rigid body + collider (world2d, Rapier 2D)');
-
-export type ScenePhysics2D = z.infer<typeof Physics2DSchema>;

package/src/world2d/schema/sprite.ts

@@ -1,99 +0,0 @@
-import { z } from 'zod';
-import { Vec2Schema } from './tuples2d';
-
-/**
- * `sprite` authored section — engine-owned 2D sprite data, NOT a `PIXI.Sprite`.
- *
- * Per ARCHITECTURE.md §Render Surfaces: authored data says `sprite`, and a runtime
- * adapter instantiates it onto the appropriate backend (here, a `PIXI.Sprite` on
- * the world2d surface). A 1x1 white texture is used when `texture` is omitted, so a
- * tinted rectangle sprite needs no asset.
- */
-export const SpriteSchema = z
-  .object({
-    texture: z
-      .string()
-      .optional()
-      .describe(
-        'Texture asset URL (loaded via PIXI.Assets). Omit for a tintable 1x1 white texture',
-      ),
-    frame: z
-      .string()
-      .min(1)
-      .optional()
-      .describe('Spritesheet frame/sub-texture name when `texture` is a spritesheet atlas'),
-    animation: z
-      .string()
-      .min(1)
-      .optional()
-      .describe(
-        'Named spritesheet animation from `texture` (PIXI.Spritesheet.animations); mutually exclusive with `frame`',
-      ),
-    anchor: Vec2Schema.optional().describe('Normalized anchor [x, y] (0..1). Default [0.5, 0.5]'),
-    tint: z
-      .string()
-      .optional()
-      .describe("Tint color as hex string (e.g. '#ff8800'). Default white"),
-    alpha: z.number().min(0).max(1).optional().describe('Opacity 0..1. Default 1'),
-    width: z
-      .number()
-      .optional()
-      .describe('Explicit display width in pixels (overrides texture size)'),
-    height: z
-      .number()
-      .optional()
-      .describe('Explicit display height in pixels (overrides texture size)'),
-    blendMode: z
-      .enum(['normal', 'add', 'multiply', 'screen'])
-      .optional()
-      .describe('PixiJS blend mode. Default normal'),
-    interactive: z
-      .boolean()
-      .optional()
-      .describe('Enable federated pointer events (eventMode=static) so this sprite can be picked'),
-    filter: z
-      .enum(['none', 'blur', 'desaturate'])
-      .optional()
-      .describe('Apply a PixiJS filter (BlurFilter / ColorMatrix desaturate). Default none'),
-    fps: z
-      .number()
-      .positive()
-      .optional()
-      .describe('AnimatedSprite playback speed in frames/sec. Default 8'),
-    loop: z
-      .boolean()
-      .optional()
-      .describe('Whether the named spritesheet animation loops. Default true'),
-  })
-  .strict()
-  .superRefine((sprite, ctx) => {
-    if (sprite.animation && !sprite.texture) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: '`animation` requires a spritesheet `texture`',
-        path: ['animation'],
-      });
-    }
-    if (sprite.animation && sprite.frame) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: '`animation` and `frame` are mutually exclusive',
-        path: ['animation'],
-      });
-    }
-  })
-  .describe('2D sprite appearance (world2d). Instantiated as a PIXI.Sprite or AnimatedSprite');
-
-export type SceneSprite = z.infer<typeof SpriteSchema>;
-
-/** `text` authored section — a world-space PIXI.Text label (world-space UI). */
-export const Text2DSchema = z
-  .object({
-    text: z.string().describe('The string to display'),
-    fontSize: z.number().optional().describe('Font size in pixels. Default 24'),
-    fill: z.string().optional().describe("Text color as hex string. Default '#ffffff'"),
-    anchor: Vec2Schema.optional().describe('Normalized anchor [x, y] (0..1). Default [0.5, 0.5]'),
-  })
-  .describe('2D world-space text label (world2d). Instantiated as a PIXI.Text');
-
-export type SceneText2D = z.infer<typeof Text2DSchema>;

package/src/world2d/schema/tilemap.ts

@@ -1,39 +0,0 @@
-import { z } from 'zod';
-
-/**
- * `tilemap` authored section — engine-owned 2D tilemap data (NOT a CompositeTilemap),
- * instantiated to a `@pixi/tilemap` CompositeTilemap by the 2D spawn path. `texture`
- * points at a native Pixi spritesheet JSON asset; `frames` gives its ordered tile
- * palette and `tiles` stores indices into that palette.
- */
-export const TilemapSchema = z
-  .object({
-    frames: z
-      .array(z.string().min(1))
-      .min(1)
-      .describe('Ordered Pixi spritesheet frame names used as tile indices'),
-    texture: z.string().min(1).describe('URL or project path to a Pixi spritesheet JSON asset'),
-    tileSize: z.number().positive().describe('Positive square tile width/height in pixels'),
-    tiles: z
-      .array(z.array(z.number().int()))
-      .describe(
-        'Row-major grid of frame indices; -1 is an empty cell (each row is an array of tile indices)',
-      ),
-  })
-  .strict()
-  .superRefine((tilemap, ctx) => {
-    for (let row = 0; row < tilemap.tiles.length; row++) {
-      for (let column = 0; column < tilemap.tiles[row]!.length; column++) {
-        const index = tilemap.tiles[row]![column]!;
-        if (index >= -1 && index < tilemap.frames.length) continue;
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `Tile index must be -1 (empty) or a frame index from 0 to ${tilemap.frames.length - 1}`,
-          path: ['tiles', row, column],
-        });
-      }
-    }
-  })
-  .describe('2D tilemap (world2d). Instantiated as a @pixi/tilemap CompositeTilemap');
-
-export type SceneTilemap = z.infer<typeof TilemapSchema>;

package/src/world2d/schema/tuples2d.ts

@@ -1,25 +0,0 @@
-import { z } from 'zod';
-
-/** 2D vector as [x, y]. The world2d analog of the 3D Vec3. */
-export const Vec2Schema = z.tuple([z.number(), z.number()]).describe('2D vector as [x, y]');
-
-export type Vec2 = z.infer<typeof Vec2Schema>;
-
-/**
- * 2D local transform — the world2d analog of the 3D TransformSchema.
- *
- * Orientation is a single scalar `rotation` (radians, about the screen Z axis),
- * NOT a quaternion: PixiJS display objects rotate in the plane. The runtime/editor
- * neutral `Transform` tuple (position[3]/quaternion[4]/scale[3]) maps onto this as
- * z = 0 and rotation about Z (see PIXI-WORLD2D-MAXIMAL-SPEC model-transform2d-section).
- */
-export const Transform2DSchema = z
-  .object({
-    position: Vec2Schema.optional().describe('Local position [x, y] in world2d pixels'),
-    rotation: z.number().optional().describe('Rotation in radians about the Z axis. Default 0'),
-    scale: Vec2Schema.optional().describe('Scale per axis [x, y]. Default [1, 1]'),
-    pivot: Vec2Schema.optional().describe('Local pivot point [x, y] (center of rotation/scale)'),
-  })
-  .describe('2D local transform relative to parent (world2d surface)');
-
-export type SceneTransform2D = z.infer<typeof Transform2DSchema>;

package/src/world2d/transform-writer-2d.ts

@@ -1,42 +0,0 @@
-import type { Container } from 'pixi.js';
-import type { Physics2DRegistry } from './physics2d-registry';
-import { relativeTransform2D } from './physics2d-transform';
-
-function normalizeAngle(angle: number): number {
-  return Math.atan2(Math.sin(angle), Math.cos(angle));
-}
-
-/**
- * Build the single postPhysics transform writer for world2d — the ~5-line 2D
- * analog of `createTransformWriter`.
- *
- * Rapier reports world-space poses. A display nested below the scene root needs
- * that pose converted through its parent's inverse transform before assignment;
- * writing the world pose as local coordinates makes parented visuals drift away
- * from their colliders. Scale is left untouched (Rapier carries no scale).
- */
-export function createTransformWriter2D(physics: Physics2DRegistry, sceneRoot: Container) {
-  return function writeTransforms2D(): void {
-    for (const [display, { body }] of physics.entries()) {
-      const t = body.translation();
-      const rotation = body.rotation();
-      const parent = display.parent;
-      const ownReflection = display.scale.x < 0 ? Math.PI : 0;
-      if (parent && parent !== sceneRoot) {
-        const parentMatrix = relativeTransform2D(parent, sceneRoot);
-        const localOrigin = parentMatrix.applyInverse({ x: t.x, y: t.y });
-        const localXAxis = parentMatrix.applyInverse({
-          x: t.x + Math.cos(rotation),
-          y: t.y + Math.sin(rotation),
-        });
-        display.position.set(localOrigin.x, localOrigin.y);
-        display.rotation = normalizeAngle(
-          Math.atan2(localXAxis.y - localOrigin.y, localXAxis.x - localOrigin.x) - ownReflection,
-        );
-      } else {
-        display.position.set(t.x, t.y);
-        display.rotation = normalizeAngle(rotation - ownReflection);
-      }
-    }
-  };
-}

package/src/world2d/types.ts

@@ -1,74 +0,0 @@
-import type RAPIER from '@dimforge/rapier2d-compat';
-import type { Application, Container } from 'pixi.js';
-import type { SystemAdapters } from '../adapter/system-adapter';
-import type { SeededRandom } from '../core/seeded-random';
-import type { createSystemRunner } from '../core/system-runner';
-import type { ComponentManager } from '../ecs/component-manager';
-import type { GameComponentClass } from '../ecs/game-component';
-import type { InputManager } from '../input/input-manager';
-import type { Game, WorldInstance } from '../runtime/game';
-import type { DebugCtxSurface } from '../runtime/types';
-import type { Collision2DSystem } from './collision-2d';
-import type { Physics2DRegistry } from './physics2d-registry';
-
-/**
- * All world2d subsystems, passed to every world2d `setup(ctx)` and to each
- * `GameComponent<'pixijs'>` lifecycle method — the 2D analog of `GameContext`.
- *
- * Raw libraries (call directly, no wrappers): `app` / `stage` (PixiJS),
- * `rapier2dWorld` / `rapier2d` (Rapier 2D). Engine handles bridge them into the
- * SAME phase-ordered loop the 3D path uses (`systems` is the very same
- * `createSystemRunner`, and `PHASE_ORDER` is shared).
- */
-export interface World2DContext {
-  /** The PixiJS application. Its renderer draws `stage`; auto-ticker is disabled. */
-  app: Application;
-  /** The world2d scene-graph root (the camera/world container under app.stage). */
-  stage: Container;
-  /** The Rapier 2D physics `World`. One shared world per world2d scene. */
-  rapier2dWorld: RAPIER.World;
-  /** The Rapier 2D module namespace (RigidBodyDesc, ColliderDesc, Vector2, …). */
-  rapier2d: typeof RAPIER;
-  /** `Container ↔ Rapier2D body/collider` registry (+ collider→entity reverse index). */
-  physics2d: Physics2DRegistry;
-  /** Rapier 2D collision/trigger event dispatcher; drained each postPhysics. */
-  collisions2d: Collision2DSystem;
-  /** Manager for all live GameComponent instances in this pixi world — the
-   *  unified `ComponentManager` (`ecs/component-manager.ts`, constructed with
-   *  `{ kind: 'pixijs' }`). The world2d-silo-only manager this replaced
-   *  (T7.3) is deleted; every 2D component attaches here, exactly like a
-   *  threejs component attaches onto its world's manager. */
-  components: ComponentManager;
-  /** The phase-ordered system runner (shared with the 3D path). */
-  systems: ReturnType<typeof createSystemRunner>;
-  /** The game-owned input manager. Pixi components use the same action maps,
-   *  rebinding, gamepad, tracing, and virtual-input path as Three components. */
-  input: InputManager;
-  /** The shared debug/synthetic-player surface, scoped to this Pixi root. */
-  debug?: DebugCtxSurface;
-  /** The game-scoped seeded random surface shared by every first-party root. */
-  random: SeededRandom;
-  /** Register a game-owned editor-facing system adapter on this root. */
-  registerSystemAdapter?<K extends keyof SystemAdapters>(
-    kind: K,
-    adapter: NonNullable<SystemAdapters[K]>,
-  ): void;
-  /**
-   * The shared Game root when this world is mounted by a first-party host.
-   * This is the cross-world data path: a Pixi component can query gameplay
-   * components owned by a sibling Three.js world without a mirror store or a
-   * bespoke synchronization bridge.
-   */
-  game?: Game | undefined;
-  /** Live alias of `game.roots`, when mounted by the universal host. */
-  roots?: ReadonlyArray<WorldInstance> | undefined;
-}
-
-/** Constructor type for `GameComponent<'pixijs'>` subclasses used in a world2d
- *  registry (carries static phase/schema) — the 2D-registry analog of
- *  `GameComponentClass` (`ecs/game-component.ts`), narrowed to the pixijs kind
- *  so `new Cls()` returns a properly-typed `GameComponent<'pixijs'>` without a cast. */
-export type Pixi2DComponentClass = GameComponentClass<'pixijs'>;
-
-/** Component registry for world2d — a plain name→class map (the 2D analog). */
-export type Component2DRegistry = Record<string, Pixi2DComponentClass>;

package/src/world3d-react/behavior.tsx

@@ -1,146 +0,0 @@
-/**
- * `<Behavior type="…" {...config}>` — the rapier-`<RigidBody>`-shaped wrapper
- * that attaches a registry GameComponent to its child's Object3D under ENGINE
- * phases (the manager provided by `EngineBridge`, ticked by the host loop via
- * ./r3f-adapter.tsx — pause freezes it), detaches on unmount, and re-applies
- * schema-parsed config on prop change.
- *
- * Upstreamed VERBATIM in semantics from `examples/r3f-first-party/src/
- * behavior.tsx` (R4, docs/R3F-FOLLOW-THROUGH-SPEC.md): the Zod-parse +
- * live-instance re-config behavior and the group-wrapper single-stamp shape
- * are live-proven and deliberately unchanged. The one structural difference:
- * the class lookup is REGISTRY-DRIVEN through the bridge (`EngineBridgeValue.
- * registry`, handed to `createR3FAdapter({ components })` by the project)
- * instead of a project-module import — an engine module cannot import
- * project code.
- *
- * WRAPPER SHAPE (the documented W3 decision): a `<group>` wrapper, NOT
- * `cloneElement` ref-injection. Reasons:
- *  - Write-back: the child element keeps its OWN JSX stamp untouched (its
- *    `userData-oid` prop pierces onto the child's Object3D exactly as it
- *    does un-wrapped), so the child's prop/gizmo write-back path is
- *    byte-identical to an un-wrapped mesh. `cloneElement` would have to
- *    merge a ref without clobbering an authored one — fragile across
- *    forwardRef/ref-as-prop shapes — and adds nothing the group doesn't.
- *  - The wrapper carries the `<Behavior>` call site's `userData-oid` stamp so
- *    its config stays source-addressable. It is an INTERNAL attachment node,
- *    not an independent spatial authoring object: the R3F authoring adapter
- *    projects this config onto the wrapped object's Inspector and promotes
- *    the child through the hierarchy.
- *  - Transform semantics: the group stays at identity, so the child's
- *    authored `position`/`rotation`/`scale` are unchanged by wrapping.
- *
- * The component attaches to the FIRST CHILD's Object3D (`group.children[0]`)
- * — the wrapper contract from the spec — not to the group, so `this.object3D`
- * inside the GameComponent is the mesh the author wrapped.
- */
-
-// NOTE: the fiber types import below is type-only; at runtime this module
-// depends only on `react`. It is still R3F-COUPLED by contract: only a
-// project that already mounts through fiber (createR3FAdapter) can render it
-// meaningfully, and the editor's OID stamping marks R3F-dialect files by
-// their fiber import — project entry files importing this module keep their
-// own `@react-three/fiber` import for the scene itself.
-import type { ThreeElements } from '@react-three/fiber';
-import { createElement, useContext, useEffect, useLayoutEffect, useRef } from 'react';
-import type { Group } from 'three';
-import type { GameComponent } from '../ecs/game-component';
-import { type BehaviorRegistry, EngineBridge, resolveBehaviorClass } from './engine-bridge';
-
-export interface BehaviorProps<Reg extends BehaviorRegistry = BehaviorRegistry>
-  extends Pick<ThreeElements['group'], 'children'> {
-  /** Project-registry key of the GameComponent class to attach. */
-  type: Extract<keyof Reg, string>;
-  /** Authored config fields, validated through the class's static Zod schema
-   *  — plus the editor's `userData-oid` stamp, forwarded to the group. */
-  [field: string]: unknown;
-}
-
-export function Behavior<Reg extends BehaviorRegistry = BehaviorRegistry>(
-  props: BehaviorProps<Reg>,
-) {
-  const { type, children, 'userData-oid': oid, ...config } = props;
-  const bridge = useContext(EngineBridge);
-  const groupRef = useRef<Group>(null);
-
-  // Latest config, readable from the attach effect without re-running it.
-  const configRef = useRef(config);
-  configRef.current = config;
-  // The live instance the config-reapply effect targets (never re-attach).
-  const liveRef = useRef<GameComponent | null>(null);
-
-  // Attachment is part of the committed world, not deferred follow-up work.
-  // A layout effect runs before `createR3FAdapter.mount()` resolves its first
-  // committed tree, so deterministic hosts can begin stepping immediately
-  // without losing every warm-up tick to an unflushed passive effect.
-  useLayoutEffect(() => {
-    if (!bridge?.registry) {
-      // Loud degrade, never a crash: a mount without the adapter's bridge
-      // (e.g. a foreign harness rendering this tree directly) — or a bridge
-      // whose adapter was built without a `components` registry — renders
-      // the children plain; behavior simply doesn't attach.
-      console.warn(
-        `<Behavior type="${type}">: no EngineBridge ${
-          bridge ? 'registry' : 'provider'
-        } — component not attached.`,
-      );
-      return;
-    }
-    const target = groupRef.current?.children[0];
-    if (!target) {
-      console.warn(`<Behavior type="${type}">: no child Object3D to attach to.`);
-      return;
-    }
-    const registry = bridge.registry;
-    const Cls = resolveBehaviorClass(registry, type);
-    const instance = new Cls();
-    const parsed = Cls.schema ? Cls.schema.parse(configRef.current) : configRef.current;
-    Object.assign(instance, parsed);
-    // `attach`'s registry info carries the raw authored props so engine-side
-    // HMR (`hotSwap`) can re-validate them against a future class version.
-    bridge.components.attach(target, instance, {
-      key: type,
-      props: { ...configRef.current },
-    });
-    liveRef.current = instance;
-    return () => {
-      // `detach(node)` removes every component on the node (the manager's
-      // public teardown op). This wrapper attaches exactly one component per
-      // child, so this is exact here.
-      bridge.components.detach(target);
-      liveRef.current = null;
-    };
-  }, [bridge, type]);
-
-  // Re-apply config on prop change, onto the LIVE instance (no re-attach).
-  const configJson = JSON.stringify(config);
-  useEffect(() => {
-    const instance = liveRef.current;
-    if (!instance || !bridge?.registry) return;
-    const Cls = resolveBehaviorClass(bridge.registry, type);
-    const parsed: Record<string, unknown> = JSON.parse(configJson);
-    Object.assign(instance, Cls.schema ? Cls.schema.parse(parsed) : parsed);
-  }, [configJson, type, bridge]);
-
-  // Built with createElement, NOT a JSX literal, deliberately: the editor's
-  // OID stamper rewrites JSX syntax only, so a JSX `<group>` here would get
-  // behavior.tsx's OWN stamp AND the forwarded call-site oid (a duplicate
-  // `userData-oid` attribute). The wrapper group must carry exactly ONE
-  // identity — the `<Behavior>` CALL SITE's oid — so the editor can edit the
-  // config while projecting the wrapper as a component of its child.
-  return createElement(
-    'group',
-    {
-      ref: groupRef,
-      // `Behavior: ` WITH the space: the editor's R3F adapter labels this node
-      // `Behavior: ${behaviorType}` when it projects it as an entity, but falls
-      // back to this `name` when the same node is projected as a component
-      // boundary. Without the space the hierarchy showed one of two different
-      // labels for the identical concept depending on which branch ran.
-      name: `Behavior: ${type}`,
-      'userData-oid': oid,
-      'userData-behaviorType': type,
-    },
-    children,
-  );
-}