lecodes-cli 0.1.7 → 0.2.0

package/README.md

@@ -13,6 +13,12 @@ npm i -g lecodes-cli      # then run: lecodes <command>
 npx lecodes-cli <command>
 ```
 
+The `render` command additionally needs the optional peer **[`lecodes-renderer`](https://www.npmjs.com/package/lecodes-renderer)** (`>= 0.2.0`, for UI + 2D rendering), plus `@napi-rs/canvas` for PNG output:
+
+```sh
+npm i -D lecodes-renderer @napi-rs/canvas
+```
+
 ## Quick start
 
 ```sh
@@ -35,7 +41,7 @@ lecodes preview > app.js            # compile the local project to JS
 | `pull` | Overwrite local files with the project's current remote state. `--force` to discard local edits. |
 | `push` | Push all local changes as **one** new checkpoint. `-m`/`--message` for the message, `--force` to override the "server moved on" guard. |
 | `preview` | Compile the local project to a single JS bundle, printed to **stdout** (pipeable). `-o`/`--out <file>` to write a file, `--entry <path>` to override the entrypoint, `--no-header` to omit the metadata header, `--public-url <url>` for the asset URL prefix. Diagnostics go to stderr. |
-| `render` | Render the local **UI** project. By default emits a semantic JSON description (great for AI/automated checks) to stdout or `-o`/`--out <file>`; `--png [file]` rasterizes a PNG (default `screenshot.png`, `--scale <n>` for DPR). `--width`/`--height` set the viewport (default 390×844). Requires the optional `lecodes-renderer` package (`npm i -D lecodes-renderer`); PNG also needs `@napi-rs/canvas`. 3D scenes aren't rendered. |
+| `render` | Render the local project (**UI + 2D**). By default emits a semantic JSON description (great for AI/automated checks) to stdout or `-o`/`--out <file>`; `--png [file]` rasterizes a PNG (default `screenshot.png`, `--scale <n>` for DPR). A creator-2d scene is composited **under** the UI; `--time <ms>` advances its physics/animation. `asset('./x.png')` resources (images, sprite textures) load from the local working tree by default — use `--remote-assets` (or an explicit `--public-url`) to fetch them from the server instead (which then needs `--wait-network`). `--width`/`--height` set the viewport (default 390×844). Requires the optional `lecodes-renderer` package (`npm i -D lecodes-renderer@^0.2.0`); PNG also needs `@napi-rs/canvas`. 3D scenes aren't rendered. |
 
 ## How it works
 

package/dist/index.js

@@ -892,7 +892,7 @@ var collectEntries = (root, manifest, project) => {
       const src = serverByPath.get(file.path)?.fileSrc;
       if (!src)
         warnings.push(`No server URL for ${file.path} — push it so its URL resolves.`);
-      entries.push({ path: file.path, type, fileSrc: src });
+      entries.push({ path: file.path, type, fileSrc: src, absPath: file.absPath });
     } else if (type === "shader") {
       const shaders = serverByPath.get(file.path)?.shaders;
       if (!shaders?.length)
@@ -907,13 +907,13 @@ var collectEntries = (root, manifest, project) => {
 
 // src/compile/projectCompile.ts
 import { existsSync as existsSync6 } from "node:fs";
-import { createRequire as createRequire2 } from "node:module";
+import { createRequire as createRequire3 } from "node:module";
 import { dirname as dirname5, join as join9 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 // ../sdk/src/compile/bundler.ts
-import * as esbuild from "esbuild";
 import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync7, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { createRequire as createRequire2 } from "node:module";
 import { dirname as dirname4, join as join8, relative as relative2 } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -942,6 +942,36 @@ var desugarAssetMacros = (src, filePath) => {
 ` + out;
 };
 
+// ../sdk/src/compile/aspectMacro.ts
+var ASPECT_RE = /\bclass\s+\w+\s+extends\s+Aspect\s*<\s*(["'])((?:[^"'\\]|\\.)*)\1[^{};]*>\s*\{/g;
+var hasAspectExtends = (src) => /\bextends\s+Aspect\s*</.test(src);
+var injectAspectNames = (src) => {
+  let out = "";
+  let last = 0;
+  ASPECT_RE.lastIndex = 0;
+  let m;
+  while ((m = ASPECT_RE.exec(src)) !== null) {
+    const braceEnd = m.index + m[0].length;
+    if (!classBodyDeclaresAspect(src, braceEnd)) {
+      out += src.slice(last, braceEnd) + ` static aspect = ${JSON.stringify(m[2])};`;
+      last = braceEnd;
+    }
+  }
+  return last === 0 ? src : out + src.slice(last);
+};
+var classBodyDeclaresAspect = (src, from) => {
+  let depth = 1;
+  let i = from;
+  for (;i < src.length && depth > 0; i++) {
+    const c2 = src[i];
+    if (c2 === "{")
+      depth++;
+    else if (c2 === "}")
+      depth--;
+  }
+  return /\bstatic\b[^;{}()=]*\baspect\b/.test(src.slice(from, i));
+};
+
 // ../sdk/src/compile/bundler.ts
 var resolveInject = () => {
   const override = process.env.LECODES_SDK_INJECT;
@@ -951,10 +981,7 @@ var resolveInject = () => {
   const src = join8(here, "..", "inject.ts");
   if (existsSync5(src))
     return src;
-  const dist = join8(here, "..", "..", "dist", "inject.js");
-  if (existsSync5(dist))
-    return dist;
-  throw new Error("sdk: could not locate the inject entry (LECODES_SDK_INJECT / src/inject.ts / dist/inject.js)");
+  throw new Error("sdk: could not locate the inject source (LECODES_SDK_INJECT / src/inject.ts)");
 };
 var normalize = (path) => {
   const parts = [];
@@ -968,79 +995,12 @@ var normalize = (path) => {
   }
   return "/" + parts.join("/");
 };
-var dirOf = (path) => {
-  const i = path.lastIndexOf("/");
-  return i <= 0 ? "/" : path.slice(0, i);
-};
-var hasExtension = (path) => /\.[a-zA-Z0-9]+$/.test(path);
-var resolveBase = (importer, specifier) => {
-  if (specifier.startsWith("/"))
-    return normalize(specifier);
-  if (specifier.startsWith("./") || specifier.startsWith("../"))
-    return normalize(dirOf(importer) + "/" + specifier);
-  throw new Error(`Bare imports are not allowed — the whole SDK is available as globals (no imports): ${specifier}`);
-};
-var resolveWithExtensions = (files, importer, specifier) => {
-  const base = resolveBase(importer, specifier);
-  if (hasExtension(base)) {
-    if (files.has(base))
-      return base;
-    throw new Error(`Module not found: ${base}`);
-  }
-  for (const candidate of [base, `${base}.ts`, `${base}.js`]) {
-    if (files.has(candidate))
-      return candidate;
-  }
-  throw new Error(`Module not found: ${specifier} from ${importer}`);
-};
-var getLoader = (path) => path.endsWith(".ts") ? "ts" : "js";
-var bundleProjectEsbuild = async (entrypoint, files, format = "esm") => {
-  const fileMap = new Map(Object.entries(files).map(([k, v]) => [normalize(k), v]));
-  const entry = normalize(entrypoint);
-  if (!fileMap.has(entry))
-    throw new Error(`Entrypoint not found: ${entry}`);
-  const plugin = {
-    name: "memfs",
-    setup(build2) {
-      build2.onResolve({ filter: /^entry$/ }, () => ({ path: entry, namespace: "mem" }));
-      build2.onResolve({ filter: /.*/, namespace: "mem" }, (args) => {
-        try {
-          return { path: resolveWithExtensions(fileMap, args.importer || entry, args.path), namespace: "mem" };
-        } catch (error) {
-          return { errors: [{ text: error instanceof Error ? error.message : String(error) }] };
-        }
-      });
-      build2.onLoad({ filter: /.*/, namespace: "mem" }, (args) => {
-        const contents = fileMap.get(args.path);
-        if (contents == null)
-          return { errors: [{ text: `Module not found: ${args.path}` }] };
-        const finalContents = /\.[tj]sx?$/.test(args.path) && hasAssetMacro(contents) ? desugarAssetMacros(contents, args.path) : contents;
-        return { contents: finalContents, loader: getLoader(args.path), resolveDir: dirOf(args.path) };
-      });
-    }
-  };
-  const result = await esbuild.build({
-    stdin: { contents: `import "entry";`, loader: "js", sourcefile: "bootstrap.js" },
-    inject: [resolveInject()],
-    define: { RAD2DEG: "57.29577951308232", DEG2RAD: "0.017453292519943295" },
-    bundle: true,
-    write: false,
-    format,
-    platform: "browser",
-    plugins: [plugin],
-    charset: "utf8"
-  });
-  const output = result.outputFiles?.[0];
-  if (!output)
-    throw new Error("Compilation produced no output");
-  return output.text;
-};
 var CHISEL_DEFINE = { RAD2DEG: "57.29577951308232", DEG2RAD: "0.017453292519943295" };
 var CHISEL_KEEP = ["_*"];
 var resolveSdkSrc = () => {
   const inject = resolveInject();
   if (!inject.endsWith("inject.ts")) {
-    throw new Error(`chisel needs the SDK source tree (src/inject.ts); got a prebuilt inject at ${inject}. ` + `Set LECODES_SDK_INJECT to the source, or use esbuild (unset LECODES_BUNDLER).`);
+    throw new Error(`chisel needs the SDK source tree (src/inject.ts); got ${inject}. Set LECODES_SDK_INJECT to the source.`);
   }
   return dirname4(inject);
 };
@@ -1057,7 +1017,7 @@ var collectSdkFiles = (sdkSrc) => {
       if (statSync(p).isDirectory())
         walk(p);
       else if (isSdkSource(p))
-        out["/__sdk/" + relative2(sdkSrc, p)] = readFileSync7(p, "utf8");
+        out["/__sdk/" + relative2(sdkSrc, p).split("\\").join("/")] = readFileSync7(p, "utf8");
     }
   };
   walk(sdkSrc);
@@ -1071,20 +1031,26 @@ var resolveChiselBin = () => {
       return override;
     throw new Error(`LECODES_CHISEL_BIN points at a missing file: ${override}`);
   }
-  const here = dirname4(fileURLToPath(import.meta.url));
-  for (const rel of ["release/chisel", "debug/chisel"]) {
-    const p = join8(here, "..", "..", "..", "..", "..", "chisel", "target", rel);
-    if (existsSync5(p))
-      return p;
-  }
-  throw new Error("chisel binary not found. Build it (`cargo build --release` in the chisel repo) or set LECODES_CHISEL_BIN.");
+  try {
+    const bin = createRequire2(import.meta.url)("@letary/chisel").binaryPath();
+    if (bin && existsSync5(bin))
+      return bin;
+  } catch {}
+  throw new Error("chisel binary not found. Install @letary/chisel, or set LECODES_CHISEL_BIN.");
 };
 var bundleProjectChisel = async (entrypoint, files, format, sourcemap) => {
   const entry = normalize(entrypoint);
   const projFiles = {};
   for (const [k, v] of Object.entries(files)) {
     const path = normalize(k);
-    projFiles[path] = /\.[tj]sx?$/.test(path) && hasAssetMacro(v) ? desugarAssetMacros(v, path) : v;
+    let src = v;
+    if (/\.[tj]sx?$/.test(path)) {
+      if (hasAssetMacro(src))
+        src = desugarAssetMacros(src, path);
+      if (hasAspectExtends(src))
+        src = injectAspectNames(src);
+    }
+    projFiles[path] = src;
   }
   if (!projFiles[entry])
     throw new Error(`Entrypoint not found: ${entry}`);
@@ -1118,12 +1084,7 @@ var bundleProjectChisel = async (entrypoint, files, format, sourcemap) => {
     throw new Error("chisel produced no code");
   return { code: parsed.code, map: parsed.map ?? null };
 };
-var bundleProjectWithMap = async (entrypoint, files, format = "esm") => {
-  if (process.env.LECODES_BUNDLER === "chisel") {
-    return bundleProjectChisel(entrypoint, files, format, true);
-  }
-  return { code: await bundleProjectEsbuild(entrypoint, files, format), map: null };
-};
+var bundleProjectWithMap = async (entrypoint, files, format = "esm") => bundleProjectChisel(entrypoint, files, format, true);
 
 // ../sdk/src/compile/header.ts
 var buildHeader = (name, code, opts = {}) => {
@@ -1234,18 +1195,14 @@ var resolveChiselBin2 = () => {
   if (process.env.LECODES_CHISEL_BIN)
     return process.env.LECODES_CHISEL_BIN;
   try {
-    return createRequire2(import.meta.url)("@letary/chisel").binaryPath() ?? null;
+    return createRequire3(import.meta.url)("@letary/chisel").binaryPath() ?? null;
   } catch {
     return null;
   }
 };
-if (!process.env.LECODES_BUNDLER) {
-  const chiselBin = resolveChiselBin2();
-  if (chiselBin) {
-    process.env.LECODES_CHISEL_BIN = chiselBin;
-    process.env.LECODES_BUNDLER = "chisel";
-  }
-}
+var chiselBin = resolveChiselBin2();
+if (chiselBin)
+  process.env.LECODES_CHISEL_BIN = chiselBin;
 var compileProject2 = (opts) => compileProject({
   entries: opts.entries.map((e) => ({ path: e.path, type: e.type, text: e.text, fileSrc: e.fileSrc, shaders: e.shaders })),
   name: opts.name,
@@ -1293,6 +1250,7 @@ var preview = async (args) => {
 // src/commands/render.ts
 import { writeFileSync as writeFileSync8 } from "node:fs";
 import { resolve as resolve4 } from "node:path";
+var LOCAL_ASSET_SCHEME = "lecodesfile://";
 var DEVICE_SAFE_AREA = {
   none: [0, 0, 0, 0],
   iphone: [47, 0, 34, 0],
@@ -1329,12 +1287,16 @@ var render = async (args) => {
   const token = requireToken(config);
   note("Resolving project assets…");
   const project = await getProject(apiUrl, token, manifest.uuid);
-  const { entries, warnings } = collectEntries(root, manifest, project);
+  const { entries, warnings: collectWarnings } = collectEntries(root, manifest, project);
+  const publicUrlFlag = flagStr(args, "public-url");
+  const useLocalAssets = !publicUrlFlag && !flagBool(args, "remote-assets");
+  const compileEntries = useLocalAssets ? entries.map((e) => e.type === "resource" && e.absPath ? { ...e, fileSrc: encodeURIComponent(e.absPath) } : e) : entries;
+  const warnings = useLocalAssets ? collectWarnings.filter((w) => !w.includes("No server URL")) : collectWarnings;
   note("Compiling…");
   const js = await compileProject2({
-    entries,
+    entries: compileEntries,
     name: manifest.name,
-    publicUrl: flagStr(args, "public-url") ?? apiUrl,
+    publicUrl: useLocalAssets ? LOCAL_ASSET_SCHEME : publicUrlFlag ?? apiUrl,
     entryOverride: flagStr(args, "entry"),
     header: false,
     format: "iife"
@@ -1342,6 +1304,9 @@ var render = async (args) => {
   if (js.includes("_creator.createScene") || js.includes("_creator.createEntity")) {
     warnings.push("This looks like a 3D/GL project — only the UI layer is rendered.");
   }
+  if (js.includes("_creator2d") && !useLocalAssets && !flagBool(args, "wait-network")) {
+    warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).");
+  }
   let renderer;
   try {
     renderer = await import("lecodes-renderer/headless");
@@ -1356,6 +1321,7 @@ var render = async (args) => {
   const timing = {
     settleMs: settleStr !== undefined ? Number(settleStr) : undefined,
     waitNetwork: flagBool(args, "wait-network"),
+    localAssets: useLocalAssets,
     timeMs: timeStr !== undefined ? Number(timeStr) : undefined,
     afterAnimations: !flagBool(args, "no-after-animations"),
     safeArea: resolveSafeArea(args),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -21,17 +21,16 @@
   },
   "scripts": {
     "vendor-runtime": "bun scripts/vendor-runtime.ts",
-    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external esbuild --external @letary/chisel --external lecodes-renderer --banner=\"#!/usr/bin/env node\"",
+    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --banner=\"#!/usr/bin/env node\"",
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.1.2",
-    "esbuild": "^0.27.3"
+    "@letary/chisel": "^0.1.2"
   },
   "peerDependencies": {
-    "lecodes-renderer": "^0.1.1"
+    "lecodes-renderer": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "lecodes-renderer": {

package/runtime/sdk/core/Aspect.ts

@@ -0,0 +1,151 @@
+// The Aspect system: attachable capabilities (animation, collider, physics, and user behaviors)
+// that hang off a node WITHOUT bloating the node class. Composition with the terseness of methods.
+//
+//   const hero = new Sprite({ texture })
+//     .aspect(SpriteAnimation, { fps: 8, clips: { walk: [1, 2, 3] } })   // attach + configure
+//     .aspect(Collider, { box: [16, 8], trigger: true })                 // chains: returns the node
+//   hero.anim.play('walk')          // access by name (the chain result is typed as having it)
+//   if (hero.has(Physics)) hero.physics.velocity = [0, 0]                // has() is a type guard
+//
+// A user aspect declares its name + target node in the generic and reads `this.node`:
+//   class Health extends Aspect<'health', Sprite> { hp = 100; hurt(n: number) { this.hp -= n } }
+//   sprite.aspect(Health, { hp: 80 }).health.hurt(10)
+//
+// The accessor name lives in the generic (Aspect<'name', Node>). The `chisel` bundler extracts it at
+// compile time and injects the runtime `static aspect` on user aspects + the virtual type accessor;
+// the SDK's own built-in aspects declare `static readonly aspect` directly (see SpriteAnimation etc.).
+
+import { Emitter, type EventMap } from "./events"
+import type { Node } from "../gl/Node"
+
+// ---- type helpers -----------------------------------------------------------
+/** The class object of an aspect — accepted even when its constructor is protected/abstract. */
+export type AspectCtor<A extends Aspect<any, any>> = abstract new () => A
+/** The accessor name carried in the aspect's generic. */
+export type KeyOf<A> = A extends Aspect<infer K, any> ? K : never
+/** The node kind an aspect targets. */
+export type TargetOf<A> = A extends Aspect<any, infer P> ? P : never
+/** `{ name: Aspect }` — the field an aspect contributes to its node. */
+export type FieldOf<A extends Aspect<any, any>> = { [P in KeyOf<A>]: A }
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
+
+/**
+ * A variable typed as a node KNOWN to carry the given aspect(s). Union, not a tuple — reads as
+ * English and mirrors the runtime guard `node.has(Health)`:
+ *   let boss: With<Sprite, Health | Physics>
+ */
+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)
+    }
+  })
+}
+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)
+}
+
+// ---- the host: mixed into every node kind (Node2D, Node) --------------------
+/**
+ * Base for anything that can carry aspects. Extends Emitter, so node kinds get events too. Provides
+ * the four verbs; the named accessor (node.physics, node.health, …) is set as an own property at
+ * attach time, keyed by the aspect class's runtime `aspect` name.
+ */
+export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<E> {
+  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  readonly _aspects = new Map<Function, Aspect<any, any>>()
+
+  /** Attach (and configure) an aspect, or reconfigure it if already present. Returns the node typed
+   *  as now-having that aspect (so no guard/`?.` is needed afterwards). Rejects a wrong target node. */
+  aspect<Self extends TargetOf<A>, A extends Aspect<any, any>>(
+    this: Self,
+    ctor: AspectCtor<A>,
+    opts?: Partial<A>,
+  ): Self & FieldOf<A> {
+    const host = this as unknown as AspectHost
+    let inst = host._aspects.get(ctor) as A | undefined
+    const fresh = inst === undefined
+    if (!inst) {
+      inst = new (ctor as unknown as new () => A)()
+      ;(inst as { node: unknown }).node = this
+      host._aspects.set(ctor, inst)
+      const name = (ctor as { aspect?: string }).aspect
+      if (name) (host as unknown as Record<string, unknown>)[name] = inst
+    }
+    if (opts) Object.assign(inst, opts)
+    if (fresh) {
+      inst.onAttach?.()
+      if (typeof inst.update === "function") registerUpdater(inst)
+    }
+    return this as Self & FieldOf<A>
+  }
+
+  /** Safe access — undefined if the aspect isn't attached. */
+  get<A extends Aspect<any, any>>(ctor: AspectCtor<A>): A | undefined {
+    return this._aspects.get(ctor) as A | undefined
+  }
+
+  /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
+  has<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
+    return this._aspects.has(ctor)
+  }
+
+  /** Detach an aspect (runs its onDetach). Named `removeAspect` so it never collides with the
+   *  child-management `add`/`remove` semantics some node kinds expose. */
+  removeAspect<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this {
+    const inst = this._aspects.get(ctor)
+    if (inst) {
+      inst.onDetach?.()
+      unregisterUpdater(inst)
+      this._aspects.delete(ctor)
+      const name = (ctor as { aspect?: string }).aspect
+      if (name) delete (this as unknown as Record<string, unknown>)[name]
+    }
+    return this
+  }
+}
+
+// ---- the aspect base --------------------------------------------------------
+/**
+ * Base for everything you attach. `K` = accessor name (extracted by chisel for the runtime). `P` =
+ * the target node kind: `this.node` is typed to it, AND attaching to a wrong node is a compile error.
+ * Initialize in `onAttach` (the node is set by then) — not a constructor; aspects are created by the
+ * engine via `node.aspect()`, never `new`.
+ */
+export abstract class Aspect<K extends string, P = Node> {
+  // NOTE: P has no `extends AspectHost` constraint on purpose — Emitter<E>'s generic
+  // addEventListener makes a specific-event node (AspectHost<NodeEvents>) not assignable to
+  // AspectHost<any>, which would reject every real node. P only types `this.node`; target
+  // enforcement happens in aspect() via `this: Self extends TargetOf<A>`. Defaults to Node
+  // (3D is the default engine) — a 2D aspect declares its own P, e.g. Aspect<'x', Sprite>.
+  /** The node this aspect is attached to (set at attach time). */
+  readonly node!: P
+  /** @internal phantom — lets the type system recover the accessor name `K`. Never read at runtime. */
+  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. */
+  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. */
+  updateWhenVisible = false
+}

package/runtime/sdk/g2/Camera2D.ts

@@ -1,16 +1,8 @@
-// Orthographic camera for a Scene2D. Position/zoom/rotation live natively; `follow` adds a
-// render-synced per-frame update that tracks a node.
+// Orthographic camera for a Scene2D. Position / zoom / rotation live natively. To make the camera
+// track a node, attach a small update(dt) aspect that eases camera.position toward the node — there's
+// no built-in follow() (and so nothing to dispose).
 
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
-import type { Node2D } from "./Node2D"
-import { offUpdate, onUpdate } from "./loop"
-
-export type FollowOptions = {
-  /** World-space offset added to the target's position. */
-  offset?: Vec2Like
-  /** 0 = snap (default). >0 = exponential smoothing time constant in seconds (smaller = snappier). */
-  smooth?: number
-}
 
 export class Camera2D {
   private _x = 0
@@ -18,10 +10,6 @@ export class Camera2D {
   private _zoom = 1
   private _rotation = 0
 
-  private _followTarget: Node2D | null = null
-  private _followOpts: FollowOptions = {}
-  private _followCb: ((dt: number) => void) | null = null
-
   private readonly sceneId: number
   constructor(sceneId: number) { this.sceneId = sceneId }
 
@@ -42,32 +30,4 @@ export class Camera2D {
     const o = _creator2d.cameraWorldToScreen(this.sceneId, worldX, worldY)
     return new Vec2(o[0], o[1])
   }
-
-  /** Track a node each frame (snaps by default; pass `smooth` for eased follow). */
-  follow(node: Node2D, options: FollowOptions = {}): this {
-    this._followTarget = node
-    this._followOpts = options
-    if (this._followCb) return this
-    this._followCb = (dt: number) => {
-      const t = this._followTarget
-      if (!t) return
-      const [ ox, oy ] = this._followOpts.offset ?? [ 0, 0 ]
-      const tx = t.x + ox
-      const ty = t.y + oy
-      const s = this._followOpts.smooth ?? 0
-      if (s > 0) {
-        const k = 1 - Math.exp(-dt / s)
-        this.position = [ this._x + (tx - this._x) * k, this._y + (ty - this._y) * k ]
-      } else {
-        this.position = [ tx, ty ]
-      }
-    }
-    onUpdate(this._followCb)
-    return this
-  }
-
-  unfollow(): void {
-    this._followTarget = null
-    if (this._followCb) { offUpdate(this._followCb); this._followCb = null }
-  }
 }

package/runtime/sdk/g2/CharacterController2D.ts

@@ -0,0 +1,75 @@
+// A platformer-friendly character controller, as an aspect on a Node2D. Built on a fixed-rotation
+// dynamic Physics2D body: you drive horizontal intent + jump, and Box2D handles gravity, falling, and
+// wall/floor collision response; a short downward ray reports `grounded`.
+//
+//   const hero = new Sprite({ texture, anchor: [0.5, 1] })
+//     .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true, shape: { type: 'capsule', from:[0,6], to:[0,26], radius:6 } })
+//     .aspect(CharacterController2D, { speed: 200, jumpSpeed: 520 })
+//   Input.on('left',  d => hero.controller.move(d ? -1 : 0))
+//   Input.on('jump',  () => hero.controller.jump())
+//
+// Velocity-control (set velocity each frame) is the standard, robust approach for platformers and
+// reuses the physics solver. For pixel-tight movement without any solver bounce/seam quirks, a
+// kinematic move-and-slide controller can be added later (see creator-2d PLAN.md, Phase G).
+
+import { Aspect } from "../core/Aspect"
+import { Vec2 } from "../math/vec"
+import { Physics2D } from "./Physics2D"
+import { Shape } from "./Shape"
+import type { Node2D } from "./Node2D"
+
+export class CharacterController2D extends Aspect<"controller", Node2D> {
+  static readonly aspect = "controller"
+
+  /** Horizontal move speed (world units/s). */
+  speed = 200
+  /** Jump take-off speed (world units/s). */
+  jumpSpeed = 500
+  /** Extra probe distance below the body's feet used for the grounded check (world units). */
+  groundProbe = 6
+  /** Distance from the node origin down to the feet. Defaults to half the sprite height. */
+  footOffset?: number
+
+  private _moveX = 0
+  private _jumpQueued = false
+  private _grounded = false
+
+  /** Horizontal intent in [-1, 1] (e.g. from input). Sticky — set 0 to stop. Applied next frame. */
+  move(dir: number): void { this._moveX = dir < -1 ? -1 : dir > 1 ? 1 : dir }
+  /** Queue a jump; consumed on the next frame if grounded. */
+  jump(): void { this._jumpQueued = true }
+  /** True while standing on something (updated each frame). */
+  get grounded(): boolean { return this._grounded }
+
+  private get phys(): Physics2D | undefined { return this.node.get(Physics2D) }
+
+  onAttach(): void {
+    // Ensure a Shape (auto box from the sprite) + a dynamic, fixed-rotation body if not already set up.
+    if (!this.node.has(Shape)) this.node.aspect(Shape, {})
+    if (!this.node.has(Physics2D)) this.node.aspect(Physics2D, { motion: "dynamic", fixedRotation: true })
+  }
+
+  update(_dt: number): void {
+    const phys = this.phys
+    if (!phys) return
+
+    // Grounded probe: a short ray straight down from the feet. The ray originates inside the body,
+    // so Box2D won't report the body's own shape; we exclude self defensively too.
+    const pos = this.node.worldPosition
+    const foot = this.footOffset ?? this._spriteHalfHeight()
+    const hit = Physics2D.raycast([pos.x, pos.y - foot * 0.5], [pos.x, pos.y - foot - this.groundProbe])
+    this._grounded = !!hit && hit.node !== this.node
+
+    let vy = phys.velocity.y
+    if (this._jumpQueued && this._grounded) { vy = this.jumpSpeed; this._grounded = false }
+    this._jumpQueued = false
+
+    // Drive horizontal velocity directly; let the sim own vertical (gravity / jump / landing).
+    phys.velocity = new Vec2(this._moveX * this.speed, vy)
+  }
+
+  private _spriteHalfHeight(): number {
+    const size = (this.node as { size?: Vec2 }).size
+    return size ? size.y * 0.5 : 8
+  }
+}