lecodes-sdk 0.20.2 → 1.1.0

package/src/canvas/Canvas.ts

@@ -35,6 +35,11 @@ const OP = {
   DRAW_IMAGE: 30,
 } as const
 
+// Above this many buffered values, a buffer that is STILL growing between bakes is a leak, not a
+// drawing (a dense static picture is a few thousand; a 15 Hz graph without reset() passes this in
+// seconds and doubles its frame cost every minute).
+const CMD_GROWTH_WARN = 20000
+
 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
@@ -76,6 +81,11 @@ export class Canvas {
   // also refreshes the on-screen image node(s) via _creatorUI — the UI consumer the 2D/3D texture
   // hooks below don't cover. Stays a bare flag so a non-UI canvas never references the UI bridge.
   private _uiBound = false
+  // Growth watch: the command buffer is a RECORDING that every bake replays in full, so a canvas
+  // redrawn every frame without `reset()` gets slower with every update. `_bakeSurface` compares the
+  // buffer against the previous bake and warns once when it keeps growing past the threshold.
+  private _lastBakeLen = 0
+  private _warnedGrowth = false
 
   constructor(width: number, height: number, opts: { pixelRatio?: number } = {}) {
     this.width = width
@@ -198,6 +208,17 @@ export class Canvas {
 
   /** @internal — rasterize the recorded commands into the surface; returns the surface id. */
   _bakeSurface(): number {
+    const len = this._cmd.length
+    if (!this._warnedGrowth && len > CMD_GROWTH_WARN && this._lastBakeLen > 0 && len > this._lastBakeLen) {
+      this._warnedGrowth = true
+      console.warn(
+        `[canvas] ${this.width}×${this.height}: the command buffer keeps growing (${len} values, ` +
+        `${this._lastBakeLen} at the previous bake) — a Canvas records every call and each update() ` +
+        `replays all of it, so a redraw that never calls reset() gets slower every frame. ` +
+        `Call canvas.reset() before redrawing (or toBitmap() + reset() to flatten a drawing).`,
+      )
+    }
+    this._lastBakeLen = len
     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

package/src/compile/__tests__/assetMacro.test.ts

@@ -34,6 +34,32 @@ test("the same asset present in the entries compiles to its URL", async () => {
   expect(js).not.toContain("./assets/lightmap.bake")
 })
 
+// Only the modules the bundle reaches are checked: a project keeps one entry per level, and a
+// level whose art is not on this machine must not fail an entry that never imports it.
+test("a missing asset in a module the entry never imports does not fail the compile", async () => {
+  const js = await compileProject({
+    name: "Unreached",
+    publicUrl: "https://le.codes",
+    entries: [
+      { path: "/main.ts", type: "text", text: "const scene = new Scene()\nconsole.log(scene)\n" },
+      { path: "/levels/lost.ts", type: "text", text: "export const lost = asset('./lost.glb')\n" },
+    ],
+  })
+  expect(js).not.toContain("lost.glb")
+})
+
+test("the same missing asset fails once the entry imports its module", async () => {
+  const compile = compileProject({
+    name: "Reached",
+    publicUrl: "https://le.codes",
+    entries: [
+      { path: "/main.ts", type: "text", text: "import { lost } from './levels/lost'\nconsole.log(lost)\n" },
+      { path: "/levels/lost.ts", type: "text", text: "export const lost = asset('./lost.glb')\n" },
+    ],
+  })
+  await expect(compile).rejects.toThrow("asset not found: ./lost.glb (levels/lost.ts:1)")
+})
+
 test("a commented-out asset() is not an asset at all", () => {
   const src = [
     "/** The atlas image — write `asset('./TileSet.png')`. */",

package/src/compile/__tests__/compile.test.ts

@@ -39,6 +39,17 @@ test("a 2D project (new Scene2D) is marked 2d: enable and gl: disable", async ()
   expect(js).toContain("_creator2d.createScene")
 })
 
+test("a 3D project with a Canvas is NOT marked 2d: enable (Canvas keeps a `_creator2d.` texture path)", async () => {
+  const js = await compileProject({
+    name: "Car",
+    publicUrl: "https://le.codes",
+    entries: [ { path: "/main.ts", type: "text", text: "const c = new Canvas(64, 64)\nc.update()\nnew Scene().open()\n" } ],
+  })
+  expect(js).toContain("_creator2d.") // the canvas 2D-texture path survives tree-shaking
+  expect(js).not.toContain("// 2d: enable") // …but no Scene2D → the 2D engine is not in use
+  expect(js).not.toContain("// gl: disable")
+})
+
 test("2D and 3D bundles are DISJOINT (tree-shake drops the other engine)", async () => {
   const twoD = await compileProject({
     name: "2D", publicUrl: "https://le.codes", header: false,

package/src/compile/__tests__/detectEntry.test.ts

@@ -130,3 +130,22 @@ test("compileProject auto-detects the importer as entry and runs the registratio
   expect(js).toContain("app-side-effect")
   expect(js).toContain("register-side-effect")
 })
+
+test("design/ screens are never the entry — a design-only project has none, app code next to a design wins", () => {
+  // A Figma import: screens on the board, shared modules, no app yet. The largest root used to win.
+  const designOnly = detectEntry([
+    text("/design/screens/a4-40.ts", "import { at } from '../shared/figma'\nexport default UIScreen([])\n" + "// big\n".repeat(50)),
+    text("/design/shared/figma.ts", "export const at = () => ({})\n"),
+    text("/app.server.ts", "export function ping() { return 1 }\n"),
+  ])
+  expect(designOnly.entry).toBe("")
+  expect(designOnly.roots).toEqual([])
+
+  // The same project once the app exists: main.ts is the entry however small it is.
+  const withApp = detectEntry([
+    text("/design/screens/a4-40.ts", "export default UIScreen([])\n" + "// big\n".repeat(50)),
+    text("/main.ts", "Router.init(home)\n"),
+  ])
+  expect(withApp.entry).toBe("/main.ts")
+  expect(withApp.roots).toEqual(["/main.ts"])
+})

package/src/compile/__tests__/serverSplit.test.ts

@@ -0,0 +1,27 @@
+import { test, expect } from "bun:test"
+import { compileServerBundle } from "../serverSplit"
+
+// The server bundle's file map is the whole project (a server module may import shared code), and
+// the bundler checks every `asset()` in that map. Seen live 2026-09-17: a Figma-exported design next
+// to app.server.ts failed the SERVER build with "asset not found: ../assets/figma/…" because the
+// map had the screens but not the binaries. Binaries are stubbed, design/ stays out.
+
+const text = (path: string, t: string) => ({ path, type: "text" as const, text: t })
+const res = (path: string) => ({ path, type: "resource" as const, fileSrc: "/uploads/x.bin" })
+
+test("a client screen's asset() does not break the server bundle", async () => {
+  const out = await compileServerBundle({
+    validate: false,
+    entries: [
+      text("/app.server.ts", "export const ping = async () => 1\n"),
+      text("/main.ts", "import { ping } from './app.server'\nconst hero = asset('./hero.png')\nping()\n"),
+      res("/hero.png"),
+      text("/design/screens/a4-40.ts", "export default UIScreen([ UIImage(asset('../assets/figma/a4-40/rectangle.png')), UIImage(asset('../assets/figma/a4-40/logo.svg')) ])\n"),
+      res("/design/assets/figma/a4-40/rectangle.png"),
+      text("/design/assets/figma/a4-40/logo.svg", "<svg/>"),
+    ],
+  })
+  expect(out).not.toBeNull()
+  expect(out!.code).toContain("ping")
+  expect(Object.keys(out!.manifest.modules)).toEqual(["app.server.ts"])
+})

package/src/compile/bundler.ts

@@ -4,7 +4,7 @@ import { createRequire } from "node:module"
 import { dirname, join, relative } from "node:path"
 import { fileURLToPath } from "node:url"
 import { collectAssetMacros, desugarAssetMacros, hasAssetMacro, type AssetMacroRef } from "./assetMacro"
-import type { ScanModule } from "./detectEntry"
+import { scanModulesFallback, type ScanModule } from "./detectEntry"
 import { hasAspectExtends, injectAspectNames } from "./aspectMacro"
 import { hasImportStatement, rewriteLibraryImports } from "./libraryImports"
 
@@ -132,8 +132,30 @@ export const scanModulesChisel = (files: MemoryFiles): Record<string, ScanModule
 }
 
 /**
- * Every `asset('…')` must name a file that's actually in the compile input — a missing one is a
- * COMPILE ERROR, never a fallback.
+ * The modules the bundle will actually contain: everything reachable from `entry` over static
+ * imports (chisel's scan, else the regex scanner — same graph detectEntry roots on). `sources` are
+ * the post-library-rewrite, pre-desugar texts, so a bare `from "acme-ui"` already points into
+ * `/__lib/<slug>/…` and follows through. A dynamic `import()` is not an edge for either scanner.
+ */
+const reachableFrom = (entry: string, sources: MemoryFiles): Set<string> => {
+  const graph = scanModulesChisel(sources) ?? scanModulesFallback(sources)
+  const seen = new Set<string>([ entry ])
+  const queue = [ entry ]
+  while (queue.length > 0) {
+    const file = queue.pop()!
+    for (const target of graph[file]?.imports ?? []) {
+      if (!seen.has(target)) { seen.add(target); queue.push(target) }
+    }
+  }
+  return seen
+}
+
+/**
+ * Every `asset('…')` in a module the bundle REACHES must name a file that's actually in the
+ * compile input — a missing one is a COMPILE ERROR, never a fallback. Modules the entry never
+ * imports are not checked: a project keeps one entry per level, and a level whose GLBs are not on
+ * this machine (gitignored art) must not fail the compile of an entry that never loads it — it
+ * fails its own compile, with the same message (fps-demo demo-logo.ts vs chernobyl, 2026-09-17).
  *
  * chisel used to turn an asset import with no backing module into `const x = "<the specifier>"`:
  * a relative source path nothing resolves at runtime, so the app got a silently broken reference
@@ -173,11 +195,15 @@ const bundleProjectChisel = async (
   //  - inject `static aspect = '<name>'` from `class … extends Aspect<'<name>', …>`
   const projFiles: MemoryFiles = {}
   const assetRefs: { file: string, ref: AssetMacroRef }[] = []
+  // What the module scanner sees: import-rewritten, NOT yet asset-desugared (a desugared asset is a
+  // default import of a non-module — the fallback scanner drops it, chisel's scan would not).
+  const scanSources: MemoryFiles = {}
   for (const [ k, v ] of Object.entries(files)) {
     const path = normalize(k)
     let src = v
     if (/\.[tj]sx?$/.test(path)) {
       if (hasImportStatement(src)) src = rewriteLibraryImports(src, slugs)
+      scanSources[path] = src
       if (hasAssetMacro(src)) {
         const found = collectAssetMacros(src, path)
         for (const ref of found) assetRefs.push({ file: path, ref })
@@ -198,6 +224,7 @@ const bundleProjectChisel = async (
       const path = normalize(`/__lib/${slug}/${k}`)
       let src = v
       if (/\.[tj]sx?$/.test(path)) {
+        scanSources[path] = src
         if (hasAssetMacro(src)) {
           const found = collectAssetMacros(src, path)
           for (const ref of found) assetRefs.push({ file: path, ref })
@@ -209,7 +236,10 @@ const bundleProjectChisel = async (
     }
   }
 
-  assertAssetsExist(assetRefs, projFiles)
+  if (assetRefs.length > 0) {
+    const reachable = reachableFrom(entry, scanSources)
+    assertAssetsExist(assetRefs.filter(({ file }) => reachable.has(file)), projFiles)
+  }
 
   const sdkFiles = collectSdkFiles(resolveSdkSrc())
   // Shipped bundles minify by default; edit-mode bundles pass `false` — mangling erases class

package/src/compile/compileProject.ts

@@ -74,17 +74,47 @@ export type CompileOptions = {
  *  unless `header: false`; `map` is already shifted past that header. */
 export type CompileResult = { code: string, map: string | null, entry: string }
 
+/** The basename a local resource would be looked up by. */
+export const localAssetBase = (path: string): string => path.split(/[\\/]/).pop() ?? path
+
+/**
+ * Runtime lookup names for `localAssets` resources — what the bundle passes to `fetchLocal` and what
+ * a host caller must copy the file to.
+ *
+ * The basename, unless two project files SHARE one: then every sharer takes its whole root-relative
+ * path with the separators folded into `__`. A flat name space is fine until it isn't, and when it
+ * isn't the failure is silent and absurd — the files are staged into one directory, so the last one
+ * copied answers for every `asset()` that ends in that name. Which one wins depends on the scan
+ * order, i.e. on nothing. (2026-09-17: a viewer project carried two asset packs that each ship
+ * `SM_Sign_01..03.glb`; the school's floor-standing "CLEANING IN PROGRESS" A-frame was drawn inside
+ * the shooting range's wall, where a flat 4 mm plate belonged.)
+ */
+export const localAssetNames = (entries: readonly { path: string, type: string }[]): Map<string, string> => {
+  const seen = new Map<string, number>()
+  for (const e of entries) if (e.type === "resource") {
+    const b = localAssetBase(e.path)
+    seen.set(b, (seen.get(b) ?? 0) + 1)
+  }
+  const names = new Map<string, string>()
+  for (const e of entries) if (e.type === "resource") {
+    const b = localAssetBase(e.path)
+    names.set(e.path, (seen.get(b) ?? 0) > 1 ? e.path.replace(/^[./]+/, "").replace(/[\\/]/g, "__") : b)
+  }
+  return names
+}
+
 /** Turn compile entries into the bundler's module map — the per-kind rules of the deployable
  *  bundle (resource → URL export, shader → per-backend URL template, .svg → SvgSource, .json →
  *  data, code verbatim). Exported for callers that build a `libraries` map from entries. */
 export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: string, localAssets?: boolean }): Record<string, string> => {
   const files: Record<string, string> = {}
+  const localNames = localAssetNames(entries)
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // The host resolves the asset by name at runtime (reads the local file → systemId); the
         // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
-        const name = e.path.split(/[\/]/).pop() ?? e.path
+        const name = localNames.get(e.path) ?? localAssetBase(e.path)
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`

package/src/compile/detectEntry.ts

@@ -37,9 +37,14 @@ export type DetectedEntry = {
 export const ENTRY_CONVENTION = "/main.ts"
 
 const isCode = (path: string) => /\.[tj]s$/.test(path) && !path.endsWith(".d.ts")
-/** Never entries: editor plugins and server modules (docs/backend-plan.md — a `*.server.ts` nobody
- *  imports is still not the app; server files compile into their own bundle). */
-const isNonEntry = (path: string) => path.endsWith(".editor.ts") || /\.server\.[tj]s$/.test(path)
+/** Never entries: editor plugins, server modules (docs/backend-plan.md — a `*.server.ts` nobody
+ *  imports is still not the app; server files compile into their own bundle) and anything under
+ *  `design/` — the board's screens are import-graph roots by construction (nothing imports a screen
+ *  file; the board runs them), so without this a project whose app code is still to come had its
+ *  largest design screen picked as the app and failed deep inside it ("asset not found:
+ *  ../assets/figma/…"). A design-only project has no entry, and says so. */
+const isNonEntry = (path: string) =>
+  path.endsWith(".editor.ts") || /\.server\.[tj]s$/.test(path) || /^\/design\//.test(path)
 
 const normalize = (path: string): string => {
   const parts: string[] = []

package/src/compile/header.ts

@@ -33,8 +33,11 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   else if (code.includes("_creator.createEngine")) header += `// gl: defer\n`
 
   // 2D (creator-2d) — non-exclusive: emitted alongside `gl: disable` so hosts skip Filament and a
-  // 2D-aware host brings up the lightweight sokol engine instead.
-  if (code.includes("_creator2d.")) header += `// 2d: enable\n`
+  // 2D-aware host brings up the lightweight sokol engine instead. Keyed on the scene constructor
+  // (like GL above), NOT on any `_creator2d.` reference: Canvas carries a 2D-texture path
+  // (`canvas.texture()` → `_creator2d.createTextureFromCanvas`) that chisel keeps in a pure-3D
+  // bundle, and nothing 2D works without a Scene2D anyway.
+  if (code.includes("_creator2d.createScene")) header += `// 2d: enable\n`
 
   if (code.includes("_creator.createARController")) header += `// ar: enable\n`
 
@@ -61,7 +64,7 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
 /** Same engine signals the header uses, for callers that need the project kind (e.g. icon type). */
 export const detectProjectKind = (code: string): "ar" | "ui" | "2d" | "3d" => {
   if (code.includes("_creator.createARController")) return "ar"
-  if (code.includes("_creator2d.")) return "2d"
+  if (code.includes("_creator2d.createScene")) return "2d"
   if (!code.includes("_creator.")) return "ui"
   return "3d"
 }

package/src/compile/index.ts

@@ -65,6 +65,8 @@ export {
   compileProject,
   compileProjectWithMap,
   entriesToFiles,
+  localAssetNames,
+  localAssetBase,
   type CompileEntry,
   type CompileOptions,
   type CompileFileType,
@@ -73,6 +75,7 @@ export {
 export {
   loadSceneHarness,
   sceneEditorEntries,
+  sceneImportsOf,
   SCENE_ENTRY_PATH,
   SCENE_HARNESS_DIR,
 } from "./sceneEditor"

package/src/compile/sceneEditor.ts

@@ -47,10 +47,44 @@ export const loadSceneHarness = (fallbackDir?: string): Record<string, string> =
  * the project's file list — `.editor.ts` entries are picked out of it. Compile with
  * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`, `editor: true`.
  */
+/** Resolve a relative import specifier against a project path ("./src/map.scene.ts" + "./map/x.scene"
+ *  → "./src/map/x.scene"). */
+const resolveRelative = (fromPath: string, spec: string): string => {
+  const segs = (p: string) => p.split("/").filter((s) => s !== "" && s !== ".")
+  const out = segs(fromPath).slice(0, -1)
+  for (const seg of segs(spec)) {
+    if (seg === "..") out.pop()
+    else out.push(seg)
+  }
+  return "./" + out.join("/")
+}
+
+/**
+ * The other scene files a scene file imports as prefabs (`import x from './x.scene'`), as project
+ * paths present in `projectPaths`. The edit bundle registers their handles BY PATH
+ * (`__lecodesSceneFiles`), so the editor can live-patch a `prefab:` node — add, duplicate, undo —
+ * without a compile: the doc sees `prefab: X` as an identifier, the host maps it through the
+ * file's import table to this path, and the harness resolves the path to the running handle.
+ */
+export const sceneImportsOf = (sceneText: string, scenePath: string, projectPaths: string[]): string[] => {
+  const known = new Set(projectPaths)
+  const out: string[] = []
+  const re = /^\s*import\s+[A-Za-z_$][\w$]*\s+from\s+["']([^"']+\.scene(?:\.ts)?)["']/gm
+  for (const m of sceneText.matchAll(re)) {
+    const spec = m[1]
+    if (!spec.startsWith(".")) continue
+    let p = resolveRelative(scenePath, spec)
+    if (!p.endsWith(".ts")) p += ".ts"
+    if (known.has(p) && !out.includes(p)) out.push(p)
+  }
+  return out
+}
+
 export const sceneEditorEntries = (
   scenePath: string,
   harness: Record<string, string>,
   projectPaths: string[] = [],
+  sceneImports: string[] = [],
 ): CompileEntry[] => {
   const entries: CompileEntry[] = Object.entries(harness).map(([ name, text ]) => ({
     path: `${SCENE_HARNESS_DIR}/${name}`,
@@ -74,15 +108,22 @@ export const sceneEditorEntries = (
   const materialImports = materialPaths.map((p, i) => `import __mat${i} from "${p}"\n`).join("")
   const materialRegister = materialPaths.length === 0 ? ""
     : `;(globalThis as any).__lecodesMaterials = { ${materialPaths.map((p, i) => `${JSON.stringify(p)}: __mat${i}`).join(", ")} }\n`
+  // The scene's prefab imports, registered by project path (see sceneImportsOf) — the same module
+  // instances the scene itself imported, so a live-patched prefab node is the same handle.
+  const sceneImportLines = sceneImports.map((p, i) => `import __scn${i} from "${p}"\n`).join("")
+  const sceneRegister = sceneImports.length === 0 ? ""
+    : `;(globalThis as any).__lecodesSceneFiles = { ${sceneImports.map((p, i) => `${JSON.stringify(p)}: __scn${i}`).join(", ")} }\n`
   entries.push({
     path: SCENE_ENTRY_PATH,
     type: "text",
     text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
       + materialImports
+      + sceneImportLines
       + `import "${scenePath}"\n`
       + editorImports
       + `import "${SCENE_HARNESS_DIR}/main.ts"\n`
-      + materialRegister,
+      + materialRegister
+      + sceneRegister,
   })
   return entries
 }

package/src/compile/serverSplit.ts

@@ -210,11 +210,17 @@ export type CompileServerOptions = {
 export const compileServerBundle = async (opts: CompileServerOptions): Promise<{ code: string, manifest: ServerManifest } | null> => {
   const modules = scanServerModules(opts.entries)
   if (Object.keys(modules).length === 0) return null
+  // The server bundle sees the whole project map (a server module may import shared code), but the
+  // bundler's asset check runs over EVERY file in the map — so binaries and svgs must be present as
+  // stubs, or a client screen's `asset("./x.png")` fails the SERVER build ("asset not found", seen
+  // with a Figma-exported design next to app.server.ts). The board's `design/` files are never
+  // server code and stay out entirely.
   const files: MemoryFiles = {}
   for (const e of opts.entries) {
-    if (e.type !== "text") continue
-    if (e.path.toLowerCase().endsWith(".svg")) continue
-    files[normalizePath(e.path)] = e.text ?? ""
+    const path = normalizePath(e.path)
+    if (/^\/design\//.test(path)) continue
+    if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ""`; continue }
+    files[path] = e.text ?? ""
   }
   let params = opts.params
   if (!params && opts.validate !== false) {

package/src/g2/Node2D.ts

@@ -16,6 +16,19 @@ import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { ensurePointerEvents } from "./touch"
 import { ensurePhysicsEvents } from "./loop"
+import type { Animation } from "../animate/tween/Animation"
+import { CLOCK_GAME, DOM_NODE2D, floatValue, vec2Value, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import { tweenBag } from "../animate/tween/Timeline"
+
+/** Animatable transform props of a 2D node; an array of values is a keyframe list. */
+export type Node2DTweenProps = {
+  x?: number | number[],
+  y?: number | number[],
+  position?: Vec2Like | Vec2Like[],
+  /** Degrees. */
+  rotation?: number | number[],
+  scale?: number | Vec2Like | (number | Vec2Like)[],
+}
 
 // re-exported so existing `import { Vec2 } from "./Node2D"` sites keep working; the canonical home is math/.
 export { Vec2, type Vec2Like }
@@ -135,6 +148,31 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
     _creator2d.setScale(this.id, sx, sy)
   }
 
+  // --- keyframe animation (docs/timeline-plan.md) ---
+  /** Tween the transform — `node.animateTo({ x: 120, rotation: 90, duration: 400, easing: 'outBack' })`;
+   *  arrays are keyframes. Game clock unless `clock: 'ui'`. Returns the {@link Animation} handle. */
+  animateTo(props: Node2DTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, true)
+  }
+  /** Tween FROM the given values to the node's current transform. */
+  animateFrom(props: Node2DTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, false)
+  }
+  /** @internal keyframe-core target protocol */
+  readonly _tweenClock: number = CLOCK_GAME
+  /** @internal */
+  _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    switch (prop) {
+      case "x": return { domain: DOM_NODE2D, id, value: floatValue, commit: (v) => { this._x = v as number } }
+      case "y": return { domain: DOM_NODE2D, id, value: floatValue, commit: (v) => { this._y = v as number } }
+      case "position": return { domain: DOM_NODE2D, id, value: vec2Value, commit: (v) => { this._x = cx(v as Vec2Like); this._y = cy(v as Vec2Like) } }
+      case "rotation": return { domain: DOM_NODE2D, id, value: floatValue, commit: (v) => { this._rotation = v as number } }
+      case "scale": return { domain: DOM_NODE2D, id, value: vec2Value, commit: (v) => { const s = typeof v === "number" ? [v, v] : v as Vec2Like; this._sx = cx(s); this._sy = cy(s) } }
+      default: return null
+    }
+  }
+
   /** Draw layer (int). Higher layers render on top. */
   get layer(): number { return this._layer }
   set layer(v: number) { this._layer = v; _creator2d.setLayer(this.id, v) }

package/src/g2/Sprite.ts

@@ -5,8 +5,16 @@
 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 { Node2D, type Node2DTweenProps } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
+import { DOM_SPRITE2D, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable sprite props on top of the 2D transform. */
+export type SpriteTweenProps = Node2DTweenProps & {
+  opacity?: number | number[],
+  color?: ColorInput | ColorInput[],
+}
 
 /** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
 export type TextureSource = Texture2D | Canvas
@@ -76,6 +84,17 @@ export class Sprite extends Node2D {
     return this
   }
 
+  /** Tween `opacity` / `color` and the transform — see {@link Node2D.animateTo}. */
+  override animateTo(props: SpriteTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: SpriteTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    if (prop === "opacity") return { domain: DOM_SPRITE2D, id, value: floatValue, commit: (v) => { this._opacity = v as number } }
+    if (prop === "color") return { domain: DOM_SPRITE2D, id, value: (v) => colorValue(v, Color.toRgba01), commit: (v) => { this._color = v as ColorInput } }
+    return super._tweenChannel(prop)
+  }
+
   get color(): ColorInput { return this._color }
   set color(c: ColorInput) { this._color = c; const [ r, g, b ] = Color.toRgb01(c); _creator2d.setSpriteColor(this.id, r, g, b) }
 

package/src/gl/Camera.ts

@@ -3,8 +3,17 @@
 
 import { Vec3 } from "../math/vec"
 import { Aspect } from "../core/Aspect"
-import { Node } from "./Node"
+import { Node, type NodeTweenProps } from "./Node"
 import { Ray } from "./Ray"
+import { DOM_GL_CAMERA, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable camera props on top of the node transform. */
+export type CameraTweenProps = NodeTweenProps & {
+  fov?: number | number[],
+  near?: number | number[],
+  far?: number | number[],
+}
 
 /** @internal `camera.follow(node)`: copies the node's world pose onto the camera every LATE frame
  *  (order 1000 — after every other aspect has moved things). One per camera; lives on the target. */
@@ -24,6 +33,24 @@ export const CAMERA_DEFAULTS = { fov: 60, near: 0.01, far: 1000 }
 
 export class Camera extends Node {
   private _sceneId = -1
+
+  /** Tween `fov` / `near` / `far` (a zoom, a dolly) and the transform — see {@link Node.animateTo}. */
+  override animateTo(props: CameraTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: CameraTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal The projection channels address the SCENE (one camera per scene on the host). */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    if (prop === "fov" || prop === "near" || prop === "far") {
+      const id = () => (this._sceneId < 0 ? 0 : this._sceneId + 1)   // scene ids start at 0; 0 = unaddressable
+      const commit = (v: unknown) => {
+        if (prop === "fov") this._fov = v as number
+        else if (prop === "near") this._near = v as number
+        else this._far = v as number
+        this._projSet = true
+      }
+      return { domain: DOM_GL_CAMERA, id, value: floatValue, commit }
+    }
+    return super._tweenChannel(prop)
+  }
   /** Live projection matrix (updated by the host when the viewport/fov changes). */
   readonly projectionMatrix = new Float32Array(16)
 
@@ -57,6 +84,12 @@ export class Camera extends Node {
    *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
    *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
    *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+  /** The camera's EV100 with the compensation in: log2(aperture² / shutterSpeed x 100 / iso) - compensation. Sunny 16 is
+   *  ~15; a lit surface of luminance L lands on screen at L / (1.2 x 2^ev100). */
+  get ev100(): number {
+    const e = this._exposure
+    return Math.log2((e.aperture * e.aperture) / e.shutterSpeed * 100 / e.iso) - this._ev
+  }
   get exposureCompensation(): number { return this._ev }
   set exposureCompensation(stops: number) {
     this._ev = Number.isFinite(stops) ? stops : 0