lecodes-sdk 2.2.4 → 2.2.5

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.4",
+  "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/src/chisel.ts

@@ -130,7 +130,7 @@ 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 / UIVirtualizedList's hand feed / the native views (NativeView, CameraView, MapView, QRScanner)

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() }

package/src/inject.ts

@@ -104,7 +104,7 @@ export {
   UITabs, type UITabDef,
   defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
-  UIOverlay, type UIWidgetContent,
+  type WidgetSet, type UIWidgetContent, type UIWidgetChild,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,
   UIPopover, type UIPopoverStyle,

package/src/ui/NativeView.ts

@@ -10,7 +10,7 @@
 // wrapper convention.
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
-import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "./UILayer"
+import { _surfaceWidgets, type LayerElement, type WidgetSet } from "./UILayer"
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "./presentable"
 import { _transitionId, TRANSITION_NONE } from "./transitions"
 import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
@@ -46,8 +46,8 @@ export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableSty
   /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
   on(event: string, callback: (data?: any) => void): this
   off(event: string, callback: (data?: any) => void): this
-  /** The UI over the view when presented: widgets over it (`Presentable.setContent`). */
-  setContent(content: UIWidgetContent): this
+  /** The widgets over the view when it is presented (`Presentable.widgets`): `map.widgets(header, card)`. */
+  readonly widgets: WidgetSet<this>
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
@@ -88,13 +88,15 @@ export class NativeViewElement extends Element<"native"> implements Presentable
 
   /** @internal */
   _dest(): DestTuple { return [TREE_DEST_NATIVE, this._viewId, this.viewName, this._paramsJson] }
-  /** @internal The view's content layer (ui/UILayer.ts), made by the first setContent. */
+  /** @internal The view's widget layer (ui/UILayer.ts), made on the first use of `widgets`. */
   _contentLayer?: LayerElement
-  /** The UI over the view when it is presented full screen — widgets (a header, a card, a sheet
-   *  over a map), laid out over it; touches outside a widget's box reach the view. */
-  setContent(content: UIWidgetContent): this {
-    _setSurfaceContent(this, content)
-    return this
+  /** @internal */
+  _widgetSet?: WidgetSet<any>
+  /** The widgets over the view while it is presented — a HUD, a dialog, a sheet: `map.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 view. */
+  get widgets(): WidgetSet<this> {
+    return _surfaceWidgets(this)
   }
 
   open(options?: PresentOptions): void {

package/src/ui/UI.ts

@@ -10,7 +10,7 @@ export { UIVideo, type UIVideoStyle } from './UIVideo'
 export { UIInput, UITextArea, type UIInputStyle } from './UIInput'
 
 export { UIWidget, type UIWidgetStyle } from './UIWidget'
-export { UIOverlay, type UIWidgetContent } from './UILayer'
+export { type WidgetSet, type UIWidgetContent, type UIWidgetChild } from './UILayer'
 export { UIModal, type UIModalStyle } from './UIModal'
 export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet'
 export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover'