lecodes-cli 0.3.0 → 0.5.1

package/runtime/sdk/gl/Node.ts

@@ -2,7 +2,7 @@
 // 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).
 //
-// Capabilities are aspects: node.aspect(Physics, …) (→ node.physics), node.aspect(Collider, …).
+// Capabilities are aspects: node.aspect(Physics, …) (→ node.physics), node.aspect(Shape, …).
 // A GLB import is the Model node kind (with the ModelAnimation aspect). Hierarchy lives here.
 
 import { AspectHost } from "../core/Aspect"
@@ -12,6 +12,7 @@ import { Quat, cw, type QuatLike } from "../math/quat"
 import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
+import { ensurePhysicsEvents } from "./physicsEvents"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
@@ -28,6 +29,10 @@ export type NodeEvents = {
   track: () => void
   /** AR anchors only: the anchor lost tracking. */
   untrack: () => void
+  /** A physics contact/trigger overlap began (the other body's node). Needs a Shape + Physics/Trigger. */
+  enter: (other: Node) => void
+  /** A physics contact/trigger overlap ended. */
+  exit: (other: Node) => void
 }
 
 export class Node extends AspectHost<NodeEvents> {
@@ -171,7 +176,7 @@ export class Node extends AspectHost<NodeEvents> {
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
   }
 
-  // --- behaviors are aspects: node.aspect(Physics, …) / node.aspect(Collider, …) ---
+  // --- behaviors are aspects: node.aspect(Shape, …) / node.aspect(Physics, …) ---
 
   /** 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 {
@@ -207,6 +212,7 @@ export class Node extends AspectHost<NodeEvents> {
   override addEventListener<K extends keyof NodeEvents>(channel: K, callback: NodeEvents[K]): void {
     if (channel === "click") registerTouchEndEvent()
     else if (channel === "touchstart") registerTouchStartEvent()
+    else if (channel === "enter" || channel === "exit") ensurePhysicsEvents()
     super.addEventListener(channel, callback)
   }
 
@@ -215,6 +221,9 @@ export class Node extends AspectHost<NodeEvents> {
     this.dispatch(channel, ...args)
   }
 
+  /** @internal — emit a physics contact/trigger event (the physics-event router can't reach dispatch). */
+  _emitCollision(channel: "enter" | "exit", other: Node): void { this.dispatch(channel, other) }
+
   /** @internal — host animation-complete callback; forwards to the ModelAnimation aspect (if any).
    *  Returns whether the clip should keep playing. */
   _onAnimationComplete(clipIndex: number): boolean {

package/runtime/sdk/gl/Physics.ts

@@ -1,47 +1,70 @@
-// 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])
+// Rigid body as an aspect on a 3D Node, backed by a JoltPhysics body in creator-gl. Requires a Shape
+// aspect on the same node (its geometry becomes the body's collision shape).
 //
-// 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. (Ported from the former Body class.)
+//   Physics.configure({ gravity: [0, -9.81, 0] })          // once, before creating bodies
+//   ground.aspect(Shape, { box: [20, 0.5, 20] }).aspect(Physics, { motion: 'static' })
+//   crate.aspect(Shape, {}).aspect(Physics, { mass: 2 })   // auto box from the mesh
+//   crate.physics.applyImpulse([0, 6, 0])
+//   crate.addEventListener('enter', other => …)            // contact / trigger overlap began
+//
+// 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.
 
 import { Aspect } from "../core/Aspect"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import type { Node } from "./Node"
+import { nodeRegistry, type Node } from "./Node"
+import { Shape } from "./Shape"
 
 export type MotionType = "static" | "dynamic" | "kinematic"
 const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
 
-export type BodyShape =
-  | { type: "auto" }
-  | { type: "box", halfExtents: Vec3Like }
-  | { type: "sphere", radius: number }
-  | { type: "cylinder", halfHeight: number, radius: number }
+export interface PhysicsConfig {
+  /** Gravity in world units/s² (Y-up: down is negative). Default [0, -9.81, 0]. */
+  gravity?: Vec3Like
+  /** Max simultaneous bodies (resizes the world; only before any body exists). Default 4096. */
+  maxBodies?: number
+}
+
+/** Closest raycast hit. */
+export interface RayHit {
+  node: Node | null
+  point: Vec3
+  normal: Vec3
+  fraction: number
+}
 
 export class Physics extends Aspect<"physics", Node> {
   static readonly aspect = "physics"
 
+  /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
+   *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
+   *  smoothness — bodies then advance in discrete steps. */
+  private static _interpolation = true
+  static get interpolation(): boolean { return Physics._interpolation }
+  static set interpolation(on: boolean) { Physics._interpolation = on; _creator.setInterpolation(on) }
+
   /** Default "dynamic". */
   motion: MotionType = "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: BodyShape = { type: "auto" }
 
   private _bodyId = 0
 
   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(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)
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
     }
+    const shapeId = shape._claim() // drop the pick-only body; reuse its shape
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
+    shape._ownBody(this._bodyId)
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    this.node.get(Shape)?._recreatePickBody() // keep the node pickable if the Shape stays
   }
 
   /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
@@ -69,27 +92,28 @@ export class Physics extends Aspect<"physics", Node> {
     return this
   }
 
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+  // --- world (static) -------------------------------------------------------------------------
+  /** Configure gravity / limits. Call once before creating bodies. */
+  static configure(config: PhysicsConfig = {}): void {
+    const g = config.gravity ?? [0, -9.81, 0]
+    _creator.physicsConfigure(cx(g), cy(g), cz(g), config.maxBodies ?? 0)
+  }
+
+  /** Whether this build has physics support (CREATOR_GL_PHYSICS). */
+  static get supported(): boolean {
+    return !!_creator.physicsHasSupport && _creator.physicsHasSupport()
   }
-}
 
-// Resolve "auto" to a box from the mesh AABB × world scale (so the physical box matches the rendered
-// size). Falls back to a unit box if there is no geometry.
-const resolveShape = (node: Node, shape: BodyShape): Exclude<BodyShape, { type: "auto" }> => {
-  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]
+  /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+  static raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000): RayHit | null {
+    const out = new Float32Array(7)
+    const id = _creator.physicsRaycast(cx(origin), cy(origin), cz(origin), cx(dir), cy(dir), cz(dir), maxDist, out)
+    if (!id) return null
+    return {
+      node: nodeRegistry.get(id) ?? null,
+      point: new Vec3(out[0], out[1], out[2]),
+      normal: new Vec3(out[3], out[4], out[5]),
+      fraction: out[6],
     }
-    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 ] }
 }

package/runtime/sdk/gl/Scene.ts

@@ -6,6 +6,7 @@
 // direct light + shadows.
 
 import { Color, type ColorInput } from "../core/color"
+import { _installAspectFrames } from "../core/Aspect"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { Camera } from "./Camera"
@@ -29,6 +30,22 @@ export type SceneOptions = {
   antialias?: boolean
 }
 
+// Route aspect update(dt) through the render-synced native phases (render() early = before physics,
+// late = after animations / before draw), so followers/cameras are in lockstep with the draw. Done from
+// the 3D layer (not core) so a 2D-only bundle never pulls in the 3D bridge. Installed once, lazily on
+// the first Scene. On an older wasm without the hooks the installer returns false → setLoop fallback.
+let framesInstalled = false
+const installRenderSyncedFrames = (): void => {
+  if (framesInstalled) return
+  framesInstalled = true
+  _installAspectFrames((early, late) => {
+    if (typeof _creator.setEarlyUpdate !== "function") return false
+    _creator.setEarlyUpdate(early)
+    _creator.setLateUpdate(late)
+    return true
+  })
+}
+
 export class Scene {
   /** @internal native scene handle. */
   readonly _id: number
@@ -44,6 +61,7 @@ export class Scene {
   static get active(): Scene | null { return Scene._active }
 
   constructor(options: SceneOptions = {}) {
+    installRenderSyncedFrames()
     const parent = (options as any)._parent as Scene | undefined
     if (parent) {
       this.camera = parent.camera

package/runtime/sdk/gl/Shape.ts

@@ -0,0 +1,98 @@
+// A collision shape, as an aspect on a 3D Node. PURE GEOMETRY: attaching a Shape does not by itself
+// make the node rigid or a sensor — pair it with a Physics (rigid body) or a Trigger (sensor), both
+// of which require a Shape. The Shape also makes the node pointer-pickable: on its own it creates a
+// lightweight "pick-only" JoltPhysics body (collides with nothing, exists only for the raycast), so
+// any node with a Shape can receive click/touchstart. Physics/Trigger REPLACE that body with the real
+// one. Set `raycast = false` to opt a shape out of pointer picking.
+//
+//   wall.aspect(Shape, { box: [1, 2, 1] }).aspect(Physics, { motion: 'static' })
+//   coin.aspect(Shape, { sphere: 0.5 }).aspect(Trigger)
+//   crate.aspect(Shape, {}).aspect(Physics)                 // auto box from the mesh AABB × world scale
+//
+// Explicit dims are world-space half-extents (not scaled by the node). Use {} ("auto") to track the
+// mesh × world scale. Note: a Shape-only pick body is a STATIC snapshot at attach time — for a moving
+// pickable object add a Physics body (which follows the sim), rather than relying on the pick body.
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Node } from "./Node"
+
+export class Shape extends Aspect<"shape", Node> {
+  static readonly aspect = "shape"
+
+  /** Box half-extents [hx, hy, hz] (world units). */
+  box?: Vec3Like
+  /** Sphere radius. */
+  sphere?: number
+  /** Cylinder aligned on Y: half-height + radius. */
+  cylinder?: { halfHeight: number, radius: number }
+  /** Capsule aligned on Y: half-height of the cylinder section + radius. */
+  capsule?: { halfHeight: number, radius: number }
+  /** Whether pointer rays can hit this shape (click / touchstart). Default true. */
+  raycast = true
+
+  private _shapeId = 0
+  private _bodyId = 0
+
+  /** @internal native shape id (0 if the build has no physics). */
+  get shapeId(): number { return this._shapeId }
+  /** @internal current native body id (a pick-only body until Physics/Trigger claim it). */
+  get bodyId(): number { return this._bodyId }
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    this._shapeId = this._build()
+    if (this._shapeId) this._createPickBody()
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    if (this._shapeId) { _creator.physicsDestroyShape(this._shapeId); this._shapeId = 0 }
+  }
+
+  /** @internal Physics/Trigger take over: drop the pick body and hand back the shape id. */
+  _claim(): number {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    return this._shapeId
+  }
+  /** @internal Physics/Trigger report the body they created, so Shape owns its lifetime + pickability. */
+  _ownBody(bodyId: number): void {
+    this._bodyId = bodyId
+    if (!this.raycast && bodyId) _creator.physicsSetPickable(bodyId, false)
+  }
+  /** @internal restore a pick-only body when Physics/Trigger detach but the Shape remains. */
+  _recreatePickBody(): void {
+    if (!this._bodyId && this._shapeId) this._createPickBody()
+  }
+
+  private _createPickBody(): void {
+    this._bodyId = _creator.physicsCreateBody(this.node.id, this._shapeId, 0, 0, false, /*pickOnly*/ true)
+    if (!this.raycast && this._bodyId) _creator.physicsSetPickable(this._bodyId, false)
+  }
+
+  private _build(): number {
+    if (this.sphere !== undefined) return _creator.physicsBuildSphere(this.sphere)
+    if (this.cylinder) return _creator.physicsBuildCylinder(this.cylinder.halfHeight, this.cylinder.radius)
+    if (this.capsule) return _creator.physicsBuildCapsule(this.capsule.halfHeight, this.capsule.radius)
+    if (this.box) return _creator.physicsBuildBox(cx(this.box), cy(this.box), cz(this.box))
+
+    // auto: a box from the mesh AABB × world scale (so the physical box matches the rendered size).
+    const s = this.node.worldScale
+    let hx = 0.5, hy = 0.5, hz = 0.5
+    const geom = this.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 _creator.physicsBuildBox(hx * s.x, hy * s.y, hz * s.z)
+  }
+}

package/runtime/sdk/gl/Texture.ts

@@ -1,6 +1,6 @@
 // A 3D GPU texture, decoded natively by creator-gl. Load from a URL or an already-fetched response.
 
-import { fetch, type FetchResponse } from "../runtime/fetch"
+import { fetch, type FetchResponse, type File } from "../runtime/fetch"
 
 export class Texture {
   /** @internal native texture handle. */
@@ -30,7 +30,7 @@ export class Texture {
     return new Texture(Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio), canvas._tex3dId)
   }
 
-  static load(source: string | FetchResponse): Promise<Texture> {
+  static load(source: string | FetchResponse | File): Promise<Texture> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {
         if (resp.status >= 400) {

package/runtime/sdk/gl/Trigger.ts

@@ -0,0 +1,46 @@
+// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
+//
+//   const goal = new Mesh(box(), material)
+//     .aspect(Shape, { box: [1, 2, 1] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => …)
+
+import { Aspect } from "../core/Aspect"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Shape } from "./Shape"
+import { ensurePhysicsEvents } from "./physicsEvents"
+import type { Node } from "./Node"
+
+export class Trigger extends Aspect<"trigger", Node> {
+  static readonly aspect = "trigger"
+
+  private _bodyId = 0
+  /** Native body id (0 if no physics support). */
+  get id(): number { return this._bodyId }
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    const shapeId = shape._claim()
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
+    shape._ownBody(this._bodyId)
+    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    this.node.get(Shape)?._recreatePickBody()
+  }
+
+  /** Reposition the trigger zone to a world point. */
+  moveTo(p: Vec3Like): this {
+    if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p))
+    return this
+  }
+}

package/runtime/sdk/gl/physicsEvents.ts

@@ -0,0 +1,20 @@
+// Routes native physics contact/sensor events to the owning nodes' 'enter'/'exit' events. Each event
+// is delivered to BOTH nodes with the other as the argument. type: 0 = enter (contact/overlap began),
+// 1 = exit (ended). Registered lazily on the first trigger/physics body or 'enter'/'exit' listener.
+
+import { nodeRegistry } from "./Node"
+
+let registered = false
+export const ensurePhysicsEvents = (): void => {
+  if (registered) return
+  if (!_creator.setOnPhysicsEvent) return // physics-less build / bridge without the hook
+  registered = true
+  _creator.setOnPhysicsEvent((a, b, type) => {
+    const na = nodeRegistry.get(a)
+    const nb = nodeRegistry.get(b)
+    if (!na || !nb) return
+    const channel = type === 1 ? "exit" : "enter"
+    na._emitCollision(channel, nb)
+    nb._emitCollision(channel, na)
+  })
+}

package/runtime/sdk/inject.ts

@@ -17,9 +17,11 @@ export { Color } from "./core/color"
 // ---- aspects (attachable node capabilities) ----
 export { Aspect, type With } from "./core/Aspect"
 
+// ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
+export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
+
 // ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
-export { Canvas } from "./canvas/Canvas"
-export { Label } from "./canvas/Label"
+export { Canvas, Bitmap } from "./canvas/Canvas"
 
 // ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
 export { toast, SvgSource } from "./runtime/misc"
@@ -29,7 +31,9 @@ export { device } from "./runtime/device"
 export { Input } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
+export { CameraViewer } from "./runtime/camera"
 export { openFilePicker } from "./runtime/files"
+export { share } from "./runtime/share"
 export { ClickEvent, TouchStartEvent } from "./runtime/touch"
 
 // ---- 2D engine (creator-2d) ----
@@ -38,9 +42,9 @@ 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 { Shape2D } from "./g2/Shape2D"
 export { Physics2D } from "./g2/Physics2D"
-export { Trigger } from "./g2/Trigger"
+export { Trigger2D } from "./g2/Trigger2D"
 export { CharacterController2D } from "./g2/CharacterController2D"
 export { Tilemap } from "./g2/Tilemap"
 export { Texture2D } from "./g2/Texture2D"
@@ -60,6 +64,7 @@ export {
   UIVirtualizedList,
   Router,
   registerFont,
+  __uiMap,
 } from "./ui/UI"
 
 // ---- animate ----
@@ -75,8 +80,10 @@ export { Scene, ARScene } from "./gl/Scene"
 export { Node } from "./gl/Node"
 export { Mesh } from "./gl/Mesh"
 export { Model } from "./gl/Model"
+export { Shape } from "./gl/Shape"
 export { Physics } from "./gl/Physics"
-export { Collider } from "./gl/Collider"
+export { Trigger } from "./gl/Trigger"
+export { CharacterController } from "./gl/CharacterController"
 export { ModelAnimation } from "./gl/ModelAnimation"
 export { Light } from "./gl/Light"
 export { Material } from "./gl/Material"

package/runtime/sdk/runtime/camera.ts

@@ -0,0 +1,31 @@
+// Device camera → a still-photo File. Ported from worker/src/utils/CameraViewer.ts. Permission is
+// requested through the engine bridge's `requestCamera` (same as QRScanner); the live preview and the
+// capture go through `_creatorUtils.camera*`. `takePhoto()` returns a File (a host buffer handle), so
+// the shot can be used as a texture (`Texture2D.load(file)`), uploaded via FormData, or shared.
+
+import { File } from "./fetch"
+
+export class CameraViewer {
+  /** Ask for camera permission and start the live preview (default: the back camera). */
+  static async open(facingMode: "front" | "back" = "back"): Promise<void> {
+    await new Promise<void>((res, rej) => _creator.requestCamera(res, rej))
+    await new Promise<void>((res, rej) => _creatorUtils.cameraOpen(facingMode, res, rej))
+  }
+
+  /** Switch between the front and back camera while the preview is open. */
+  static setFacingMode(facingMode: "front" | "back"): void {
+    _creatorUtils.cameraSetFacingMode(facingMode)
+  }
+
+  /** Capture a still frame as an image File (host-encoded). */
+  static takePhoto(): Promise<File> {
+    return new Promise<File>((res, rej) => {
+      _creatorUtils.cameraTakePhoto((bufferId, name, size) => res(new File(bufferId, name, size)), rej)
+    })
+  }
+
+  /** Stop the preview and release the camera. */
+  static close(): void {
+    _creatorUtils.cameraClose()
+  }
+}

package/runtime/sdk/runtime/device.ts

@@ -17,6 +17,32 @@ export const device = {
   get language(): string {
     return _creatorUtils.language
   },
+  /** Display device-pixel ratio (physical px per logical/CSS px): 1 on standard displays, 2–3 on
+   *  retina / iOS. Bake a Canvas at this ratio for crisp output without hardcoding, e.g.
+   *  `new Canvas(w, h, { pixelRatio: device.pixelRatio })`. NOTE: the web 2D/GL surface currently
+   *  renders at logical resolution, so on web this only helps UI canvases / is forward-looking for
+   *  2D; on iOS (physical surface) it makes 2D canvases crisp. Falls back to 1 if the host omits it. */
+  get pixelRatio(): number {
+    return _creatorUtils.pixelRatio || 1
+  },
+  /** Current display width in logical px — the same value the "resize" event delivers, but readable at
+   *  any time (not only inside the listener). 0 until the host has reported a size. */
+  get width(): number {
+    return _creatorUI.getDisplaySize?.()?.[0] ?? 0
+  },
+  /** Current display height in logical px — the same value the "resize" event delivers, readable at any
+   *  time. 0 until the host has reported a size. */
+  get height(): number {
+    return _creatorUI.getDisplaySize?.()?.[1] ?? 0
+  },
+  /** Opt into the precise-touch system where the platform supports it. OFF by default. When on, fast
+   *  strokes are sampled at the touch digitizer's full rate (iOS coalesced touches, ≈120–240 Hz) instead
+   *  of once per display frame (~60 Hz), so a pointer-heavy app (drawing, handwriting, dragging) gets more
+   *  points and smoother lines. Leave it off for tap/button UIs. No-op on hosts without a coalesced-input
+   *  concept (web already coalesces pointermove; headless). */
+  setPreciseTouch(enabled: boolean): void {
+    _creatorUtils.setPreciseTouch?.(enabled)
+  },
   addEventListener(channel: "resize", callback: ResizeCallback): void {
     if (channel !== "resize") return
     resizeListeners.push(callback)

package/runtime/sdk/runtime/share.ts

@@ -0,0 +1,9 @@
+// Share a media File (image/video) via the OS share sheet. Wraps `_creatorUtils.shareMedia`, which
+// takes the host buffer id behind the File. On iOS the sheet also lets the user save to Files/Photos;
+// on web it saves (downloads) the file. `text` is an optional caption/message.
+
+import type { File, FetchResponse } from "./fetch"
+
+export function share(media: File | FetchResponse, text?: string): void {
+  _creatorUtils.shareMedia((media as any).id ?? (media as any)._id, text)
+}

package/runtime/sdk/ui/UI.ts

@@ -16,4 +16,8 @@ export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
 
 export { UIVirtualizedList } from './UIVirtualizedList'
 
-export { Router } from './router'
+export { Router } from './router'
+
+// Internal: memoized map for reactive children — the chisel `reactiveUi` pass rewrites
+// `list.map(fn)` inside children bindings to `__uiMap(list, fn, slot)` calls.
+export { __uiMap } from './UINode'

package/runtime/sdk/ui/UIButton.ts

@@ -1,6 +1,6 @@
 import { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType } from "../runtime/touch"
-import { type ElementStyle, type ContainerStyle, type Style, ContainerElement, type DrawableStyle, type UINodeChild, type OnLayoutCallback, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
+import { type ElementStyle, type ContainerStyle, type Style, ContainerElement, type DrawableStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
 
@@ -18,9 +18,15 @@ export interface UIButton {
   append(...nodes: UINodeChild[]): this
   insert(index: number, ...nodes: UINodeChild[]): this
   remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[]): this
+  setContent(nodes: UINodeChild[] | ChildrenFn): this
 
   onLayout(onLayout: OnLayoutCallback): this
+
+  setClass(name: string, enabled: boolean): this
+  toggleClass(name: string): this
+  hasClass(name: string): boolean
+  bindClass(name: string, fn: () => boolean): this
+
   readonly children: UINodeChild[],
 }
 
@@ -66,14 +72,14 @@ class ButtonElement extends ContainerElement<"button"> {
 }
 
 export function UIButton(): UIButton;
-export function UIButton(children: UINodeChild[]): UIButton;
+export function UIButton(children: UINodeChild[] | ChildrenFn): UIButton;
 export function UIButton(style: UIButtonStyle): UIButton;
 export function UIButton(style: UIButtonStyle, children: UINodeChild[]): UIButton;
-export function UIButton(...args: [] | [UINodeChild[] | UIButtonStyle] | [UIButtonStyle, children: UINodeChild[]]): UIButton {
+export function UIButton(...args: [] | [UINodeChild[] | ChildrenFn | UIButtonStyle] | [UIButtonStyle, children: UINodeChild[] | ChildrenFn]): UIButton {
   if (args.length === 0) {
     return new ButtonElement("button", {}, [])
   } else if (args.length === 1) {
-    if (Array.isArray(args[0])) {
+    if (Array.isArray(args[0]) || typeof args[0] === "function") {
       return new ButtonElement("button", {}, args[0])
     } else {
       return new ButtonElement("button", args[0], [])