lecodes-sdk 1.2.0 → 2.0.0

package/src/ui/UIPager.ts

@@ -1,6 +1,9 @@
 import { ContainerElement, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode"
 import { disposeBinding } from "../core/signals"
 import type { UIScreen } from "./UIScreen"
+import type { NavigateOptions, PopOptions } from "./router"
+import { _transitionBack, _transitionId, TRANSITION_UNSET } from "./transitions"
+import { pin, tree } from "./tree"
 
 // UIPager — the system's ONE screen-navigation element (docs/pager-component-plan.md): sibling
 // tabs that swipe natively side to side, with a native navigation STACK per tab. `push` opens a
@@ -11,12 +14,15 @@ import type { UIScreen } from "./UIScreen"
 // the current screen (UIPager.current) — no reference threading into child screens. Router stays
 // distinct: `Router.push` opens ON TOP of the pager (bars and all), the pager navigates within.
 //
-// Wire node type "pager": children are separate layout roots (full UIScreens), NOT yoga children.
-// The wire shape is `children` flat in TAB-MAJOR order (tab 0's stack root→top, then tab 1's, …)
-// partitioned by `_lens` (per-tab stack lengths) with `_index` = selected tab. State is mutated
-// BEFORE each command, so the host reconciles against the node; commands only name the native
-// transition to play. Host-driven changes come back via `_hostDidSelect` / `_hostDidPop` — both
-// idempotent no-ops when the logical state already matches.
+// The SDK owns the logical state (`_pages` flat in TAB-MAJOR order, `_lens` = per-tab stack
+// lengths, `_index` = the selected tab) and sends it to the runtime whole (`pagerSetContent`) or
+// as a stack command with the page id; the runtime mirrors it, parents the pages' views under the
+// pager and reports host-driven changes back (TREE_EVENT_PAGER_SELECT / PAGER_POP) — both
+// idempotent no-ops here when the logical state already matches.
+//
+// A change of a tab's stack plays a transition exactly as the Router's does (transitions.ts): the
+// same names and specs, the same way back remembered by the entry — the runtime plays it between
+// the two pages, inside the pager's box.
 
 /** Styles a pager accepts — layout box + drawable (background, borders, …). Pages style
  *  themselves; the pager only owns its own slot. */
@@ -59,17 +65,21 @@ export interface UIPager extends UIElementBase<UIPagerStyle, DrawableStyle & Bas
   /** Fires when the selected tab changes and has settled — a user swipe or `select()`. */
   onSelect(callback: (index: number) => void): this,
 
-  /** Push `screen` on top of the **current tab** — slides in natively; the edge back-swipe (or
-   *  `pop()`) removes it. Other tabs are unaffected. */
-  push(screen: UIScreen): this,
+  /** Push `screen` on top of the **current tab**; the edge back-swipe (or `pop()`) removes it.
+   *  Other tabs are unaffected. Transitions as in `Router.push`: `"push"` unless one is named, and
+   *  the screen remembers its way back (`popTransition`, or the mirror of the way it came). */
+  push(screen: UIScreen, opts?: NavigateOptions): this,
   /** Pop the current tab's top screen (no-op at the tab root — the root never pops). The
-   *  programmatic twin of the native edge back-swipe. */
-  pop(): this,
-  /** Unwind the current tab back to its root screen in one step. */
-  popToRoot(): this,
+   *  programmatic twin of the native edge back-swipe. Plays the way back the screen remembers
+   *  unless a transition is named. */
+  pop(opts?: PopOptions): this,
+  /** Unwind the current tab back to its root screen in one step: the top screen leaves with its
+   *  way back (or the named transition), the ones between are never shown. */
+  popToRoot(opts?: PopOptions): this,
   /** Swap the current tab's top screen for `screen` without growing the stack (at depth 1 this
-   *  swaps the tab's root). */
-  replace(screen: UIScreen): this,
+   *  swaps the tab's root). `"fade"` unless a transition is named; the way back stays the one of
+   *  the place in the stack unless `popTransition` names another. */
+  replace(screen: UIScreen, opts?: NavigateOptions): this,
   /** The current tab's screens, root → top (read-only snapshot). */
   readonly stack: UIScreen[],
   /** The current tab's stack depth — 1 means only the root. While `depth > 1`, swiping between
@@ -77,13 +87,16 @@ export interface UIPager extends UIElementBase<UIPagerStyle, DrawableStyle & Bas
   readonly depth: number,
   /** Fires when the current tab's depth changes — push, pop, replace, or a back-swipe. */
   onChange(callback: (depth: number) => void): this,
+  /** The pages, tab-major (every tab's stack root → top). */
+  readonly children: UIScreen[],
 }
 
 export class PagerElement extends ContainerElement<"pager"> {
-  /** Per-tab stack lengths — partitions the flat tab-major `children`. Named `_*` so chisel
-   *  keeps it (the host reads it live). */
-  _lens: number[]
-  /** Selected tab. */
+  /** @internal The pages, flat in tab-major order. */
+  _pages: any[] = []
+  /** @internal Per-tab stack lengths — partitions `_pages`. */
+  _lens: number[] = []
+  /** @internal Selected tab. */
   _index = 0
   // >0 while a screen owned by this pager is the visible one (its onOpen fired, onClose hasn't).
   // Only one owned screen is ever open, so this is effectively 0/1 — the count only makes the
@@ -96,24 +109,33 @@ export class PagerElement extends ContainerElement<"pager"> {
     // flexShrink: 1 default (SDK-owned, like UIScrollable's): pages are separate layout roots
     // sized to the pager's box, so yoga sees no shrinkable content — without this a pager in a
     // flex column overflows the screen instead of leaving room for the tab bar.
-    super("pager", { flexShrink: 1, ...style }, tabs as any)
-    this._lens = tabs.map(() => 1)
-    for (const s of this.children) this._track(s)
+    super("pager", { flexShrink: 1, ...style }, [])
+    this._rebuild(tabs as any[])
   }
 
-  /** Start offset of tab `i`'s segment in the flat `children`. */
+  /** Start offset of tab `i`'s segment in the flat `_pages`. */
   private _offset(i: number): number {
     let off = 0
     for (let t = 0; t < i; t++) off += this._lens[t]
     return off
   }
 
+  /** Push the whole picture to the runtime. */
+  private _sync(): void {
+    if (this._h.id === 0) return
+    for (const p of this._pages) pin(p)
+    tree().pagerSetContent(this._h.id, this._pages.map((p) => p._h.id), this._lens.slice(), this._index)
+  }
+
+  get children(): any[] {
+    return this._pages.slice()
+  }
   get index(): number {
     return this._index
   }
   get stack(): UIScreen[] {
     const off = this._offset(this._index)
-    return this.children.slice(off, off + (this._lens[this._index] ?? 0))
+    return this._pages.slice(off, off + (this._lens[this._index] ?? 0))
   }
   get depth(): number {
     return this._lens[this._index] ?? 0
@@ -131,74 +153,78 @@ export class PagerElement extends ContainerElement<"pager"> {
   select(index: number, animated = false): this {
     if (index < 0 || index >= this._lens.length || index === this._index) return this
     this._index = index
-    if (this._id !== 0) _creatorUI.command(this, "select", animated)
+    if (this._h.id !== 0) tree().pagerSelect(this._h.id, index, animated)
     this._emitSelect()
     return this
   }
 
-  push(screen: UIScreen): this {
+  push(screen: UIScreen, opts?: NavigateOptions): this {
     if (this._lens.length === 0) {
       console.warn("UIPager.push: pager has no tabs")
       return this
     }
-    this.children.splice(this._offset(this._index) + this._lens[this._index], 0, screen)
+    this._pages.splice(this._offset(this._index) + this._lens[this._index], 0, screen)
     this._lens[this._index]++
     this._track(screen)
-    if (this._id !== 0) _creatorUI.command(this, "push")
+    pin(screen as any)
+    if (this._h.id !== 0) {
+      const transition = opts?.transition ?? "push"
+      const back = opts?.popTransition !== undefined ? _transitionId(opts.popTransition) : _transitionBack(transition)
+      tree().pagerPush(this._h.id, (screen as any)._h.id, _transitionId(transition), back)
+    }
     this._emitChange()
     return this
   }
 
-  pop(): this {
+  pop(opts?: PopOptions): this {
     if ((this._lens[this._index] ?? 0) <= 1) return this
-    this.children.splice(this._offset(this._index) + this._lens[this._index] - 1, 1)
+    this._pages.splice(this._offset(this._index) + this._lens[this._index] - 1, 1)
     this._lens[this._index]--
-    if (this._id !== 0) _creatorUI.command(this, "pop")
+    // the runtime detaches the page when its transition lands (its close fires first)
+    if (this._h.id !== 0) tree().pagerPop(this._h.id, _transitionId(opts?.transition, TRANSITION_UNSET))
     this._emitChange()
     return this
   }
 
-  popToRoot(): this {
+  popToRoot(opts?: PopOptions): this {
     const len = this._lens[this._index] ?? 0
     if (len <= 1) return this
-    this.children.splice(this._offset(this._index) + 1, len - 1)
+    this._pages.splice(this._offset(this._index) + 1, len - 1)
     this._lens[this._index] = 1
-    if (this._id !== 0) _creatorUI.command(this, "popToRoot")
+    if (this._h.id !== 0) tree().pagerPopToRoot(this._h.id, _transitionId(opts?.transition, TRANSITION_UNSET))
     this._emitChange()
     return this
   }
 
-  replace(screen: UIScreen): this {
+  replace(screen: UIScreen, opts?: NavigateOptions): this {
     if (this._lens.length === 0) {
       console.warn("UIPager.replace: pager has no tabs")
       return this
     }
-    this.children[this._offset(this._index) + this._lens[this._index] - 1] = screen
+    const at = this._offset(this._index) + this._lens[this._index] - 1
+    const old = this._pages[at]
+    if (old === screen) return this
+    this._pages[at] = screen
     this._track(screen)
-    if (this._id !== 0) _creatorUI.command(this, "replace")
+    pin(screen as any)
+    if (this._h.id !== 0) tree().pagerReplace(this._h.id, (screen as any)._h.id, _transitionId(opts?.transition ?? "fade"), _transitionId(opts?.popTransition))
     this._emitChange()
     return this
   }
 
   // ── Children ARE the tabs ──────────────────────────────────────────────────────────────────
-  // Every inherited container mutation would send a generic setContent/insertNode/removeNode wire
-  // op, and a host must never run those on a pager: its children are page ROOTS the host owns
-  // (each laid out independently at the pager's box), not yoga children — the generic path frees
-  // the live pages and rebuilds them as ordinary children stacked on the first tab. So each one is
-  // overridden to mutate the element first (children, `_lens`, `_index`) and then notify over the
-  // same command channel every other pager op uses, where the host reconciles against the node.
-  //
-  // Content set this way is always one screen per tab: a per-tab STACK only ever grows through
-  // push/replace, so `_lens` resets to all-ones here.
+  // Every inherited container mutation is overridden to mutate the logical state first and then
+  // hand the runtime the whole picture (pagerSetContent), where it reconciles the pages. Content set
+  // this way is always one screen per tab: a per-tab STACK only ever grows through push/replace,
+  // so `_lens` resets to all-ones here.
   private _rebuild(children: any[]): this {
     const tabs = children.filter(Boolean)
     const prevIndex = this._index
-    this.children.length = 0
-    this.children.push(...tabs)
+    this._pages = tabs
     this._lens = tabs.map(() => 1)
     if (this._index >= tabs.length) this._index = Math.max(0, tabs.length - 1)
     for (const s of tabs) this._track(s)
-    if (this._id !== 0) _creatorUI.command(this, "content")
+    this._sync()
     if (this._index !== prevIndex) this._emitSelect()
     this._emitChange()
     return this
@@ -213,36 +239,36 @@ export class PagerElement extends ContainerElement<"pager"> {
     return this._rebuild(children as any[])
   }
   append(...nodes: UINodeChild[]): this {
-    return this._rebuild([...this.children, ...nodes])
+    return this._rebuild([...this._pages, ...nodes])
   }
   insert(index: number, ...nodes: UINodeChild[]): this {
-    const next = this.children.slice()
+    const next = this._pages.slice()
     next.splice(index, 0, ...(nodes as any[]))
     return this._rebuild(next)
   }
-  remove(...nodesToDelete: UIScreen[]): this {
+  remove(...nodesToDelete: UINodeChild[]): this {
     const drop = new Set<any>(nodesToDelete)
-    return this._rebuild(this.children.filter((c: any) => !drop.has(c)))
+    return this._rebuild(this._pages.filter((c: any) => !drop.has(c)))
   }
   _reconcile(next: UINodeChild[]): void {
     this._rebuild(next as any[])
   }
 
-  // Host-driven tab change (committed swipe): the native pager already moved — sync the logical
-  // index + fire onSelect. Named `_*` so chisel keeps it (hosts call it).
+  /** @internal Host-driven tab change (committed swipe): the native pager already moved — sync
+   *  the logical index + fire onSelect. */
   _hostDidSelect(index: number): void {
     if (index < 0 || index >= this._lens.length || index === this._index) return
     this._index = index
     this._emitSelect()
   }
 
-  // Host-driven pop on the current tab (interactive edge back-swipe): the native stack already
-  // popped — sync the logical stack + fire onChange. Idempotent, safe after every transition.
+  /** @internal Host-driven pop on the current tab (interactive edge back-swipe / back button): the
+   *  native stack already popped — sync the logical stack + fire onChange. Idempotent. */
   _hostDidPop(depth: number): void {
     if (depth < 1) depth = 1
     const len = this._lens[this._index] ?? 0
     if (depth >= len) return
-    this.children.splice(this._offset(this._index) + depth, len - depth)
+    this._pages.splice(this._offset(this._index) + depth, len - depth)
     this._lens[this._index] = depth
     this._emitChange()
   }
@@ -281,8 +307,6 @@ export class PagerElement extends ContainerElement<"pager"> {
   }
 }
 
-const isScreenArg = (v: any): boolean => v != null && typeof v === "object" && v.type === "screen"
-
 /** Callable factory + ambient statics. The name `UIPager` is a value (this factory) and a type
  *  (the instance interface above) — a standard value/type merge. */
 interface UIPagerConstructor {
@@ -291,32 +315,23 @@ interface UIPagerConstructor {
    *  swiping); several → swipeable sibling tabs, fixed at construction, each starting as its own
    *  one-screen stack. */
   (...tabs: (UIScreen | UIScreen[] | false | null | undefined)[]): UIPager
-  /** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-  (style: UIPagerStyle, content?: UIScreen | UIScreen[]): UIPager
   /** The pager that owns the currently visible screen, or `null` when the visible screen isn't
    *  hosted by one. With pagers nested inside pages, resolves to the **innermost** — so ambient
    *  calls act on the pager the user is actually looking at. */
   readonly current: UIPager | null
   /** `UIPager.current.push(screen)` — push onto the pager owning the visible screen, no
    *  reference threading. No-op with a console warning when there is no current pager. */
-  push(screen: UIScreen): void
+  push(screen: UIScreen, opts?: NavigateOptions): void
   /** `UIPager.current.pop()` — pop the visible pager's current tab (no-op at the tab root, or
    *  with a warning when there is no current pager). */
-  pop(): void
+  pop(opts?: PopOptions): void
   /** `UIPager.current.popToRoot()` — unwind the visible pager's current tab to its root. */
-  popToRoot(): void
+  popToRoot(opts?: PopOptions): void
 }
 
 function pagerFactory(...args: any[]): UIPager {
-  let style: any = null
-  let start = 0
-  const a0 = args.length > 0 ? args[0] : undefined
-  if (a0 != null && typeof a0 === "object" && !Array.isArray(a0) && !isScreenArg(a0)) {
-    style = a0
-    start = 1
-  }
   const tabs: any[] = []
-  for (let i = start; i < args.length; i++) {
+  for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (Array.isArray(a)) {
       for (let j = 0; j < a.length; j++) if (a[j]) tabs.push(a[j])
@@ -324,7 +339,7 @@ function pagerFactory(...args: any[]): UIPager {
       tabs.push(a)
     }
   }
-  return new PagerElement(style, tabs) as unknown as UIPager
+  return new PagerElement(null, tabs) as unknown as UIPager
 }
 
 /**
@@ -351,12 +366,12 @@ const _resolveCurrent = (): UIPager | null => {
 // as part of that binding's declaration (`ItemKind::AttachedTo`, chisel >= 0.4.2) — kept iff
 // `UIPager` is reached, shaken away with it otherwise. Under chisel <= 0.4.1 they were dropped
 // outright and `UIPager.push` arrived as `undefined` at runtime, in bundled builds only; don't lower
-// the pinned `@letary/chisel` back past 0.4.2. Covered by sdk/tests/compile.test.ts.
+// the pinned `@letary/chisel` back past 0.4.2. Covered by sdk/tests/compile/inject.test.ts.
 // `Object.defineProperty` for `current`, not `Object.assign({ get current() {} })` — Object.assign
 // *invokes* the getter and copies the resulting value, freezing it at null forever.
 Object.defineProperty(UIPager, "current", {
   get: () => (_activeStack[_activeStack.length - 1] ?? null) as unknown as UIPager | null,
 })
-;(UIPager as any).push = (screen: UIScreen) => { _resolveCurrent()?.push(screen) }
-;(UIPager as any).pop = () => { _resolveCurrent()?.pop() }
-;(UIPager as any).popToRoot = () => { _resolveCurrent()?.popToRoot() }
+;(UIPager as any).push = (screen: UIScreen, opts?: NavigateOptions) => { _resolveCurrent()?.push(screen, opts) }
+;(UIPager as any).pop = (opts?: PopOptions) => { _resolveCurrent()?.pop(opts) }
+;(UIPager as any).popToRoot = (opts?: PopOptions) => { _resolveCurrent()?.popToRoot(opts) }

package/src/ui/UIPopover.ts

@@ -93,8 +93,6 @@ const makePopover = (style: any, children: any) => new PopoverElement(style, chi
  *  `show(anchor)` next to an element or `{x, y}` point. Same argument forms as `UIColumn`. */
 export function UIPopover(...children: UIChildArg[]): UIPopover;
 export function UIPopover(children: UINodeChild[] | ChildrenFn): UIPopover;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIPopover(style: UIPopoverStyle, children?: UINodeChild[] | ChildrenFn): UIPopover;
 export function UIPopover(...args: any[]): UIPopover {
   return buildUI(args, null, makePopover)
 }

package/src/ui/UIScreen.ts

@@ -1,6 +1,8 @@
 import { TouchStartEvent } from "../runtime/touch"
-import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
+import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "./presentable"
+import { _transitionId, TRANSITION_NONE } from "./transitions"
 import { ContainerElement, buildUI, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { TREE_DEST_SCREEN, TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_KEEP_ALIVE, pin, tree } from "./tree"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
@@ -15,9 +17,12 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
    *  scene, a native view — suspending an active Router until `Router.restore()`). */
   open(options?: PresentOptions): void,
   /** Dismiss if this screen is the visible destination. */
-  close(): void
+  close(options?: DismissOptions): void
 
   /** Hardware/system back while this screen is current. */
+  onBack(callback: () => void): this
+  /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+   *  rename; removed with the release that recompiles them. */
   onBackPressed(callback: () => void): this
 
   /** The screen became the visible destination (first open, or revealed by a pop). */
@@ -26,38 +31,32 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
   onClose(callback: () => void): this
 
   /**
-   * Keep this screen's built native tree alive when a host detaches it: instead of being destroyed,
-   * its views + layout + live state (scroll position, input text) are retained, so re-hosting the
-   * SAME screen object restores it in place rather than rebuilding. `onClose`/`onOpen` still fire on
-   * detach/re-attach. You own the lifetime — a kept tree is freed only by `dispose()` or when the
-   * project unloads. (Native-only today; web rebuilds.)
+   * Keep this screen's native state when a pager releases it: instead of dropping its view, the
+   * host keeps it (scroll position, input text), so re-pushing the SAME screen object restores it
+   * in place. `onClose`/`onOpen` still fire on detach/re-attach. Free it with `destroy()`.
    */
   keepAlive(enabled?: boolean): this
-  /** Free a `keepAlive()` screen's retained tree now. No-op unless it's currently detached-and-kept. */
-  dispose(): this
 
   /** Touch began on the screen; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
+  /** @internal The destination tuple (Presentable). */
+  _dest(): DestTuple
 }
 
 export class ScreenElement extends ContainerElement<"screen"> {
+  /** @internal */
+  _dest(): DestTuple { return [TREE_DEST_SCREEN, this._h.id, "", ""] }
+
   open(options?: PresentOptions): void {
+    if (this._h.id === 0) return
     _bumpNavEpoch()
-    if (_navSupported()) {
-      _creatorUI.openView!(this, options?.transition ?? "none")
-    } else {
-      // Legacy host: no destination navigation — transition is dropped.
-      _creatorUI.openScreen(this)
-    }
+    pin(this)   // presented: the runtime holds it until it retires it (TREE_EVENT_DETACHED)
+    tree().open(TREE_DEST_SCREEN, this._h.id, "", "", _transitionId(options?.transition, TRANSITION_NONE))
     _setCurrent(this as any)
   }
-  close(): void {
+  close(options?: DismissOptions): void {
     _bumpNavEpoch()
-    if (_navSupported()) {
-      _creatorUI.closeView!()
-    } else {
-      _creatorUI.closeScreen()
-    }
+    tree().close(TREE_DEST_SCREEN, this._h.id, _transitionId(options?.transition, TRANSITION_NONE))
     if (Presentable.current === (this as any)) _setCurrent(null)
   }
   protected ol: (() => void)[] = []
@@ -70,25 +69,24 @@ export class ScreenElement extends ContainerElement<"screen"> {
     this.cl.push(callback)
     return this
   }
-  // Read by the host at detach time (a plain flag on the node, like _interactive).
-  _keepAlive = false
+  /** @internal presentation lifecycle from the runtime (also a pager's page open / close). */
+  _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
+  /** @internal */
+  _emitClose(): void { for (const cb of this.cl.slice()) cb() }
+
   keepAlive(enabled = true): this {
-    this._keepAlive = enabled
-    return this
-  }
-  dispose(): this {
-    // Rides the generic command channel (no dedicated bridge). No-op while _id is 0 (never mounted)
-    // or when the tree isn't currently detached-and-kept — the host ignores it then.
-    if (this._id !== 0) _creatorUI.command(this, "disposeKeepAlive")
+    if (enabled) this._addFlags(TREE_FLAG_KEEP_ALIVE)
+    else this._removeFlags(TREE_FLAG_KEEP_ALIVE)
     return this
   }
+
   readonly touchStartListeners: any[] = []
-  _interactive = false
   onTouchStart (callback: any): this {
-    this._interactive = true
     this.touchStartListeners.push(callback)
+    this._addFlags(TREE_FLAG_INTERACTIVE)
     return this
   }
+  /** @internal */
   _emitTouchStart(pointerId: number, clientX: number, clientY: number): any {
     const touchEvent = new TouchStartEvent(clientX, clientY, pointerId)
     touchEvent.target = this
@@ -100,11 +98,20 @@ export class ScreenElement extends ContainerElement<"screen"> {
     }
     return null
   }
-  _backButtonCallback?: () => void
-  onBackPressed(callback: any): this {
+  private _backButtonCallback?: () => void
+  onBack(callback: any): this {
     this._backButtonCallback = callback
+    this._addFlags(TREE_FLAG_BACK)
     return this
   }
+  /** @deprecated see the interface */
+  onBackPressed(callback: any): this { return this.onBack(callback) }
+  /** @internal the runtime's back chain: true = handled. */
+  _emitBack(): boolean {
+    if (!this._backButtonCallback) return false
+    this._backButtonCallback()
+    return true
+  }
 }
 
 const makeScreen = (style: any, children: any) => new ScreenElement("screen", style, children)
@@ -116,8 +123,6 @@ export const __UIScreen = (children: UINodeChild[] | ChildrenFn): UIScreen => ma
  *  as `UIColumn`. */
 export function UIScreen(...children: UIChildArg[]): UIScreen;
 export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIScreen(style: UIScreenStyle, children?: UINodeChild[] | ChildrenFn): UIScreen;
 export function UIScreen(...args: any[]): UIScreen {
   return buildUI(args, null, makeScreen)
 }

package/src/ui/UIScrollable.ts

@@ -1,5 +1,6 @@
 import type { UIContainerStyle } from "./UIContainer"
 import { type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type Color, ContainerElement, buildUI } from "./UINode"
+import { TREE_FLAG_OVERSCROLL, TREE_FLAG_REFRESH, TREE_FLAG_SCROLL, TREE_FLAG_SCROLL_RELEASE } from "./tree"
 
 export type ScrollStyle = {
   showScrollbar?: boolean,
@@ -30,42 +31,49 @@ export interface UIScrollable extends UIContainerBase<UIScrollableStyle> {
   onScrollRelease(callback: () => void): UIScrollable,
   /** Pulled past the content edge by `delta` px. */
   onOverscroll(callback: (delta: number) => void): UIScrollable
-  /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
-   *  node mounts (hosts read it at creation). Vertical only; native hosts — no-op on web. */
+  /** Pull-to-refresh: the spinner stays until the returned promise settles. Vertical only. */
   onRefresh(callback: () => void | Promise<void>): UIScrollable
 }
 
 class ScrollableElement extends ContainerElement<"scrollable"> {
 
-  readonly osl: any[] = []
-  readonly sl: any[] = []
-  readonly srl: any[] = []
-
-  get scrollListeners() {
-    return this.sl
-  }
+  private readonly osl: any[] = []
+  private readonly sl: any[] = []
+  private readonly srl: any[] = []
+  private _refreshCallback?: () => void | Promise<void>
 
   onScroll (callback: any): this {
     this.sl.push(callback)
+    this._addFlags(TREE_FLAG_SCROLL)
     return this
   }
 
   onScrollRelease (callback: any): this {
     this.srl.push(callback)
+    this._addFlags(TREE_FLAG_SCROLL_RELEASE)
     return this
   }
 
   onOverscroll (callback: any): this {
     this.osl.push(callback)
+    this._addFlags(TREE_FLAG_OVERSCROLL)
     return this
   }
 
-  // Read by the host at mount (same contract the scrollable screen had before 2026-07-22).
-  declare _refreshCallback: any
   onRefresh (callback: any): this {
     this._refreshCallback = callback
+    this._addFlags(TREE_FLAG_REFRESH)
     return this
   }
+
+  /** @internal */
+  _emitScroll(position: number): void { for (const cb of this.sl.slice()) cb(position) }
+  /** @internal */
+  _emitScrollRelease(): void { for (const cb of this.srl.slice()) cb() }
+  /** @internal */
+  _emitOverscroll(delta: number): void { for (const cb of this.osl.slice()) cb(delta) }
+  /** @internal the host awaits the returned promise (its spinner) */
+  _emitRefresh(): unknown { return this._refreshCallback?.() }
 }
 
 // flexShrink: 1 default (SDK-owned, like UIRow's flexDirection): without it a scrollable in a
@@ -80,8 +88,6 @@ export const __UIScrollable = (children: UINodeChild[] | ChildrenFn): UIScrollab
  *  `flexGrow: 1`. */
 export function UIScrollable(...children: UIChildArg[]): UIScrollable
 export function UIScrollable(children: UINodeChild[] | ChildrenFn): UIScrollable
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export function UIScrollable(style: UIScrollableStyle, children?: UINodeChild[] | ChildrenFn): UIScrollable
 export function UIScrollable(...args: any[]): UIScrollable {
   return buildUI(args, SCROLLABLE_DEFAULTS, makeScrollable)
 }

package/src/ui/UISpacer.ts

@@ -11,4 +11,4 @@ export function UISpacer(): UISpacer
 export function UISpacer(style: UISpacerStyle): UISpacer
 export function UISpacer(style?: UISpacerStyle): UISpacer {
   return new Element("spacer", { flexGrow: 1, ...style })
-}
+}

package/src/ui/UITabs.ts

@@ -73,6 +73,7 @@ export class TabsElement extends ScreenElement {
 
   constructor(defs: Record<string, UITabDef>) {
     super("screen", { bgColor: SCREEN_BG }, [])
+    this.style({ bgColor: SCREEN_BG })
     this.ids = Object.keys(defs)
     if (this.ids.length === 0) console.warn("UITabs: no tabs declared")
 
@@ -94,16 +95,17 @@ export class TabsElement extends ScreenElement {
       this._badges.push(badge)
       this._badgeTexts.push(badgeText)
       const button = UIButton(anchor, icon ? label : null)
-        .style({ name: `tab-${id}`, flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 })
+        .style({ flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 })
+        .named(`tab-${id}`)
         .onClick(() => this.select(id))
       this._buttons.push(button)
       return button
     })
 
     this._bar = UIRow(buttons).style({
-      name: "tabbar", bgColor: BAR_BG, pb: "comfort-bottom",
+      bgColor: BAR_BG, pb: "comfort-bottom",
       borderTopWidth: 1, borderTopColor: BAR_BORDER,
-    })
+    }).named("tabbar")
 
     this._pagerEl.onSelect((i) => {
       this._applyActive(i)
@@ -220,11 +222,11 @@ export function defineTabs<T extends Record<string, TabDef>>(tabs: T): TabsHandl
       return UIButton(
         def.icon ? UIImage(def.icon).style({ width: 22, height: 22, tintColor: color }) : null,
         UIText(def.label).style({ fontSize: 10, color }),
-      ).style({ name: `tab-${id}`, flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 })
+      ).style({ flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 }).named(`tab-${id}`)
     })).style({
-      name: "tabbar", bgColor: BAR_BG, pb: "comfort-bottom",
+      bgColor: BAR_BG, pb: "comfort-bottom",
       borderTopWidth: 1, borderTopColor: BAR_BORDER,
-    })
+    }).named("tabbar")
 
   const screen = (active: keyof T & string, ...children: UIChildArg[]) =>
     UIScreen(