lecodes-cli 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "@letary/chisel": "^0.1.2"
   },
   "peerDependencies": {
-    "lecodes-renderer": "^0.2.0"
+    "lecodes-renderer": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "lecodes-renderer": {

package/runtime/sdk/canvas/Canvas.ts

@@ -0,0 +1,184 @@
+// A core 2D drawing surface that bakes to a texture — see docs/canvas-contract.md. It is NOT part of
+// creator-2d/creator-gl: the texture it produces is consumed by 2D sprites, 3D materials and UI
+// images alike ("a canvas is just a texture"), so world/label text and arbitrary 2D graphics are
+// drawn once, per platform, on that platform's native 2D stack (web OffscreenCanvas, iOS CoreGraphics,
+// Android Canvas).
+//
+// The API looks immediate but RECORDS commands into a compact buffer and flushes them to the backend
+// ONCE per bake (one bridge crossing, not one per lineTo). Colors and fonts are CSS strings, resolved
+// by the platform. Do all drawing AFTER `await registerFont(...)` — an unloaded font mis-measures.
+//
+// State (fillStyle, font, textAlign, …) is get/set like the browser; drawing calls are methods (they
+// return `this`, so drawing still chains). `pixelRatio` is the device-pixel multiplier (browser-style
+// `scale(sx, sy)` is a transform).
+//
+//   const c = new Canvas(160, 40, { pixelRatio: 2 })
+//   c.font = 'bold 24px Inter'
+//   const w = c.measureText('Alice').width + 24
+//   c.resize(w, 40)
+//   c.fillStyle = '#000a'; c.roundRect(0, 0, w, 40, 12).fill()
+//   c.fillStyle = '#fff'; c.textAlign = 'center'; c.fillText('Alice', w / 2, 27)
+//   new Sprite({ texture: c })          // Canvas is a valid texture source everywhere
+
+import { Texture2D } from "../g2/Texture2D"
+
+// Opcodes — MUST stay in sync with docs/canvas-contract.md.
+const OP = {
+  SAVE: 0, RESTORE: 1, TRANSLATE: 2, SCALE: 3, ROTATE: 4, GLOBAL_ALPHA: 5,
+  FILL_STYLE: 6, STROKE_STYLE: 7, LINE_WIDTH: 8, LINE_JOIN: 9, LINE_CAP: 10,
+  FONT: 11, TEXT_ALIGN: 12, TEXT_BASELINE: 13,
+  BEGIN_PATH: 14, CLOSE_PATH: 15, MOVE_TO: 16, LINE_TO: 17, QUADRATIC_TO: 18, BEZIER_TO: 19,
+  ARC: 20, RECT: 21, ROUND_RECT: 22, FILL: 23, STROKE: 24,
+  FILL_RECT: 25, STROKE_RECT: 26, CLEAR_RECT: 27, FILL_TEXT: 28, STROKE_TEXT: 29,
+} as const
+
+const ALIGN = { left: 0, center: 1, right: 2, start: 3, end: 4 } as const
+const BASELINE = { alphabetic: 0, top: 1, middle: 2, bottom: 3, hanging: 4, ideographic: 5 } as const
+const JOIN = { miter: 0, round: 1, bevel: 2 } as const
+const CAP = { butt: 0, round: 1, square: 2 } as const
+
+export type TextAlign = keyof typeof ALIGN
+export type TextBaseline = keyof typeof BASELINE
+export type LineJoin = keyof typeof JOIN
+export type LineCap = keyof typeof CAP
+export interface CanvasTextMetrics { width: number, ascent: number, descent: number }
+
+export class Canvas {
+  /** Brand so `Sprite`/`UIImage`/`Material` can accept a Canvas anywhere a texture source is expected. */
+  readonly __canvas = true as const
+
+  width: number
+  height: number
+  /** Device-pixel multiplier (draw at 2 for crisp retina text). Applied by the backend. */
+  pixelRatio: number
+
+  private _cmd: number[] = []
+  private _refs: string[] = []
+  // Shadowed drawing state so the get/set accessors read back the current value (like the browser).
+  private _globalAlpha = 1
+  private _fillStyle = "#000000"
+  private _strokeStyle = "#000000"
+  private _lineWidth = 1
+  private _lineJoin: LineJoin = "miter"
+  private _lineCap: LineCap = "butt"
+  private _font = "10px sans-serif"
+  private _textAlign: TextAlign = "start"
+  private _textBaseline: TextBaseline = "alphabetic"
+  private _surfaceId = 0
+  private _tex2d?: Texture2D   // cached 2D texture, re-uploaded on update()
+  /** @internal — cached 3D (creator-gl) texture id, set by gl/Texture.fromCanvas; re-uploaded on
+   *  update(). Kept as a bare id (not a Texture import) so a 2D-only canvas never pulls the 3D engine. */
+  _tex3dId = 0
+
+  constructor(width: number, height: number, opts: { pixelRatio?: number } = {}) {
+    this.width = width
+    this.height = height
+    this.pixelRatio = opts.pixelRatio ?? 1
+  }
+
+  private _ref(s: string): number {
+    const i = this._refs.indexOf(s)
+    if (i >= 0) return i
+    this._refs.push(s)
+    return this._refs.length - 1
+  }
+
+  /** Discard the recorded drawing to start a new one (for dynamic canvases). */
+  reset(): this { this._cmd.length = 0; this._refs.length = 0; return this }
+  /** Change the surface size; takes effect on the next bake. */
+  resize(width: number, height: number): this { this.width = width; this.height = height; return this }
+
+  // --- transforms & state stack (actions; chainable) ---
+  save(): this { this._cmd.push(OP.SAVE); return this }
+  restore(): this { this._cmd.push(OP.RESTORE); return this }
+  translate(x: number, y: number): this { this._cmd.push(OP.TRANSLATE, x, y); return this }
+  scale(sx: number, sy: number): this { this._cmd.push(OP.SCALE, sx, sy); return this }
+  rotate(rad: number): this { this._cmd.push(OP.ROTATE, rad); return this }
+
+  // --- drawing state (get/set like the browser; colors/fonts are CSS strings resolved by the platform).
+  // The setter records the state op AND shadows the value so the getter reads it back.
+  get globalAlpha(): number { return this._globalAlpha }
+  set globalAlpha(a: number) { this._globalAlpha = a; this._cmd.push(OP.GLOBAL_ALPHA, a) }
+  get fillStyle(): string { return this._fillStyle }
+  set fillStyle(color: string) { this._fillStyle = color; this._cmd.push(OP.FILL_STYLE, this._ref(color)) }
+  get strokeStyle(): string { return this._strokeStyle }
+  set strokeStyle(color: string) { this._strokeStyle = color; this._cmd.push(OP.STROKE_STYLE, this._ref(color)) }
+  get lineWidth(): number { return this._lineWidth }
+  set lineWidth(w: number) { this._lineWidth = w; this._cmd.push(OP.LINE_WIDTH, w) }
+  get lineJoin(): LineJoin { return this._lineJoin }
+  set lineJoin(j: LineJoin) { this._lineJoin = j; this._cmd.push(OP.LINE_JOIN, JOIN[j]) }
+  get lineCap(): LineCap { return this._lineCap }
+  set lineCap(c: LineCap) { this._lineCap = c; this._cmd.push(OP.LINE_CAP, CAP[c]) }
+  get font(): string { return this._font }
+  set font(f: string) { this._font = f; this._cmd.push(OP.FONT, this._ref(f)) }
+  get textAlign(): TextAlign { return this._textAlign }
+  set textAlign(a: TextAlign) { this._textAlign = a; this._cmd.push(OP.TEXT_ALIGN, ALIGN[a]) }
+  get textBaseline(): TextBaseline { return this._textBaseline }
+  set textBaseline(b: TextBaseline) { this._textBaseline = b; this._cmd.push(OP.TEXT_BASELINE, BASELINE[b]) }
+
+  // --- paths ---
+  beginPath(): this { this._cmd.push(OP.BEGIN_PATH); return this }
+  closePath(): this { this._cmd.push(OP.CLOSE_PATH); return this }
+  moveTo(x: number, y: number): this { this._cmd.push(OP.MOVE_TO, x, y); return this }
+  lineTo(x: number, y: number): this { this._cmd.push(OP.LINE_TO, x, y); return this }
+  quadraticCurveTo(cx: number, cy: number, x: number, y: number): this { this._cmd.push(OP.QUADRATIC_TO, cx, cy, x, y); return this }
+  bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this {
+    this._cmd.push(OP.BEZIER_TO, c1x, c1y, c2x, c2y, x, y); return this
+  }
+  arc(x: number, y: number, r: number, a0: number, a1: number, ccw = false): this {
+    this._cmd.push(OP.ARC, x, y, r, a0, a1, ccw ? 1 : 0); return this
+  }
+  rect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.RECT, x, y, w, h); return this }
+  roundRect(x: number, y: number, w: number, h: number, r: number): this { this._cmd.push(OP.ROUND_RECT, x, y, w, h, r); return this }
+  fill(evenOdd = false): this { this._cmd.push(OP.FILL, evenOdd ? 1 : 0); return this }
+  stroke(): this { this._cmd.push(OP.STROKE); return this }
+
+  // --- shape/text sugar ---
+  fillRect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.FILL_RECT, x, y, w, h); return this }
+  strokeRect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.STROKE_RECT, x, y, w, h); return this }
+  clearRect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.CLEAR_RECT, x, y, w, h); return this }
+  fillText(text: string, x: number, y: number, maxWidth = 0): this { this._cmd.push(OP.FILL_TEXT, this._ref(text), x, y, maxWidth); return this }
+  strokeText(text: string, x: number, y: number, maxWidth = 0): this { this._cmd.push(OP.STROKE_TEXT, this._ref(text), x, y, maxWidth); return this }
+
+  /** Measure `text` in the current font on THIS platform. The one synchronous round-trip. */
+  measureText(text: string): CanvasTextMetrics {
+    const o = _creatorCanvas.measureText(text, this._font)
+    return { width: o[0], ascent: o[1], descent: o[2] }
+  }
+
+  /** @internal — rasterize the recorded commands into the surface; returns the surface id. */
+  _bakeSurface(): number {
+    const buf = new Float32Array(this._cmd)
+    this._surfaceId = _creatorCanvas.rasterize(this._surfaceId, this.width, this.height, this.pixelRatio, buf, buf.length, this._refs)
+    return this._surfaceId
+  }
+
+  /** Bake and return the 2D texture (created once, then cached). */
+  texture(): Texture2D {
+    if (!this._tex2d) this._tex2d = Texture2D.fromCanvas(this)
+    return this._tex2d
+  }
+
+  /** Re-rasterize and re-upload to every texture this canvas produced (call after redrawing) — the
+   *  cached 2D and/or 3D texture, whichever engines this canvas was baked into. */
+  update(): this {
+    const surfaceId = this._bakeSurface()
+    if (this._tex2d) _creator2d.updateTextureFromCanvas(this._tex2d.id, surfaceId)
+    if (this._tex3dId) _creator.updateTextureFromCanvas(this._tex3dId, surfaceId)
+    return this
+  }
+
+  destroy(): void {
+    if (this._surfaceId) _creatorCanvas.destroySurface(this._surfaceId)
+    this._tex2d?.destroy()
+    // The 3D texture (if any) is owned by creator-gl's engine and freed at its teardown — no per-texture
+    // destroy in the 3D API — so we just drop our cached id here.
+    this._surfaceId = 0
+    this._tex2d = undefined
+    this._tex3dId = 0
+  }
+}
+
+/** Duck-type guard so consumers can accept a Canvas anywhere a texture source is expected. */
+export const isCanvas = (v: unknown): v is Canvas =>
+  typeof v === "object" && v !== null && (v as { __canvas?: unknown }).__canvas === true

package/runtime/sdk/canvas/Label.ts

@@ -0,0 +1,57 @@
+// Convenience recipe (userland-style TS, not a native primitive): draw a text pill into a Canvas and
+// hand back a Sprite you can drop over an NPC / actor. The same Canvas texture also works as a 3D
+// billboard or a UIImage — Label just wraps the common 2D case.
+//
+//   const tag = Label('Alice')
+//   tag.position = npc.worldPosition          // float it above the NPC (offset in y as needed)
+//
+// Fonts must be registered first: `await registerFont('Inter', url)` before Label(...).
+
+import { Canvas } from "./Canvas"
+import { Sprite } from "../g2/Sprite"
+
+export interface LabelOptions {
+  /** CSS font shorthand. Default 'bold 24px sans-serif'. */
+  font?: string
+  /** Text color. Default '#fff'. */
+  color?: string
+  /** Pill background; null for no pill (bare text). Default '#000a'. */
+  background?: string | null
+  /** Horizontal / vertical padding around the text (logical px). Default 12 / 6. */
+  padX?: number
+  padY?: number
+  /** Corner radius of the pill. Default 10. */
+  radius?: number
+  /** Device-pixel multiplier for crisp text. Default 2. */
+  pixelRatio?: number
+  /** Sprite draw layer. */
+  layer?: number
+}
+
+export function Label(text: string, opts: LabelOptions = {}): Sprite {
+  const font = opts.font ?? "bold 24px sans-serif"
+  const color = opts.color ?? "#fff"
+  const bg = opts.background === undefined ? "#000a" : opts.background
+  const padX = opts.padX ?? 12
+  const padY = opts.padY ?? 6
+  const radius = opts.radius ?? 10
+  const pixelRatio = opts.pixelRatio ?? 2
+
+  // measure first (native metrics) to size the pill to the text
+  const c = new Canvas(1, 1, { pixelRatio })
+  c.font = font
+  const m = c.measureText(text)
+  const lineH = m.ascent + m.descent
+  const w = Math.ceil(m.width + padX * 2)
+  const h = Math.ceil(lineH + padY * 2)
+  c.reset().resize(w, h)
+  c.font = font   // reset() cleared the buffer — re-record the font for the actual draw
+
+  if (bg !== null) { c.fillStyle = bg; c.roundRect(0, 0, w, h, radius).fill() }
+  c.fillStyle = color
+  c.textAlign = "center"
+  c.textBaseline = "middle"
+  c.fillText(text, w / 2, h / 2)
+
+  return new Sprite({ texture: c, anchor: [0.5, 1], layer: opts.layer })
+}

package/runtime/sdk/core/Aspect.ts

@@ -39,28 +39,70 @@ type UnionToIntersection<U> =
 export type With<N, A extends Aspect<any, any>> =
   N & UnionToIntersection<A extends any ? FieldOf<A> : never>
 
-// ---- per-frame update dispatch ----------------------------------------------
-// Aspects that define update(dt) are ticked every frame from a SINGLE global loop, created LAZILY on
-// the first such aspect (a project with no behavior aspects starts no loop). dt is seconds, like
-// setLoop. No visibility/frustum culling yet — every registered aspect ticks regardless of on-screen
-// state.
-const updaters: Aspect<any, any>[] = []
-let updateLoopId: number | undefined
-
-const ensureUpdateLoop = (): void => {
-  if (updateLoopId !== undefined) return
-  updateLoopId = setLoop((dt) => {
-    // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
-    for (const a of updaters.slice()) {
-      // later (visibility culling): if (a.updateWhenVisible && nodeOffScreen(a)) continue
-      a.update?.(dt)
-    }
-  })
+// ---- per-frame update dispatch (two phases) ---------------------------------
+// Aspects that define update(dt) are ticked every frame in ONE of two phases, chosen by the aspect's
+// `updateBeforePhysics` field:
+//   • LATE (default): after the physics step + transform sync, right before the frame draws. Reads of
+//     node.worldPosition are the FINAL drawn position — cameras/followers land exactly, no 1-frame lag.
+//   • EARLY (updateBeforePhysics = true): before the physics step, so writing velocity/force/kinematic
+//     transforms is consumed by the SAME frame's step (zero input latency).
+// The FRAME SOURCE is pluggable so core never names a specific engine bridge (a 3D-only bundle must not
+// pull in the 2D one): the 2D layer installs a render-synced source via _installAspectFrames (the native
+// c2dRender early/late hooks), so dispatch is in lockstep with the draw. With none installed (3D-only,
+// or a runtime without the hooks) it falls back to a single host setLoop, early-then-late — no true
+// post-physics slot. Both lists stay sorted by the aspect's `order` field (default 0; ties keep
+// insertion order). Lazy: the first update-bearing aspect installs the dispatch; a project with none
+// starts nothing. No visibility culling yet — every registered aspect ticks regardless of on-screen state.
+type Updatable = Aspect<any, any>
+type PhaseFn = (dt: number) => void
+const earlyUpdaters: Updatable[] = []
+const lateUpdaters: Updatable[] = []
+let dispatchInstalled = false
+
+// A render-synced frame source: given the two phase runners, wire them to the engine and return true;
+// return false if unavailable (→ setLoop fallback). Installed by the 2D layer (see Scene2D) so core
+// never references a concrete engine bridge — that keeps the 2D bridge out of a 3D-only bundle.
+type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
+let frameInstaller: FrameInstaller | undefined
+/** @internal Install a render-synced frame source for aspect update(dt). Called from the 2D layer. */
+export const _installAspectFrames = (fn: FrameInstaller): void => { frameInstaller = fn }
+
+const policyOf = (a: Updatable): { early: boolean; order: number } =>
+  ({ early: a.updateBeforePhysics === true, order: a.order ?? 0 })
+
+// Stable insert by ascending order: place after the last element whose order is <= this one's.
+const addSorted = (list: Updatable[], a: Updatable, order: number): void => {
+  let i = list.length
+  while (i > 0 && policyOf(list[i - 1]).order > order) i--
+  list.splice(i, 0, a)
 }
-const registerUpdater = (a: Aspect<any, any>): void => { updaters.push(a); ensureUpdateLoop() }
-const unregisterUpdater = (a: Aspect<any, any>): void => {
-  const i = updaters.indexOf(a)
-  if (i >= 0) updaters.splice(i, 1)
+
+const runPhase = (list: Updatable[], dt: number): void => {
+  // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
+  for (const a of list.slice()) a.update?.(dt)
+}
+
+const ensureDispatch = (): void => {
+  if (dispatchInstalled) return
+  dispatchInstalled = true
+  const early: PhaseFn = (dt) => runPhase(earlyUpdaters, dt)
+  const late: PhaseFn = (dt) => runPhase(lateUpdaters, dt)
+  // render-synced source if the engine layer installed one; else one host loop (early then late).
+  if (!(frameInstaller && frameInstaller(early, late))) {
+    setLoop((dt) => { early(dt); late(dt) })
+  }
+}
+
+const registerUpdater = (a: Updatable): void => {
+  const { early, order } = policyOf(a)
+  addSorted(early ? earlyUpdaters : lateUpdaters, a, order)
+  ensureDispatch()
+}
+const unregisterUpdater = (a: Updatable): void => {
+  let i = earlyUpdaters.indexOf(a)
+  if (i >= 0) { earlyUpdaters.splice(i, 1); return }
+  i = lateUpdaters.indexOf(a)
+  if (i >= 0) lateUpdaters.splice(i, 1)
 }
 
 // ---- the host: mixed into every node kind (Node2D, Node) --------------------
@@ -142,10 +184,24 @@ export abstract class Aspect<K extends string, P = Node> {
   declare protected readonly __key__?: K
   onAttach?(): void
   onDetach?(): void
-  /** Called every frame while attached (dt = seconds since the last frame), via a lazy global loop. */
+  /**
+   * Called every frame while attached (dt = seconds since the last frame). Render-synced: runs in the
+   * LATE phase by default — after the physics step + transform sync, right before the frame draws — so
+   * reads of `node.worldPosition` are the final drawn position (cameras/followers have no 1-frame lag).
+   * Set `updateBeforePhysics = true` (an instance field) to run in the EARLY phase (before the step)
+   * instead — for aspects that WRITE velocity/force/kinematic transforms and want the same frame's
+   * step to consume them. Cameras/followers READ, so they stay in the default LATE phase.
+   */
   update?(dt: number): void
-  /** Opt-in: only run update(dt) while the node is on-screen. Lives on the aspect (not the node) so
-   *  aspects on the same node can choose independently. NOOP for now — visibility culling isn't wired
-   *  yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
+
+  /** Run update(dt) in the EARLY phase (before the physics step) rather than the default LATE phase.
+   *  An instance field (like `updateWhenVisible`) — set it as a class field: `updateBeforePhysics = true`.
+   *  Use only when you FEED the simulation (velocity/force/kinematic transform). Read once, at attach. */
+  updateBeforePhysics = false
+  /** Tick order within a phase — ascending; default 0, ties keep attach order. Read once, at attach. */
+  order = 0
+
+  /** Opt-in: only run update(dt) while the node is on-screen. NOOP for now — visibility culling isn't
+   *  wired yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
   updateWhenVisible = false
 }

package/runtime/sdk/g2/Scene2D.ts

@@ -2,12 +2,29 @@
 // 2D engine and starts its RAF loop; only the active scene renders. Grown from the Phase 0 seed.
 
 import { Color, type ColorInput } from "../core/color"
+import { _installAspectFrames } from "../core/Aspect"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
 import { node2dRegistry, type Node2D } from "./Node2D"
 import { ensurePointerEvents } from "./touch"
 
+// Route aspect update(dt) through the render-synced native phases (c2dRender early = before physics,
+// late = after animations / before draw), so followers/cameras are in lockstep with the draw. Done from
+// the 2D layer (not core) so a 3D-only bundle never pulls in the 2D bridge. Installed once, lazily on
+// the first Scene2D. 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 _creator2d.setEarlyUpdate !== "function") return false
+    _creator2d.setEarlyUpdate(early)
+    _creator2d.setLateUpdate(late)
+    return true
+  })
+}
+
 export type Scene2DOptions = {
   /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
   background?: ColorInput
@@ -38,6 +55,7 @@ export class Scene2D {
   readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void> = []
 
   constructor(options: Scene2DOptions = {}) {
+    installRenderSyncedFrames()
     this.id = _creator2d.createScene()
     this.camera = new Camera2D(this.id)
     if (options.background !== undefined) this.background = options.background

package/runtime/sdk/g2/Sprite.ts

@@ -4,11 +4,15 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { Vec2, type Vec2Like } from "../math/vec"
+import { Canvas, isCanvas } from "../canvas/Canvas"
 import { Node2D } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
 
+/** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
+export type TextureSource = Texture2D | Canvas
+
 export type SpriteOptions = {
-  texture?: Texture2D
+  texture?: TextureSource
   /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
   anchor?: Vec2Like
   /** World size; defaults to the texture's pixel dimensions. */
@@ -44,10 +48,11 @@ export class Sprite extends Node2D {
   }
 
   get texture(): Texture2D | undefined { return this._texture }
-  set texture(t: Texture2D | undefined) {
-    this._texture = t
-    if (!t) return
-    _creator2d.setSprite(this.id, t.id) // native resets UV + size to the full texture
+  set texture(t: TextureSource | undefined) {
+    const tex = isCanvas(t) ? t.texture() : t   // a Canvas bakes to a texture on assign
+    this._texture = tex
+    if (!tex) return
+    _creator2d.setSprite(this.id, tex.id) // native resets UV + size to the full texture
     if (this._size) _creator2d.setSpriteSize(this.id, this._size.x, this._size.y)
   }
 

package/runtime/sdk/g2/Texture2D.ts

@@ -17,6 +17,14 @@ export class Texture2D {
     this.height = height
   }
 
+  // Wrap a Canvas's baked surface as a texture (RGBA8, already rasterized → synchronous, no decode).
+  // Structural type avoids a Canvas import cycle (Canvas imports Texture2D).
+  static fromCanvas(canvas: { _bakeSurface(): number, width: number, height: number, pixelRatio: number }): Texture2D {
+    const surfaceId = canvas._bakeSurface()
+    const texId = _creator2d.createTextureFromCanvas(surfaceId)
+    return new Texture2D(texId, Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio))
+  }
+
   static load(source: string | FetchResponse): Promise<Texture2D> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {

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/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

@@ -17,6 +17,10 @@ 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"

package/runtime/sdk/ui/UIImage.ts

@@ -1,13 +1,28 @@
 import type { FetchResponse } from "../runtime/fetch"
 import type { SvgSourceValue as SvgSource } from "../runtime/misc"
 import type { File } from "../runtime/fetch"
+import { Canvas, isCanvas } from "../canvas/Canvas"
 import { Element, type AnimateStyle, type Color, type ElementStyle, type OnLayoutCallback, type Style } from "./UINode"
 
 export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
 
+/** A baked Canvas surface as an image source. The UI backend resolves it to a UI texture — see
+ *  docs/canvas-contract.md ("Pending"). */
+export type CanvasImageSource = { canvasSurface: number }
+
+/** Accepted image sources. A Canvas is baked to a surface marker on assign. */
+export type ImageSource = string | FetchResponse | File | SvgSource | Canvas
+
+const toSrc = (src: ImageSource): string | FetchResponse | File | SvgSource | CanvasImageSource =>
+  isCanvas(src) ? { canvasSurface: src._bakeSurface() } : src
+
+/** The stored/resolved image source (a Canvas is resolved to a surface marker). */
+export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource
+
 export interface UIImage {
   readonly type: "image",
-  src: string | FetchResponse | File | SvgSource,
+  get src(): ResolvedImageSource
+  set src(value: ImageSource)
   style: Style<this, UIImageStyle>
   animateTo: AnimateStyle<this, UIImageStyle>
   animateFrom: AnimateStyle<this, UIImageStyle>
@@ -23,23 +38,23 @@ export interface UIImage {
 }
 
 class ImageElement extends Element<"image"> {
-  private _src: string | FetchResponse | File | SvgSource
+  private _src: ResolvedImageSource
   // Current source sub-rect; undefined until the first setSourceRect. Kept on the node (not
   // just sent as a command) so a crop set while detached (_id == 0) is reapplied at mount —
   // the viewer reads it when it creates the element.
   private _sourceRect?: [number, number, number, number]
-  constructor(style: any, src: string | FetchResponse | File | SvgSource) {
+  constructor(style: any, src: ImageSource) {
     super("image", style)
-    this._src = src
+    this._src = toSrc(src)
   }
 
-  get src() {
+  get src(): ResolvedImageSource {
     return this._src
   }
-  set src(value) {
-    this._src = value
+  set src(value: ImageSource) {
+    this._src = toSrc(value)
     if (this._id !== 0) {
-      _creatorUI.updateNode(this._id, "src", value)
+      _creatorUI.updateNode(this._id, "src", this._src)
     }
   }
 
@@ -57,9 +72,9 @@ class ImageElement extends Element<"image"> {
   }
 }
 
-export function UIImage(src: string | FetchResponse | File | SvgSource): UIImage
-export function UIImage(style: UIImageStyle, src: string | FetchResponse | File | SvgSource): UIImage
-export function UIImage(...args: [string | FetchResponse | File | SvgSource] | [UIImageStyle, string | FetchResponse | File | SvgSource]): UIImage {
+export function UIImage(src: ImageSource): UIImage
+export function UIImage(style: UIImageStyle, src: ImageSource): UIImage
+export function UIImage(...args: [ImageSource] | [UIImageStyle, ImageSource]): UIImage {
   if (args.length === 1) {
     return new ImageElement({}, args[0])
   } else {

package/runtime/sdk/ui/UIScreen.ts

@@ -3,7 +3,12 @@ import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type C
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & ScrollStyle & BaseStyle & ScrollStyle & { refreshControlColor?: Color }
 
-export interface UIScreen <Scrollable extends boolean = boolean> {
+// Default to `false`: a bare `UIScreen` means the non-scrollable screen the `UIScreen(...)`
+// constructor returns, so `const s: UIScreen = UIScreen([...])` type-checks. The type is invariant
+// in `Scrollable` (the fluent `style()` puts `this` in a contravariant position), so a `boolean`
+// default wouldn't accept the constructor's `UIScreen<false>`. Opt into scrolling via
+// `.makeScrollable(): UIScreen<true>`; write `UIScreen<boolean>` explicitly when you need the union.
+export interface UIScreen <Scrollable extends boolean = false> {
   readonly type: "screen",
   scrollable: Scrollable,
   style: Style<this, UIScreenStyle>,
@@ -31,7 +36,7 @@ export interface UIScreen <Scrollable extends boolean = boolean> {
 
   onLayout(onLayout: OnLayoutCallback): this
 
-  onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
+  onTouchStart(callback: (ev: TouchStartEvent<UIScreen<boolean>>) => void): this,
 }
 
 export class ScreenElement extends ContainerElement<"screen"> {