lecodes-sdk 2.2.3 → 2.2.5

package/src/ui/UIVirtualizedList.ts

@@ -10,20 +10,14 @@ export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & {
   keyboardDismissMode?: "interactive" | "scroll" | "none",
 }
 
-export interface VListConfig<T> {
-    /** The rows, read reactively: the list follows the signals this reads, the way a container's
-     *  function children do. Rows are told apart by `keyOf`; a row whose item is another object
-     *  re-renders. Appended rows and rows added at the start are told from a rewrite (a chat at
-     *  its bottom follows what is appended; older history above moves nothing). */
-    data: () => T[]
+interface VListBaseConfig<T> {
     /** Stable unique key of an item. */
     keyOf: (item: T) => string
     /** Subtree factory — called when the item enters the window; the subtree lives until it
      *  leaves. */
     render: (item: T) => UINodeChild
     /** Height estimate (px) used before the first measurement — a number, or a per-item function
-     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Computed once when the item is
-     *  added. */
+     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Read when the item is added. */
     estimatedHeight: number | ((item: T) => number)
     /** Extra px around the viewport kept mounted. Default: one viewport height. */
     overscan?: number
@@ -32,9 +26,26 @@ export interface VListConfig<T> {
     inverted?: boolean
 }
 
-/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
- *  and chats. Fed by `data`, a function over signals. */
-export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
+/** A list fed by `data`: the rows are read reactively, the way a container's function children
+ *  are. Such a list has no imperative feed (`append` and the rest are not on its type). */
+export interface VListBoundConfig<T> extends VListBaseConfig<T> {
+    /** The rows, read reactively: the list follows the signals this reads. Rows are told apart by
+     *  `keyOf`; a row whose item is another object re-renders. The change is told from the keys:
+     *  rows gone are removals, new rows are inserts where they stand (a chat at its bottom follows
+     *  an append; rows above the reader move nothing), a reorder rewrites the keys. */
+    data: () => T[]
+}
+
+/** A list fed by hand: `setData` / `append` / `prepend` / `update` / `removeByKey`. */
+export interface VListFedConfig<T> extends VListBaseConfig<T> {
+    data?: undefined
+}
+
+export type VListConfig<T> = VListBoundConfig<T> | VListFedConfig<T>
+
+/** What both forms of the list share: the items held, scrolling, the scroll / refresh / edge
+ *  callbacks. */
+export interface UIVirtualizedListBase<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
     readonly type: "vlist"
 
     /** Number of data items (mounted or not). */
@@ -60,7 +71,31 @@ export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtuali
     onStartReached(thresholdPx: number, callback: () => void): this
 }
 
-export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {
+/** A virtualized list fed by `data` (a function over signals): write the signal, the list follows. */
+export interface UIBoundVirtualizedList<T = unknown> extends UIVirtualizedListBase<T> {}
+
+/** A virtualized list fed by hand. Each call goes straight to the runtime: `append` is O(1). */
+export interface UIFedVirtualizedList<T = unknown> extends UIVirtualizedListBase<T> {
+    /** Replace the data wholesale — diffed by key like a `data` write (vanished keys are removed,
+     *  new ones inserted where they stand, a reorder rewrites). */
+    setData(items: T[]): this
+    /** Append items to the end (auto-scrolls when `inverted` and resting at the bottom). */
+    append(...items: T[]): this
+    /** Insert at the start WITHOUT a scroll jump (the runtime compensates the offset). */
+    prepend(...items: T[]): this
+    /** Update items with the same keys: mounted ones re-render; the cached height persists until
+     *  re-measured. */
+    update(...items: T[]): this
+    /** Remove items by key. */
+    removeByKey(...keys: string[]): this
+}
+
+/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
+ *  and chats. Fed by `data`, a function over signals, or by hand (`append` and the rest); which
+ *  one is the config's and the type's. */
+export type UIVirtualizedList<T = unknown> = UIBoundVirtualizedList<T> | UIFedVirtualizedList<T>
+
+export class VListElement<T> extends Element<"vlist"> implements UIFedVirtualizedList<T> {
     private readonly sl: ((scrollPosition: number) => void)[] = []     // scroll
     private readonly erl: (() => void)[] = []                          // endReached
     private readonly strl: (() => void)[] = []                         // startReached
@@ -74,6 +109,7 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     private estimate: (item: T) => number
     private readonly _overscan: number
     private readonly _inverted: boolean
+    private readonly _bound: boolean
     private _endThreshold = 0
     private _startThreshold = 0
     private _inited = false
@@ -90,10 +126,12 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
             : () => config.estimatedHeight as number
         this._overscan = config.overscan ?? -1
         this._inverted = config.inverted ?? false
+        const data = config.data
+        this._bound = data !== undefined
         // The data binding is the element's (it goes with it); its first run waits a microtask so the
         // edge thresholds chained after the constructor (`.onEndReached(…)`) are in the runtime's list
         // state, which is created on the first write.
-        Promise.resolve().then(() => { if (this._h.id !== 0) createBinding(this, "data", () => this._apply(config.data())) })
+        if (data !== undefined) Promise.resolve().then(() => { if (this._h.id !== 0) createBinding(this, "data", () => this._apply(data())) })
     }
 
     // The runtime's list state is created on the first data write — after the app had its chance to
@@ -104,42 +142,68 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         tree().vlistInit(this._h.id, this._overscan, this._inverted, this._startThreshold, this._endThreshold)
     }
 
-    /** The data as it is now against what the runtime holds: rows added at the end or at the start
-     *  are inserts (the runtime anchors the scroll: a chat follows an append, history above moves
-     *  nothing), rows gone are removals, anything else a rewrite of the keys (measured heights stay). */
+    /** The two feeds are exclusive per list: a hand-made change to a list `data` feeds would be
+     *  undone by the binding's next run, so it is refused and logged. */
+    private _fed(method: string): boolean {
+        if (!this._bound) return true
+        console.error(`UIVirtualizedList.${method}(): the list is fed by data — write the signal it reads instead`)
+        return false
+    }
+
+    /** The data as it is now against what the runtime holds. Keys gone are removals, keys new are
+     *  inserts where they stand in the new order — both anchored by the runtime (a chat follows an
+     *  append, rows above the reader move nothing) — as long as the keys kept keep their order;
+     *  a reorder rewrites the keys (measured heights stay). A mounted row whose item is another
+     *  object re-renders. */
     private _apply(next: T[]): void {
         const prevKeys = this.keys
         const prevItems = this.items
         const keys: string[] = []
-        const estimates: number[] = []
         const items = new Map<string, T>()
         for (const item of next) {
             const k = this.keyOf(item)
             if (items.has(k)) continue                      // a repeated key: the first row stands
             items.set(k, item)
             keys.push(k)
-            estimates.push(this.estimate(item))
         }
         this.keys = keys
         this.items = items
         this._ensure()
         const id = this._h.id
         if (id === 0) return
+        // the estimates of keys[from, to): read for the rows the runtime is told of, not for every row
+        const estimates = (from: number, to: number): number[] => {
+            const out: number[] = []
+            for (let i = from; i < to; i++) out.push(this.estimate(items.get(keys[i])!))
+            return out
+        }
         const n = prevKeys.length, m = keys.length
-        const same = (from: number) => { for (let i = 0; i < n; i++) if (keys[from + i] !== prevKeys[i]) return false; return true }
         if (n === 0 || m === 0) {
-            tree().vlistSetKeys(id, keys, estimates)
-        } else if (m >= n && same(0)) {
-            if (m > n) tree().vlistInsertKeys(id, -1, keys.slice(n), estimates.slice(n))   // the same keys: nothing to tell
-        } else if (m > n && same(m - n)) {
-            tree().vlistInsertKeys(id, 0, keys.slice(0, m - n), estimates.slice(0, m - n))
+            tree().vlistSetKeys(id, keys, estimates(0, m))
         } else {
-            // removals only: the new keys are the old ones in order, some left out
+            // the keys kept, in the old order, must be the keys kept in the new order
             const gone: string[] = []
-            let j = 0
-            for (const k of prevKeys) { if (j < m && keys[j] === k) j++; else gone.push(k) }
-            if (m < n && j === m) tree().vlistRemoveKeys(id, gone)
-            else tree().vlistSetKeys(id, keys, estimates)
+            let j = 0, ordered = true
+            for (const k of prevKeys) {
+                if (!items.has(k)) { gone.push(k); continue }
+                while (j < m && !prevItems.has(keys[j])) j++    // skip the new rows
+                if (keys[j] !== k) { ordered = false; break }
+                j++
+            }
+            if (!ordered) {
+                tree().vlistSetKeys(id, keys, estimates(0, m))
+            } else {
+                if (gone.length > 0) tree().vlistRemoveKeys(id, gone)
+                // runs of new rows, in order: everything before a run is already in the list, so the
+                // run's position in the new array is its index in the list as it stands
+                for (let i = 0; i < m;) {
+                    if (prevItems.has(keys[i])) { i++; continue }
+                    let e = i + 1
+                    while (e < m && !prevItems.has(keys[e])) e++
+                    tree().vlistInsertKeys(id, e === m ? -1 : i, keys.slice(i, e), estimates(i, e))
+                    i = e
+                }
+            }
         }
         // a mounted row whose item is another object re-renders; the others pick theirs up when they re-enter
         for (const k of this.mounted.keys()) {
@@ -147,6 +211,67 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         }
     }
 
+    /** The new rows of `items` (keys not held yet, repeats dropped), registered. */
+    private _register(items: T[]): [string[], number[]] {
+        const keys: string[] = []
+        const estimates: number[] = []
+        for (const item of items) {
+            const k = this.keyOf(item)
+            if (this.items.has(k)) continue
+            this.items.set(k, item)
+            keys.push(k)
+            estimates.push(this.estimate(item))
+        }
+        return [keys, estimates]
+    }
+
+    // --- the hand feed: each call is the runtime's operation, no diff ---
+    setData(items: T[]): this {
+        if (this._fed("setData")) this._apply(items)
+        return this
+    }
+
+    append(...items: T[]): this {
+        if (!this._fed("append")) return this
+        const [keys, estimates] = this._register(items)
+        if (keys.length === 0) return this
+        this.keys.push(...keys)
+        this._ensure()
+        if (this._h.id !== 0) tree().vlistInsertKeys(this._h.id, -1, keys, estimates)
+        return this
+    }
+
+    prepend(...items: T[]): this {
+        if (!this._fed("prepend")) return this
+        const [keys, estimates] = this._register(items)
+        if (keys.length === 0) return this
+        this.keys = keys.concat(this.keys)
+        this._ensure()
+        if (this._h.id !== 0) tree().vlistInsertKeys(this._h.id, 0, keys, estimates)
+        return this
+    }
+
+    update(...items: T[]): this {
+        if (!this._fed("update")) return this
+        for (const item of items) {
+            const k = this.keyOf(item)
+            if (!this.items.has(k) || this.items.get(k) === item) continue
+            this.items.set(k, item)
+            if (this._h.id !== 0 && this.mounted.has(k)) tree().vlistInvalidate(this._h.id, k)
+        }
+        return this
+    }
+
+    removeByKey(...keys: string[]): this {
+        if (!this._fed("removeByKey")) return this
+        const gone: string[] = []
+        for (const k of keys) if (this.items.delete(k)) gone.push(k)
+        if (gone.length === 0) return this
+        this.keys = this.keys.filter((k) => this.items.has(k))
+        if (this._h.id !== 0) tree().vlistRemoveKeys(this._h.id, gone)
+        return this
+    }
+
     get itemCount(): number { return this.items.size }
     getItem(key: string): T | undefined { return this.items.get(key) }
 
@@ -212,8 +337,11 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     }
 }
 
-/** Create a virtualized list from a config (`data` + `keyOf` + `render` + `estimatedHeight`
- *  required). Give it a size (`flexGrow: 1` as a screen body). */
+/** Create a virtualized list (`keyOf` + `render` + `estimatedHeight` required). With `data` the
+ *  list follows the signals it reads and has no hand feed; without it, feed it with `setData` /
+ *  `append` / `prepend` / `update` / `removeByKey`. Give it a size (`flexGrow: 1` as a screen body). */
+export function UIVirtualizedList<T>(config: VListBoundConfig<T>): UIBoundVirtualizedList<T>
+export function UIVirtualizedList<T>(config: VListFedConfig<T>): UIFedVirtualizedList<T>
 export function UIVirtualizedList<T>(config: VListConfig<T>): UIVirtualizedList<T> {
     return new VListElement<T>(config)
 }

package/src/ui/UIWidget.ts

@@ -1,7 +1,8 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { ContainerElement, buildUI, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type PaddingStyle, type PositionStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode"
-import { UIOverlay } from "./UILayer"
-import { TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, tree } from "./tree"
+import { _appLayer } from "./UILayer"
+import type { Presentable } from "./presentable"
+import { TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, tree, unpin } from "./tree"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
@@ -14,13 +15,13 @@ export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
 }
 
 
-/** A floating overlay that belongs to a WINDOW, not to a box (docs/plans/widgets-plan.md): a dialog,
- *  a sheet, a HUD, a mini-player. A widget is a CHILD of the place it belongs to — a `UIScreen`
- *  (among its children), a surface's content (`scene.setContent([hud])`) or the app layer
- *  (`UIOverlay`) — and is laid out and painted in the box of the outermost presented destination
- *  that contains it: absolutely positioned in that box, above everything else in it. A widget on a
- *  tab page covers the tab bar and rides the shell's push and pop. A widget inside a `UIColumn` or
- *  any other box is an error: a floating element of a box is an absolute child, not a widget.
+/** A floating overlay that belongs to a DESTINATION, not to a box (docs/plans/widgets-plan.md): a
+ *  dialog, a sheet, a HUD, a mini-player. A widget is one of the `widgets` of the place it belongs
+ *  to — `UIScreen(content).widgets(dialog)`, `scene.widgets(hud)` — and is laid out and painted in
+ *  the box of the outermost presented destination that contains it: absolutely positioned in that
+ *  box, above everything else in it. A widget on a tab page covers the tab bar and rides the
+ *  shell's push and pop. A widget among the children of a box is an error: a floating element of
+ *  a box is an absolute child, not a widget.
  *
  *  It shows with its place unless its style says `display: "none"`; `show()` / `hide()` flip that,
  *  and so does a state block (`$class: { display: "flex" }`). `UIModal` / `UIPopover` /
@@ -28,13 +29,12 @@ export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
 export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle & BaseStyle & { overlayColor?: Color | null }> {
   readonly type: "widget",
 
-  /** Show the widget: `display: "flex"`, on top of its root — it moves to the end of its parent's
-   *  children, so a dialog opened later covers an earlier one and a HUD declared after it. A widget
-   *  with no parent is appended to the app layer first (`UIOverlay`) — a global overlay above every
-   *  destination, up until `hide()`. */
+  /** Show the widget: `display: "flex"`, on top of its root — it moves to the end of its
+   *  destination's widgets, so a dialog opened later covers an earlier one and a HUD declared after
+   *  it. A widget that belongs nowhere goes ABOVE EVERY destination — a global loader, a dialog
+   *  opened from anywhere — and stays there, hidden by `hide()`, until it is given a place. */
   show(): void,
-  /** Hide the widget: `display: "none"`. It stays where it is (its place, the app layer), ready
-   *  for the next `show()`. */
+  /** Hide the widget: `display: "none"`. It stays where it is, ready for the next `show()`. */
   hide(): void,
 
   /** Shown right now by its own display (`show()` ran, `hide()` hasn't, no state block hides
@@ -42,6 +42,14 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
    *  visibility, not the widget's. */
   readonly isShown: boolean,
 
+  /** @deprecated A widget is one of the `widgets` of the place it belongs to (2026-10-07): write
+   *  `UIScreen(content).widgets(widget)` / `scene.widgets(widget)` instead. This alias is
+   *  `owner.widgets.append(widget)` with the widget hidden, so the `show()` that follows flips it as
+   *  on any placed widget; `attachTo(null)` takes it out, and the next `show()` puts it above every
+   *  destination. For the projects compiled before the change; removed with the release that
+   *  recompiles them. */
+  attachTo(owner: Presentable | null): this,
+
   /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this,
   /** Tap on the overlay layer (requires an `overlayColor`). */
@@ -74,7 +82,7 @@ export class WidgetElement extends ContainerElement<"widget"> {
       // is a display flip wherever the widget is, so its pose plays (a modal's fade) exactly as on
       // a placed one. Appended shown, it would merely appear: a widget shows with its place, no pose.
       this.style({ display: "none" } as any)
-      UIOverlay.append(this as any)   // pins it: _pinned reads the display
+      _appLayer().append(this as any)   // pins it: _pinned reads the display
     } else {
       // Shown = on top of its root: a show() moves the widget to the TAIL of its parent's children
       // (child order is the one ordering rule), so a modal opened later covers an earlier one and
@@ -97,6 +105,21 @@ export class WidgetElement extends ContainerElement<"widget"> {
   get isShown(): boolean {
     return this._shown
   }
+  /** @deprecated see the interface */
+  attachTo(owner: Presentable | null): this {
+    if (this._h.id === 0) return this
+    const parentId = tree().parent(this._h.id)
+    if (parentId !== 0) {                                      // one parent: a re-attach moves it
+      tree().remove(parentId, this._h.id)
+      unpin(this._h.id)                                        // as a node's remove(): shown nowhere
+    }
+    if (owner) {
+      // Hidden first: a widget shows with its place, and the old contract showed it on show() only.
+      this.style({ display: "none" } as any)
+      owner.widgets.append(this as any)
+    }
+    return this
+  }
   /** @internal The intent changed (the app's call, or the runtime's report of a cascade flip):
    *  subclasses hook the change (UIModal's onOpen / onClose). */
   _setShown(shown: boolean): void {
@@ -163,8 +186,8 @@ const makeWidget = (style: any, children: any) => new WidgetElement("widget", st
 /** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
 export const __UIWidget = (children: UINodeChild[] | ChildrenFn): UIWidget => makeWidget({}, children)
 
-/** Create a widget (same argument forms as `UIColumn`). Put it where it belongs — among a screen's
- *  children, in `scene.setContent([...])`, or `UIOverlay` — position it with absolute-style props
+/** Create a widget (same argument forms as `UIColumn`). Give it to the destination it belongs to —
+ *  `UIScreen(content).widgets(w)`, `scene.widgets(w)` — position it with absolute-style props
  *  (`top`/`left`/`bottom`/`right`), then `show()`/`hide()`. */
 export function UIWidget(...children: UIChildArg[]): UIWidget;
 export function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;

package/src/ui/presentable.ts

@@ -2,7 +2,7 @@
 // Anything that can occupy the app's main slot implements it: UIScreen, Scene (+ARScene),
 // Scene2D, NativeView, UIVideo. Exactly one Presentable is visible at a time — a screen no
 // longer overlays a scene, it replaces it (with a transition); UI over a scene goes through
-// `scene.setContent([hud])` — a widget is the destination's content (docs/plans/widgets-plan.md).
+// `scene.widgets(hud)` — a widget belongs to a destination (docs/plans/widgets-plan.md).
 //
 // A destination is addressed by (kind, id): a screen / video by its node id, a scene by its
 // scene id, a native view by its viewId (`_dest()`). The runtime reports the lifecycle back through
@@ -12,7 +12,7 @@
 // element code into engine-only bundles.
 
 import type { EasingInput } from "../animate/tween/easing"
-import type { UIWidget } from "./UIWidget"
+import type { WidgetSet } from "./UILayer"
 
 /** The built-in transitions (ui/transitions.ts holds what each one is). `push` / `pop` are the
  *  stacked-navigation pair — the incoming screen slides over the other one, which drifts and dims;
@@ -101,12 +101,12 @@ export interface Presentable {
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
   onBack(callback: () => void): this
-  /** The destination's widgets (docs/plans/widgets-plan.md): a dialog, a HUD, a sheet declared as
-   *  CONTENT of the place they belong to. A `UIScreen` takes them among its children; a surface — a
-   *  `Scene`, a `Scene2D`, a `NativeView`, a `UIVideo` — takes widgets alone, laid out over it while
-   *  it is presented (touches outside a widget's box reach the surface). A widget shows with its
-   *  destination unless its style says `display: "none"`; `show()` / `hide()` flip that. */
-  setContent(content: (UIWidget | null | undefined | false)[] | (() => (UIWidget | null | undefined | false)[])): this
+  /** The destination's widgets (docs/plans/widgets-plan.md): a dialog, a HUD, a sheet — what floats
+   *  over it. `x.widgets(a, b)` sets them, `x.widgets.append` / `.remove` manage them, `x.widgets.list`
+   *  reads them; the same on a `UIScreen` (apart from its `children`), a `Scene`, a `Scene2D`, a
+   *  `NativeView`, a `UIVideo`. A widget shows with its destination unless its style says
+   *  `display: "none"`; `show()` / `hide()` flip that. */
+  readonly widgets: WidgetSet<this>
   /** @internal Async work that must finish BEFORE this destination replaces the current one
    *  (camera permission, warm render, session launch — ARScene). The previous destination —
    *  typically a loading screen — stays visible while it runs; `open()` and `Router.push/replace`

package/src/ui/transitions.ts

@@ -128,7 +128,7 @@ type Side = { lanes: Lane[], atMs: number, durMs: number, easing: EasingSpec }
 const list = <T>(v: T | T[]): T[] => (Array.isArray(v) ? v : [v])
 
 const transformLane = (value: string | string[]): Lane | null => {
-  const parsed = list(value).map((v) => parseTransformList(v, true))
+  const parsed = list(value).map((v) => parseTransformList(v))
   const first = parsed[0]
   if (!first || parsed.some((p) => p === null || p.sig !== first.sig)) {
     warnOnce("transition:transform", "a transition's transform must be a list of translate / scale / rotate, the same functions in every keyframe — ignored")

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.2.3"
+export const SDK_VERSION = "2.2.5"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {

package/tests/helpers/fakeTree.ts

@@ -87,7 +87,12 @@ export class FakeTree {
     if (!p || !c) return
     if (c.parent !== 0) return
     c.parent = parent
-    const i = Math.max(0, Math.min(index, p.children.length))
+    // tree.cpp treeInsert: a widget is the TAIL of a screen's children (its index counted past the
+    // content, clamped into the tail); a content index past the content lands before the widgets.
+    const own = p.type === "layer" ? 0 : p.children.filter((x) => this.nodes.get(x)?.type !== "widget").length
+    const i = c.type === "widget"
+      ? own + Math.max(0, Math.min(index < own ? 0 : index - own, p.children.length - own))
+      : Math.max(0, Math.min(index, own))
     p.children.splice(i, 0, child)
   }
   remove = (parent: number, child: number): void => {