lecodes-sdk 0.20.0 → 1.0.0

package/dist/inject.js

@@ -1235,6 +1235,88 @@ var Color = {
   }
 };
 
+// src/core/events.ts
+var Emitter = class {
+  _listeners = {};
+  addEventListener(channel, callback) {
+    const list = this._listeners[channel];
+    if (list) list.push(callback);
+    else this._listeners[channel] = [callback];
+  }
+  removeEventListener(channel, callback) {
+    const list = this._listeners[channel];
+    if (!list) return;
+    const i = list.indexOf(callback);
+    if (i >= 0) list.splice(i, 1);
+  }
+  /** Fire all listeners on a channel. Protected: only the owning class emits. */
+  dispatch(channel, ...args) {
+    const list = this._listeners[channel];
+    if (!list) return;
+    for (const fn of list.slice()) fn(...args);
+  }
+  hasListeners(channel) {
+    const list = this._listeners[channel];
+    return !!list && list.length > 0;
+  }
+  /** Drop every listener on every channel (used when the owning object is disposed). */
+  clearListeners() {
+    this._listeners = {};
+  }
+};
+
+// src/core/Aspect.ts
+var AspectHost = class extends Emitter {
+  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  _aspects = /* @__PURE__ */ new Map();
+  /** Attach (and configure) an aspect, or reconfigure it if already present. Returns the node typed
+   *  as now-having that aspect (so no guard/`?.` is needed afterwards). Rejects a wrong target node. */
+  aspect(ctor, opts) {
+    const host = this;
+    let inst = host._aspects.get(ctor);
+    const fresh = inst === void 0;
+    if (!inst) {
+      inst = new ctor();
+      inst.node = this;
+      host._aspects.set(ctor, inst);
+      const name = ctor.aspect;
+      if (name) host[name] = inst;
+    }
+    if (opts) Object.assign(inst, opts);
+    if (fresh) inst.onAttach?.();
+    return this;
+  }
+  /** Safe access — undefined if the aspect isn't attached. */
+  get(ctor) {
+    return this._aspects.get(ctor);
+  }
+  /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
+  has(ctor) {
+    return this._aspects.has(ctor);
+  }
+  /** Detach an aspect (runs its onDetach). Named `removeAspect` so it never collides with the
+   *  child-management `add`/`remove` semantics some node kinds expose. */
+  removeAspect(ctor) {
+    const inst = this._aspects.get(ctor);
+    if (inst) {
+      inst.onDetach?.();
+      this._aspects.delete(ctor);
+      const name = ctor.aspect;
+      if (name) delete this[name];
+    }
+    return this;
+  }
+};
+var Aspect = class {
+  // NOTE: P has no `extends AspectHost` constraint on purpose — Emitter<E>'s generic
+  // addEventListener makes a specific-event node (AspectHost<NodeEvents>) not assignable to
+  // AspectHost<any>, which would reject every real node. P only types `this.node`; target
+  // enforcement happens in aspect() via `this: Self extends TargetOf<A>`. Defaults to Node
+  // (3D is the default engine) — a 2D aspect declares its own P, e.g. Aspect<'x', Sprite>.
+  /** The node this aspect is attached to (set at attach time). */
+  node;
+};
+
 // src/runtime/misc.ts
 var toast = (msg) => _creatorUI.toast(msg);
 var SvgSource = (svg) => ({ svg, tintColor: null });
@@ -1336,36 +1418,6 @@ var Input = {
   }
 };
 
-// src/core/events.ts
-var Emitter = class {
-  _listeners = {};
-  addEventListener(channel, callback) {
-    const list = this._listeners[channel];
-    if (list) list.push(callback);
-    else this._listeners[channel] = [callback];
-  }
-  removeEventListener(channel, callback) {
-    const list = this._listeners[channel];
-    if (!list) return;
-    const i = list.indexOf(callback);
-    if (i >= 0) list.splice(i, 1);
-  }
-  /** Fire all listeners on a channel. Protected: only the owning class emits. */
-  dispatch(channel, ...args) {
-    const list = this._listeners[channel];
-    if (!list) return;
-    for (const fn of list.slice()) fn(...args);
-  }
-  hasListeners(channel) {
-    const list = this._listeners[channel];
-    return !!list && list.length > 0;
-  }
-  /** Drop every listener on every channel (used when the owning object is disposed). */
-  clearListeners() {
-    this._listeners = {};
-  }
-};
-
 // src/runtime/net.ts
 var WebSocket = class extends Emitter {
   _id = null;
@@ -1585,7 +1637,7 @@ var Registry = class {
 
 // src/g2/Node2D.ts
 var node2dRegistry = new Registry();
-var Node2D = class extends Emitter {
+var Node2D = class extends AspectHost {
   /** Native entity handle. */
   id;
   _x = 0;
@@ -1665,17 +1717,15 @@ var Node2D = class extends Emitter {
     this._visible = v;
     _creator2d.setVisible(this.id, v);
   }
-  /**
-   * Attach a collider for overlap detection. DEFERRED: native 2D physics/triggers are not built yet,
-   * so this records intent and is a no-op until the engine lands — the 'enter'/'exit' events won't
-   * fire. The API is here so game code that uses it compiles and stays stable.
-   */
-  collider(_options = {}) {
-    return this;
-  }
-  /** @internal — overridden by Sprite to translate native clip ids into named animation events. */
+  /** @internal — host animation events route here by id; the SpriteAnimation aspect installs an
+   *  instance override that translates clip ids to names and emits 'loopReached' / 'completed'. */
   _dispatchAnimEvent(_clipId, _type) {
   }
+  /** @internal — emit a translated animation event (the SpriteAnimation aspect can't reach the
+   *  protected dispatch directly). */
+  _emitAnim(channel, clip) {
+    this.dispatch(channel, clip);
+  }
   destroy() {
     node2dRegistry.delete(this.id);
     _creator2d.destroyEntity(this.id);
@@ -1837,9 +1887,6 @@ var Sprite = class extends Node2D {
   _flipX = false;
   _flipY = false;
   _size = null;
-  _clipIds = {};
-  _clipNames = {};
-  _current = null;
   constructor(options = {}) {
     super();
     if (options.texture) this.texture = options.texture;
@@ -1913,71 +1960,94 @@ var Sprite = class extends Node2D {
     this._flipY = v;
     _creator2d.setSpriteFlip(this.id, this._flipX, v);
   }
-  // --- animation (chainable) ---
-  /**
-   * Define named sprite-sheet clips from a uniform grid. Frame indices are row-major into the grid.
-   * Sets the sprite's display size to one cell. Once defined, clips advance entirely in native code.
-   */
-  clips(def) {
-    const tex = this._texture;
-    if (!tex) throw new Error("Sprite.clips(): set a texture before defining clips");
-    const [fw, fh] = def.size;
-    const defFps = typeof def.fps === "number" ? def.fps : 12;
-    const defLoop = typeof def.loop === "boolean" ? def.loop : true;
+};
+
+// src/g2/SpriteAnimation.ts
+var SpriteAnimation = class extends Aspect {
+  static aspect = "anim";
+  /** Grid cell size in texture pixels (defaults to the full texture). */
+  size;
+  /** Default fps for clips that don't override it. */
+  fps = 12;
+  /** Default loop for clips that don't override it. */
+  loop = true;
+  /** Named clips; frame indices are row-major into the grid. Set via the attach opts. */
+  clips = {};
+  _clipIds = {};
+  _clipNames = {};
+  _current = null;
+  onAttach() {
+    this._define();
+    this.node._dispatchAnimEvent = (clipId, type) => this.node._emitAnim(type === 1 ? "completed" : "loopReached", this._clipNames[clipId] ?? "");
+    ensureAnimEvents();
+  }
+  /** (Re)build native clips from `this.clips`. Called on attach; call again after changing clips. */
+  define() {
+    this._define();
+    return this;
+  }
+  _define() {
+    const node = this.node;
+    const tex = node.texture;
+    if (!tex) throw new Error("SpriteAnimation: set a texture on the Sprite before adding the aspect");
+    const [fw, fh] = this.size ?? [tex.width, tex.height];
     const cols = Math.max(1, Math.floor(tex.width / fw));
-    for (const name of Object.keys(def)) {
-      if (name === "size" || name === "fps" || name === "loop") continue;
-      const value = def[name];
+    for (const name of Object.keys(this.clips)) {
+      const value = this.clips[name];
       const indices = Array.isArray(value) ? value : value.frames;
-      const fps = Array.isArray(value) ? defFps : value.fps ?? defFps;
-      const loop = Array.isArray(value) ? defLoop : value.loop ?? defLoop;
+      const fps = Array.isArray(value) ? this.fps : value.fps ?? this.fps;
+      const loop = Array.isArray(value) ? this.loop : value.loop ?? this.loop;
       const frames = new Float32Array(indices.length * 4);
       indices.forEach((idx, i) => {
-        const cx2 = idx % cols * fw;
-        const cy2 = Math.floor(idx / cols) * fh;
-        frames[i * 4 + 0] = cx2 / tex.width;
-        frames[i * 4 + 1] = cy2 / tex.height;
-        frames[i * 4 + 2] = (cx2 + fw) / tex.width;
-        frames[i * 4 + 3] = (cy2 + fh) / tex.height;
+        const px = idx % cols * fw;
+        const py = Math.floor(idx / cols) * fh;
+        frames[i * 4 + 0] = px / tex.width;
+        frames[i * 4 + 1] = py / tex.height;
+        frames[i * 4 + 2] = (px + fw) / tex.width;
+        frames[i * 4 + 3] = (py + fh) / tex.height;
       });
-      const clipId = _creator2d.defineAnimation(this.id, frames, fps, loop);
+      const clipId = _creator2d.defineAnimation(node.id, frames, fps, loop);
       this._clipIds[name] = clipId;
       this._clipNames[clipId] = name;
     }
-    if (!this._size) _creator2d.setSpriteSize(this.id, fw, fh);
-    ensureAnimEvents();
-    return this;
+    if (this.size) _creator2d.setSpriteSize(node.id, fw, fh);
   }
   /** Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly). */
   play(name) {
     const id = this._clipIds[name];
-    if (id === void 0) throw new Error(`Sprite.play(): unknown clip "${name}"`);
+    if (id === void 0) throw new Error(`SpriteAnimation.play(): unknown clip "${name}"`);
     if (this._current === name) return this;
     this._current = name;
-    _creator2d.playAnimation(this.id, id);
+    _creator2d.playAnimation(this.node.id, id);
     return this;
   }
   stop() {
     this._current = null;
-    _creator2d.stopAnimation(this.id);
+    _creator2d.stopAnimation(this.node.id);
     return this;
   }
-  set animationSpeed(value) {
-    _creator2d.setAnimationSpeed(this.id, value);
+  set speed(value) {
+    _creator2d.setAnimationSpeed(this.node.id, value);
   }
-  get currentClip() {
+  get current() {
     return this._current;
   }
-  get animationFrame() {
-    return _creator2d.getAnimationFrame(this.id);
-  }
-  /** @internal — translate a native clip id back to its name and emit the animation event. */
-  _dispatchAnimEvent(clipId, type) {
-    const name = this._clipNames[clipId] ?? "";
-    this.dispatch(type === 1 ? "completed" : "loopReached", name);
+  get frame() {
+    return _creator2d.getAnimationFrame(this.node.id);
   }
 };
 
+// src/g2/Collider2D.ts
+var Collider2D = class extends Aspect {
+  static aspect = "collider";
+  /** Box half-extents (world units). Defaults to the sprite size when omitted. */
+  box;
+  /** Center offset from the node. */
+  offset;
+  /** Report overlaps via the node's 'enter'/'exit' events instead of blocking (always true for now). */
+  trigger = true;
+};
+
 // src/g2/Tilemap.ts
 var Tilemap = class extends Node2D {
   cols;
@@ -3156,82 +3226,6 @@ var QRScanner = class _QRScanner {
   }
 };
 
-// src/gl/Body.ts
-var MOTION = { static: 0, kinematic: 1, dynamic: 2 };
-var Body = class {
-  _bodyId = 0;
-  _motion;
-  constructor(node, options = {}) {
-    this._motion = options.motion ?? "dynamic";
-    const mass = options.mass ?? 1;
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return;
-    const motion = MOTION[this._motion];
-    const shape = resolveShape(node, options.shape ?? { type: "auto" });
-    if (shape.type === "sphere") {
-      this._bodyId = _creator.physicsCreateSphere(node.id, shape.radius, motion, mass);
-    } else if (shape.type === "cylinder") {
-      this._bodyId = _creator.physicsCreateCylinder(node.id, shape.halfHeight, shape.radius, motion, mass);
-    } else {
-      this._bodyId = _creator.physicsCreateBox(node.id, cx(shape.halfExtents), cy(shape.halfExtents), cz(shape.halfExtents), motion, mass);
-    }
-  }
-  /** Native Jolt body id. 0 until assigned, or if the build has no physics support. */
-  get id() {
-    return this._bodyId;
-  }
-  get motion() {
-    return this._motion;
-  }
-  /** Linear velocity in world units/second (fresh Vec3 on read). */
-  get velocity() {
-    const out = new Float32Array(3);
-    if (this._bodyId) _creator.physicsGetLinearVelocity(this._bodyId, out);
-    return new Vec3(out[0], out[1], out[2]);
-  }
-  set velocity(v) {
-    if (this._bodyId) _creator.physicsSetLinearVelocity(this._bodyId, cx(v), cy(v), cz(v));
-  }
-  /** Apply an instantaneous impulse (kg·m/s) and wake the body. */
-  applyImpulse(v) {
-    if (this._bodyId) _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v));
-    return this;
-  }
-  /** Teleport / drive a kinematic (or dynamic) body to a world position. */
-  moveTo(p) {
-    if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p));
-    return this;
-  }
-  /** Remove the body from the simulation. */
-  remove() {
-    if (this._bodyId) {
-      _creator.physicsRemoveBody(this._bodyId);
-      this._bodyId = 0;
-    }
-  }
-};
-var resolveShape = (node, shape) => {
-  if (shape.type !== "auto") return shape;
-  const scale = node.worldScale;
-  let hx = 0.5, hy = 0.5, hz = 0.5;
-  const geom = node.geometry;
-  if (geom) {
-    const v = geom.vertices;
-    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
-    for (let i = 0; i + 2 < v.length; i += 3) {
-      if (v[i] < minX) minX = v[i];
-      if (v[i] > maxX) maxX = v[i];
-      if (v[i + 1] < minY) minY = v[i + 1];
-      if (v[i + 1] > maxY) maxY = v[i + 1];
-      if (v[i + 2] < minZ) minZ = v[i + 2];
-      if (v[i + 2] > maxZ) maxZ = v[i + 2];
-    }
-    hx = (maxX - minX) * 0.5;
-    hy = (maxY - minY) * 0.5;
-    hz = (maxZ - minZ) * 0.5;
-  }
-  return { type: "box", halfExtents: [hx * scale.x, hy * scale.y, hz * scale.z] };
-};
-
 // src/gl/state.ts
 var glState = { activeScene: null };
 
@@ -3285,17 +3279,9 @@ var registerTouchEndEvent = () => {
 
 // src/gl/Node.ts
 var nodeRegistry = new Registry();
-var animatorRegistered = false;
-var ensureAnimator = () => {
-  if (animatorRegistered) return;
-  animatorRegistered = true;
-  _creator.setOnAnimationComplete((entityId, clipIndex) => nodeRegistry.get(entityId)?._onAnimationComplete(clipIndex) ?? true);
-};
-var Node = class _Node extends Emitter {
+var Node = class _Node extends AspectHost {
   /** Native entity handle. */
   id;
-  /** Physics handle once .physics() is called. */
-  body;
   /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
    *  'track' / 'untrack' events; `false` for any non-anchor node. */
   isTracked = false;
@@ -3303,10 +3289,8 @@ var Node = class _Node extends Emitter {
   _lastSync = 0;
   _worldMatrix;
   _scaleCache;
-  _animPlaying = false;
-  _animClip = 0;
-  _animSpeed = 1;
-  _animLoop = false;
+  /** @internal — the active animation aspect's clip-complete handler (installed by ModelAnimation). */
+  _animComplete;
   constructor(internalId) {
     super();
     this.id = internalId ?? _creator.createEntity();
@@ -3476,24 +3460,7 @@ var Node = class _Node extends Emitter {
     callback(this);
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new _Node(id)));
   }
-  // --- behaviors ---
-  /** Add a physics body (reach it at node.body). Chainable. */
-  physics(options = {}) {
-    this.body = new Body(this, options);
-    return this;
-  }
-  /** Add a collider for click/touch hit-testing. Derives from the mesh by default. Chainable. */
-  collider(options = {}) {
-    const form = options.shape ?? "box";
-    if (form === "box" && options.center && options.size) {
-      _creator.setColliderBox(this.id, cx(options.center), cy(options.center), cz(options.center), cx(options.size), cy(options.size), cz(options.size));
-    } else if (form === "sphere" && options.center && options.radius !== void 0) {
-      _creator.setColliderSphere(this.id, cx(options.center), cy(options.center), cz(options.center), options.radius);
-    } else {
-      _creator.setColliderFromMesh(this.id, this.id, form === "sphere" ? 1 : 0);
-    }
-    return this;
-  }
+  // --- behaviors are aspects: node.aspect(Physics, …) / node.aspect(Collider, …) ---
   /** Orient the node so the given axis (default "-z", "forward") points at a world point. */
   lookAt(point, mode = "-z", ortho = [0, 1, 0]) {
     const world = this.worldMatrix;
@@ -3542,52 +3509,6 @@ var Node = class _Node extends Emitter {
     );
     return this;
   }
-  // --- GLB animation (no-op until a GLB is loaded as this node) ---
-  get clips() {
-    return _creator.getGlbAnimations(this.id);
-  }
-  get animationPlaying() {
-    return this._animPlaying;
-  }
-  set animationPlaying(value) {
-    this._animPlaying = value;
-    _creator.setAnimation(this.id, value, this._animClip, this._animSpeed);
-  }
-  /** Play a GLB clip by name or index. Chainable. */
-  play(clip, options = {}) {
-    if (typeof clip === "number") this._animClip = clip;
-    else if (typeof clip === "string") {
-      const i = this.clips.findIndex((c2) => c2.name === clip);
-      if (i >= 0) this._animClip = i;
-    }
-    if (options.loop !== void 0) this._animLoop = options.loop;
-    this.animationPlaying = true;
-    ensureAnimator();
-    return this;
-  }
-  stop() {
-    this.animationPlaying = false;
-    return this;
-  }
-  get animationLoop() {
-    return this._animLoop;
-  }
-  set animationLoop(v) {
-    this._animLoop = v;
-  }
-  get animationSpeed() {
-    return this._animSpeed;
-  }
-  set animationSpeed(v) {
-    this._animSpeed = v;
-    _creator.setAnimation(this.id, this._animPlaying, this._animClip, v);
-  }
-  get animationTime() {
-    return _creator.getAnimationTime(this.id);
-  }
-  set animationTime(v) {
-    _creator.setAnimationTime(this.id, this._animClip, v);
-  }
   // --- events ---
   addEventListener(channel, callback) {
     if (channel === "click") registerTouchEndEvent();
@@ -3598,14 +3519,14 @@ var Node = class _Node extends Emitter {
   _dispatchEvent(channel, ...args) {
     this.dispatch(channel, ...args);
   }
-  /** @internal — host animation-complete callback; returns whether the clip should keep playing. */
+  /** @internal — host animation-complete callback; forwards to the ModelAnimation aspect (if any).
+   *  Returns whether the clip should keep playing. */
   _onAnimationComplete(clipIndex) {
-    if (clipIndex !== this._animClip) return true;
-    if (!this._animLoop) {
-      this._animPlaying = false;
-      this.dispatch("completed", clipIndex);
-    } else this.dispatch("loopReached", clipIndex);
-    return this._animPlaying;
+    return this._animComplete?.(clipIndex) ?? true;
+  }
+  /** @internal — emit a GLB animation event (the ModelAnimation aspect can't reach protected dispatch). */
+  _emitAnim(channel, clip) {
+    this.dispatch(channel, clip);
   }
   destroy() {
     nodeRegistry.delete(this.id);
@@ -4166,10 +4087,10 @@ var createPlane = (options = {}) => {
   let upVector, rightVec;
   if (normal[1] === 0 && normal[2] === 0) {
     upVector = [0, 1, 0];
-    rightVec = [0, 0, normal[0]];
+    rightVec = [0, 0, -normal[0]];
   } else if (normal[0] === 0 && normal[2] === 0) {
     upVector = [0, 0, 1];
-    rightVec = [normal[1], 0, 0];
+    rightVec = [-normal[1], 0, 0];
   } else if (normal[0] === 0 && normal[1] === 0) {
     upVector = [0, 1, 0];
     rightVec = [normal[2], 0, 0];
@@ -4259,15 +4180,101 @@ var Mesh = class _Mesh extends Node {
   static from(geometry, options = {}) {
     return apply(new _Mesh(geometry, options.material), options);
   }
-  /**
-   * Load a GLB model. Returns the model's root Node (a GLB is a node hierarchy); its animation clips
-   * are available via node.clips and driven with node.play(name|index).
-   */
+};
+var sizeToVec = (s) => typeof s === "number" ? [s, s, s] : [cx(s), cy(s), cz(s)];
+var apply = (mesh, o) => {
+  if (o.position) mesh.position = o.position;
+  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles;
+  if (o.scale !== void 0) mesh.scale = typeof o.scale === "number" ? [o.scale, o.scale, o.scale] : o.scale;
+  if (o.name !== void 0) mesh.name = o.name;
+  if (o.castShadows !== void 0) mesh.castShadows = o.castShadows;
+  if (o.receiveShadows !== void 0) mesh.receiveShadows = o.receiveShadows;
+  return mesh;
+};
+
+// src/gl/ModelAnimation.ts
+var animatorRegistered = false;
+var ensureAnimator = () => {
+  if (animatorRegistered) return;
+  animatorRegistered = true;
+  _creator.setOnAnimationComplete((entityId, clipIndex) => nodeRegistry.get(entityId)?._onAnimationComplete(clipIndex) ?? true);
+};
+var ModelAnimation = class extends Aspect {
+  static aspect = "anim";
+  _playing = false;
+  _clip = 0;
+  _speed = 1;
+  _loop = false;
+  onAttach() {
+    this.node._animComplete = (clipIndex) => {
+      if (clipIndex !== this._clip) return true;
+      if (!this._loop) {
+        this._playing = false;
+        this.node._emitAnim("completed", clipIndex);
+      } else this.node._emitAnim("loopReached", clipIndex);
+      return this._playing;
+    };
+  }
+  /** The clips baked into the glb. */
+  get clips() {
+    return _creator.getGlbAnimations(this.node.id);
+  }
+  get playing() {
+    return this._playing;
+  }
+  set playing(value) {
+    this._playing = value;
+    _creator.setAnimation(this.node.id, value, this._clip, this._speed);
+  }
+  /** Play a clip by name or index. Chainable. */
+  play(clip, options = {}) {
+    if (typeof clip === "number") this._clip = clip;
+    else if (typeof clip === "string") {
+      const i = this.clips.findIndex((c2) => c2.name === clip);
+      if (i >= 0) this._clip = i;
+    }
+    if (options.loop !== void 0) this._loop = options.loop;
+    this.playing = true;
+    ensureAnimator();
+    return this;
+  }
+  stop() {
+    this.playing = false;
+    return this;
+  }
+  get loop() {
+    return this._loop;
+  }
+  set loop(v) {
+    this._loop = v;
+  }
+  get speed() {
+    return this._speed;
+  }
+  set speed(v) {
+    this._speed = v;
+    _creator.setAnimation(this.node.id, this._playing, this._clip, v);
+  }
+  get time() {
+    return _creator.getAnimationTime(this.node.id);
+  }
+  set time(v) {
+    _creator.setAnimationTime(this.node.id, this._clip, v);
+  }
+};
+
+// src/gl/Model.ts
+var Model = class _Model extends Node {
+  constructor(internalId) {
+    super(internalId);
+    this.aspect(ModelAnimation);
+  }
+  /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
   static load(source, options = {}) {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true, onProgress: options.onProgress }).then((resp) => {
         if (resp.status >= 400) return Promise.reject(new Error(`Failed to load GLB from ${source}. HTTP ${resp.status}`));
-        return _Mesh.load(resp, options);
+        return _Model.load(resp, options);
       });
     }
     return new Promise((resolve, reject) => {
@@ -4276,22 +4283,109 @@ var Mesh = class _Mesh extends Node {
           reject(new Error("Failed to load GLB"));
           return;
         }
-        const node = new Node(entityId);
+        const model = new _Model(entityId);
         if (options.culling !== true) _creator.setGlbCulling(entityId, false);
-        resolve(node);
+        resolve(model);
       }, reject);
     });
   }
 };
-var sizeToVec = (s) => typeof s === "number" ? [s, s, s] : [cx(s), cy(s), cz(s)];
-var apply = (mesh, o) => {
-  if (o.position) mesh.position = o.position;
-  if (o.eulerAngles) mesh.eulerAngles = o.eulerAngles;
-  if (o.scale !== void 0) mesh.scale = typeof o.scale === "number" ? [o.scale, o.scale, o.scale] : o.scale;
-  if (o.name !== void 0) mesh.name = o.name;
-  if (o.castShadows !== void 0) mesh.castShadows = o.castShadows;
-  if (o.receiveShadows !== void 0) mesh.receiveShadows = o.receiveShadows;
-  return mesh;
+
+// src/gl/Physics.ts
+var MOTION = { static: 0, kinematic: 1, dynamic: 2 };
+var Physics = class extends Aspect {
+  static aspect = "physics";
+  /** Default "dynamic". */
+  motion = "dynamic";
+  /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
+  mass = 1;
+  /** Default { type: "auto" } — a box from the mesh AABB × world scale. */
+  shape = { type: "auto" };
+  _bodyId = 0;
+  onAttach() {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return;
+    const motion = MOTION[this.motion];
+    const shape = resolveShape(this.node, this.shape);
+    if (shape.type === "sphere") {
+      this._bodyId = _creator.physicsCreateSphere(this.node.id, shape.radius, motion, this.mass);
+    } else if (shape.type === "cylinder") {
+      this._bodyId = _creator.physicsCreateCylinder(this.node.id, shape.halfHeight, shape.radius, motion, this.mass);
+    } else {
+      this._bodyId = _creator.physicsCreateBox(this.node.id, cx(shape.halfExtents), cy(shape.halfExtents), cz(shape.halfExtents), motion, this.mass);
+    }
+  }
+  /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
+  get id() {
+    return this._bodyId;
+  }
+  /** Linear velocity in world units/second (fresh Vec3 on read). */
+  get velocity() {
+    const out = new Float32Array(3);
+    if (this._bodyId) _creator.physicsGetLinearVelocity(this._bodyId, out);
+    return new Vec3(out[0], out[1], out[2]);
+  }
+  set velocity(v) {
+    if (this._bodyId) _creator.physicsSetLinearVelocity(this._bodyId, cx(v), cy(v), cz(v));
+  }
+  /** Apply an instantaneous impulse (kg·m/s) and wake the body. */
+  applyImpulse(v) {
+    if (this._bodyId) _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v));
+    return this;
+  }
+  /** Teleport / drive a kinematic (or dynamic) body to a world position. */
+  moveTo(p) {
+    if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p));
+    return this;
+  }
+  onDetach() {
+    if (this._bodyId) {
+      _creator.physicsRemoveBody(this._bodyId);
+      this._bodyId = 0;
+    }
+  }
+};
+var resolveShape = (node, shape) => {
+  if (shape.type !== "auto") return shape;
+  const scale = node.worldScale;
+  let hx = 0.5, hy = 0.5, hz = 0.5;
+  const geom = node.geometry;
+  if (geom) {
+    const v = geom.vertices;
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    for (let i = 0; i + 2 < v.length; i += 3) {
+      if (v[i] < minX) minX = v[i];
+      if (v[i] > maxX) maxX = v[i];
+      if (v[i + 1] < minY) minY = v[i + 1];
+      if (v[i + 1] > maxY) maxY = v[i + 1];
+      if (v[i + 2] < minZ) minZ = v[i + 2];
+      if (v[i + 2] > maxZ) maxZ = v[i + 2];
+    }
+    hx = (maxX - minX) * 0.5;
+    hy = (maxY - minY) * 0.5;
+    hz = (maxZ - minZ) * 0.5;
+  }
+  return { type: "box", halfExtents: [hx * scale.x, hy * scale.y, hz * scale.z] };
+};
+
+// src/gl/Collider.ts
+var Collider = class extends Aspect {
+  static aspect = "collider";
+  shape = "box";
+  /** Explicit box: center + full size. */
+  center;
+  size;
+  /** Explicit sphere: center + radius. */
+  radius;
+  onAttach() {
+    const id = this.node.id;
+    if (this.shape === "box" && this.center && this.size) {
+      _creator.setColliderBox(id, cx(this.center), cy(this.center), cz(this.center), cx(this.size), cy(this.size), cz(this.size));
+    } else if (this.shape === "sphere" && this.center && this.radius !== void 0) {
+      _creator.setColliderSphere(id, cx(this.center), cy(this.center), cz(this.center), this.radius);
+    } else {
+      _creator.setColliderFromMesh(id, id, this.shape === "sphere" ? 1 : 0);
+    }
+  }
 };
 
 // src/gl/Light.ts
@@ -4560,9 +4654,12 @@ var dynamic = (baseValue, type, ...args) => {
 };
 export {
   ARScene,
+  Aspect,
   AudioPlayer,
   Camera,
   ClickEvent,
+  Collider,
+  Collider2D,
   Color,
   File,
   FormData,
@@ -4573,10 +4670,13 @@ export {
   Material,
   Mathf,
   Mesh,
+  Model,
+  ModelAnimation,
   Node,
   Node2D,
   Noise,
   Particles,
+  Physics,
   Plane,
   QRScanner,
   Quat,
@@ -4585,6 +4685,7 @@ export {
   Scene,
   Scene2D,
   Sprite,
+  SpriteAnimation,
   SvgSource,
   Texture,
   Texture2D,