lecodes-sdk 2.2.3 → 2.2.5

package/package.json

@@ -42,10 +42,10 @@
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4",
-    "marcidb-embedded": "^0.14.1",
+    "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.3",
+  "version": "2.2.5",
   "files": [
     "src",
     "dist",

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

@@ -69,7 +69,7 @@ export class Spinner extends Aspect<'spinner'> {
 // 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 })
-scene.setContent([hud])
+scene.widgets(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 })
-scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
+scene.widgets(UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }))
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/prompts/3d-scene.md

@@ -117,6 +117,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.widgets(hud)
 scene.open()
 </file>

package/prompts/dist/2d-game.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
 
@@ -229,6 +229,7 @@ new WebSocket(url, headers?: Record<string, string>)
 // ===== STORAGE / DEVICE / MISC =====
 
 localStorage.getItem(key): string | null / .setItem(key, value) / .removeItem(key)   // nothing else
+signal<Line[]>([]).stored("cart")      // a signal kept on the device under the key (JSON values): back on the next launch
 
 device.platform: "ios" | "android" | "web"    // getter, no ()
 device.language: string                       // "en", "ru", …
@@ -794,6 +795,8 @@ const tabs = UITabs({
 Router.init(tabs)          // UITabs IS a UIScreen — present it directly
 // .select(id), .tab (getter), .onSelect(cb(id, i)) — fires on a bar tap, swipe, or select()
 // .badge(id, value) — true = dot, number/string = count pill, false/null/0 clears
+// Ambient, from any screen, no reference threading: UITabs.current (the visible tabs, or null) and
+//   UITabs.select("profile") — the twin of UIPager.current / UIPager.push
 // .pager — the UIPager underneath; UIPager.push(detail) from any screen keeps the bar
 // The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
 //   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: UIPager below.
@@ -876,17 +879,17 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
+    data?: () => T[],                      // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+                                           // absent = fed by hand: .setData(items) / .append(...items) / .prepend(...items) / .update(...items) / .removeByKey(...keys)
+                                           // (one feed per list: a list with `data` has no append on its type)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)
     overscan?: number,                     // extra px mounted above/below the viewport (default: one viewport)
     inverted?: boolean,                    // true = chat mode: starts scrolled to the end, append at bottom auto-scrolls
 })
-// Data is driven IMPERATIVELY (no diffing) — call these, never re-create the list:
-//   .setData(items: T[])                    // replace everything (diffed by key)
-//   .append(...items) / .prepend(...items)  // variadic; append = newest chat msg; prepend = history, no scroll jump
-//   .update(...items)                       // re-render rows with the same keyOf(); unknown keys ignored
-//   .removeByKey(...keys)
+// Rows added at the end scroll a chat at its bottom; rows added before the first (history) move nothing; a row
+// whose item is a new object re-renders. Never re-create the list.
 //   .itemCount (getter) / .getItem(key)
 //   .scrollTo(offset, animated?) / .scrollToKey(key, animated?) / .scrollToEnd(animated?) / .onScroll(cb(pos))
 //   .onEndReached(thresholdPx: number, cb)   // threshold FIRST and required; fires near the BOTTOM — load next page
@@ -914,7 +917,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)
@@ -944,6 +947,7 @@ UIInput() / UITextArea()
 //   type: "text"|"password"|"search"|"phone"|"email"|"number"|"decimal"|"url"|"date"|"time"
 //   enterKey: "done"|"go"|"next"|"search"|"send" (UIInput only) — return-key label
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
+//   autofocus: boolean — takes the focus as its screen opens (a composer, a chat, a search; once, one per screen)
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
 //   $focused: { borderColor, ..., duration? } — style while focused (reserved class)
@@ -1219,6 +1223,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).
@@ -1273,12 +1279,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/prompts/dist/3d-app.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
 
@@ -229,6 +229,7 @@ new WebSocket(url, headers?: Record<string, string>)
 // ===== STORAGE / DEVICE / MISC =====
 
 localStorage.getItem(key): string | null / .setItem(key, value) / .removeItem(key)   // nothing else
+signal<Line[]>([]).stored("cart")      // a signal kept on the device under the key (JSON values): back on the next launch
 
 device.platform: "ios" | "android" | "web"    // getter, no ()
 device.language: string                       // "en", "ru", …
@@ -666,8 +667,11 @@ setLoop(() => { mesh.material = Material.lit({ color: next() }) })
 new Scene(options?: {
   ibl?: boolean                  // image-based ambient light; default TRUE — every scene has ambient
   environmentIntensity?: number  // IBL strength; default 20000
-  bloom?: boolean                // default false
-  bloomIntensity?: number        // default 0.2 (only with bloom: true)
+  postProcessing?: {             // the look: tone mapping, grading, a .cube LUT, bloom, vignette, AO, reflections, DoF
+    toneMapping?: 'aces' | 'neutral' | 'linear' | 'filmic', exposure?: number, contrast?: number, saturation?: number,
+    lut?: string, bloom?: boolean | { intensity?: number }, vignette?: boolean | { feather?: number },
+    ambientOcclusion?: boolean | { radius?: number }, screenSpaceReflections?: boolean, depthOfField?: boolean | { focusDistance?: number, aperture?: number }
+  }                              // live: scene.postProcessing.contrast = 1.1; .apply({ ... }) = the named fields only; .reset(); never assigned
   skybox?: ColorInput            // solid background / clear color
   antialias?: boolean            // 4× MSAA; default false
 })
@@ -775,7 +779,7 @@ 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.widgets(hud)
 scene.open()
 </file>
 
@@ -850,7 +854,7 @@ export class Spinner extends Aspect<'spinner'> {
 // 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 })
-scene.setContent([hud])
+scene.widgets(hud)
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -888,7 +892,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
+scene.widgets(UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }))
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>
@@ -936,6 +940,8 @@ const tabs = UITabs({
 Router.init(tabs)          // UITabs IS a UIScreen — present it directly
 // .select(id), .tab (getter), .onSelect(cb(id, i)) — fires on a bar tap, swipe, or select()
 // .badge(id, value) — true = dot, number/string = count pill, false/null/0 clears
+// Ambient, from any screen, no reference threading: UITabs.current (the visible tabs, or null) and
+//   UITabs.select("profile") — the twin of UIPager.current / UIPager.push
 // .pager — the UIPager underneath; UIPager.push(detail) from any screen keeps the bar
 // The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
 //   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: UIPager below.
@@ -1018,17 +1024,17 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
+    data?: () => T[],                      // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+                                           // absent = fed by hand: .setData(items) / .append(...items) / .prepend(...items) / .update(...items) / .removeByKey(...keys)
+                                           // (one feed per list: a list with `data` has no append on its type)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)
     overscan?: number,                     // extra px mounted above/below the viewport (default: one viewport)
     inverted?: boolean,                    // true = chat mode: starts scrolled to the end, append at bottom auto-scrolls
 })
-// Data is driven IMPERATIVELY (no diffing) — call these, never re-create the list:
-//   .setData(items: T[])                    // replace everything (diffed by key)
-//   .append(...items) / .prepend(...items)  // variadic; append = newest chat msg; prepend = history, no scroll jump
-//   .update(...items)                       // re-render rows with the same keyOf(); unknown keys ignored
-//   .removeByKey(...keys)
+// Rows added at the end scroll a chat at its bottom; rows added before the first (history) move nothing; a row
+// whose item is a new object re-renders. Never re-create the list.
 //   .itemCount (getter) / .getItem(key)
 //   .scrollTo(offset, animated?) / .scrollToKey(key, animated?) / .scrollToEnd(animated?) / .onScroll(cb(pos))
 //   .onEndReached(thresholdPx: number, cb)   // threshold FIRST and required; fires near the BOTTOM — load next page
@@ -1056,7 +1062,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)
@@ -1086,6 +1092,7 @@ UIInput() / UITextArea()
 //   type: "text"|"password"|"search"|"phone"|"email"|"number"|"decimal"|"url"|"date"|"time"
 //   enterKey: "done"|"go"|"next"|"search"|"send" (UIInput only) — return-key label
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
+//   autofocus: boolean — takes the focus as its screen opens (a composer, a chat, a search; once, one per screen)
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
 //   $focused: { borderColor, ..., duration? } — style while focused (reserved class)
@@ -1361,6 +1368,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).
@@ -1415,12 +1424,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/prompts/dist/ar-app.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
 
@@ -229,6 +229,7 @@ new WebSocket(url, headers?: Record<string, string>)
 // ===== STORAGE / DEVICE / MISC =====
 
 localStorage.getItem(key): string | null / .setItem(key, value) / .removeItem(key)   // nothing else
+signal<Line[]>([]).stored("cart")      // a signal kept on the device under the key (JSON values): back on the next launch
 
 device.platform: "ios" | "android" | "web"    // getter, no ()
 device.language: string                       // "en", "ru", …
@@ -812,6 +813,8 @@ const tabs = UITabs({
 Router.init(tabs)          // UITabs IS a UIScreen — present it directly
 // .select(id), .tab (getter), .onSelect(cb(id, i)) — fires on a bar tap, swipe, or select()
 // .badge(id, value) — true = dot, number/string = count pill, false/null/0 clears
+// Ambient, from any screen, no reference threading: UITabs.current (the visible tabs, or null) and
+//   UITabs.select("profile") — the twin of UIPager.current / UIPager.push
 // .pager — the UIPager underneath; UIPager.push(detail) from any screen keeps the bar
 // The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
 //   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: UIPager below.
@@ -894,17 +897,17 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
+    data?: () => T[],                      // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+                                           // absent = fed by hand: .setData(items) / .append(...items) / .prepend(...items) / .update(...items) / .removeByKey(...keys)
+                                           // (one feed per list: a list with `data` has no append on its type)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)
     overscan?: number,                     // extra px mounted above/below the viewport (default: one viewport)
     inverted?: boolean,                    // true = chat mode: starts scrolled to the end, append at bottom auto-scrolls
 })
-// Data is driven IMPERATIVELY (no diffing) — call these, never re-create the list:
-//   .setData(items: T[])                    // replace everything (diffed by key)
-//   .append(...items) / .prepend(...items)  // variadic; append = newest chat msg; prepend = history, no scroll jump
-//   .update(...items)                       // re-render rows with the same keyOf(); unknown keys ignored
-//   .removeByKey(...keys)
+// Rows added at the end scroll a chat at its bottom; rows added before the first (history) move nothing; a row
+// whose item is a new object re-renders. Never re-create the list.
 //   .itemCount (getter) / .getItem(key)
 //   .scrollTo(offset, animated?) / .scrollToKey(key, animated?) / .scrollToEnd(animated?) / .onScroll(cb(pos))
 //   .onEndReached(thresholdPx: number, cb)   // threshold FIRST and required; fires near the BOTTOM — load next page
@@ -932,7 +935,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)
@@ -962,6 +965,7 @@ UIInput() / UITextArea()
 //   type: "text"|"password"|"search"|"phone"|"email"|"number"|"decimal"|"url"|"date"|"time"
 //   enterKey: "done"|"go"|"next"|"search"|"send" (UIInput only) — return-key label
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
+//   autofocus: boolean — takes the focus as its screen opens (a composer, a chat, a search; once, one per screen)
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
 //   $focused: { borderColor, ..., duration? } — style while focused (reserved class)
@@ -1237,6 +1241,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).
@@ -1291,12 +1297,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/prompts/dist/ui-app.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
 
@@ -229,6 +229,7 @@ new WebSocket(url, headers?: Record<string, string>)
 // ===== STORAGE / DEVICE / MISC =====
 
 localStorage.getItem(key): string | null / .setItem(key, value) / .removeItem(key)   // nothing else
+signal<Line[]>([]).stored("cart")      // a signal kept on the device under the key (JSON values): back on the next launch
 
 device.platform: "ios" | "android" | "web"    // getter, no ()
 device.language: string                       // "en", "ru", …
@@ -402,6 +403,8 @@ const tabs = UITabs({
 Router.init(tabs)          // UITabs IS a UIScreen — present it directly
 // .select(id), .tab (getter), .onSelect(cb(id, i)) — fires on a bar tap, swipe, or select()
 // .badge(id, value) — true = dot, number/string = count pill, false/null/0 clears
+// Ambient, from any screen, no reference threading: UITabs.current (the visible tabs, or null) and
+//   UITabs.select("profile") — the twin of UIPager.current / UIPager.push
 // .pager — the UIPager underneath; UIPager.push(detail) from any screen keeps the bar
 // The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
 //   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: UIPager below.
@@ -484,17 +487,17 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
+    data?: () => T[],                      // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+                                           // absent = fed by hand: .setData(items) / .append(...items) / .prepend(...items) / .update(...items) / .removeByKey(...keys)
+                                           // (one feed per list: a list with `data` has no append on its type)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)
     overscan?: number,                     // extra px mounted above/below the viewport (default: one viewport)
     inverted?: boolean,                    // true = chat mode: starts scrolled to the end, append at bottom auto-scrolls
 })
-// Data is driven IMPERATIVELY (no diffing) — call these, never re-create the list:
-//   .setData(items: T[])                    // replace everything (diffed by key)
-//   .append(...items) / .prepend(...items)  // variadic; append = newest chat msg; prepend = history, no scroll jump
-//   .update(...items)                       // re-render rows with the same keyOf(); unknown keys ignored
-//   .removeByKey(...keys)
+// Rows added at the end scroll a chat at its bottom; rows added before the first (history) move nothing; a row
+// whose item is a new object re-renders. Never re-create the list.
 //   .itemCount (getter) / .getItem(key)
 //   .scrollTo(offset, animated?) / .scrollToKey(key, animated?) / .scrollToEnd(animated?) / .onScroll(cb(pos))
 //   .onEndReached(thresholdPx: number, cb)   // threshold FIRST and required; fires near the BOTTOM — load next page
@@ -522,7 +525,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)
@@ -552,6 +555,7 @@ UIInput() / UITextArea()
 //   type: "text"|"password"|"search"|"phone"|"email"|"number"|"decimal"|"url"|"date"|"time"
 //   enterKey: "done"|"go"|"next"|"search"|"send" (UIInput only) — return-key label
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
+//   autofocus: boolean — takes the focus as its screen opens (a composer, a chat, a search; once, one per screen)
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
 //   $focused: { borderColor, ..., duration? } — style while focused (reserved class)
@@ -827,6 +831,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).
@@ -881,12 +887,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/prompts/ui.md

@@ -125,7 +125,9 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
-    data: () => T[],                       // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+    data?: () => T[],                      // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+                                           // absent = fed by hand: .setData(items) / .append(...items) / .prepend(...items) / .update(...items) / .removeByKey(...keys)
+                                           // (one feed per list: a list with `data` has no append on its type)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)

package/src/animate/tween/spec.ts

@@ -200,7 +200,7 @@ export const uiValue = (v: unknown): ({ kind: number, sig?: string } & TweenValu
 
 /** Per-function argument counts of a UI transform list (degrees / px are the SDK's units). A
  *  translate named with a trailing `%` holds PERCENTS of the target's own box — a screen
- *  transition's pose (ui/transitions.ts), the only place that writes one. */
+ *  transition's pose (ui/transitions.ts) and a style's own `translate(-50%, -50%)` alike. */
 const TRANSFORM_FNS: Record<string, number> = {
   translate: 2, translateX: 1, translateY: 1, rotate: 1, scale: 2, scaleX: 1, scaleY: 1, skewX: 1, skewY: 1,
   "translate%": 2, "translateX%": 1, "translateY%": 1,
@@ -210,11 +210,10 @@ const TRANSFORM_FNS: Record<string, number> = {
  *  function is unknown (the caller falls back to matrix decomposition on the host). `scale(2)` and
  *  `translate(5px)` complete their second argument like CSS.
  *
- *  `percent`: a `%` in a translate is a percent of the target's box (`translateX(100%)` →
- *  `translateX%` [100]; a translate mixing the units splits into its two axes). Without it a `%`
- *  reads as px, as the style's own parser reads it — with a warning: only a screen transition
- *  measures a translate in percents. */
-export const parseTransformList = (s: string, percent = false): { sig: string, lanes: number[] } | null => {
+ *  A `%` in a translate is a percent of the target's own box (`translateX(100%)` → `translateX%`
+ *  [100]; a translate mixing the units splits into its two axes), the way the runtime reads a
+ *  style's transform: the box is measured when the matrix is composed, so a track fits any size. */
+export const parseTransformList = (s: string): { sig: string, lanes: number[] } | null => {
   const sig: string[] = []
   const lanes: number[] = []
   const re = /([a-zA-Z]+)\s*\(([^)]*)\)/g
@@ -236,17 +235,13 @@ export const parseTransformList = (s: string, percent = false): { sig: string, l
     if (args.length < n) { args.push(fn === "translate" ? 0 : args[0]!); units.push(units[0]!) }
     consumed = re.lastIndex
     if (fn.startsWith("translate") && units.includes("%")) {
-      if (!percent) {
-        warnOnce("transform:%", `transform: a % in ${fn}() is read as px — percents of the box work in a screen transition only`)
-      } else if (fn === "translate" && units[0] !== units[1]) {
+      if (fn === "translate" && units[0] !== units[1]) {
         sig.push(units[0] === "%" ? "translateX%" : "translateX", units[1] === "%" ? "translateY%" : "translateY")
-        lanes.push(...args)
-        continue
       } else {
         sig.push(fn + "%")
-        lanes.push(...args)
-        continue
       }
+      lanes.push(...args)
+      continue
     }
     sig.push(fn)
     lanes.push(...args)

package/src/chisel.ts

@@ -130,11 +130,11 @@ export const chiselVocab: ChiselVocab = {
       "onScroll", "onScrollRelease", "onOverscroll", "onRefresh", "onSubmit",
       "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",
       "onEndReached", "onStartReached",
-      "append", "insert", "remove", "setContent", "keepAlive", "url",
+      "append", "insert", "remove", "setContent", "widgets", "keepAlive", "url",
       "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
-      // UITabs / the native views (NativeView, CameraView, MapView, QRScanner)
-      "badge", "setData",
+      // UITabs / UIVirtualizedList's hand feed / the native views (NativeView, CameraView, MapView, QRScanner)
+      "badge", "setData", "update", "prepend", "removeByKey",
       "on", "off", "onReady", "onError", "onTap", "onMove", "onScan",
       "flyTo", "jumpTo", "fitPoints", "setPadding", "setUserLocation",
     ],

package/src/compile/serverSplit.ts

@@ -258,13 +258,15 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
   // The server bundle sees the whole project map (a server module may import shared code), but the
   // bundler's asset check runs over EVERY file in the map — so binaries and svgs must be present as
   // stubs, or a client screen's `asset("./x.png")` fails the SERVER build ("asset not found", seen
-  // with a Figma-exported design next to app.server.ts). The board's `design/` files are never
-  // server code and stay out entirely.
+  // with a Figma-exported design next to app.server.ts). A stub's value is the resource's PATH: a
+  // row of shared data that names a picture (`photo: "images/a.jpg"`) reaches the server as the
+  // path of that picture, which a seed stores into a file field (files/db.ts). The board's `design/`
+  // files are never server code and stay out entirely.
   const files: MemoryFiles = {}
   for (const e of opts.entries) {
     const path = normalizePath(e.path)
     if (/^\/design\//.test(path)) continue
-    if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ""`; continue }
+    if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ${JSON.stringify(path)}`; continue }
     files[path] = e.text ?? ""
   }
   let params = opts.params

package/src/g2/Scene2D.ts

@@ -6,7 +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 { _surfaceWidgets, type LayerElement, type WidgetSet } from "../ui/UILayer"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
@@ -189,14 +189,16 @@ 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. */
+  /** @internal The scene's widget layer (ui/UILayer.ts), made on the first use of `widgets`. */
   _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 {
+  /** @internal */
+  _widgetSet?: WidgetSet<any>
+  /** The widgets over the scene while it is presented — a HUD, a dialog, a sheet: `scene.widgets(hud)`
+   *  sets them, `widgets.append` / `.remove` manage them, `widgets.list` reads them. Laid out
+   *  over it; touches outside a widget's box reach the scene. */
+  get widgets(): WidgetSet<this> {
     ensureEmitter()
-    _setSurfaceContent(this, content)
-    return this
+    return _surfaceWidgets(this)
   }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }

package/src/gl/Scene.ts

@@ -10,7 +10,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _navEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
-import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
+import { _surfaceWidgets, type LayerElement, type WidgetSet } from "../ui/UILayer"
 import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
@@ -458,14 +458,16 @@ export class Scene implements Presentable {
     registerDest(TREE_DEST_SCENE3D, this._id, this)
     return [TREE_DEST_SCENE3D, this._id, "", ""]
   }
-  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  /** @internal The scene's widget layer (ui/UILayer.ts), made on the first use of `widgets`. */
   _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. `scene.setContent([hud])`. */
-  setContent(content: UIWidgetContent): this {
+  /** @internal */
+  _widgetSet?: WidgetSet<any>
+  /** The widgets over the scene while it is presented — a HUD, a dialog, a sheet: `scene.widgets(hud)`
+   *  sets them, `widgets.append` / `.remove` manage them, `widgets.list` reads them. Laid out
+   *  over it; touches outside a widget's box reach the scene. */
+  get widgets(): WidgetSet<this> {
     ensureEmitter()
-    _setSurfaceContent(this, content)
-    return this
+    return _surfaceWidgets(this)
   }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }