lecodes-cli 0.1.7 → 0.3.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.3.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.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 })
+}