lecodes-cli 0.1.7 → 0.3.0

package/runtime/sdk/g2/touch.ts

@@ -0,0 +1,83 @@
+// 2D pointer dispatch + track (drag) system. The host (createViewer2d canvas / Creator2DView) delivers
+// raw pointer phases via _creator2d.setOnPointer; this module hit-tests in the active scene and routes
+// to the struck node and the scene's listeners. Mirrors the 3D gl/touch.ts, but the hit-test is done
+// here (screen→world via the camera, then a physics overlap), not by the host.
+//
+// What can be hit: a node with a Physics2D shape (precise) → its 'touchstart'/'click' events; the
+// active Scene2D always gets the event too (target = the hit node or null). A node listener can call
+// ev.track({ onMove, onEnd, onCancel }) to capture the rest of the gesture (drag/pan).
+
+import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch"
+import { Physics2D } from "./Physics2D"
+import { Scene2D } from "./Scene2D"
+import type { Node2D } from "./Node2D"
+
+type Active = { tracker?: TrackHandler, lastX: number, lastY: number }
+const active = new Map<number, Active>()
+
+let registered = false
+/** Register the host pointer callback once, on the first click/touchstart listener (node or scene). */
+export const ensurePointerEvents = (): void => {
+  if (registered) return
+  registered = true
+  _creator2d.setOnPointer((phase, id, x, y) => {
+    if (phase === 0) onDown(id, x, y)
+    else if (phase === 1) onMove(id, x, y)
+    else if (phase === 2) onUp(id, x, y)
+    else onCancel(id)
+  })
+}
+
+// Hit-test: screen (logical px) → world → topmost physics body at the point.
+const hitTest = (scene: Scene2D, sx: number, sy: number): { node: Node2D | null, wx: number, wy: number } => {
+  const w = scene.camera.screenToWorld(sx, sy)
+  return { node: Physics2D.overlapPoint(w), wx: w.x, wy: w.y }
+}
+
+const onDown = (id: number, sx: number, sy: number): void => {
+  const scene = Scene2D.active
+  if (!scene) return
+  const { node, wx, wy } = hitTest(scene, sx, sy)
+  const ev = new TouchStartEvent<Node2D | null>(sx, sy, id)
+  ev.worldX = wx; ev.worldY = wy
+  ev.target = node
+
+  let tracker: TrackHandler | undefined
+  if (node) { node._dispatchEvent("touchstart", ev); tracker = ev._trackHandler }
+  if (!tracker) {
+    for (const l of scene._touchStartListeners.slice()) {
+      l(ev)
+      if (ev._trackHandler) { tracker = ev._trackHandler; break }
+    }
+  }
+  active.set(id, { tracker, lastX: sx, lastY: sy })
+}
+
+const onMove = (id: number, sx: number, sy: number): void => {
+  const a = active.get(id)
+  if (!a) return
+  a.tracker?.onMove?.({ clientX: sx, clientY: sy, deltaX: sx - a.lastX, deltaY: sy - a.lastY })
+  a.lastX = sx; a.lastY = sy
+}
+
+const onUp = (id: number, sx: number, sy: number): void => {
+  const a = active.get(id)
+  active.delete(id)
+  a?.tracker?.onEnd?.({ clientX: sx, clientY: sy, deltaX: a ? sx - a.lastX : 0, deltaY: a ? sy - a.lastY : 0 })
+
+  // A pointer-up is also a click, dispatched at the up location (independent of any track).
+  const scene = Scene2D.active
+  if (!scene) return
+  const { node, wx, wy } = hitTest(scene, sx, sy)
+  const ev = new ClickEvent<Node2D | null>(sx, sy, id)
+  ev.worldX = wx; ev.worldY = wy
+  ev.target = node
+  if (node) node._dispatchEvent("click", ev)
+  for (const l of scene._clickListeners.slice()) l(ev)
+}
+
+const onCancel = (id: number): void => {
+  const a = active.get(id)
+  active.delete(id)
+  a?.tracker?.onCancel?.()
+}

package/runtime/sdk/gl/Collider.ts

@@ -0,0 +1,29 @@
+// A 3D collider for click/touch hit-testing, as an aspect. Derives a box from the mesh by default.
+// (3D is the default engine, so this is the unsuffixed Collider; the 2D one is Collider2D.)
+//   node.aspect(Collider, { shape: 'box' })
+//   node.aspect(Collider, { shape: 'box', center: [0,1,0], size: [2,2,2] })
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Node } from "./Node"
+
+export class Collider extends Aspect<"collider", Node> {
+  static readonly aspect = "collider"
+  shape: "box" | "sphere" = "box"
+  /** Explicit box: center + full size. */
+  center?: Vec3Like
+  size?: Vec3Like
+  /** Explicit sphere: center + radius. */
+  radius?: number
+
+  onAttach(): void {
+    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 !== undefined) {
+      _creator.setColliderSphere(id, cx(this.center), cy(this.center), cz(this.center), this.radius)
+    } else {
+      _creator.setColliderFromMesh(id, id, this.shape === "sphere" ? 1 : 0)
+    }
+  }
+}

package/runtime/sdk/gl/Material.ts

@@ -6,6 +6,12 @@
 import { Color, type ColorInput } from "../core/color"
 import { fetch, type FetchResponse } from "../runtime/fetch"
 import { Texture } from "./Texture"
+// Type-only (erased at build) so a 3D material never pulls the 2D-canvas runtime; the guard is inline.
+import type { Canvas } from "../canvas/Canvas"
+
+/** Duck-type a Canvas without importing it (keeps 3D material free of 2D-canvas code). */
+const isCanvasSource = (v: unknown): v is Canvas =>
+  typeof v === "object" && v !== null && (v as { __canvas?: unknown }).__canvas === true
 
 type UniformValue = string | Texture | number | boolean | number[] | Float32Array | null
 
@@ -28,7 +34,7 @@ const applyUniform = (id: number, key: string, value: UniformValue): void => {
   }
 }
 
-export type MaterialColorOptions = { color?: ColorInput, map?: Texture | null }
+export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
 
 export class Material {
   /** @internal native material-instance handle. */
@@ -65,11 +71,12 @@ export class Material {
     if (this._colorKey) this.uniforms[this._colorKey] = Color.toHexString(c)
   }
 
-  set map(value: Texture | null) {
+  set map(value: Texture | Canvas | null) {
     if (value === null) {
       if (this._useMapFlag) this.uniforms.useBaseColorMap = false
     } else {
-      this.uniforms.baseColorMap = value
+      // A Canvas bakes to a (cached) 3D texture on assign — same as Sprite accepting a Canvas in 2D.
+      this.uniforms.baseColorMap = isCanvasSource(value) ? Texture.fromCanvas(value) : value
       if (this._useMapFlag) this.uniforms.useBaseColorMap = true
     }
   }

package/runtime/sdk/gl/Mesh.ts

@@ -1,9 +1,7 @@
-// A renderable 3D node. Static factories build the common shapes; Mesh.from wraps a custom Geometry;
-// Mesh.load brings in a GLB (returned as its root Node, with baked animation clips). Ported from
-// worker/src/components/Mesh.ts — folded into the node (no component).
+// A renderable 3D node from raw geometry — the primitive shapes (box/sphere/cylinder/plane) and
+// Mesh.from for a custom Geometry. A GLB import is a different kind: see Model.load.
 
 import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import { fetch, type FetchResponse } from "../runtime/fetch"
 import {
   Geometry,
   type CylinderOptions,
@@ -87,27 +85,6 @@ export class Mesh extends Node {
   static from(geometry: Geometry, options: MeshOptions = {}): Mesh {
     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).
-   */
-  static load(source: string | FetchResponse, options: { culling?: boolean, onProgress?: (p: { loaded: number, total?: number }) => void } = {}): Promise<Node> {
-    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 new Promise<Node>((resolve, reject) => {
-      _creator.createGlb((source as any)._id, (entityId) => {
-        if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
-        const node = new Node(entityId)
-        if (options.culling !== true) _creator.setGlbCulling(entityId, false)
-        resolve(node)
-      }, reject)
-    })
-  }
 }
 
 const sizeToVec = (s: Vec3Like | number): [number, number, number] => (typeof s === "number" ? [ s, s, s ] : [ cx(s), cy(s), cz(s) ])

package/runtime/sdk/gl/Model.ts

@@ -0,0 +1,40 @@
+// A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
+// distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
+// model.anim:
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.play('Run')
+
+import { fetch, type FetchResponse } from "../runtime/fetch"
+import { Node } from "./Node"
+import { ModelAnimation } from "./ModelAnimation"
+
+export class Model extends Node {
+  /** GLB skeletal animation — always present on a Model. */
+  declare readonly anim: ModelAnimation
+
+  constructor(internalId: number) {
+    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: string | FetchResponse,
+    options: { culling?: boolean, onProgress?: (p: { loaded: number, total?: number }) => void } = {},
+  ): Promise<Model> {
+    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 Model.load(resp, options)
+      })
+    }
+    return new Promise<Model>((resolve, reject) => {
+      _creator.createGlb((source as unknown as { _id: number })._id, (entityId: number) => {
+        if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
+        const model = new Model(entityId)
+        if (options.culling !== true) _creator.setGlbCulling(entityId, false)
+        resolve(model)
+      }, reject)
+    })
+  }
+}

package/runtime/sdk/gl/ModelAnimation.ts

@@ -0,0 +1,64 @@
+// GLB skeletal animation as an aspect. Auto-attached by Model (a glb always has its clips), so you
+// reach it directly: model.anim.play('Run'). Clips come baked in the glb; play by name or index.
+
+import { Aspect } from "../core/Aspect"
+import { nodeRegistry } from "./Node"
+import type { Model } from "./Model"
+
+let animatorRegistered = false
+const ensureAnimator = (): void => {
+  if (animatorRegistered) return
+  animatorRegistered = true
+  _creator.setOnAnimationComplete((entityId, clipIndex) => nodeRegistry.get(entityId)?._onAnimationComplete(clipIndex) ?? true)
+}
+
+export class ModelAnimation extends Aspect<"anim", Model> {
+  static readonly aspect = "anim"
+
+  private _playing = false
+  private _clip = 0
+  private _speed = 1
+  private _loop = false
+
+  onAttach(): void {
+    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(): { name: string, duration: number }[] { return _creator.getGlbAnimations(this.node.id) }
+
+  get playing(): boolean { return this._playing }
+  set playing(value: boolean) {
+    this._playing = value
+    _creator.setAnimation(this.node.id, value, this._clip, this._speed)
+  }
+
+  /** Play a clip by name or index. Chainable. */
+  play(clip?: string | number, options: { loop?: boolean } = {}): this {
+    if (typeof clip === "number") this._clip = clip
+    else if (typeof clip === "string") {
+      const i = this.clips.findIndex((c) => c.name === clip)
+      if (i >= 0) this._clip = i
+    }
+    if (options.loop !== undefined) this._loop = options.loop
+    this.playing = true
+    ensureAnimator()
+    return this
+  }
+  stop(): this { this.playing = false; return this }
+
+  get loop(): boolean { return this._loop }
+  set loop(v: boolean) { this._loop = v }
+  get speed(): number { return this._speed }
+  set speed(v: number) {
+    this._speed = v
+    _creator.setAnimation(this.node.id, this._playing, this._clip, v)
+  }
+  get time(): number { return _creator.getAnimationTime(this.node.id) }
+  set time(v: number) { _creator.setAnimationTime(this.node.id, this._clip, v) }
+}

package/runtime/sdk/gl/Node.ts

@@ -2,15 +2,14 @@
 // on them. Native (creator-gl) owns the authoritative transform; reads decompose a cached local
 // matrix (re-synced lazily, since physics can write the transform from native each frame).
 //
-// "Behaviors are methods, not components": .physics() (+ node.body), .collider(), GLB animation
-// (.play()/.stop()), and hierarchy all live here.
+// Capabilities are aspects: node.aspect(Physics, …) (→ node.physics), node.aspect(Collider, …).
+// A GLB import is the Model node kind (with the ModelAnimation aspect). Hierarchy lives here.
 
-import { Emitter } from "../core/events"
+import { AspectHost } from "../core/Aspect"
 import { Registry } from "../core/registry"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import { Quat, cw, type QuatLike } from "../math/quat"
 import { Mat4, type Mat4Like } from "../math/mat4"
-import { Body, type PhysicsOptions } from "./Body"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
@@ -31,29 +30,10 @@ export type NodeEvents = {
   untrack: () => void
 }
 
-export type ColliderOptions = {
-  shape?: "box" | "sphere"
-  /** Explicit box: center + full size. */
-  center?: Vec3Like
-  size?: Vec3Like
-  /** Explicit sphere: center + radius. */
-  radius?: number
-}
-
-let animatorRegistered = false
-const ensureAnimator = (): void => {
-  if (animatorRegistered) return
-  animatorRegistered = true
-  _creator.setOnAnimationComplete((entityId, clipIndex) => nodeRegistry.get(entityId)?._onAnimationComplete(clipIndex) ?? true)
-}
-
-export class Node extends Emitter<NodeEvents> {
+export class Node extends AspectHost<NodeEvents> {
   /** Native entity handle. */
   readonly id: number
 
-  /** Physics handle once .physics() is called. */
-  body?: 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
@@ -63,10 +43,8 @@ export class Node extends Emitter<NodeEvents> {
   private _worldMatrix?: Float32Array
   private _scaleCache?: [number, number, number]
 
-  private _animPlaying = false
-  private _animClip = 0
-  private _animSpeed = 1
-  private _animLoop = false
+  /** @internal — the active animation aspect's clip-complete handler (installed by ModelAnimation). */
+  _animComplete?: (clipIndex: number) => boolean
 
   constructor(internalId?: number) {
     super()
@@ -193,26 +171,7 @@ export class Node extends Emitter<NodeEvents> {
     _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: PhysicsOptions = {}): this {
-    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: ColliderOptions = {}): this {
-    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 !== undefined) {
-      _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: Vec3Like, mode: "z" | "-z" | "x" | "-x" | "y" | "-y" = "-z", ortho: Vec3Like = [ 0, 1, 0 ]): this {
@@ -244,39 +203,6 @@ export class Node extends Emitter<NodeEvents> {
     return this
   }
 
-  // --- GLB animation (no-op until a GLB is loaded as this node) ---
-  get clips(): { name: string, duration: number }[] { return _creator.getGlbAnimations(this.id) }
-
-  get animationPlaying(): boolean { return this._animPlaying }
-  set animationPlaying(value: boolean) {
-    this._animPlaying = value
-    _creator.setAnimation(this.id, value, this._animClip, this._animSpeed)
-  }
-
-  /** Play a GLB clip by name or index. Chainable. */
-  play(clip?: string | number, options: { loop?: boolean } = {}): this {
-    if (typeof clip === "number") this._animClip = clip
-    else if (typeof clip === "string") {
-      const i = this.clips.findIndex((c) => c.name === clip)
-      if (i >= 0) this._animClip = i
-    }
-    if (options.loop !== undefined) this._animLoop = options.loop
-    this.animationPlaying = true
-    ensureAnimator()
-    return this
-  }
-  stop(): this { this.animationPlaying = false; return this }
-
-  get animationLoop(): boolean { return this._animLoop }
-  set animationLoop(v: boolean) { this._animLoop = v }
-  get animationSpeed(): number { return this._animSpeed }
-  set animationSpeed(v: number) {
-    this._animSpeed = v
-    _creator.setAnimation(this.id, this._animPlaying, this._animClip, v)
-  }
-  get animationTime(): number { return _creator.getAnimationTime(this.id) }
-  set animationTime(v: number) { _creator.setAnimationTime(this.id, this._animClip, v) }
-
   // --- events ---
   override addEventListener<K extends keyof NodeEvents>(channel: K, callback: NodeEvents[K]): void {
     if (channel === "click") registerTouchEndEvent()
@@ -289,14 +215,15 @@ export class Node extends Emitter<NodeEvents> {
     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: number): boolean {
-    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: "loopReached" | "completed", clip: number): void { this.dispatch(channel, clip) }
+
   destroy(): void {
     nodeRegistry.delete(this.id)
     _creator.destroyEntity(this.id)

package/runtime/sdk/gl/{Body.ts → Physics.ts}

@@ -1,10 +1,11 @@
-// Physics handle for a Node, backed by a JoltPhysics body in creator-gl. Created by node.physics();
-// reached as node.body. Ported from worker/src/components/RigidBody.ts.
+// Physics body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl.
+//   node.aspect(Physics, { motion: 'dynamic' });  node.physics.applyImpulse([0, 6, 0])
 //
 // For a `dynamic` body, physics OWNS the transform — do NOT set node.position per frame; drive it
 // via velocity / applyImpulse. Reading node.position is free (native already wrote it). Kinematic
-// bodies are driven with moveTo.
+// bodies are driven with moveTo. (Ported from the former Body class.)
 
+import { Aspect } from "../core/Aspect"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import type { Node } from "./Node"
 
@@ -17,40 +18,34 @@ export type BodyShape =
   | { type: "sphere", radius: number }
   | { type: "cylinder", halfHeight: number, radius: number }
 
-export type PhysicsOptions = {
+export class Physics extends Aspect<"physics", Node> {
+  static readonly aspect = "physics"
+
   /** Default "dynamic". */
-  motion?: MotionType
+  motion: MotionType = "dynamic"
   /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
-  mass?: number
+  mass = 1
   /** Default { type: "auto" } — a box from the mesh AABB × world scale. */
-  shape?: BodyShape
-}
+  shape: BodyShape = { type: "auto" }
 
-export class Body {
   private _bodyId = 0
-  private readonly _motion: MotionType
-
-  constructor(node: Node, options: PhysicsOptions = {}) {
-    this._motion = options.motion ?? "dynamic"
-    const mass = options.mass ?? 1
 
+  onAttach(): void {
     // No physics in this build (CREATOR_GL_PHYSICS=OFF) → bodyId stays 0; all methods no-op.
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-
-    const motion = MOTION[this._motion]
-    const shape = resolveShape(node, options.shape ?? { type: "auto" })
+    const motion = MOTION[this.motion]
+    const shape = resolveShape(this.node, this.shape)
     if (shape.type === "sphere") {
-      this._bodyId = _creator.physicsCreateSphere(node.id, shape.radius, motion, mass)
+      this._bodyId = _creator.physicsCreateSphere(this.node.id, shape.radius, motion, this.mass)
     } else if (shape.type === "cylinder") {
-      this._bodyId = _creator.physicsCreateCylinder(node.id, shape.halfHeight, shape.radius, motion, mass)
+      this._bodyId = _creator.physicsCreateCylinder(this.node.id, shape.halfHeight, shape.radius, motion, this.mass)
     } else {
-      this._bodyId = _creator.physicsCreateBox(node.id, cx(shape.halfExtents), cy(shape.halfExtents), cz(shape.halfExtents), motion, mass)
+      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 assigned, or if the build has no physics support. */
+  /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
   get id(): number { return this._bodyId }
-  get motion(): MotionType { return this._motion }
 
   /** Linear velocity in world units/second (fresh Vec3 on read). */
   get velocity(): Vec3 {
@@ -74,8 +69,7 @@ export class Body {
     return this
   }
 
-  /** Remove the body from the simulation. */
-  remove(): void {
+  onDetach(): void {
     if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
   }
 }

package/runtime/sdk/gl/Texture.ts

@@ -19,6 +19,17 @@ export class Texture {
     this._id = id
   }
 
+  // Wrap a Canvas's baked surface as a 3D texture (RGBA8, already rasterized → synchronous, no decode).
+  // The id is cached on the canvas (opaque _tex3dId), so backing several materials shares one texture and
+  // canvas.update() re-uploads it. Structural type avoids a Canvas import (keeps 3D free of 2D-canvas code).
+  static fromCanvas(canvas: { _bakeSurface(): number, width: number, height: number, pixelRatio: number, _tex3dId: number }): Texture {
+    if (!canvas._tex3dId) {
+      const surfaceId = canvas._bakeSurface()
+      canvas._tex3dId = _creator.createTextureFromCanvas(surfaceId)
+    }
+    return new Texture(Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio), canvas._tex3dId)
+  }
+
   static load(source: string | FetchResponse): Promise<Texture> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {

package/runtime/sdk/inject.ts

@@ -14,6 +14,13 @@ export { Quat } from "./math/quat"
 export { Mat4 } from "./math/mat4"
 export { Color } from "./core/color"
 
+// ---- aspects (attachable node capabilities) ----
+export { Aspect, type With } from "./core/Aspect"
+
+// ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
+export { Canvas } from "./canvas/Canvas"
+export { Label } from "./canvas/Label"
+
 // ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
 export { toast, SvgSource } from "./runtime/misc"
 export { fetch, fetchLocal, FormData, File } from "./runtime/fetch"
@@ -28,7 +35,13 @@ export { ClickEvent, TouchStartEvent } from "./runtime/touch"
 // ---- 2D engine (creator-2d) ----
 export { Scene2D } from "./g2/Scene2D"
 export { Node2D } from "./g2/Node2D"
+export { Camera2D } from "./g2/Camera2D"
 export { Sprite } from "./g2/Sprite"
+export { SpriteAnimation } from "./g2/SpriteAnimation"
+export { Shape } from "./g2/Shape"
+export { Physics2D } from "./g2/Physics2D"
+export { Trigger } from "./g2/Trigger"
+export { CharacterController2D } from "./g2/CharacterController2D"
 export { Tilemap } from "./g2/Tilemap"
 export { Texture2D } from "./g2/Texture2D"
 
@@ -61,6 +74,10 @@ export { QRScanner } from "./plugins/qr"
 export { Scene, ARScene } from "./gl/Scene"
 export { Node } from "./gl/Node"
 export { Mesh } from "./gl/Mesh"
+export { Model } from "./gl/Model"
+export { Physics } from "./gl/Physics"
+export { Collider } from "./gl/Collider"
+export { ModelAnimation } from "./gl/ModelAnimation"
 export { Light } from "./gl/Light"
 export { Material } from "./gl/Material"
 export { Geometry } from "./gl/Geometry"

package/runtime/sdk/runtime/touch.ts

@@ -8,6 +8,9 @@ export class ClickEvent<T = any> {
   readonly pointerId: number
   readonly clientX: number
   readonly clientY: number
+  /** World-space hit position (2D scenes only; undefined in 3D). */
+  worldX?: number
+  worldY?: number
   target!: T
   constructor(clientX: number, clientY: number, pointerId: number) {
     this.clientX = clientX
@@ -28,6 +31,9 @@ export class TouchStartEvent<T = any> {
   readonly pointerId: number
   readonly clientX: number
   readonly clientY: number
+  /** World-space hit position (2D scenes only; undefined in 3D). */
+  worldX?: number
+  worldY?: number
   target!: T
   /** @internal — read by the dispatch system after the handler runs. */
   _trackHandler?: TrackHandler