lecodes-cli 0.10.4 → 0.12.0

package/runtime/sdk/compile/libraryImports.ts

@@ -0,0 +1,52 @@
+// Pre-chisel rewrite of user-library bare-specifier imports. chisel's resolver hard-errors on any
+// bare import (the whole SDK is globals), so a project that imports a component library by its slug
+// —`import { Card } from "acme-ui"`— is rewritten here to the injected library tree under
+// `/__lib/<slug>/…` BEFORE chisel runs. Only libraries present in the dependency map are known
+// slugs; any other bare specifier is an author error, surfaced with a friendly message instead of
+// chisel's generic one. Static string-literal specifiers only — dynamic `import()` is unsupported
+// (documented). Chisel itself is untouched. See docs/library-system-plan.md §4.
+
+/** Cheap pre-check so the regexes don't run over files with no imports at all. */
+export const hasImportStatement = (src: string): boolean => src.includes("import") || src.includes("from")
+
+// A static `from "…"` clause (import-from OR export-from). Anchored at a statement boundary
+// (line start / `;` / `}`) and disallowing quotes/backticks/semicolons between the keyword and
+// `from`, so it can never span into a string literal or a neighbouring statement. Named-import
+// lists may span multiple lines (newlines are allowed between the keyword and `from`).
+const IMPORT_FROM_RE = /(^|[;\n}])(\s*(?:import|export)\b[^"'`;]*?\bfrom\s*)(["'])([^"'\n]+)\3/g
+
+// A side-effect `import "…"` (a bare quote directly after the keyword — not `import x`, not `import(`).
+const SIDE_EFFECT_RE = /(^|[;\n}])(\s*import\s*)(["'])([^"'\n]+)\3/g
+
+const isRelativeOrAbsolute = (spec: string): boolean =>
+  spec.startsWith("/") || spec.startsWith("./") || spec.startsWith("../")
+
+/**
+ * Rewrite every known-library bare import in `src` to its `/__lib/<slug>/…` path. Relative and
+ * absolute specifiers pass through untouched; an unknown bare specifier throws a friendly Error.
+ * `slugs` is the set of library slugs available to this project (its dependency map's keys).
+ */
+export const rewriteLibraryImports = (src: string, slugs: Set<string>): string => {
+  const rewriteSpec = (spec: string): string => {
+    if (isRelativeOrAbsolute(spec)) return spec
+    const slash = spec.indexOf("/")
+    const slug = slash === -1 ? spec : spec.slice(0, slash)
+    if (slugs.has(slug)) {
+      // `acme-ui` → `/__lib/acme-ui/index`; `acme-ui/theme` → `/__lib/acme-ui/theme`.
+      const sub = slash === -1 ? "/index" : spec.slice(slash)
+      return `/__lib/${slug}${sub}`
+    }
+    // Legacy worker-module imports (`import { UIScreen } from "ui"`) predate the globals-only SDK —
+    // chisel would reject them anyway; say so here instead of "Unknown library".
+    if (slug === "ui" || slug === "creator" || slug === "utils") {
+      throw new Error(`import from "${slug}": the SDK needs no imports — UIScreen, Scene, etc. are globals; remove this import line.`)
+    }
+    throw new Error(`Unknown library "${slug}" — add it in Settings → Libraries, or use a relative path like "./${slug}".`)
+  }
+
+  let out = src.replace(IMPORT_FROM_RE, (_m, boundary, head, quote, spec) =>
+    `${boundary}${head}${quote}${rewriteSpec(spec)}${quote}`)
+  out = out.replace(SIDE_EFFECT_RE, (m, boundary, head, quote, spec) =>
+    isRelativeOrAbsolute(spec) ? m : `${boundary}${head}${quote}${rewriteSpec(spec)}${quote}`)
+  return out
+}

package/runtime/sdk/compile/sceneEditor.ts

@@ -0,0 +1,78 @@
+// The scene-editor compile composition, shared by every host that compiles an edit-mode bundle
+// for a .scene.ts file: the platform backend (src/scene/compileSceneEditor.ts), the standalone
+// scene-editor dev server, and (later) the lecodes CLI. One bundle on purpose: chisel's
+// method-granular DCE trims each bundle's SDK copy to its own calls, so a separately-compiled
+// harness could not call scene methods on objects the scene bundle created.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type { CompileEntry } from "./compileProject"
+
+/** Where the harness sources land in the compile's file map. The dotfolder can't collide with
+ *  project assets (the tree forbids leading-dot names) and reads clearly in compile errors. */
+export const SCENE_HARNESS_DIR = "./.scene-editor"
+
+/** The virtual entrypoint path (`entryOverride`). */
+export const SCENE_ENTRY_PATH = "./.scene-entry.ts"
+
+/**
+ * Read the harness sources (packages/projects/src/scene-editor) from a directory:
+ * `LECODES_SCENE_HARNESS_DIR` env override first (deployments vendor the sources, like
+ * LECODES_SDK_INJECT does for the SDK), else the given fallback dir. Returns name → source.
+ */
+export const loadSceneHarness = (fallbackDir?: string): Record<string, string> => {
+  const override = process.env.LECODES_SCENE_HARNESS_DIR
+  const dir = override && existsSync(override) ? override
+    : fallbackDir && existsSync(fallbackDir) ? fallbackDir
+    : null
+  if (!dir) throw new Error("scene-editor harness sources not found (set LECODES_SCENE_HARNESS_DIR)")
+  const out: Record<string, string> = {}
+  for (const f of readdirSync(dir)) {
+    if (f.endsWith(".ts")) out[f] = readFileSync(join(dir, f), "utf8")
+  }
+  return out
+}
+
+/**
+ * The extra entries that turn a project compile into a scene-editor compile: the harness modules
+ * plus a virtual entry that (1) sets the edit-mode flag in its own module — imports hoist, so the
+ * flag must run as a module, first — (2) imports the scene, which registers its handle on
+ * `__lecodesScenes`, (3) imports the project's `*.editor.ts` plugin files (editor bundles ONLY —
+ * production compiles never import them, so they cost zero bytes in shipped `app.js`), and
+ * (4) imports the harness main, which installs `__lecodesSceneHarness`.
+ * FULL extensions everywhere — exact-match specifiers need no resolver guesswork on dotted names,
+ * so even the unpatched published chisel resolves the `.scene.ts` import.
+ *
+ * `scenePath` is the project path of the scene file ("./scenes/city.scene.ts"); `projectPaths` is
+ * 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`.
+ */
+export const sceneEditorEntries = (
+  scenePath: string,
+  harness: Record<string, string>,
+  projectPaths: string[] = [],
+): CompileEntry[] => {
+  const entries: CompileEntry[] = Object.entries(harness).map(([ name, text ]) => ({
+    path: `${SCENE_HARNESS_DIR}/${name}`,
+    type: "text" as const,
+    text,
+  }))
+  entries.push({
+    path: `${SCENE_HARNESS_DIR}/.edit-mode.ts`,
+    type: "text",
+    text: `;(globalThis as any).__lecodesSceneEdit = true\nexport {}\n`,
+  })
+  const editorImports = projectPaths
+    .filter((p) => p.endsWith(".editor.ts"))
+    .map((p) => `import "${p}"\n`)
+    .join("")
+  entries.push({
+    path: SCENE_ENTRY_PATH,
+    type: "text",
+    text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
+      + `import "${scenePath}"\n`
+      + editorImports
+      + `import "${SCENE_HARNESS_DIR}/main.ts"\n`,
+  })
+  return entries
+}

package/runtime/sdk/compile/sfnt.ts

@@ -0,0 +1,98 @@
+// Minimal sfnt (TTF/OTF) reader for the `font()` compile macro: family name from the `name` table,
+// weight/italic from `OS/2` (with a `head.macStyle` fallback). Reads only what the macro needs —
+// this is not a font sanitizer or validator.
+
+export type SfntInfo = { family: string, weight: number, italic: boolean }
+
+const TAG_TTF = 0x00010000
+const TAG_OTTO = 0x4f54544f // 'OTTO' (CFF outlines)
+const TAG_TTCF = 0x74746366 // 'ttcf' (collection)
+const TAG_WOFF = 0x774f4646 // 'wOFF'
+const TAG_WOF2 = 0x774f4632 // 'wOF2'
+
+/** Parse a .ttf/.otf. Throws a message meant to surface verbatim in a compile error. */
+export const parseSfnt = (bytes: Uint8Array): SfntInfo => {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (bytes.byteLength < 12) throw new Error("not a font file (truncated)")
+  const version = dv.getUint32(0)
+  if (version === TAG_TTCF) throw new Error("font collections (.ttc) aren't supported — export a single face")
+  if (version === TAG_WOFF || version === TAG_WOF2) throw new Error("WOFF/WOFF2 project fonts aren't supported — use the .ttf/.otf")
+  if (version !== TAG_TTF && version !== TAG_OTTO) throw new Error("not a TTF/OTF font file")
+
+  const numTables = dv.getUint16(4)
+  const tables = new Map<string, { offset: number, length: number }>()
+  for (let i = 0; i < numTables; i++) {
+    const rec = 12 + i * 16
+    if (rec + 16 > bytes.byteLength) throw new Error("not a font file (truncated table directory)")
+    const tag = String.fromCharCode(bytes[rec], bytes[rec + 1], bytes[rec + 2], bytes[rec + 3])
+    tables.set(tag, { offset: dv.getUint32(rec + 8), length: dv.getUint32(rec + 12) })
+  }
+
+  const family = readFamily(dv, bytes, tables.get("name"))
+  if (!family) throw new Error("no family name in the font's `name` table")
+
+  let weight = 400
+  let italic = false
+  const os2 = tables.get("OS/2")
+  if (os2 && os2.offset + 64 <= bytes.byteLength) {
+    weight = dv.getUint16(os2.offset + 4) // usWeightClass
+    italic = (dv.getUint16(os2.offset + 62) & 1) === 1 // fsSelection ITALIC
+  } else {
+    const head = tables.get("head")
+    if (head && head.offset + 46 <= bytes.byteLength) {
+      const macStyle = dv.getUint16(head.offset + 44)
+      if (macStyle & 1) weight = 700
+      italic = (macStyle & 2) === 2
+    }
+  }
+  if (weight < 1 || weight > 1000) weight = 400
+
+  return { family, weight, italic }
+}
+
+/** Best family name: typographic family (nameID 16) over legacy family (1); Windows-English
+ *  records over the rest. Returns "" when the table yields nothing decodable. */
+const readFamily = (dv: DataView, bytes: Uint8Array, name?: { offset: number, length: number }): string => {
+  if (!name || name.offset + 6 > bytes.byteLength) return ""
+  const base = name.offset
+  const count = dv.getUint16(base + 2)
+  const stringOffset = base + dv.getUint16(base + 4)
+
+  let best = ""
+  let bestScore = -1
+  for (let i = 0; i < count; i++) {
+    const rec = base + 6 + i * 12
+    if (rec + 12 > bytes.byteLength) break
+    const platformID = dv.getUint16(rec)
+    const languageID = dv.getUint16(rec + 4)
+    const nameID = dv.getUint16(rec + 6)
+    const length = dv.getUint16(rec + 8)
+    const offset = stringOffset + dv.getUint16(rec + 10)
+    if (nameID !== 16 && nameID !== 1) continue
+    if (offset + length > bytes.byteLength) continue
+
+    // nameID 16 beats 1; within an id, Windows-English > Windows > Unicode > Mac.
+    let score = nameID === 16 ? 100 : 0
+    if (platformID === 3) score += languageID === 0x409 ? 30 : 20
+    else if (platformID === 0) score += 10
+    if (score <= bestScore) continue
+
+    const text = platformID === 1 ? decodeLatin1(bytes, offset, length) : decodeUtf16be(bytes, offset, length)
+    if (!text.trim()) continue
+    best = text.trim()
+    bestScore = score
+  }
+  return best
+}
+
+const decodeUtf16be = (bytes: Uint8Array, offset: number, length: number): string => {
+  let out = ""
+  for (let i = 0; i + 1 < length; i += 2) out += String.fromCharCode((bytes[offset + i] << 8) | bytes[offset + i + 1])
+  return out
+}
+
+const decodeLatin1 = (bytes: Uint8Array, offset: number, length: number): string => {
+  let out = ""
+  for (let i = 0; i < length; i++) out += String.fromCharCode(bytes[offset + i])
+  return out
+}

package/runtime/sdk/compile/sourcemap.ts

@@ -0,0 +1,25 @@
+// Helpers for serving the bundler's source map alongside the bundle. The map's generated positions
+// are relative to the bundle code; when the deploy/preview prepends a comment header, the map must be
+// shifted down by that many lines, then inlined into the bundle as a data URL (the preview executes
+// the bundle via `new Function(string)`, which has no URL identity, so an external `.map` can't be
+// fetched — it must be inline).
+
+/** Shift every generated position in `mapJson` down by `lines` (each VLQ line is `;`-separated). */
+export const offsetSourceMap = (mapJson: string, lines: number): string => {
+  if (lines <= 0) return mapJson
+  const map = JSON.parse(mapJson) as { mappings: string }
+  map.mappings = ";".repeat(lines) + map.mappings
+  return JSON.stringify(map)
+}
+
+/**
+ * Inline the map into a bundle string under a **non-standard** directive (`lecodesMap`, not
+ * `sourceMappingURL`), so the browser does NOT auto-apply it. The bundle runs via `new Function`, and
+ * the browser maps the raw stack position *including* the `new Function` wrapper (~2-3 lines) which the
+ * map can't subtract — so its native source location would be off by those lines. Our preview mapper
+ * reads `lecodesMap` and subtracts the (calibrated) wrapper itself, so its locations are correct.
+ */
+export const inlineSourceMapComment = (mapJson: string): string => {
+  const b64 = Buffer.from(mapJson, "utf8").toString("base64")
+  return `//# lecodesMap=data:application/json;charset=utf-8;base64,${b64}`
+}

package/runtime/sdk/g2/Node2D.ts

@@ -39,6 +39,9 @@ export class Node2D extends AspectHost<Node2DEvents> {
   /** Native entity handle. */
   readonly id: number
 
+  /** Optional debug/editor name (plain JS data — scene2d files stamp their node names here). */
+  name?: string
+
   protected _x = 0
   protected _y = 0
   protected _rotation = 0

package/runtime/sdk/g2/SpriteAnimation.ts

@@ -4,32 +4,55 @@
 //   sprite.anim.play('walk')
 // Once defined, clips advance entirely in native code; the aspect just translates clip ids back to
 // names for the node's 'loopReached' / 'completed' events.
+//
+// Directional sheets (one texture row per facing): set `directions` in row order and mark clips
+// `perDirection` — each expands to `name_DIR` with the frames offset by that row. Then
+// `play('walk', 'SE')` or `play('walk', moveVector)` picks the row (compass tokens: E/NE/N/NW/W/SW/S/SE),
+// and the last direction sticks, so a later `play('idle')` keeps facing.
+//
+// The native clips need the texture's dimensions, so when the Sprite has no texture yet (SpriteSheet's
+// deferred load), the define is postponed: play() calls queue by name and start once define() runs.
 
 import { Aspect } from "../core/Aspect"
+import { cx, cy, type Vec2Like } from "../math/vec"
 import { ensureAnimEvents } from "./loop"
 import type { Sprite } from "./Sprite"
 
-/** Per-clip frame list, or an object for per-clip fps/loop overrides. */
-export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean }
+/** Per-clip frame list, or an object for per-clip fps/loop/direction overrides. */
+export type Clip = number[] | { frames: number[], fps?: number, loop?: boolean, perDirection?: boolean }
+
+// Compass angles in Y-up world degrees (E = +x, N = +y) for vector → direction resolution.
+const COMPASS: Record<string, number> = { E: 0, NE: 45, N: 90, NW: 135, W: 180, SW: 225, S: 270, SE: 315 }
 
 export class SpriteAnimation extends Aspect<"anim", Sprite> {
   static readonly aspect = "anim"
 
   /** Grid cell size in texture pixels (defaults to the full texture). */
   size?: [number, number]
+  /** Grid columns override — for sheets with padding; defaults to floor(texWidth / cellWidth). */
+  cols?: number
+  /** Pixel origin of the grid in the texture — cells index from here (a SpriteSheet region). */
+  origin?: [number, number]
   /** Default fps for clips that don't override it. */
   fps = 12
   /** Default loop for clips that don't override it. */
   loop = true
   /** Named clips; frame indices are row-major into the grid. Set via the attach opts. */
   clips: Record<string, Clip> = {}
+  /** Facing names in texture-row order (row i = directions[i]) for `perDirection` clips. */
+  directions?: string[]
 
   private _clipIds: Record<string, number> = {}
   private _clipNames: Record<number, string> = {}
   private _current: string | null = null
+  private _defined = false
+  private _queued: string | null = null
+  private _dir: string | null = null
 
   onAttach(): void {
-    this._define()
+    // No texture yet (deferred sheet load): postpone the native define — SpriteSheet (or the user)
+    // calls define() after assigning the texture; play() calls queue until then.
+    if (this.node.texture) this._define()
     // route native animation events for this entity to named 'loopReached'/'completed' events.
     ;(this.node as { _dispatchAnimEvent: (clipId: number, type: number) => void })._dispatchAnimEvent =
       (clipId, type) => this.node._emitAnim(type === 1 ? "completed" : "loopReached", this._clipNames[clipId] ?? "")
@@ -42,20 +65,16 @@ export class SpriteAnimation extends Aspect<"anim", Sprite> {
   private _define(): void {
     const node = this.node
     const tex = node.texture
-    if (!tex) throw new Error("SpriteAnimation: set a texture on the Sprite before adding the aspect")
+    if (!tex) throw new Error("SpriteAnimation: set a texture on the Sprite before defining clips")
     const [ fw, fh ] = this.size ?? [ tex.width, tex.height ]
-    const cols = Math.max(1, Math.floor(tex.width / fw))
-
-    for (const name of Object.keys(this.clips)) {
-      const value = this.clips[name]
-      const indices = Array.isArray(value) ? value : value.frames
-      const fps = Array.isArray(value) ? this.fps : (value.fps ?? this.fps)
-      const loop = Array.isArray(value) ? this.loop : (value.loop ?? this.loop)
+    const cols = this.cols ?? Math.max(1, Math.floor(tex.width / fw))
+    const [ ox, oy ] = this.origin ?? [ 0, 0 ]
 
+    const defineOne = (name: string, indices: number[], fps: number, loop: boolean): void => {
       const frames = new Float32Array(indices.length * 4)
       indices.forEach((idx, i) => {
-        const px = (idx % cols) * fw
-        const py = Math.floor(idx / cols) * fh
+        const px = ox + (idx % cols) * fw
+        const py = oy + Math.floor(idx / cols) * fh
         frames[i * 4 + 0] = px / tex.width
         frames[i * 4 + 1] = py / tex.height
         frames[i * 4 + 2] = (px + fw) / tex.width
@@ -65,26 +84,88 @@ export class SpriteAnimation extends Aspect<"anim", Sprite> {
       this._clipIds[name] = clipId
       this._clipNames[clipId] = name
     }
+
+    for (const name of Object.keys(this.clips)) {
+      const value = this.clips[name]
+      const indices = Array.isArray(value) ? value : value.frames
+      const fps = Array.isArray(value) ? this.fps : (value.fps ?? this.fps)
+      const loop = Array.isArray(value) ? this.loop : (value.loop ?? this.loop)
+      const dirs = !Array.isArray(value) && value.perDirection ? this.directions : undefined
+
+      if (dirs && dirs.length > 0) {
+        // one clip per facing: row i's frames are the base (row-0) frames shifted down i rows.
+        dirs.forEach((dir, row) => defineOne(`${name}_${dir}`, indices.map((f) => f + row * cols), fps, loop))
+      } else {
+        defineOne(name, indices, fps, loop)
+      }
+    }
     if (this.size) _creator2d.setSpriteSize(node.id, fw, fh)
+    this._defined = true
+
+    if (this._queued) {
+      const queued = this._queued
+      this._queued = null
+      const id = this._clipIds[queued]
+      if (id === undefined) throw new Error(`SpriteAnimation.play(): unknown clip "${queued}"`)
+      _creator2d.playAnimation(node.id, id)
+    }
   }
 
-  /** Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly). */
-  play(name: string): this {
-    const id = this._clipIds[name]
-    if (id === undefined) throw new Error(`SpriteAnimation.play(): unknown clip "${name}"`)
-    if (this._current === name) return this
-    this._current = name
+  /**
+   * Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly).
+   * For a `perDirection` clip, `dir` picks the facing — a direction name or a movement vector
+   * (nearest compass row wins); omitted, the last direction (or the first row) is kept.
+   */
+  play(name: string, dir?: string | Vec2Like): this {
+    let target = name
+    const clip = this.clips[name]
+    if (clip && !Array.isArray(clip) && clip.perDirection && this.directions?.length) {
+      const resolved = this._resolveDir(dir)
+      if (resolved) { this._dir = resolved; target = `${name}_${resolved}` }
+    }
+    if (this._current === target) return this
+    this._current = target
+    if (!this._defined) { this._queued = target; return this }
+    const id = this._clipIds[target]
+    if (id === undefined) throw new Error(`SpriteAnimation.play(): unknown clip "${target}"`)
     _creator2d.playAnimation(this.node.id, id)
     return this
   }
 
   stop(): this {
     this._current = null
-    _creator2d.stopAnimation(this.node.id)
+    this._queued = null
+    if (this._defined) _creator2d.stopAnimation(this.node.id)
     return this
   }
 
+  /** Current facing (last direction resolved by play()), or null before the first directional play. */
+  get direction(): string | null { return this._dir }
+
   set speed(value: number) { _creator2d.setAnimationSpeed(this.node.id, value) }
   get current(): string | null { return this._current }
   get frame(): number { return _creator2d.getAnimationFrame(this.node.id) }
+
+  // A direction name passes through; a vector resolves to the nearest compass row this sheet has.
+  // A zero vector (standing still) keeps the current facing.
+  private _resolveDir(dir?: string | Vec2Like): string | null {
+    const dirs = this.directions!
+    if (typeof dir === "string") return dir
+    if (dir !== undefined) {
+      const x = cx(dir), y = cy(dir)
+      if (x !== 0 || y !== 0) {
+        const angle = (Math.atan2(y, x) * 180 / Math.PI + 360) % 360
+        let best: string | null = null
+        let bestDist = Infinity
+        for (const d of dirs) {
+          const a = COMPASS[d]
+          if (a === undefined) continue
+          const dist = Math.min(Math.abs(a - angle), 360 - Math.abs(a - angle))
+          if (dist < bestDist) { bestDist = dist; best = d }
+        }
+        if (best) return best
+      }
+    }
+    return this._dir ?? dirs[0] ?? null
+  }
 }

package/runtime/sdk/g2/SpriteSheet.ts

@@ -0,0 +1,166 @@
+// Sprite sheets as data: one `.sprite.ts` file per image, `export default defineSpriteSheet({...})`.
+// ONE model: every named entry is a region of the image (a rect), optionally SLICED into an
+// animation grid, optionally carrying named clips over that grid — so game code (and the scene
+// editor) reference frames by NAME and never hardcode rects:
+//
+//   import props from './props.sprite'
+//   import hero from './hero.sprite'
+//   scene.add(props.make('tree_orange', { position: [80, 144], layer: 1 }))
+//   scene.add(props.make('water', { position: [0, 0] }))            // sliced, loops on its own
+//   const player = hero.make('hero', { clip: 'idle', layer: 1 })
+//   player.anim.play('walk', inputVector)
+//
+// A sheet describes ART only — rects, slices, clips, anchors. World semantics (colliders, bodies)
+// are the SCENE's job: attach Shape2D / Physics2D / Trigger2D aspects to the placed node (a
+// `.scene2d.ts` `aspects:` list, or `.aspect(...)` in code). Each tool owns its own part.
+//
+// The texture loads lazily on the first make()/load(); sprites created before it resolves get their
+// texture/frame applied on arrival (the world size is known up front from the rect / slice cell, so
+// layout doesn't wait). The sprite editor reads and writes these files — hand edits are preserved
+// (see packages/scene-doc).
+
+import { type Vec2Like } from "../math/vec"
+import { Sprite } from "./Sprite"
+import { SpriteAnimation, type Clip } from "./SpriteAnimation"
+import { Texture2D } from "./Texture2D"
+
+/**
+ * A named region of the image. Just a rect is a static sprite; `slice` subdivides the rect into an
+ * animation grid ([cols, rows] — the cell is rect size / counts); `clips` names frame runs over
+ * that grid (local, row-major). A sliced entry with NO clips loops all of its cells in order.
+ */
+export type SheetSprite = {
+  /** Pixel rect [x, y, w, h] in the image. */
+  rect?: [number, number, number, number]
+  /** Subdivide the rect into an animation grid: [cols, rows]. */
+  slice?: [number, number]
+  /** Playback fps for this sprite's animation (defaults to the sheet fps, then 12). */
+  fps?: number
+  /** Named clips over the local grid (see SpriteAnimation). Omit to loop every cell. */
+  clips?: Record<string, Clip>
+  /** Facing names in local-row order for `perDirection` clips (compass tokens: S/SE/E/…). */
+  directions?: string[]
+  /** Overrides the sheet anchor. */
+  anchor?: Vec2Like
+}
+
+export type SpriteSheetDef = {
+  /** The image URL — write `asset('./sheet.png')`. */
+  image: string
+  /** Default pivot for every sprite made from this sheet ([0.5, 1] = feet, for Y-sorted worlds). */
+  anchor?: Vec2Like
+  /** Default fps for sliced sprites / clips that don't override it. */
+  fps?: number
+  /** The named sprites. */
+  sprites?: Record<string, SheetSprite>
+}
+
+export type SpriteMakeOptions = {
+  position?: Vec2Like
+  layer?: number
+  /** Overrides the sheet/sprite anchor. */
+  anchor?: Vec2Like
+  /** Start this clip immediately (sliced sprites with clips). */
+  clip?: string
+  /** Initial facing for `perDirection` clips. */
+  direction?: string
+}
+
+/** The name a sliced-but-clipless sprite's implicit everything-loop plays under. */
+const LOOP_ALL = "all"
+
+export class SpriteSheet {
+  private _def: SpriteSheetDef
+  private _tex: Texture2D | null = null
+  private _loading: Promise<Texture2D> | null = null
+
+  constructor(def: SpriteSheetDef) {
+    this._def = def
+  }
+
+  /** The sheet definition (read-only by convention — the editor owns the file). */
+  get def(): SpriteSheetDef { return this._def }
+
+  /** The loaded texture, or null before load() resolves. */
+  get texture(): Texture2D | null { return this._tex }
+
+  /** Load the sheet's texture (idempotent). make() starts this automatically. */
+  load(): Promise<Texture2D> {
+    if (!this._loading) {
+      this._loading = Texture2D.load(this._def.image).then((tex) => { this._tex = tex; return tex })
+    }
+    return this._loading
+  }
+
+  /** Names of the sheet's sprites. */
+  get spriteNames(): string[] { return Object.keys(this._def.sprites ?? {}) }
+
+  /** Build a named sprite; starting a clip hands back the animation handle. */
+  make(name: string, opts: SpriteMakeOptions & { clip: string }): Sprite & { anim: SpriteAnimation }
+  make(name: string, opts?: SpriteMakeOptions): Sprite
+  make(name: string, opts: SpriteMakeOptions = {}): Sprite {
+    const def = this._def
+    const named = def.sprites?.[name]
+    if (!named) {
+      throw new Error(`SpriteSheet.make(): unknown sprite "${name}" (have: ${this.spriteNames.join(", ") || "none"})`)
+    }
+    const rect = named.rect
+    const slice = named.slice
+
+    const sprite = new Sprite({
+      anchor: opts.anchor ?? named.anchor ?? def.anchor,
+      layer: opts.layer,
+      position: opts.position,
+    })
+
+    // The world size is known without the texture (the rect, or its slice cell) — set it up front
+    // so layout, Y-sort and colliders are correct even while the image is still loading.
+    if (rect) sprite.size = slice ? [ rect[2] / slice[0], rect[3] / slice[1] ] : [ rect[2], rect[3] ]
+
+    // sliced sprite: all animation flows through SpriteAnimation, anchored at the rect's origin.
+    // No clips declared = one implicit clip looping every cell (animated tiles).
+    if (rect && slice) {
+      const [ cols, rows ] = slice
+      const clips = named.clips && Object.keys(named.clips).length > 0
+        ? named.clips
+        : { [LOOP_ALL]: Array.from({ length: cols * rows }, (_, i) => i) }
+      const animOpts: Partial<SpriteAnimation> = {
+        size: [ rect[2] / cols, rect[3] / rows ],
+        cols,
+        origin: [ rect[0], rect[1] ],
+        clips,
+      }
+      const fps = named.fps ?? def.fps
+      if (fps !== undefined) animOpts.fps = fps
+      if (named.directions) animOpts.directions = named.directions
+      sprite.aspect(SpriteAnimation, animOpts)
+      const start = opts.clip ?? (named.clips ? undefined : LOOP_ALL)
+      if (start) (sprite as Sprite & { anim: SpriteAnimation }).anim.play(start, opts.direction)
+    }
+
+    // texture + frame: now if loaded, else on arrival
+    if (this._tex) this._applyTexture(sprite, named, this._tex)
+    else this.load().then((tex) => this._applyTexture(sprite, named, tex))
+    return sprite
+  }
+
+  /** The pixel rect [x, y, w, h] of a named sprite's REGION (the whole rect, sliced or not). */
+  rectOf(name: string): [number, number, number, number] | null {
+    const rect = this._def.sprites?.[name]?.rect
+    return rect ? [ ...rect ] : null
+  }
+
+  private _applyTexture(sprite: Sprite, named: SheetSprite, tex: Texture2D): void {
+    sprite.texture = tex // native resets UV/size; the Sprite setter re-applies our explicit size
+    const rect = named.rect
+    if (rect) {
+      const [ cw, ch ] = named.slice ? [ rect[2] / named.slice[0], rect[3] / named.slice[1] ] : [ rect[2], rect[3] ]
+      sprite.setFramePx(rect[0], rect[1], cw, ch) // cell 0 (or the whole static rect)
+    }
+    const anim = (sprite as Partial<{ anim: SpriteAnimation }>).anim
+    if (anim) anim.define()
+  }
+}
+
+/** Declare a sprite sheet (the default export of a `.sprite.ts` file). */
+export const defineSpriteSheet = (def: SpriteSheetDef): SpriteSheet => new SpriteSheet(def)