lecodes-sdk 2.0.8 → 2.0.10

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.14.1",
     "sharp": "^0.35.2"
   },
-  "version": "2.0.8",
+  "version": "2.0.10",
   "files": [
     "src",
     "dist",

package/prompts/3d-scene-files.md

@@ -66,10 +66,10 @@ export class Spinner extends Aspect<'spinner'> {
 // ===== UI OVER AN OPEN SCENE =====
 
 // Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+// a UIWidget that is the scene's CONTENT — it shows and hides together with it:
 const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
     .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
+scene.setContent([hud])
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -107,7 +107,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/prompts/3d-scene.md

@@ -114,6 +114,6 @@ const hud = UIWidget(
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
 ).style({ top: 'max(safe-top, 16px)', right: 16 })
 
+scene.setContent([hud])
 scene.open()
-hud.attachTo(scene).show()
 </file>

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 importing it or with the inline `asset('./path')` macro — a compile-time equivalent of the import (string LITERAL only, never a variable). 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 no file fails the compile). A `.json` path stays a string. External `https://…` URLs are used directly as strings.
 
 ## Project context
 

package/prompts/dist/3d-app.md

@@ -775,8 +775,8 @@ const hud = UIWidget(
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
 ).style({ top: 'max(safe-top, 16px)', right: 16 })
 
+scene.setContent([hud])
 scene.open()
-hud.attachTo(scene).show()
 </file>
 
 ## Scene files (.scene.ts)
@@ -847,10 +847,10 @@ export class Spinner extends Aspect<'spinner'> {
 // ===== UI OVER AN OPEN SCENE =====
 
 // Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+// a UIWidget that is the scene's CONTENT — it shows and hides together with it:
 const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
     .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
+scene.setContent([hud])
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -888,7 +888,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/prompts/ui.md

@@ -161,7 +161,7 @@ UIImage(src)  // src: string url | FetchResponse | File | SvgSource | Canvas (se
 // .setSourceRect(x, y, w, h) — crop to a sub-rect of the source (texture px); frame fills the box, objectFit
 //   ignored. Chainable, safe to call before mount. For atlases/spritesheets — swap the rect to change frame.
 // Note: tintColor applies only to SVG sources — it replaces ALL fill and stroke colors (monochrome icons only)
-// Note: a bare relative path won't resolve — plain strings are https:// URLs; project files via import or asset('./photo.png')
+// Note: a project file by its path as a string — UIImage("images/photo.png") — is the bundled asset (the compile resolves it; a path that names no file fails the compile); plain https:// strings are remote URLs
 
 // UIVideo — the on-screen surface only; playback lives entirely on the VideoPlayer (see AUDIO / VIDEO above)
 UIVideo(player)
@@ -466,6 +466,8 @@ UIImage(heart).style({ width: 24, height: 24, tintColor: "#666" })  // tintColor
 // ===== ICONS (assetIcon) =====
 // Use real icons instead of emoji. assetIcon("pack:name") resolves the icon at COMPILE time and
 // inlines it as an image source (same shape as SvgSource) — no imports, no project files, offline.
+// It returns an SvgSource — the same type an imported .svg and SvgSource(xml) give — so a component
+// that takes an icon is typed (icon: SvgSource), never (icon: string).
 UIImage(assetIcon("lucide:bell")).style({ width: 24, height: 24, tintColor: "#8a8f98" })
 // The id must be a string literal; an unknown id is a compile error (with name suggestions).
 // Recolor via the tintColor style or the { color } option (hex literal bakes in; expression tints).
@@ -520,12 +522,6 @@ UIRow(isGroup ? button : UIColumn())              // WRONG
 // ✅ null is skipped in children — no phantom element
 UIRow(isGroup ? button : null)
 
-// ❌ pointing UIImage / bgImage at a project file by bare path — it won't resolve to the bundled asset
-UIImage("./photo.png")                              // WRONG (a plain string works only for remote http(s) URLs)
-// ✅ import the asset, or wrap its path in asset()
-import photo from './photo.png'
-UIImage(photo)                                      // or:  UIImage(asset('./photo.png'))
-
 // ❌ callback-first edge callbacks on UIVirtualizedList
 list.onEndReached(loadNextPage)                     // WRONG — threshold is the first argument, and required
 // ✅ threshold (px from the edge) first

package/src/bridges/gl.d.ts

@@ -95,6 +95,11 @@ declare global {
     /** Punctual light. `intensity` is luminous POWER in lumens; `falloff` is the metres of
      *  influence (filament's own default is 1 m, i.e. invisible, so it is always passed). */
     createPointLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, castShadows: boolean): void
+    /** Spot light: the point light's lumens and falloff in a cone along the entity's local -Z. `inner` / `outer` are
+     *  HALF-angles in radians (outer ≤ π/2); the cone does not change the brightness. Real time only (the bake skips it). */
+    createSpotLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, inner: f32, outer: f32, castShadows: boolean): void
+    /** A spot light's cone, live — half-angles in radians, as createSpotLight. */
+    setLightCone?(entityId: u32, inner: f32, outer: f32): void
     /** The lightmap bake takes this point light as a RECTANGLE of `width` x `height` metres (an area light: a ceiling
      *  panel) in the light's local XZ plane, emitting along its local -Y with the same lumens; 0, 0 = a point again. */
     setLightBakeArea?(entityId: u32, width: f32, height: f32): void

package/src/bridges/tree.d.ts

@@ -112,10 +112,20 @@ declare global {
     isViewSupported(name: string): boolean
     viewVersion(name: string): i32
     viewCall(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-    // Show a widget root; `ownerKind` / `ownerId` bind it to a destination (widget.attachTo: it
-    // mounts inside that page and rides its transition) — TREE_DEST_NONE = a global overlay.
-    showWidget(id: TreeNodeId, ownerKind: u8, ownerId: f64): void
-    hideWidget(id: TreeNodeId): void
+    // ---- widgets (docs/plans/widgets-plan.md): a widget is a CHILD — of a screen root, of a
+    //      destination's content layer, of the app layer — never a root of its own; `insert` /
+    //      `remove` place it, `display` shows it, the runtime lays it out in the outermost presented
+    //      destination's box (the portal) and mounts it under that root for the host. ------------
+    // The content LAYER of a destination: a "layer" root (a pass-through root laid out at the frame,
+    // shown while the destination is presented) whose widget children are the surface's UI — a HUD
+    // over a scene, a card over a map. `kind` TREE_DEST_NONE (id 0) = the APP layer, above every
+    // destination, always shown. 0 takes the layer away.
+    setLayer(kind: u8, id: f64, layer: TreeNodeId): void
+    // The pose a widget child enters from and leaves to: a transition id (defineTransition) whose
+    // ALONE roles the runtime plays as tracks on the widget when its resolved `display` flips —
+    // `none → flex` from the enter pose to rest, `flex → none` from rest to the exit pose, `none`
+    // taking effect when the tracks land. TRANSITION_NONE = no pose (the flip is instant).
+    setWidgetPose(id: TreeNodeId, transition: i32): void
 
     // ---- pager (a "pager" node's children are its pages; TAB-MAJOR order, `lens` = per-tab stack
     //      lengths, `index` = the selected tab). A change of the current tab's stack plays a
@@ -251,11 +261,16 @@ export interface HostUI {
    *  call's arguments, valid for the call. Settle exactly one of the two callbacks through the
    *  dispatch bridge — `onComplete` with the result as ONE value, or with none. */
   viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-  /** Show a widget root: `ownerKind` = TREE_DEST_* (0xFF = a global overlay), `ownerId` = the sceneId /
-   *  viewId of a scene / native owner (0 for a screen), `ownerNode` = the owner screen's root (a
-   *  screen destination or a pager page) — 0 otherwise. */
-  widgetOpen(node: nodeid, ownerKind: u8, ownerId: i32, ownerNode: nodeid): void
-  widgetClose(node: nodeid): void
+  /** A LAYER root is shown: a pass-through root the runtime lays out at the frame, above every
+   *  destination (the app layer) or over the presented surface (a scene's / a native view's / a
+   *  video's content layer). Its own box is never hit — only its children are — so a touch outside
+   *  them reaches what is under the layer; it is painted after the destination, layers in open
+   *  order. Its children are widgets (the runtime inserts them with insertNode, as under a screen
+   *  root): a widget child with an overlay layer (`overlayColor`, any color — "transparent" too)
+   *  intercepts every touch outside its own box within its root and reports it as the overlay tap. */
+  layerOpen(node: nodeid): void
+  /** The layer root is hidden (its view stays; releaseNode says when it is gone). */
+  layerClose(node: nodeid): void
   /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle
    *  one of the callbacks through the dispatch bridge. */
   registerFont(url: string, fontFamily: string, weight: i32, style: i32, onComplete: () => void, onReject: (err: string) => void): void
@@ -289,9 +304,6 @@ export interface HostUI {
    *  a child (covered by a push, a keepAlive page); a page that is released goes through
    *  removeNode right after. */
   pagerDropPage?(node: nodeid, page: nodeid): void
-  /** A pager page root (`page`) was mounted under the pager or released (an attachTo widget names the
-   *  page node as its owner). */
-  pagerPageMounted?(page: nodeid, mounted: boolean): void
   /** Optional: the host may PLAY a UI tween track itself — a platform animation interpolating on its
    *  own clock (Core Animation on iOS) instead of one style write per runtime frame. `samples` holds
    *  the track evaluated at even points of its length, easing included, `lanes` floats each: 1 for a

package/src/chisel.ts

@@ -129,7 +129,7 @@ export const chiselVocab: ChiselVocab = {
       "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",
       "onEndReached", "onStartReached",
       "append", "insert", "remove", "setContent", "keepAlive", "url",
-      "attachTo", "detents", "dismissible", "transition", "setSourceRect",
+      "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
       // UITabs / UIVirtualizedList / the native views (NativeView, CameraView, MapView, QRScanner)
       "badge", "setData", "update", "prepend", "removeByKey",

package/src/compile/assetMacro.ts

@@ -20,7 +20,7 @@ export const hasAssetMacro = (src: string): boolean => src.includes("asset(")
  * Not a full lexer: a regex LITERAL containing `asset(` would still be seen as code. That case
  * doesn't occur in practice and behaves exactly as it did before this masking existed.
  */
-const maskNonCode = (src: string): string => {
+const maskNonCode = (src: string, onString?: (start: number, end: number) => void): string => {
   const out = src.split("")
   const blank = (from: number, to: number) => {
     for (let k = from; k < to && k < out.length; k++) if (out[k] !== "\n") out[k] = " "
@@ -57,12 +57,15 @@ const maskNonCode = (src: string): string => {
     if (c === "'" || c === "\"") {
       const start = i
       i++
+      let closed = false
       while (i < src.length) {
         const q = src[i]
         if (q === "\\") { i += 2; continue }
         i++
-        if (q === c || q === "\n") break
+        if (q === c) { closed = true; break }
+        if (q === "\n") break
       }
+      if (closed && onString) onString(start, i)
       blank(start, i); continue
     }
     if (c === "`") { i++; scanTemplate(); continue }
@@ -77,8 +80,70 @@ const maskNonCode = (src: string): string => {
   return out.join("")
 }
 
-/** One `asset('…')` call site: the path as written, plus where it sits in the file. */
-export type AssetMacroRef = { path: string, index: number, length: number, line: number }
+/** One `asset('…')` call site: the path as written, plus where it sits in the file. A bare path
+ *  literal (`collectPathLiterals`) is the same shape: `path` is then the RESOLVED root path of the
+ *  file it names, or, with `missing`, the literal as written — a path-looking string that names no
+ *  file, reported by the bundler the way a missing `asset()` is. */
+export type AssetMacroRef = { path: string, index: number, length: number, line: number, missing?: true }
+
+/** The file kinds a bare path literal may stand for: what `asset()` returns a REFERENCE for (an
+ *  image, a sound, a video, a model, a font, raw bytes) plus `.svg` (an SvgSource, what UIImage
+ *  takes). Not `.json`, whose asset is its parsed data — a `.json` path in a string stays a string. */
+const BARE_PATH_EXT = /\.(png|jpe?g|webp|gif|avif|bmp|svg|mp3|wav|ogg|m4a|aac|flac|mp4|webm|mov|m4v|glb|gltf|ktx2|hdr|exr|ttf|otf|woff2?|bin|bake|filamat)$/i
+const CODE_EXT = /\.([tj]sx?|mjs|cjs|json)$/i
+// What precedes an import specifier: the literal is a module path, never a resource reference.
+const IMPORT_BEFORE = /(?:\bfrom|\bimport|\bimport\s*\(|\brequire\s*\()\s*$/
+
+const normalizePath = (path: string): string => {
+  const out: string[] = []
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") continue
+    if (part === "..") { out.pop(); continue }
+    out.push(part)
+  }
+  return "/" + out.join("/")
+}
+
+/**
+ * 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
+ * `asset('…')` call nobody had to write (2026-10-08: a model writes the path it put the file at and
+ * 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.
+ */
+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 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
+    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
+    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
+}
 
 /**
  * Every `asset('…')` macro call in `src`, skipping the ones inside comments and string literals

package/src/compile/bundler.ts

@@ -3,7 +3,7 @@ import { spawnSync } from "node:child_process"
 import { createRequire } from "node:module"
 import { dirname, join, relative } from "node:path"
 import { fileURLToPath } from "node:url"
-import { collectAssetMacros, desugarAssetMacros, hasAssetMacro, type AssetMacroRef } from "./assetMacro"
+import { collectAssetMacros, collectPathLiterals, desugarAssetMacros, hasAssetMacro, type AssetMacroRef } from "./assetMacro"
 import { scanModulesFallback, type ScanModule } from "./detectEntry"
 import { hasAspectExtends, injectAspectNames } from "./aspectMacro"
 import { hasImportStatement, rewriteLibraryImports } from "./libraryImports"
@@ -178,6 +178,9 @@ const reachableFrom = (entry: string, sources: MemoryFiles): Set<string> => {
 const assertAssetsExist = (refs: { file: string, ref: AssetMacroRef }[], files: MemoryFiles) => {
   const missing: string[] = []
   for (const { file, ref } of refs) {
+    // A path literal that named no file of the project (collectPathLiterals): the string said
+    // where a file is, and it is not there.
+    if (ref.missing) { missing.push(`file not found: ${ref.path} (${file.replace(/^\//, "")}:${ref.line})`); continue }
     // Bare specifiers aren't paths at all — chisel reports those as bare imports.
     if (!ref.path.startsWith("./") && !ref.path.startsWith("../") && !ref.path.startsWith("/")) continue
     const dir = file.slice(0, file.lastIndexOf("/"))
@@ -216,8 +219,12 @@ const bundleProjectChisel = async (
     if (/\.[tj]sx?$/.test(path)) {
       if (hasImportStatement(src)) src = rewriteLibraryImports(src, slugs)
       scanSources[path] = src
-      if (hasAssetMacro(src)) {
-        const found = collectAssetMacros(src, path)
+      // `asset('…')` calls, then the bare path literals that name a resource of the project (the
+      // same reference without the macro); both desugar to the import the author could have written.
+      const macros = hasAssetMacro(src) ? collectAssetMacros(src, path) : []
+      const paths = collectPathLiterals(src, path, (rootPath) => files[rootPath] !== undefined, macros)
+      const found = macros.concat(paths).sort((a, b) => a.index - b.index)
+      if (found.length > 0) {
         for (const ref of found) assetRefs.push({ file: path, ref })
         src = desugarAssetMacros(src, path, found)
       }

package/src/g2/Scene2D.ts

@@ -6,6 +6,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE2D, ensureEmitter, registerDest } from "../ui/tree"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
@@ -188,6 +189,15 @@ export class Scene2D implements Presentable {
     registerDest(TREE_DEST_SCENE2D, this.id, this)
     return [TREE_DEST_SCENE2D, this.id, "", ""]
   }
+  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the scene — widgets (a HUD, a dialog), laid out over the scene while it is
+   *  presented; touches outside a widget's box reach the scene. */
+  setContent(content: UIWidgetContent): this {
+    ensureEmitter()
+    _setSurfaceContent(this, content)
+    return this
+  }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
   /** @internal */