lecodes-sdk 2.2.5 → 2.2.6

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.5",
+  "version": "2.2.6",
   "files": [
     "src",
     "dist",

package/prompts/core.md

@@ -112,7 +112,7 @@ Everything in this prompt is a global — no imports needed. A project's only im
 
 Imports of the project's own files are also managed automatically: if your <edit> or <replace> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
 
-Reference a project asset (image, font, video, .svg, .glb, …) by its path as a string LITERAL — `UIImage("images/hero.png")`, `"./x.png"` from the file, `"/x.png"` from the root — or with the inline `asset('./path')` macro; both are a compile-time equivalent of the import (a literal, never a variable; a path that names no file fails the compile). A `.json` path stays a string. External `https://…` URLs are used directly as strings.
+Reference a project asset (image, font, video, .svg, .glb, …) by its path as a string LITERAL — `UIImage("images/hero.png")`, `"./x.png"` from the file, `"/x.png"` from the root — or with the inline `asset('./path')` macro; both are a compile-time equivalent of the import (a literal, never a variable). A path that names a file is that file anywhere — a table of rows `{ photo: "images/x.jpg" }` too; one that names no file fails the compile where the SDK takes a file (UIImage, bgImage, a tab icon, Model.load, Sound.load, a scene's model …) and stays a plain string elsewhere (a path in the app's own files, a storage key). A `.json` path stays a string. External `https://…` URLs are used directly as strings.
 
 ## Project context
 

package/prompts/ui-design.md

@@ -51,8 +51,8 @@ UIText(text)
 UIImage(src)  // src: string url | SvgSource | imported asset
 // extra styles: objectFit ("cover"|"contain"|"fill"), tintColor (SVG only), borderRadius (number px only on UIImage)
 // Note: tintColor applies only to SVG sources — it replaces ALL fill and stroke colors (monochrome icons only)
-// Note: a bare relative path string won't resolve — plain strings are for https:// URLs; project files go
-//   through import or asset('./photo.jpg')
+// Note: a project file by its path as a string — UIImage("images/photo.jpg") — is the bundled asset (or
+//   asset('./images/photo.jpg')); a path that names no file fails the compile; https:// strings are remote URLs
 
 // UIButton — the only TAPPABLE container: a UIRow with children centered on both axes by default.
 // Anything clickable in the prototype (a card, a list row, an icon) — wrap it in a UIButton.
@@ -191,10 +191,10 @@ UIRow(isSelected ? check : UIColumn())            // WRONG
 // ✅ null is skipped in children — no phantom element
 UIRow(isSelected ? check : null)
 
-// ❌ pointing UIImage / bgImage at a project file by bare path — it won't resolve to the bundled asset
-UIImage("./photo.jpg")                              // WRONG (a plain string works only for remote http(s) URLs)
-// ✅ import the asset, or wrap its path in asset()
-UIImage(asset('./assets/avatars/alina.jpg'))
+// ❌ pointing UIImage / bgImage at a project file that is not there — the compile fails: file not found
+UIImage("assets/avatars/nobody.jpg")                // WRONG (no such file in the project)
+// ✅ the path of a file the project has (or the same path in asset()) — the bundled asset
+UIImage("assets/avatars/alina.jpg")
 
 // ❌ setting a UIImage's content through bgImage
 // bgImage is a container background, not image content — pass the source to UIImage(...)

package/src/animate/tween/Timeline.ts

@@ -1,175 +1,175 @@
-// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
-// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
-// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
-// builder every target class delegates to (`tweenBag`).
-
-import { TweenAnimation, type Animation } from "./Animation"
-import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
-import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
-
-/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
-const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
-
-const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
-  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
-
-/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
-export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
-  const meta = bag as TweenMeta
-  const tracks: Track[] = []
-  for (const [prop, value] of bagProps(bag)) {
-    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
-    if (track) tracks.push(track)
-  }
-  return tracks
-}
-
-/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
-export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
-  const meta = bag as TweenMeta
-  const tracks = bagTracks(target, bag, 0, fromCurrent)
-  let durationMs = 0
-  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
-  const spec: TweenSpec = {
-    clock: clockOf(meta.clock, target._tweenClock),
-    durationMs, delayMs: 0,
-    iterations: iterationsOf(meta.loop),
-    pingPong: meta.loopMode !== "restart",
-    rate: 1, tracks, calls: [],
-  }
-  return new TweenAnimation(spec).play()
-}
-
-export type TimelineOptions = {
-  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
-  clock?: "ui" | "game",
-  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
-  loop?: boolean | number,
-  loopMode?: "restart" | "ping-pong",
-  /** Wait before the first play, ms. */
-  delay?: number,
-}
-
-/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
-export type TimelinePosition = number | string | [string, number]
-
-export type TimelineAddOptions = {
-  at?: TimelinePosition,
-  /** With several targets: each starts this many ms after the previous one. */
-  stagger?: number,
-}
-
-/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
- *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
- *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
- *  starts, the last one after it ends). */
-export class TimelineImpl extends TweenAnimation {
-  private _labels = new Map<string, number>()
-  private _end = 0
-
-  constructor(options: TimelineOptions = {}) {
-    super({
-      clock: clockOf(options.clock, CLOCK_UI),
-      durationMs: 0,
-      delayMs: options.delay ?? 0,
-      iterations: iterationsOf(options.loop),
-      pingPong: options.loopMode !== "restart",
-      rate: 1, tracks: [], calls: [],
-    })
-  }
-
-  private _at(at: TimelinePosition | undefined): number {
-    if (at === undefined) return this._end
-    if (typeof at === "number") return at
-    const name = Array.isArray(at) ? at[0] : at
-    const offset = Array.isArray(at) ? at[1] : 0
-    const base = this._labels.get(name)
-    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
-    return base + offset
-  }
-
-  private _grow(endMs: number): void {
-    if (endMs > this._end) this._end = endMs
-    this._spec.durationMs = this._end
-  }
-
-  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
-   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
-  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, true)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
-  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, false)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
-   *  every frame with the value. */
-  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
-    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
-    this._values.set(slot, deliver)
-    this._spec.tracks.push(track)
-    this._grow(track.atMs + track.durMs)
-    return this
-  }
-
-  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
-   *  finish, never from a previous run. */
-  call(at: TimelinePosition, fn: () => void): this {
-    const t = this._at(at)
-    this._spec.calls.push(t)
-    this._calls.push(fn)
-    this._grow(t)
-    return this
-  }
-
-  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
-  label(name: string, at?: TimelinePosition): this {
-    this._labels.set(name, this._at(at))
-    return this
-  }
-
-  /** Named times, ms. */
-  get labels(): Record<string, number> {
-    const o: Record<string, number> = {}
-    for (const [k, v] of this._labels) o[k] = v
-    return o
-  }
-
-  /** Extend the timeline with stillness after its current end. */
-  hold(ms: number): this {
-    this._grow(this._end + Math.max(0, ms))
-    return this
-  }
-
-  /** The current end, ms (tracks, calls and holds). */
-  get end(): number { return this._end }
-
-  /** `seek` also accepts a label. */
-  override seek(at: number | string): this {
-    return super.seek(typeof at === "string" ? this._at(at) : at)
-  }
-}
-
-/** The timeline handle type (see {@link TimelineImpl} for the members). */
-export type Timeline = TimelineImpl
-
-/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
-export function Timeline(options?: TimelineOptions): Timeline {
-  return new TimelineImpl(options)
-}
+// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
+// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
+// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
+// builder every target class delegates to (`tweenBag`).
+
+import { TweenAnimation, type Animation } from "./Animation"
+import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
+import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
+
+/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
+const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
+
+const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
+  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
+
+/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
+export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
+  const meta = bag as TweenMeta
+  const tracks: Track[] = []
+  for (const [prop, value] of bagProps(bag)) {
+    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
+    if (track) tracks.push(track)
+  }
+  return tracks
+}
+
+/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
+export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
+  const meta = bag as TweenMeta
+  const tracks = bagTracks(target, bag, 0, fromCurrent)
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  const spec: TweenSpec = {
+    clock: clockOf(meta.clock, target._tweenClock),
+    durationMs, delayMs: 0,
+    iterations: iterationsOf(meta.loop),
+    pingPong: meta.loopMode !== "restart",
+    rate: 1, tracks, calls: [],
+  }
+  return new TweenAnimation(spec).play()
+}
+
+export type TimelineOptions = {
+  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
+  clock?: "ui" | "game",
+  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
+  loop?: boolean | number,
+  loopMode?: "restart" | "ping-pong",
+  /** Wait before the first play, ms. */
+  delay?: number,
+}
+
+/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
+export type TimelinePosition = number | string | [string, number]
+
+export type TimelineAddOptions = {
+  at?: TimelinePosition,
+  /** With several targets: each starts this many ms after the previous one. */
+  stagger?: number,
+}
+
+/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
+ *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
+ *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
+ *  starts, the last one after it ends). */
+export class TimelineImpl extends TweenAnimation {
+  private _labels = new Map<string, number>()
+  private _end = 0
+
+  constructor(options: TimelineOptions = {}) {
+    super({
+      clock: clockOf(options.clock, CLOCK_UI),
+      durationMs: 0,
+      delayMs: options.delay ?? 0,
+      iterations: iterationsOf(options.loop),
+      pingPong: options.loopMode !== "restart",
+      rate: 1, tracks: [], calls: [],
+    })
+  }
+
+  private _at(at: TimelinePosition | undefined): number {
+    if (at === undefined) return this._end
+    if (typeof at === "number") return at
+    const name = Array.isArray(at) ? at[0] : at
+    const offset = Array.isArray(at) ? at[1] : 0
+    const base = this._labels.get(name)
+    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
+    return base + offset
+  }
+
+  private _grow(endMs: number): void {
+    if (endMs > this._end) this._end = endMs
+    this._spec.durationMs = this._end
+  }
+
+  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
+   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
+  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, true)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
+  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, false)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
+   *  every frame with the value. */
+  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
+    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
+    this._values.set(slot, deliver)
+    this._spec.tracks.push(track)
+    this._grow(track.atMs + track.durMs)
+    return this
+  }
+
+  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
+   *  finish, never from a previous run. */
+  call(at: TimelinePosition, fn: () => void): this {
+    const t = this._at(at)
+    this._spec.calls.push(t)
+    this._calls.push(fn)
+    this._grow(t)
+    return this
+  }
+
+  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
+  label(name: string, at?: TimelinePosition): this {
+    this._labels.set(name, this._at(at))
+    return this
+  }
+
+  /** Named times, ms. */
+  get labels(): Record<string, number> {
+    const o: Record<string, number> = {}
+    for (const [k, v] of this._labels) o[k] = v
+    return o
+  }
+
+  /** Extend the timeline with stillness after its current end. */
+  hold(ms: number): this {
+    this._grow(this._end + Math.max(0, ms))
+    return this
+  }
+
+  /** The current end, ms (tracks, calls and holds). */
+  get end(): number { return this._end }
+
+  /** `seek` also accepts a label. */
+  override seek(at: number | string): this {
+    return super.seek(typeof at === "string" ? this._at(at) : at)
+  }
+}
+
+/** The timeline handle type (see {@link TimelineImpl} for the members). */
+export type Timeline = TimelineImpl
+
+/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
+export function Timeline(options?: TimelineOptions): Timeline {
+  return new TimelineImpl(options)
+}

package/src/compile/assetMacro.ts

@@ -2,6 +2,8 @@
 // compile-time `asset('./x.png')` macro is desugared into a real import so it goes through the same
 // loader/resolver as a hand-written import.
 
+import { resourceSlots } from "./resourceSlots"
+
 // Matches `asset("./img.png")` / `asset('./img.png')` calls whose argument is a single string
 // literal (handling escaped chars inside the literal). The lookbehind excludes property access —
 // a METHOD named asset (`ui.asset("model")`, InspectorUI) is not the macro.
@@ -104,6 +106,63 @@ const normalizePath = (path: string): string => {
   return "/" + out.join("/")
 }
 
+// ---- the resource slots (resourceSlots.ts): is a literal what the SDK takes a file in? ----------
+
+const OPENERS = "([{"
+const CLOSERS = ")]}"
+// The callee before a `(`: `UIImage`, `Model.load`, `new AudioPlayer` (whitespace allowed around the dots).
+const CALLEE = /(?:\b(new)\s+)?([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*$/
+// An object literal's entry up to its value: `bgImage: `, `"icon": `.
+const ENTRY_KEY = /^\s*(["']?)([A-Za-z_$][\w$]*)\1\s*:/
+// The target of an assignment: `img.src = `.
+const SET_TARGET = /\.\s*([A-Za-z_$][\w$]*)\s*$/
+
+/**
+ * Whether the literal at `start` sits in a resource slot: an argument of a call or a constructor of
+ * the list at its position, the value of a listed key of an object literal, or the right side of a
+ * listed property set. Walks OUT from the literal over `mask` (maskNonCode's: strings and comments
+ * blanked, so their brackets do not count) and lets the innermost call or object entry decide.
+ * Arrays (`Sound.load([…])`, `normals: […]`), grouping parens, ternaries and an arrow's body (its
+ * statements, `return "…"`) are seen through; an assignment to anything else ends the walk — the
+ * literal is that variable's or that property's, not a slot's.
+ */
+const inResourceSlot = (src: string, mask: string, start: number): boolean => {
+  let depth = 0      // brackets closed between the literal and the walk (theirs, not its own)
+  let commas = 0     // the literal's argument / entry position in the bracket it sits in
+  let entry = -1     // the closest of those commas: where the literal's entry starts
+  for (let i = start - 1; i >= 0; i--) {
+    const c = mask[i]
+    if (CLOSERS.includes(c)) { depth++; continue }
+    if (OPENERS.includes(c)) {
+      if (depth > 0) { depth--; continue }
+      if (c === "(") {
+        // A call — the innermost decides; a keyword (`if (`, `return (`) is no slot of the list.
+        const m = CALLEE.exec(mask.slice(Math.max(0, i - 128), i))
+        if (m) {
+          const slots = m[1] ? resourceSlots.constructors[m[2]] : resourceSlots.calls[m[2].replace(/\s+/g, "")]
+          return !!slots && slots.includes(commas)
+        }
+      } else if (c === "{") {
+        // An object literal's entry — its key decides; no key: a block (an arrow's body), seen through.
+        const key = ENTRY_KEY.exec(src.slice((entry >= 0 ? entry : i) + 1, start))
+        if (key) return resourceSlots.keys.includes(key[2])
+      }
+      commas = 0
+      entry = -1
+      continue
+    }
+    if (depth > 0) continue
+    if (c === ",") { commas++; if (entry < 0) entry = i; continue }
+    if (c === ";") { commas = 0; entry = -1; continue }   // a statement of a block: the block decides
+    // an assignment (not `==`, `!=`, `<=`, `>=`, `=>`): `img.src = "…"` is a slot, any other target is not
+    if (c === "=" && mask[i + 1] !== "=" && mask[i + 1] !== ">" && !"=!<>".includes(mask[i - 1] ?? "")) {
+      const target = SET_TARGET.exec(mask.slice(Math.max(0, i - 128), i))
+      return !!target && resourceSlots.assignments.includes(target[1])
+    }
+  }
+  return false
+}
+
 /**
  * Every string literal in `src` that is a PATH to a resource file of the project — `"images/hero.png"`,
  * `"./hero.png"`, `"/sounds/tap.mp3"` — as the asset references they stand for: a bare path is the
@@ -111,37 +170,46 @@ const normalizePath = (path: string): string => {
  * not the macro; the two now mean the same). Resolution: `./` and `../` from the file first, then
  * from the project root (a model writes `./images/x.png` in `views/cart.ts` meaning the root);
  * `/x` from the root; `a/b.png` from the root first, then the file. `exists(rootPath)` says whether
- * the project has that file. A literal with a resource extension that starts with `./`, `../`, `/`
- * or holds a `/` and names NO file comes back `missing` — the bundler reports it when the module
- * is reached, the way it reports a missing `asset()`. A bare name (`"hero.png"`) that names no
- * file is left as the string it is. Import specifiers, `asset()` arguments (`taken`: the ranges
- * already claimed) and `.json` paths are never touched.
+ * the project has that file.
+ *
+ * A literal that names a file is its asset wherever it stands — a table of rows (`photo:
+ * "images/espresso.jpg"`) the screens draw and a seed stores. One with a resource extension that
+ * starts with `./`, `../`, `/` or holds a `/` and names NO file comes back `missing` only in a
+ * resource slot (resourceSlots.ts: `UIImage("…")`, `.style({ bgImage: "…" })`, `Model.load("…")` …) —
+ * the bundler reports it when the module is reached, the way it reports a missing `asset()`;
+ * anywhere else it is the string it says (2026-10-12: `files.write("photos/a.jpg")`, a storage key,
+ * `endsWith("/thumb.jpg")`). A bare name (`"hero.png"`) that names no file is left as it is.
+ * Import specifiers, `asset()` arguments (`taken`: the ranges already claimed) and `.json` paths are
+ * never touched.
  */
 export const collectPathLiterals = (
   src: string, filePath: string, exists: (rootPath: string) => boolean, taken: AssetMacroRef[] = [],
 ): AssetMacroRef[] => {
   const refs: AssetMacroRef[] = []
   const dir = filePath.slice(0, filePath.lastIndexOf("/"))
-  maskNonCode(src, (start, end) => {
+  const literals: [ number, number ][] = []
+  const mask = maskNonCode(src, (start, end) => { literals.push([ start, end ]) })
+  for (const [ start, end ] of literals) {
     const value = src.slice(start + 1, end - 1)
-    if (value.length === 0 || value.length > 256) return
-    if (!BARE_PATH_EXT.test(value) || CODE_EXT.test(value)) return
-    if (/[\s:*?"'`<>|\\]/.test(value)) return                     // a url, an icon id, a sentence, a glob
-    if (taken.some((t) => start >= t.index && start < t.index + t.length)) return
-    if (IMPORT_BEFORE.test(src.slice(Math.max(0, start - 32), start))) return
+    if (value.length === 0 || value.length > 256) continue
+    if (!BARE_PATH_EXT.test(value) || CODE_EXT.test(value)) continue
+    if (/[\s:*?"'`<>|\\]/.test(value)) continue                     // a url, an icon id, a sentence, a glob
+    if (taken.some((t) => start >= t.index && start < t.index + t.length)) continue
+    if (IMPORT_BEFORE.test(src.slice(Math.max(0, start - 32), start))) continue
     const relative = value.startsWith("./") || value.startsWith("../")
     const rooted = value.startsWith("/")
     const candidates = rooted ? [ normalizePath(value) ]
       : relative ? [ normalizePath(`${dir}/${value}`), normalizePath(value) ]
       : [ normalizePath(value), normalizePath(`${dir}/${value}`) ]
     const found = candidates.find(exists)
-    if (found === undefined && !relative && !rooted && !value.includes("/")) return
+    if (found === undefined && !relative && !rooted && !value.includes("/")) continue
+    if (found === undefined && !inResourceSlot(src, mask, start)) continue
     let line = 1
     for (let k = 0; k < start; k++) if (src[k] === "\n") line++
     refs.push(found !== undefined
       ? { path: found, index: start, length: end - start, line }
       : { path: value, index: start, length: end - start, line, missing: true })
-  })
+  }
   return refs
 }
 

package/src/compile/resourceSlots.ts

@@ -0,0 +1,45 @@
+/**
+ * The resource SLOTS: where the SDK takes a reference to a file of the project — an image, a sound,
+ * a model, a font — the places `asset('…')` or an `https://` url is passed to.
+ *
+ * compile/assetMacro.ts reads them for the bare path literals (2026-10-12): a literal that names a
+ * file of the project is its asset ANYWHERE (a table of rows names its pictures that way — the
+ * screens draw them, a seed stores them); a path-looking literal that names NO file fails the
+ * compile only in a slot. Anywhere else it is the string it says: a path in the app's own files, a
+ * storage key, a suffix test, a test's expected text.
+ *
+ * Plain data, the names user code writes. A rename in the SDK is an edit here
+ * (tests/compile/resourceSlots.test.ts fails until it is made).
+ */
+export const resourceSlots = {
+  /** A call as written — a global, or `Global.method` — and the argument positions that take a file. */
+  calls: {
+    UIImage: [ 0 ],
+    registerFont: [ 1 ],
+    fetchLocal: [ 0 ],
+    "Texture2D.load": [ 0 ],
+    "Texture.load": [ 0 ],
+    "Model.load": [ 0 ],
+    "AnimationClip.load": [ 0 ],
+    "AnimationClip.loadAll": [ 0 ],
+    "Geometry.load": [ 0 ],
+    "Material.load": [ 0 ],
+    "Terrain.load": [ 0 ],
+    "Sound.load": [ 0 ],
+  } as Record<string, number[]>,
+  /** `new X(…)` and the argument positions that take a file. */
+  constructors: {
+    AudioPlayer: [ 0 ],
+    VideoPlayer: [ 0 ],
+  } as Record<string, number[]>,
+  /** `x.<name> = "…"`: `img.src`, `scene.postProcessing.lut`. */
+  assignments: [ "src", "lut" ],
+  /** The keys of an object literal whose value is a file: `.style({ bgImage })`, `UITabs({ id: { icon } })`,
+   *  `defineSpriteSheet({ image })`, `defineScene({ nodes: { x: { model } }, env: { ibl, skybox: { texture },
+   *  lightmap: { data, light, … } } })`, `Terrain.create({ layers: [{ albedo }], normals })`, a material's
+   *  `map` / `shader`, `Level.place({ build })`. The value may sit in an array, a ternary or an arrow's body. */
+  keys: [
+    "bgImage", "backgroundImage", "icon", "image", "texture", "model", "ibl", "lut", "albedo", "normals",
+    "map", "shader", "build", "data", "light", "aux", "direct", "indirect", "probes", "volume",
+  ],
+}