@galfus/engine 0.0.0-stage → 0.31.1-alpha

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# @galfus/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript high-level engine runtime for **Galfus Engine**. Provides an ECS-driven architecture, incremental dirty-flag synchronization, anchor-based transform hierarchy, 2D/3D realms, multiverse composition, and spatial audio.
+
+---
+
+## Architecture Overview
+
+1. **ECS as Single Source of Truth**:
+   - Entities hold spatial `Model3D` or `Model2D` components.
+   - Renderables (`Mesh3D`, `Sprite2D`, `Shape2D`, `Svg2D`) attach directly to the model entity.
+   - Assets (`Geometry`, `Material`, `Texture`) are managed in resource registries outside the ECS and survive entity destruction.
+
+2. **Anchor Graph (`origin` / `target`)**:
+   - Replaces traditional rigid parent/child hierarchies.
+   - `origin` is the dependent entity; `target` is the anchor reference.
+   - Detaching an entity or destroying its target preserves the resolved global matrix into the local transform.
+
+3. **Incremental Dirty Sync & Zero Overhead**:
+   - Spatial and descriptor updates are tracked via `DirtyRegistry`.
+   - Completely static scenes produce **zero** transform ABI calls per frame.
+
+4. **Dynamic Multiverse Invocations**:
+   - Targets represent render surfaces (windows or offscreen textures).
+   - Invocations compose Realms onto Targets via responsive viewports.
+   - Mutate viewports seamlessly without rebinding via `invocation.update({ viewport: ... })`.
+
+5. **Deterministic Lifecycle**:
+   - `realm.reset()`: Resets the ECS world, entities, and realm-owned assets, keeping the realm registered.
+   - `realm.dispose()`: Unregisters the realm from the Multiverse and frees its native resources.
+   - `runtime.reset()`: Purges all realms, invocations, targets, audio, and caches while keeping the transport backend ready for new scenes.
+   - `runtime.dispose()`: Terminal shutdown of both runtime and transport.
+
+2D materials are realm-owned resources. `Realm2D.createMaterial` returns a logical ID and queues the material for the next sync or `flush()`, even if the realm is not yet bound to an engine. `destroyMaterial(id)` queues its removal without destroying entities that reference it. `reset()` and `dispose()` release the realm's materials.
+
+The Multiverse maintains a host-side `presentationGraph` rooted at targets of open windows. It is populated from the renderer's resolved schedule and published after a successful dispatch. `getWindow(windowId)` is unavailable before the first successful dispatch or after the window closes; otherwise it exposes an immutable snapshot of reachable targets, invocations, resolved viewports, render order and texture-binding candidates. The last snapshot remains available while paused and when a dispatch fails. Unchanged schedules and links reuse the existing snapshot. A texture binding alone is a candidate, not a traversable surface; future interaction code must validate and maintain surface mappings. Cycle edges sampled from the previous frame are exposed as `softCutEdges`.
+
+2D objects are drawn back to front by `zLayer`, then `drawOrder`, then logical resource ID. Set distinct layers or draw orders when overlap must remain independent of resource creation order. Changing `Model2DComponent.zLayer` or `drawOrder` is synchronized on the next frame.
+
+## Colliders
+
+Each collider belongs to an entity with a matching `Model2D` or `Model3D` component. `addCollider` returns a realm-owned logical collider ID; multiple colliders may share one entity. Local matrices are column-major and relative to the model. Collision queries resolve the model hierarchy on the host and return hits with collider and entity IDs; ray hits are sorted by distance. Queries do not require a bound engine or call the rendering core. Point-query boundaries are inclusive. Rays starting inside a volume return distance zero and a zero normal. A singular world transform temporarily excludes the collider until its transform is invertible again.
+
+```typescript
+const entity = realm2d.createSpatialNode({ position: [3, 4] });
+const colliderId = realm2d.addCollider(entity, { type: 'circle', radius: 2 }, { sensor: true });
+const inside = realm2d.queryPoint([3, 4]);
+const hits = realm2d.raycast([0, 4], [1, 0], 10);
+const component = realm2d.world.getComponent<Collider2DComponent>(entity, 'Collider2D');
+component?.remove(colliderId);
+```
+
+2D supports circles, rectangles and simple polygons. 3D supports spheres, boxes and finite planes in local XY. Queries use a layer mask; the collider's own mask is retained for future pairwise collision filtering. These APIs perform geometric queries and do not simulate rigid bodies.
+
+---
+
+## Input methods
+
+Enable IME only while a text target is focused, and provide its caret area in physical window pixels so the platform can position its candidate UI:
+
+```typescript
+runtime.platform.window.setImeAllowed(windowId, true);
+runtime.platform.window.setImeCursorArea(windowId, x, y, width, height);
+const off = runtime.on('keyboard', (event) => {
+  if (event.type === 'imePreedit') console.log('Preview:', event.text, event.selection);
+  if (event.type === 'imeCommit') console.log('Confirmed:', event.text);
+});
+// On blur or disposal:
+runtime.platform.window.setImeAllowed(windowId, false);
+off();
+```
+
+Selection offsets, when supplied, use UTF-16 code units within the preedit text. The browser does not expose this selection in composition events. The browser input bridge takes DOM focus and releases it on disable or focus loss; enable it from a user interaction when the browser requires a user gesture.
+
+`textInput` is the committed text stream; `input.text` and `imeCommit.text` remain available as raw platform details. Text editors should insert from `textInput` only to avoid processing the same text twice. `TextEditor` stores Unicode text and grapheme-aware selection; `applyTextKeyboardEvent` maps the normalized keyboard stream to the editor.
+
+`runtime.textInput(realmId, { svgId, elementId, hitAreaId, value, tabIndex })` binds an editor to an SVG text element and a focusable SVG hit area. `hitAreaId` defaults to `elementId`; use a separate visible hit area when the text can be empty. The `value` option defaults to an empty string and replaces the element's existing children. The returned input supports `requestFocus`, `blur`, `setValue`, `setSelection`, `selectAll`, `on`, `off`, and `dispose`. It updates the SVG with the IME preview while retaining the committed `value`. Automatic caret and selection rendering, pointer-based text selection, candidate positioning, clipboard integration, and full native/browser IME parity are not yet implemented.
+
+Focusable pointer targets can be registered with `runtime.focusable(realmId, target, { tabIndex })`. Call `requestFocus(windowId)`, `blur(windowId)`, and `dispose()` on the returned target; subscribe to `focus` and `blur` with `on`. `runtime.getFocused(windowId)` reports the focused target. Tab and Shift+Tab navigate registered targets in direct, successfully submitted window presentations. A negative `tabIndex` excludes a target from Tab navigation but permits explicit focus. Browser keyboard delivery still depends on platform focus and must not be interpreted as complete SVG text input support.
+
+`SvgTextDecorations` updates an existing SVG rectangle for a caret and either rectangles or a path for selection spans. It accepts `cursorColor` and `selectionColor`; its caller must provide viewport-space geometry. Automatic cursor placement, pointer selection, and blinking are not provided by this low-level utility.
+
+`runtime.svg.getTextLayout(realmId, svgId, elementId)` returns shaped cluster metrics on demand.
+The result contains normalized text chunks, cluster byte ranges within those UTF-8 chunks,
+advances, ascent and descent, text direction, and affine transforms in SVG viewport coordinates.
+The host caches the result until the SVG or font data changes; missing or non-rendered text
+returns `undefined`. SVG whitespace normalization may change chunk text from the original source,
+and a cluster can contain multiple graphemes, so these metrics alone do not yet define every
+editor caret position. Empty text is not currently returned by the SVG parser.
+
+For explicit text/byte conversions, each runtime defaults to UTF-8. Set `createRuntime(transport, { charset: 'shift_jis' })` or call `runtime.textEncoding.setCharset('windows-1252')`, then use `runtime.textEncoding.encode(text)` and `decode(bytes)`. This setting does not restrict or recode editor strings or change the platform ABI. Unknown charsets throw; invalid bytes and characters not representable in the chosen charset are replaced according to the codec.
+
+---
+
+## Quick Start
+
+```typescript
+import { createBunTransport } from '@galfus/transport-bun';
+import { createRuntime } from '@galfus/engine';
+
+// 1. Initialize transport and runtime
+const transport = await createBunTransport({ targetFps: 60, headless: false });
+const runtime = createRuntime(transport);
+
+// 2. Create 3D Realm and resources
+const realm3d = runtime.createRealm3D(1);
+const geoId = realm3d.createGeometry({ kind: 'cube', size: 1.0 });
+const matId = realm3d.createMaterial({ baseColor: [0.8, 0.2, 0.3, 1.0] });
+
+// 3. Create Model entity and attach Mesh
+const entity = realm3d.createModel({
+  geometryId: geoId,
+  materialId: matId,
+  transform: { position: [0, 1, 0] }
+});
+
+// 4. Set up Multiverse Target and Invocation
+const targetId = runtime.multiverse.createTarget({
+  kind: { type: 'window', windowId: 1 }
+});
+
+const invocationId = runtime.multiverse.createInvocation({
+  realmId: realm3d.realmId,
+  targetId,
+  viewport: { width: { vw: 100 }, height: { vh: 100 } }
+});
+
+// 5. Start main loop
+runtime.start();
+```
+
+---
+
+## SVG element bounds
+
+`runtime.svg.getRect(realmId, svgId, elementId)` returns the geometric bounds of an SVG
+element or `undefined` if it cannot be found. The result is expressed in the SVG viewport's
+coordinates (top-left origin, Y down), before the entity transform. `viewportWidth` and
+`viewportHeight` describe that coordinate space. Bounds are cached and refreshed after SVG
+edits, font changes, re-creation, and native attribute animations.
+
+## Pointer interaction
+
+Run `bun host:demo interaction` to try direct 2D, SVG, and 3D interaction in a window.
+Run `bun host:demo text-input` to try multiple SVG text fields and Tab/Shift+Tab focus.
+To test characters outside the bundled font, pass `--font /path/to/font.ttf` (TTF, OTF, or TTC).
+The demo draws the keyboard caret and selection for single-line text; positions inside a ligature
+are estimated because the current layout API does not expose ligature caret positions.
+For a bounded headless smoke test, use `bun host:demo interaction --headless --frames 10`.
+The host tutorial is available as `bun host:demo tutorial`, with the same headless option.
+Use `bun host:demo help` to list the available demos.
+
+For an entity with a `Collider2D` or `Collider3D`, or for an SVG element in a 2D realm:
+
+```ts
+const listener = runtime.interactive(realmId, { type: 'collider', entityId });
+const unsubscribe = listener.on('hover', (event) => console.log(event.pointer.position));
+listener.on('click', () => console.log('clicked'));
+unsubscribe();
+listener.dispose();
+```
+
+Use `{ type: 'svg', svgId, elementId }` for an SVG element. The supported event types are
+`hover`, `leave`, `move`, `down`, `up`, `click`, `cancel`, `pressmove`, and `pressup`.
+`pressmove` and `pressup` go to the target originally pressed even when the pointer is no
+longer over it, as long as the platform continues delivering pointer events; `cancel` ends
+the interaction when the pointer or window is lost. When an entity has multiple
+colliders, specify `colliderId`. Events use the most recently submitted presentation state.
+When the registered entity or collider is removed, the listener is cancelled and disposed
+after the next successful dispatch.
+Currently this supports realms presented directly to a window. Traversal through textures
+connecting realms is not implemented yet, and native animations of camera or model transforms
+and camera field of view are not yet reflected in interaction snapshots. Occlusion is resolved
+among registered interactive targets; geometry and colliders without listeners do not block them.
+
+## Migration Guide
+
+| Legacy Pattern                            | Modern `@galfus/engine` Pattern                                                                    |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `parent` / `child` hierarchy              | `origin` (dependent) and `target` (reference) via `r3d.hierarchy.attach(origin, target, strategy)` |
+| `Transform3DComponent` standalone         | Embedded inside `Model3DComponent.transform` (local + world matrices)                              |
+| Standalone `Geometry3D` in ECS            | Realm resource via `realm.createGeometry(...)`                                                     |
+| Direct Core transform writes in animation | Animation drives ECS `Model3DComponent`/`Model2DComponent`                                         |
+| Viewport mutations via separate setters   | Unified `coordinator.updateInvocation(id, { viewport })`                                           |
+| Fallbacks to ID `1` on missing component  | Explicit typed error thrown describing the missing component                                       |
+
+The host APIs `runtime.onTick`, `animation.onEvent`, `world.clear`, `realm3d.attachMesh`,
+the separate Multiverse invocation setters, `stepRealms`, and `syncAllRealms` have been removed.
+Use `runtime.on('tick', ...)`, `animation.on('animation', ...)`, `world.reset`,
+`realm3d.createMesh`, `multiverse.updateInvocation`, and the separate pre-render, sync, and
+post-render stages respectively.

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@galfus/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.31.1-alpha",
+  "description": "Lightweight, high-performance TypeScript ECS and multiverse game engine built for Galfus",
+  "author": "Renato Rodrigues (morbden) <renato@vulppi.dev>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/galfus-lang/galfus-engine.git",
+    "directory": "host/engine"
+  },
+  "bugs": {
+    "url": "https://github.com/galfus-lang/galfus-engine/issues"
+  },
+  "homepage": "https://github.com/galfus-lang/galfus-engine#readme",
+  "keywords": [
+    "galfus",
+    "game-engine",
+    "ecs",
+    "2d",
+    "3d",
+    "multiverse",
+    "webgpu",
+    "scene-graph",
+    "audio",
+    "animation",
+    "spatial",
+    "raycast",
+    "input"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./math": "./src/math/index.ts",
+    "./ecs": "./src/ecs/index.ts",
+    "./anchors": "./src/anchors/index.ts",
+    "./multiverse": "./src/multiverse/index.ts",
+    "./realm2d": "./src/realm2d/index.ts",
+    "./realm2d/utils": "./src/realm2d/utils/index.ts",
+    "./realm2d/presets": "./src/realm2d/presets/index.ts",
+    "./realm3d": "./src/realm3d/index.ts",
+    "./realm3d/utils": "./src/realm3d/utils/index.ts",
+    "./realm3d/presets": "./src/realm3d/presets/index.ts",
+    "./resources": "./src/resources/index.ts",
+    "./audio": "./src/audio/index.ts",
+    "./animation": "./src/animation/index.ts",
+    "./platform": "./src/platform/index.ts",
+    "./types": "./src/types.ts"
+  },
+  "dependencies": {
+    "@galfus/transport-types": "^0.31.1-alpha",
+    "iconv-lite": "^0.7.3",
+    "unicode-segmenter": "0.17.3"
+  }
+}

package/src/anchors/cache.ts

@@ -0,0 +1,101 @@
+/**
+ * Persistent matrix memory cache for anchors and transforms.
+ *
+ * Keeps pre-allocated TypedArray buffers in memory and mutates them in-place
+ * across frames to eliminate Garbage Collector overhead and allocation jitter.
+ */
+
+import type { EntityId } from '../ecs/entity';
+import { mat2d, type Mat2d, mat4, type Mat4 } from '../math/index';
+
+export class AnchorMatrixCache {
+  // 2D Matrix Buffers: Float32Array(6)
+  private readonly _local2D = new Map<EntityId, Mat2d>();
+  private readonly _world2D = new Map<EntityId, Mat2d>();
+
+  // 3D Matrix Buffers: Float32Array(16)
+  private readonly _local3D = new Map<EntityId, Mat4>();
+  private readonly _world3D = new Map<EntityId, Mat4>();
+
+  /**
+   * Retrieves or creates a persistent local 2D matrix buffer for the given entity.
+   */
+  getOrCreateLocal2D(entityId: EntityId): Mat2d {
+    let m = this._local2D.get(entityId);
+    if (!m) {
+      m = mat2d.create();
+      this._local2D.set(entityId, m);
+    }
+    return m;
+  }
+
+  /**
+   * Retrieves or creates a persistent world 2D matrix buffer for the given entity.
+   */
+  getOrCreateWorld2D(entityId: EntityId): Mat2d {
+    let m = this._world2D.get(entityId);
+    if (!m) {
+      m = mat2d.create();
+      this._world2D.set(entityId, m);
+    }
+    return m;
+  }
+
+  /**
+   * Retrieves or creates a persistent local 3D matrix buffer for the given entity.
+   */
+  getOrCreateLocal3D(entityId: EntityId): Mat4 {
+    let m = this._local3D.get(entityId);
+    if (!m) {
+      m = mat4.create();
+      this._local3D.set(entityId, m);
+    }
+    return m;
+  }
+
+  /**
+   * Retrieves or creates a persistent world 3D matrix buffer for the given entity.
+   */
+  getOrCreateWorld3D(entityId: EntityId): Mat4 {
+    let m = this._world3D.get(entityId);
+    if (!m) {
+      m = mat4.create();
+      this._world3D.set(entityId, m);
+    }
+    return m;
+  }
+
+  /**
+   * Gets an existing world 2D matrix buffer if already resolved.
+   */
+  getWorld2D(entityId: EntityId): Mat2d | undefined {
+    return this._world2D.get(entityId);
+  }
+
+  /**
+   * Gets an existing world 3D matrix buffer if already resolved.
+   */
+  getWorld3D(entityId: EntityId): Mat4 | undefined {
+    return this._world3D.get(entityId);
+  }
+
+  /**
+   * Removes cached buffers for an entity upon destruction.
+   */
+  remove(entityId: EntityId): void {
+    this._local2D.delete(entityId);
+    this._world2D.delete(entityId);
+    this._local3D.delete(entityId);
+    this._world3D.delete(entityId);
+  }
+
+  /**
+   * Clears all cached buffers.
+   */
+  clear(): void {
+    this._local2D.clear();
+    this._world2D.clear();
+    this._local3D.clear();
+    this._world3D.clear();
+  }
+}

package/src/anchors/component.ts

@@ -0,0 +1,123 @@
+/**
+ * Spatial transform components and Anchor components for hierarchical relationships.
+ */
+
+import type { Component } from '../ecs/component';
+import type { EntityId } from '../ecs/entity';
+import type { EcsWorld } from '../ecs/world';
+import { type Mat2d, type Mat4, type Quat, type Vec2, type Vec3 } from '../math/index';
+import type { Model2DComponent } from '../realm2d/components';
+import type { Model3DComponent } from '../realm3d/components';
+import { SpatialDirtyFlags } from '../spatial/flags';
+import type { AnchorConstraintCallback2D, AnchorConstraintCallback3D } from './strategy';
+
+/**
+ * Spatial transform descriptors for initial setup.
+ */
+export interface Transform2DProps {
+  position?: [number, number] | Vec2;
+  rotation?: number;
+  scale?: [number, number] | Vec2;
+  zLayer?: number;
+  drawOrder?: number;
+}
+
+export interface Transform3DProps {
+  position?: [number, number, number] | Vec3;
+  rotation?: [number, number, number, number] | Quat;
+  scale?: [number, number, number] | Vec3;
+}
+
+/**
+ * Anchor component linking an origin entity to a target entity with an arbitrary strategy or functional constraint.
+ */
+export interface AnchorComponent extends Component {
+  readonly type: 'Anchor';
+  /** The target entity to which this entity is anchored. */
+  targetEntityId: EntityId;
+  /** Anchor solving strategy name (defaults to 'static'). */
+  strategy: string;
+  /** Optional distance constraint parameter. */
+  distance?: number;
+  /** Optional 2D offset matrix if anchoring in 2D space. */
+  offset2d?: Mat2d;
+  /** Optional 3D offset matrix if anchoring in 3D space. */
+  offset3d?: Mat4;
+  /** Optional custom in-place constraint callback for 2D. */
+  callback2d?: AnchorConstraintCallback2D;
+  /** Optional custom in-place constraint callback for 3D. */
+  callback3d?: AnchorConstraintCallback3D;
+  /** Whether this anchor is currently active. */
+  active: boolean;
+}
+
+export interface AnchorProps {
+  targetEntityId: EntityId;
+  strategy?: string;
+  distance?: number;
+  offset2d?: Mat2d;
+  offset3d?: Mat4;
+  callback2d?: AnchorConstraintCallback2D;
+  callback3d?: AnchorConstraintCallback3D;
+  active?: boolean;
+}
+
+export function createAnchor(props: AnchorProps): AnchorComponent {
+  return {
+    type: 'Anchor',
+    targetEntityId: props.targetEntityId,
+    strategy: props.strategy ?? 'static',
+    distance: props.distance,
+    offset2d: props.offset2d,
+    offset3d: props.offset3d,
+    callback2d: props.callback2d,
+    callback3d: props.callback3d,
+    active: props.active ?? true
+  };
+}
+
+/**
+ * Observable anchor mutation helpers that invalidate origin spatial dirty flags immediately.
+ */
+export function setAnchorDistance(world: EcsWorld, entityId: EntityId, distance: number): boolean {
+  const anchor = world.getComponent<AnchorComponent>(entityId, 'Anchor');
+  if (!anchor) return false;
+  anchor.distance = distance;
+  _invalidateOrigin(world, entityId);
+  return true;
+}
+
+export function setAnchorStrategy(world: EcsWorld, entityId: EntityId, strategy: string): boolean {
+  const anchor = world.getComponent<AnchorComponent>(entityId, 'Anchor');
+  if (!anchor) return false;
+  anchor.strategy = strategy;
+  _invalidateOrigin(world, entityId);
+  return true;
+}
+
+export function setAnchorOffset3D(world: EcsWorld, entityId: EntityId, offset: Mat4): boolean {
+  const anchor = world.getComponent<AnchorComponent>(entityId, 'Anchor');
+  if (!anchor) return false;
+  anchor.offset3d = offset;
+  _invalidateOrigin(world, entityId);
+  return true;
+}
+
+export function setAnchorOffset2D(world: EcsWorld, entityId: EntityId, offset: Mat2d): boolean {
+  const anchor = world.getComponent<AnchorComponent>(entityId, 'Anchor');
+  if (!anchor) return false;
+  anchor.offset2d = offset;
+  _invalidateOrigin(world, entityId);
+  return true;
+}
+
+function _invalidateOrigin(world: EcsWorld, entityId: EntityId): void {
+  const model3d = world.getComponent<Model3DComponent>(entityId, 'Model3D');
+  if (model3d) {
+    model3d.flags |= SpatialDirtyFlags.LocalDirty;
+  }
+  const model2d = world.getComponent<Model2DComponent>(entityId, 'Model2D');
+  if (model2d) {
+    model2d.flags |= SpatialDirtyFlags.LocalDirty;
+  }
+}

package/src/anchors/hierarchy.ts

@@ -0,0 +1,192 @@
+/**
+ * HierarchyCoordinator provides high-level scene graph and anchor management for a Realm.
+ * Maintains an O(1) reverse lookup (target -> dependents), prevents cyclic relationships,
+ * and enforces safe world-transform preservation upon target detachment.
+ */
+
+import type { EntityId } from '../ecs/entity';
+import type { EcsWorld } from '../ecs/world';
+import { mat2d, mat4 } from '../math/index';
+import type { Model2DComponent } from '../realm2d/components';
+import type { Model3DComponent } from '../realm3d/components';
+import { SpatialDirtyFlags } from '../spatial/flags';
+import { type AnchorComponent, createAnchor } from './component';
+import type { AnchorConstraintCallback2D, AnchorConstraintCallback3D } from './strategy';
+
+export type EntityLike = EntityId | { entityId: EntityId };
+
+export type AnchorConstraint3D = string | AnchorConstraintCallback3D;
+export type AnchorConstraint2D = string | AnchorConstraintCallback2D;
+
+export function resolveEntityId(entity: EntityLike): EntityId {
+  return typeof entity === 'number' ? entity : entity.entityId;
+}
+
+export class HierarchyCoordinator<Kind extends '2d' | '3d' = '2d' | '3d'> {
+  private readonly _dependentsByTarget = new Map<EntityId, Set<EntityId>>();
+
+  constructor(
+    private readonly _world: EcsWorld,
+    private readonly _dimension: Kind
+  ) {}
+
+  /**
+   * Attaches an origin entity to a target reference entity with an optional constraint.
+   * Rejects self-anchoring and cycles proactively.
+   *
+   * @param origin The dependent entity to anchor.
+   * @param target The target entity to follow.
+   * @param constraint Optional strategy name ('static', 'translation') or in-place zero-GC callback.
+   */
+  attach(
+    origin: EntityLike,
+    target: EntityLike,
+    constraint?: Kind extends '3d' ? AnchorConstraint3D : AnchorConstraint2D
+  ): void {
+    const originId = resolveEntityId(origin);
+    const targetId = resolveEntityId(target);
+
+    if (originId === targetId) {
+      throw new Error(`Anchor error: Entity ${originId} cannot anchor to itself.`);
+    }
+
+    if (!this._world.isAlive(originId) || !this._world.isAlive(targetId)) {
+      throw new Error(
+        `Anchor error: Both origin (${originId}) and target (${targetId}) must be alive.`
+      );
+    }
+
+    // Proactive cycle detection
+    let curr: EntityId | undefined = targetId;
+    while (curr !== undefined) {
+      if (curr === originId) {
+        throw new Error(
+          `Anchor cycle detected: cannot attach entity ${originId} to ${targetId} as it forms a cycle.`
+        );
+      }
+      curr = this.getTarget(curr);
+    }
+
+    // Disconnect previous target from reverse index if re-anchoring
+    const prevTarget = this.getTarget(originId);
+    if (prevTarget !== undefined) {
+      this._dependentsByTarget.get(prevTarget)?.delete(originId);
+    }
+
+    let strategy = 'static';
+    let callback2d: AnchorConstraintCallback2D | undefined;
+    let callback3d: AnchorConstraintCallback3D | undefined;
+
+    if (typeof constraint === 'string') {
+      strategy = constraint;
+    } else if (typeof constraint === 'function') {
+      if (this._dimension === '3d') {
+        callback3d = constraint as AnchorConstraintCallback3D;
+      } else {
+        callback2d = constraint as AnchorConstraintCallback2D;
+      }
+    }
+
+    this._world.attachComponent(
+      originId,
+      createAnchor({
+        targetEntityId: targetId,
+        strategy,
+        callback2d,
+        callback3d
+      })
+    );
+
+    // Register in reverse index
+    let set = this._dependentsByTarget.get(targetId);
+    if (!set) {
+      set = new Set<EntityId>();
+      this._dependentsByTarget.set(targetId, set);
+    }
+    set.add(originId);
+
+    // Invalidate origin spatial state immediately
+    this._invalidateOrigin(originId);
+  }
+
+  /**
+   * Detaches an origin entity from its target anchor.
+   *
+   * @param origin The entity to detach.
+   * @param preserveWorldTransform When true (default), converts the last resolved worldMatrix
+   * into the entity's independent localMatrix so it does not pop back to the origin.
+   */
+  detach(origin: EntityLike, preserveWorldTransform = true): void {
+    const originId = resolveEntityId(origin);
+    const targetId = this.getTarget(originId);
+
+    if (targetId !== undefined) {
+      this._dependentsByTarget.get(targetId)?.delete(originId);
+    }
+
+    if (preserveWorldTransform) {
+      const model3d = this._world.getComponent<Model3DComponent>(originId, 'Model3D');
+      if (model3d) {
+        mat4.copy(model3d.localMatrix, model3d.worldMatrix);
+        model3d.flags |= SpatialDirtyFlags.LocalDirty;
+      }
+      const model2d = this._world.getComponent<Model2DComponent>(originId, 'Model2D');
+      if (model2d) {
+        mat2d.copy(model2d.localMatrix, model2d.worldMatrix);
+        model2d.flags |= SpatialDirtyFlags.LocalDirty;
+      }
+    }
+
+    this._world.detachComponent(originId, 'Anchor');
+  }
+
+  /**
+   * Checks whether an origin entity is currently attached to a target.
+   */
+  isAttached(origin: EntityLike): boolean {
+    const originId = resolveEntityId(origin);
+    return this._world.hasComponent(originId, 'Anchor');
+  }
+
+  /**
+   * Returns the target EntityId if attached, or undefined.
+   */
+  getTarget(origin: EntityLike): EntityId | undefined {
+    const originId = resolveEntityId(origin);
+    const anchor = this._world.getComponent<AnchorComponent>(originId, 'Anchor');
+    return anchor?.targetEntityId;
+  }
+
+  /**
+   * Returns all dependent entity IDs anchored to the given target entity in O(1) time.
+   */
+  getDependents(target: EntityLike): EntityId[] {
+    const targetId = resolveEntityId(target);
+    const set = this._dependentsByTarget.get(targetId);
+    return set ? Array.from(set) : [];
+  }
+
+  /**
+   * Cleans up all dependent relationships when a target entity is destroyed,
+   * safely detaching them and preserving their world transforms.
+   */
+  handleTargetDestroyed(target: EntityLike): void {
+    const targetId = resolveEntityId(target);
+    const dependents = this.getDependents(targetId);
+    for (const depId of dependents) {
+      this.detach(depId, true);
+    }
+    this._dependentsByTarget.delete(targetId);
+  }
+
+  private _invalidateOrigin(originId: EntityId): void {
+    const model3d = this._world.getComponent<Model3DComponent>(originId, 'Model3D');
+    if (model3d) {
+      model3d.flags |= SpatialDirtyFlags.LocalDirty;
+    }
+    const model2d = this._world.getComponent<Model2DComponent>(originId, 'Model2D');
+    if (model2d) {
+      model2d.flags |= SpatialDirtyFlags.LocalDirty;
+    }
+  }
+}