lecodes-sdk 1.2.0 → 2.0.1

package/src/ui/UINode.ts

@@ -1,13 +1,22 @@
 import type { FetchResponse } from "../runtime/fetch"
+import type { ColorInput } from "../core/color"
 import { createBinding, disposeBinding } from "../core/signals"
 import type { Animation } from "../animate/tween/Animation"
 import { CLOCK_UI, DOM_UI, KIND_DISCRETE, KIND_TRANSFORM, KIND_TRANSFORM_MATRIX, parseTransformList, uiValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
 import { tweenBag } from "../animate/tween/Timeline"
+import { wireStyle, wireValue } from "./styleColor"
+import { DEAD_HANDLE, TREE_FLAG_LAYOUT, elementsOf, ensureEmitter, pin, tree, unpin, type TreeElement } from "./tree"
+
+// The UI element model since phase 9 (docs/plans/hosts-unification-plan.md): the runtime OWNS the tree —
+// every element is a HANDLE over a runtime node that exists from the constructor on (`_h`: the
+// owned handle, `_h.id` the node id, its collection frees a detached node). Structure, styles and content live in the
+// runtime; the element keeps only what the app set (`_style`, `_text`, …) for reads, its listeners,
+// and its flags. `children` is a snapshot read from the runtime, `parent` is available.
 
 export interface UINode {
   readonly type: string
   /** Author-given semantic name (a stable selector for tests + AI review feedback). */
-  readonly name?: string
+  name?: string
   style: Style<this, any>
   /** Style-class proxy — read/set/toggle/bind the `$`-classes declared in `.style()`. See {@link Classes}. */
   readonly class: Classes<this>
@@ -21,9 +30,11 @@ export type UINodeChild = UINode | null | undefined | false
  *  needs no spread. */
 export type UIChildArg = UINodeChild | UINodeChild[]
 
-/** A color: CSS-style string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"var(--primaryColor)"`) or
- *  packed number; `null` clears. */
-export type Color = number | string | null
+/** A color: any CSS color string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"green"`, `"hsl(210 50% 40%)"`),
+ *  a theme reference (`"var(--primaryColor)"`), an opaque `0xRRGGBB` number or `[r, g, b(, a)]` in
+ *  0..1; `null` clears. A string is the core's to parse (an unknown one is transparent, as in
+ *  CSS); a number or an array that is not a color throws at the write. */
+export type Color = ColorInput | null
 
 /** Style props every element accepts. */
 export type BaseStyle = {
@@ -37,12 +48,6 @@ export type BaseStyle = {
   bgColor?: Color | null,
   overflow?: "visible" | "hidden",
   boxSizing?: "border-box" | "content-box",
-  /**
-   * Author-given semantic name — a stable selector for tests and for marking elements in the AI
-   * code-review feedback loop. NOT a style: it's extracted at construction (never sent to the layout
-   * engine) and surfaced on the node + in the renderer's serialized output. Available on every element.
-   */
-  name?: string,
 }
 
 /** Painted-box props: background, gradient, border, radius. */
@@ -187,7 +192,141 @@ export type TextStyle =  {
   textOverflow?: "ellipsis" | "clip"
 }
 
-// Pulls function-valued props out of `style` (mutating it — they must never reach the host bridge)
+/** Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
+ *  re-applies when a signal it read changes. Nested `$class` blocks stay static — bindings are
+ *  extracted at the top level only. */
+export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]) }
+
+/** The curve of a `$class` block's swap (with a `duration`): a curve name (`outCubic`,
+ *  `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)` or `steps(n)`. A
+ *  function cannot ride a style block; use `animateTo` for those. */
+export type LayerEasing = string
+
+/** Style states: any `$`-prefixed key in `.style()` declares a state block; `duration`/`delay`/
+ *  `easing` animate its swap. User classes (`$checked`, `$selected`, …) are toggled from code via the
+ *  `el.class` proxy and INHERIT down the tree (CSS-`.dark`-on-body style): a class set on a node also
+ *  activates same-name `$` blocks on all descendants within the same root (sdk/docs/ui/classes.md).
+ *
+ *  Five classes are reserved — the system toggles them, `el.class` cannot:
+ *  - `$hovered` / `$pressed` / `$focused` — the host's hover (mouse only) / press / focus. They
+ *    cascade from the node the host toggled and STOP at the nearest interactive descendant (a
+ *    button inside a pressed card is not pressed; it has its own scope).
+ *  - `$landscape` / `$portrait` — the display orientation, GLOBAL: active on every node at once.
+ *
+ *  Precedence on the same prop: base < `$landscape`/`$portrait` < user `$classes` (later-declared
+ *  beats earlier) < `$hovered` < `$pressed` < `$focused`.
+ *
+ *  Instantiated with the node's FULL style `T` — a class block accepts everything the node's
+ *  `.style()` does. Narrowing it wrongly rejects valid props such as `$active: { color }`; guarded
+ *  by tests/ui/types.test.ts. */
+export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number, easing?: LayerEasing } }
+
+/** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
+ *  the class then tracks the signals the function reads (re-evaluated on change). Reads through
+ *  the proxy always return a plain boolean, never the bound function. */
+export type ClassValue = boolean | (() => boolean)
+
+/** The `el.class` proxy — the runtime switch for `$`-class blocks declared in `.style()`
+ *  (see {@link ClassStyles}). One surface, mirroring `el.style`:
+ *
+ *  ```ts
+ *  el.class.checked                    // read: is it active on THIS element? → boolean
+ *  el.class.checked = true             // activate (false deactivates)
+ *  el.class.open = !el.class.open      // toggle
+ *  el.class.done = () => todo.done.value          // reactive binding (signals)
+ *  el.class({ checked: true, done: () => … })     // batch form — returns the element, chainable
+ *  ```
+ *
+ *  Class names are accepted with or without the declaration-site `$` prefix. A write of a reserved
+ *  class (`hovered` `pressed` `focused` `landscape` `portrait`) throws — the system toggles those.
+ *  `R` is the concrete node type, so the batch form chains like `.style()`.
+ *
+ *  Typing note: property access is `any` because an index signature can't give reads (`boolean`)
+ *  and writes ({@link ClassValue}) different types — the batch form is the fully typed path;
+ *  single-key writes are runtime-coerced with `!!`. */
+export type Classes<R> = ((classes: Record<string, ClassValue>) => R) & { [key: string]: any }
+
+/** Members every UI element shares — element interfaces extend this so docs and types live in one
+ *  place. `S` is the element's style object; `A` is the subset `animateTo` accepts (defaults to `S`). */
+export interface UIElementBase<S extends object, A extends object = S> {
+  /** Style: `.style({...})` merges (chainable); `el.style.key = v` writes one prop, a `() => v`
+   *  value binds it to signals — see {@link Style}. */
+  style: Style<this, S>
+  /** Author-given semantic name — a stable selector for tests and for marking elements in the AI
+   *  code-review feedback loop; surfaced in the renderer's serialized output. Set it with `.named()`
+   *  (chainable) or assign it. */
+  name?: string
+  /** Set the semantic name (chainable). */
+  named(name: string): this
+  /** Tween to the target style — meta keys `duration`/`delay`/`loop`/…, see {@link AnimateStyle}. */
+  animateTo: AnimateStyle<this, A>
+  /** Tween from the given style to the current one (entrance animations). */
+  animateFrom: AnimateStyle<this, A>
+  /** Fires after every layout pass with the parent-relative box. */
+  onLayout(onLayout: OnLayoutCallback): this
+  /** Absolute rect in device space, read live (includes scroll); `null` before layout. */
+  getBoundingClientRect(): BoundingClientRect | null
+  /** The parent element, or `null` for a root (a screen, a widget, an unmounted subtree's top). */
+  readonly parent: UINode | null
+  /** Free this element's subtree now (views, layout, native state). Only for a DETACHED subtree —
+   *  remove / hide / close it first; an attached one is left alone. After it the element is dead. */
+  destroy(): void
+  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
+   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
+   *  Classes cascade to descendants. See {@link Classes}. */
+  readonly class: Classes<this>
+}
+
+/** {@link UIElementBase} plus the child-management surface every container shares. */
+export interface UIContainerBase<S extends object, A extends object = S> extends UIElementBase<S, A> {
+  /** Append children. */
+  append(...nodes: UINodeChild[]): this
+  /** Insert children at `index`. */
+  insert(index: number, ...nodes: UINodeChild[]): this
+  /** Remove (unmount) the given children. */
+  remove(...nodes: UINodeChild[]): this
+  /** Replace all children — an array, or a function for reactive children. */
+  setContent(nodes: UINodeChild[] | ChildrenFn): this
+  /** The children — a SNAPSHOT read from the runtime; mutate via `append`/`insert`/`remove`/`setContent`. */
+  readonly children: UINode[]
+}
+
+// NB: do NOT annotate `this: R` on StyleFn. As a parameter it makes R contravariant, turning every
+// node type INVARIANT (UIScreen<false> stopped being assignable to UIScreen<boolean>). Runtime
+// `this` is already fixed by `styleFunction.bind(this)`; R stays covariant in the return, so
+// `.style()` still chains. Guarded by tests/ui/types.test.ts.
+export type StyleFn <R, T extends object> = ((style: Reactive<T> & ClassStyles<T>) => R)
+
+/** The `el.style` surface: callable — `.style({...})` merges and returns the element for
+ *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
+ *  installs a reactive binding). Reads answer what the app set. */
+export type Style <R, T extends object> = StyleFn<R,T> & T & ClassStyles<T>
+
+/** Style props of an animate bag: a single value (tween from the current value) or an array of
+ *  KEYFRAMES (`opacity: [1, 0.3, 1]`, offsets via `times`). */
+export type AnimateProps<T extends object> = { [K in keyof T]?: T[K] | T[K][] }
+
+/** The `animateTo`/`animateFrom` surface: target style props (single values or keyframe arrays) plus
+ *  the flat meta keys — `duration` / `delay` / `easing` / `times` / `loop` / `loopMode` / `commit` /
+ *  `clock`, see {@link TweenMeta}. Returns the {@link Animation} handle (seek, rate, `finished`). */
+export type AnimateStyle<R, T extends object> = ((style: AnimateProps<T> & TweenMeta) => Animation)
+
+
+export type AppearStyle <R, T> = (arg: { from: T, duration?: number, delay?: number }) => R
+export type DisappearStyle <R, T> = (arg: { to: T, duration?: number, delay?: number }) => R
+
+/** `onLayout` payload — the node's box in PARENT-relative coordinates. */
+export type OnLayoutCallback = (layout: { left: number, top: number, width: number, height: number }) => void
+
+/** Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
+ *  right/bottom/x/y derived SDK-side — hosts only report [left, top, width, height]. */
+export type BoundingClientRect = {
+  x: number, y: number,
+  left: number, top: number, right: number, bottom: number,
+  width: number, height: number,
+}
+
+// Pulls function-valued props out of `style` (mutating it — they must never reach the bridge)
 // and returns them. A static value under the same key overrides (disposes) an existing binding.
 function extractBindings(el: any, style: any): [string, () => any][] | null {
   let fns: [string, () => any][] | null = null
@@ -204,8 +343,7 @@ function extractBindings(el: any, style: any): [string, () => any][] | null {
 }
 
 // One reactive binding per style key: re-runs when a signal the function read changes, writing
-// through the style proxy (so a mounted node hits _creatorUI.updateStyle, an unmounted one just
-// keeps _style current for the next mount).
+// through the style proxy.
 function applyBindings(el: any, fns: [string, () => any][]) {
   for (const [ key, fn ] of fns) {
     createBinding(el, key, () => { el.style[key] = fn() })
@@ -214,20 +352,12 @@ function applyBindings(el: any, fns: [string, () => any][]) {
 
 // NB: returns `this` — `.style()` must chain. Don't rewrite.
 function styleFunction(this: any, newStyle: any) {
-  // `name` is a JS-node selector (read by hosts off el.name), not a layout property — extract it
-  // exactly like the constructor so `.style({ name })` is equivalent to the first-arg style. Left
-  // in the style it would never become el.name (breaking name-based lookups) and would leak into
-  // the layout engine.
-  if (newStyle && typeof newStyle.name === "string" && newStyle.name.length > 0) {
-    this.name = newStyle.name
-    delete newStyle.name
-  }
-  if (newStyle) this._mapStyle?.(newStyle)
+  if (!newStyle) return this
+  this._mapStyle?.(newStyle)
   const fns = extractBindings(this, newStyle)
+  const wire = wireStyle(newStyle)   // before the store: a bad color throws with `_style` untouched
   Object.assign(this._style, newStyle)
-  if (this._id !== 0) {
-    _creatorUI.mergeStyle(this._id, newStyle)
-  }
+  if (this._h.id !== 0) tree().mergeStyle(this._h.id, wire)
   if (fns) applyBindings(this, fns)
   return this
 }
@@ -254,9 +384,8 @@ const handler: ProxyHandler<any> = {
       el._mapStyle(mapped)
       value = mapped[key]
     }
-    if (el._id !== 0) {
-      _creatorUI.updateStyle(el._id, key, value)
-    }
+    const wire = wireValue(key, value)
+    if (el._h.id !== 0) tree().setStyle(el._h.id, key, wire as any)
     el._style[key] = value
     return true
   },
@@ -273,6 +402,20 @@ const handler: ProxyHandler<any> = {
 // `$checked` and `checked` name the same class — `$` is only the declaration-site prefix in .style().
 const classKey = (name: string) => name[0] === "$" ? name.slice(1) : name
 
+// The classes the system toggles (ClassStyles): the host's hover / press / focus, the engine's
+// orientation. `el.class` reads them like any class but never writes them.
+const RESERVED_CLASSES = new Set(["hovered", "pressed", "focused", "landscape", "portrait"])
+
+// The class a write names, without the `$`; a reserved one throws before anything is written.
+function writableClass(name: string): string {
+  const key = classKey(name)
+  if (RESERVED_CLASSES.has(key)) {
+    const query = key === "pressed" ? "; read `button.isPressed`" : key === "hovered" ? "; read `button.isHovered`" : ""
+    throw new Error(`el.class: \`$${key}\` is a reserved class the system toggles, not a class to set${query}`)
+  }
+  return key
+}
+
 // Single-class state write, shared by the set trap, the batch form and binding re-runs. No-op when
 // the state already matches, so an unchanged binding re-run doesn't resend over the bridge.
 function writeClass(el: any, name: string, enabled: boolean) {
@@ -282,16 +425,14 @@ function writeClass(el: any, name: string, enabled: boolean) {
   } else {
     el._classes.delete(name)
   }
-  if (el._id !== 0) {
-    _creatorUI.setClass(el._id, name, enabled)
-  }
+  if (el._h.id !== 0) tree().setClass(el._h.id, name, enabled)
 }
 
 // One class write: a function value installs/replaces a reactive binding, a plain value replaces
 // the binding (last write wins — unlike the style proxy's hot-path caveat, a stale class binding
 // silently reverting a later plain write would be a footgun, and class flips are never per-frame).
 function writeClassValue(el: any, name: string, value: ClassValue) {
-  name = classKey(name)
+  name = writableClass(name)
   if (typeof value === "function") {
     createBinding(el, "#class:" + name, () => { writeClass(el, name, !!value()) })
   } else {
@@ -302,7 +443,9 @@ function writeClassValue(el: any, name: string, value: ClassValue) {
 
 // The callable target of the el.class proxy (batch form), bound to the element like styleFunction.
 function classFunction(this: any, classes: Record<string, ClassValue>) {
-  for (const key of Object.keys(classes)) {
+  const keys = Object.keys(classes)
+  for (const key of keys) writableClass(key)   // a reserved name rejects the whole batch
+  for (const key of keys) {
     writeClassValue(this, key, classes[key])
   }
   return this
@@ -328,179 +471,67 @@ const classHandler: ProxyHandler<any> = {
   }
 }
 
-/** Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
- *  re-applies when a signal it read changes. Nested state blocks (onPressed, onLandscape, …) stay
- *  static — bindings are extracted at the top level only. */
-export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]) }
-
-/** The curve of a state block's swap (`$class` / `onPressed` / `onFocused` with a `duration`): a
- *  curve name (`outCubic`, `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)`
- *  or `steps(n)`. A function cannot ride a style block; use `animateTo` for those. */
-export type LayerEasing = string
-
-/** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
- *  from code via the `el.class` proxy; `duration`/`delay`/`easing` animate the swap. Class state INHERITS
- *  down the tree (CSS-`.dark`-on-body style): a class set on a node also activates same-name `$`
- *  blocks on all descendants within the same root (docs/style-class-cascade-plan.md).
- *  `$pressed`/`$focused` are reserved — hosts toggle them on press/focus (they beat other
- *  classes, lose to onPressed/onFocused), so children can react to an ancestor's press.
- *
- *  Instantiated with the node's FULL style `T` — a class block accepts everything the node's
- *  `.style()` does, like `onLandscape`. Narrowing it wrongly rejects valid props such as
- *  `$active: { color }`; guarded by tests/ui-types.test.ts. */
-export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number, easing?: LayerEasing } }
-
-/** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
- *  the class then tracks the signals the function reads (re-evaluated on change). Reads through
- *  the proxy always return a plain boolean, never the bound function. */
-export type ClassValue = boolean | (() => boolean)
-
-/** The `el.class` proxy — the runtime switch for `$`-class blocks declared in `.style()`
- *  (see {@link ClassStyles}). One surface, mirroring `el.style`:
- *
- *  ```ts
- *  el.class.checked                    // read: is it active on THIS element? → boolean
- *  el.class.checked = true             // activate (false deactivates)
- *  el.class.open = !el.class.open      // toggle
- *  el.class.done = () => todo.done.value          // reactive binding (signals)
- *  el.class({ checked: true, done: () => … })     // batch form — returns the element, chainable
- *  ```
- *
- *  Class names are accepted with or without the declaration-site `$` prefix. `R` is the concrete
- *  node type, so the batch form chains like `.style()`.
- *
- *  Typing note: property access is `any` because an index signature can't give reads (`boolean`)
- *  and writes ({@link ClassValue}) different types — the batch form is the fully typed path;
- *  single-key writes are runtime-coerced with `!!`. */
-export type Classes<R> = ((classes: Record<string, ClassValue>) => R) & { [key: string]: any }
-
-/** Members every UI element shares — element interfaces extend this so docs and types live in one
- *  place. `S` is the element's style object; `A` is the subset `animateTo` accepts (defaults to `S`). */
-export interface UIElementBase<S extends object, A extends object = S> {
-  // NB: no `name` member here. Declaring it would give every element a property in common with
-  // the style types (BaseStyle.name), letting TS's weak-type check match a NODE against a legacy
-  // style-first overload — `UIPager(UIText("x"))` must stay a type error (tests/ui-types.test.ts).
-  /** Style: `.style({...})` merges (chainable); `el.style.key = v` writes one prop, a `() => v`
-   *  value binds it to signals — see {@link Style}. */
-  style: Style<this, S>
-  /** Tween to the target style — meta keys `duration`/`delay`/`loop`/…, see {@link AnimateStyle}. */
-  animateTo: AnimateStyle<this, A>
-  /** Tween from the given style to the current one (entrance animations). */
-  animateFrom: AnimateStyle<this, A>
-  /** Fires after every layout pass with the parent-relative box. */
-  onLayout(onLayout: OnLayoutCallback): this
-  /** Absolute rect in device space, read live (includes scroll); `null` before mount. */
-  getBoundingClientRect(): BoundingClientRect | null
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
-}
-
-/** {@link UIElementBase} plus the child-management surface every container shares. */
-export interface UIContainerBase<S extends object, A extends object = S> extends UIElementBase<S, A> {
-  /** Append children. */
-  append(...nodes: UINodeChild[]): this
-  /** Insert children at `index`. */
-  insert(index: number, ...nodes: UINodeChild[]): this
-  /** Remove (unmount) the given children. */
-  remove(...nodes: UINodeChild[]): this
-  /** Replace all children — an array, or a function for reactive children. */
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-  /** The children array — mutate via `append`/`insert`/`remove`/`setContent`. */
-  readonly children: UINodeChild[]
-}
-
-/** Orientation state blocks — override props applied only in landscape / portrait (like a
- *  `$`-class, keyed by device orientation instead of `el.class`). Same full-`T` rule as class
- *  blocks. */
-export type OrientationStyles<T> = {
-  onLandscape?: T,
-  onPortrait?: T,
-  /** @deprecated Misspelling of `onPortrait` (no second "r"). Kept so existing projects and published
-   *  bundles keep working — hosts still honour it — but new code should use `onPortrait`. */
-  onPortait?: T,
-}
-
-// NB: do NOT annotate `this: R` on StyleFn. As a parameter it makes R contravariant, turning every
-// node type INVARIANT (UIScreen<false> stopped being assignable to UIScreen<boolean>). Runtime
-// `this` is already fixed by `styleFunction.bind(this)`; R stays covariant in the return, so
-// `.style()` still chains. Guarded by tests/ui-types.test-d.ts.
-export type StyleFn <R, T extends object> = ((style: Reactive<T> & OrientationStyles<T> & ClassStyles<T>) => R)
-
-/** The `el.style` surface: callable — `.style({...})` merges and returns the element for
- *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
- *  installs a reactive binding). */
-export type Style <R, T extends object> = StyleFn<R,T> & T & OrientationStyles<T> & ClassStyles<T>
-
-/** Style props of an animate bag: a single value (tween from the current value) or an array of
- *  KEYFRAMES (`opacity: [1, 0.3, 1]`, offsets via `times`). */
-export type AnimateProps<T extends object> = { [K in keyof T]?: T[K] | T[K][] }
-
-/** The `animateTo`/`animateFrom` surface: target style props (single values or keyframe arrays) plus
- *  the flat meta keys — `duration` / `delay` / `easing` / `times` / `loop` / `loopMode` / `commit` /
- *  `clock`, see {@link TweenMeta}. Returns the {@link Animation} handle (seek, rate, `finished`). */
-export type AnimateStyle<R, T extends object> = ((style: AnimateProps<T> & TweenMeta) => Animation)
-
-
-export type AppearStyle <R, T> = (arg: { from: T, duration?: number, delay?: number }) => R
-export type DisappearStyle <R, T> = (arg: { to: T, duration?: number, delay?: number }) => R
-
-/** `onLayout` payload — the node's box in PARENT-relative coordinates. */
-export type OnLayoutCallback = (layout: { left: number, top: number, width: number, height: number }) => void
-
-/** Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
- *  right/bottom/x/y derived SDK-side — hosts only report [left, top, width, height]. */
-export type BoundingClientRect = {
-  x: number, y: number,
-  left: number, top: number, right: number, bottom: number,
-  width: number, height: number,
-}
+// ---- the element -----------------------------------------------------------------------------------
 
-export class Element<T extends string> {
+export class Element<T extends string> implements TreeElement {
   readonly type: T
-  /** Author-given semantic name (LeCodes `name`) — see BaseStyle.name. Extracted from the options
-   *  object so it never reaches the layout engine; the renderer reads it off the node. */
-  readonly name?: string
+  /** @internal The owned handle: `_h.id` is the node id (the element's identity everywhere; 0 once
+   *  the node is gone — DEAD_HANDLE), its collection frees a detached subtree. */
+  _h: Handle
+  /** @internal What the app set — reads answer this; the runtime holds the truth. */
   protected _style: any
-
-  protected _id: number = 0
+  /** @internal TREE_FLAG_* the runtime and the host know about this element. */
+  _flags = 0
+  private _name?: string
 
   protected _styleProxy: any
-  protected _appear: any
-  protected _disappear: any
   /** @internal Reactive bindings owned by this element (style key / "#text" → effect). The element
    *  is the effect's only strong owner, so discarding a subtree lets its bindings collect with it. */
   _fx?: Map<string, any>
 
   /** @internal Per-subclass style normalization (SDK-name → wire-name, e.g. UIInput's
    *  `type: "phone"` → `"tel"`), mutating the style in place before it is stored or sent. Runs on
-   *  every entry point: the first-arg style, `.style()`, and single-key `el.style.k =` writes. */
+   *  every entry point: the constructor's style, `.style()`, and single-key `el.style.k =` writes. */
   _mapStyle?(style: any): void
 
   // Per-type default styles are inlined at each component's construction site (spread UNDER the
   // user's style — e.g. UIRow's `flexDirection: "row"`), so every node reaches the host with
   // explicit values and hosts keep no per-type style opinions of their own.
   constructor(type: T, style: any) {
+    ensureEmitter()
     this.type = type
-    if (style && typeof style.name === "string" && style.name.length > 0) {
-      this.name = style.name
-      delete style.name
+    this._h = tree().create(type)
+    // Creation-site capture for an element inspector: the host sets the flag before running the
+    // bundle, and the stack (mapped through the bundle's source map) points at the user code that
+    // created this element. A host of the tree of truth sees nodes and no element: it sets a
+    // FUNCTION, called here — straight after the create, which told the host of the node, so the
+    // node the host heard of last is this element's. It is handed the element too: what the app
+    // SET (`_style`) is the element's to tell, the runtime keeps what it resolved. Off everywhere
+    // else — zero cost when unset.
+    const capture = (globalThis as any).__lecodesCaptureSites
+    if (capture) {
+      const site = (this as any)._site = new Error("lecodes-site")
+      if (typeof capture === "function") capture(this._h.id, site, this)
     }
-    if (style) this._mapStyle?.(style)
-    this._style = style
+    this._style = style ?? {}
     if (style) {
+      this._mapStyle?.(style)
       const fns = extractBindings(this, style)
-      if (fns) applyBindings(this, fns)   // sync first run — _style holds concrete values pre-mount
-    }
-    // Creation-site capture for the editor preview's element inspector: the host sets the flag
-    // before running the bundle, and the stack (mapped through the bundle's source map) points at
-    // the user code that created this element. Off everywhere else — zero cost when unset.
-    if ((globalThis as any).__lecodesCaptureSites) {
-      (this as any)._site = new Error("lecodes-site")
+      if (Object.keys(style).length > 0) tree().mergeStyle(this._h.id, wireStyle(style))
+      if (fns) applyBindings(this, fns)
     }
   }
 
+  get name(): string | undefined { return this._name }
+  set name(value: string | undefined) {
+    this._name = value
+    if (this._h.id !== 0) tree().setString(this._h.id, "name", value ?? null)
+  }
+  named(name: string): this {
+    this.name = name
+    return this
+  }
+
   get style(): any {
     if (this._styleProxy) return this._styleProxy
     const obj = styleFunction.bind(this)
@@ -535,7 +566,7 @@ export class Element<T extends string> {
     if (prop === "text") {
       if (!("text" in this)) return null
       return {
-        domain: DOM_UI, id: () => this._id,
+        domain: DOM_UI, id: () => this._h.id,
         value: (v) => (typeof v === "string" || typeof v === "number" ? { kind: KIND_DISCRETE, str: String(v) } : null),
         commit: (v) => { (this as any).text = String(v) },
       }
@@ -544,7 +575,7 @@ export class Element<T extends string> {
       // A function list tweens per argument when every key shares the list; anything else is handed
       // to the host as a raw string for matrix decomposition (its old path).
       return {
-        domain: DOM_UI, id: () => this._id,
+        domain: DOM_UI, id: () => this._h.id,
         value: (v) => {
           if (typeof v !== "string") return null
           const list = parseTransformList(v)
@@ -553,15 +584,15 @@ export class Element<T extends string> {
         commit: (v) => { this._style.transform = v },
       }
     }
+    // Keys tween their WIRE value: a color as a string (the runtime makes it a COLOR track), never
+    // a FLOAT over a packed number. The commit stores the app's value, like `.style()`.
     return {
-      domain: DOM_UI, id: () => this._id, value: uiValue,
+      domain: DOM_UI, id: () => this._h.id, value: (v) => uiValue(wireValue(prop, v)),
       commit: (v) => { this._style[prop] = v },
     }
   }
 
-  /** @internal Active style-class names (stored without the `$`). Kept on the element — not just in
-   *  the layout engine — so hosts re-apply them when a detached node is re-mounted (screens
-   *  re-assign _id on every open). */
+  /** @internal Active style-class names (stored without the `$`) — what the class proxy reads. */
   protected _classes?: Set<string>
 
   protected _classProxy?: any
@@ -579,7 +610,9 @@ export class Element<T extends string> {
    *  Names are accepted with or without the leading `$`. A class set on an element CASCADES: it is
    *  also active on every descendant (their same-name `$` blocks light up), until the subtree's
    *  root — hosted screens/widgets don't inherit. Reads reflect only this element's own classes;
-   *  there is no opt-out below an active ancestor. `Object.keys(el.class)` lists the active names. */
+   *  there is no opt-out below an active ancestor. `Object.keys(el.class)` lists the active names.
+   *  The reserved classes (`$hovered` `$pressed` `$focused` `$landscape` `$portrait`) are the
+   *  system's: writing one throws. */
   get class(): any {
     if (this._classProxy) return this._classProxy
     const obj = classFunction.bind(this)
@@ -591,6 +624,19 @@ export class Element<T extends string> {
     return proxy
   }
 
+  /** @internal Add TREE_FLAG_* bits (tells the runtime and the host which events to route here). */
+  _addFlags(bits: number): void {
+    if ((this._flags & bits) === bits) return
+    this._flags |= bits
+    if (this._h.id !== 0) tree().setFlags(this._h.id, this._flags)
+  }
+  /** @internal */
+  _removeFlags(bits: number): void {
+    if ((this._flags & bits) === 0) return
+    this._flags &= ~bits
+    if (this._h.id !== 0) tree().setFlags(this._h.id, this._flags)
+  }
+
   protected ll?: OnLayoutCallback[]
   /** Observe layout: fires after every host layout pass with the parent-relative box. */
   onLayout(onLayout: OnLayoutCallback): this {
@@ -599,21 +645,47 @@ export class Element<T extends string> {
     } else {
       this.ll = [ onLayout ]
     }
+    this._addFlags(TREE_FLAG_LAYOUT)
     return this
   }
+  /** @internal */
+  _emitLayout(box: { left: number, top: number, width: number, height: number }): void {
+    if (!this.ll) return
+    for (const cb of this.ll) cb(box)
+  }
 
   /** Absolute rect in device space — the space `UIWidget` positions in and touch events report
    *  `clientX`/`clientY` in — including scroll offsets, read live at call time (unlike `onLayout`,
    *  whose coordinates are parent-relative and go stale when an ancestor scrolls). `null` before
-   *  the element is mounted and on hosts without the bridge read. Anchor popovers position-once
+   *  the element is laid out and on hosts without the read. Anchor popovers position-once
    *  at open; don't poll per frame. */
   getBoundingClientRect(): BoundingClientRect | null {
-    if (this._id === 0) return null
-    const rect = _creatorUI.getBoundingClientRect?.(this._id)
+    if (this._h.id === 0) return null
+    const rect = tree().getBoundingClientRect(this._h.id)
     if (!rect) return null
     const [left, top, width, height] = rect
     return { x: left, y: top, left, top, right: left + width, bottom: top + height, width, height }
   }
+
+  /** The parent element, or `null`. Resolves while the parent is itself attached (mounted under a
+   *  presented / router-held screen, a shown widget, a pager page …); a loose subtree's root is
+   *  held only by its handle and is not findable from its children. */
+  get parent(): any {
+    if (this._h.id === 0) return null
+    const id = tree().parent(this._h.id)
+    return id !== 0 ? (elementsOf([id])[0] ?? null) : null
+  }
+
+  destroy(): void {
+    if (this._h.id === 0) return
+    tree().destroy(this._h.id)
+    this._h = DEAD_HANDLE   // the runtime freed the subtree; drop the handle so its record can go
+  }
+
+  /** @internal The runtime freed the node underneath (an ancestor's free): the element is dead. */
+  _freed(): void {
+    this._h = DEAD_HANDLE
+  }
 }
 
 // ---- reactive children --------------------------------------------------------------------------
@@ -667,38 +739,26 @@ export function __uiMap(list: any, render: (item: any, index: number) => any, sl
 // ---- factory argument dispatch ------------------------------------------------------------------
 
 /** @internal Shared argument dispatch for the UI factories (`UIRow(...)`, `UIButton(...)`, …).
- *  Children are variadic; an array argument is flattened one level, so both the legacy
- *  `UIColumn([a, b])` and `UIColumn(header, items.map(row), footer)` work. A lone function
- *  argument is a reactive {@link ChildrenFn}. A plain non-node object in first position is the
- *  legacy style bag: it is spread over `defaults`, or — when `defaults` is null — stored as-is
- *  (the Element constructor mutates it in place, matching the old path). The rest-args array is
- *  taken over as the children array when nothing needs flattening — callers must hand it off. */
+ *  Children are variadic; an array argument is flattened one level, so both `UIColumn([a, b])` and
+ *  `UIColumn(header, items.map(row), footer)` work. A lone function argument is a reactive
+ *  {@link ChildrenFn}. Styles come from `.style()` only. The rest-args array is taken over as the
+ *  children array when nothing needs flattening — callers must hand it off. */
 export function buildUI<R>(args: any[], defaults: any, make: (style: any, children: any[] | ChildrenFn) => R): R {
   const n = args.length
-  const a0 = n > 0 ? args[0] : undefined
-  let style: any
-  let start = 0
-  if (a0 !== null && typeof a0 === "object" && !Array.isArray(a0) && !(a0 instanceof Element)) {
-    style = defaults ? { ...defaults, ...a0 } : a0
-    start = 1
-  } else {
-    style = defaults ? { ...defaults } : {}
-  }
-  if (n === start + 1) {
-    const a = args[start]
+  const style = defaults ? { ...defaults } : {}
+  if (n === 1) {
+    const a = args[0]
     // lone function → reactive children; lone array → used as the children array directly
-    // (the legacy zero-copy path — nested arrays inside it are NOT flattened)
     if (typeof a === "function" || Array.isArray(a)) return make(style, a)
   }
   // Single pass: reuse the rest-args array as the children array until the first array argument
-  // shows up, then copy the prefix once and flatten from there. Falsy entries stay — they are
-  // compacted at mount like always.
+  // shows up, then copy the prefix once and flatten from there. Falsy entries are skipped at mount.
   let flat: any[] | undefined
-  for (let i = start; i < n; i++) {
+  for (let i = 0; i < n; i++) {
     const a = args[i]
     if (flat === undefined) {
       if (Array.isArray(a)) {
-        flat = args.slice(start, i)
+        flat = args.slice(0, i)
         for (let j = 0; j < a.length; j++) flat.push(a[j])
       }
     } else if (Array.isArray(a)) {
@@ -707,22 +767,43 @@ export function buildUI<R>(args: any[], defaults: any, make: (style: any, childr
       flat.push(a)
     }
   }
-  if (flat !== undefined) return make(style, flat)
-  return make(style, start === 0 ? args : args.slice(1))
+  return make(style, flat !== undefined ? flat : args)
 }
 
-export class ContainerElement<T extends string> extends Element<T> {
-  children: any[] = []
+/** A child slot takes a UI element (falsy = conditional, skipped silently). Anything else is
+ *  reported and skipped — never inserted: a non-element's `_h.id` (an Animation's, say) is an id
+ *  from ANOTHER space, and the tree would move whatever node happens to own that number. The hint
+ *  names the usual cause (both come from code written for the older SDK). */
+const acceptChild = (parent: { type: string }, node: any): boolean => {
+  if (!node) return false
+  if (node instanceof Element) return true
+  const hint =
+    typeof node === "function" ? "reactive children are the factory's only argument: UIColumn(() => [ ... ])"
+    // by its backing fields: in a bundle chisel drops the accessors nobody reads (`finished`)
+    : typeof node.play === "function" && ("finished" in node || "_finished" in node) ? "animateTo() / animateFrom() return the Animation, not the element: call it on the element and put the element in the tree"
+    : typeof node === "object" && Object.getPrototypeOf(node) === Object.prototype ? "a style object? Styles go through .style() — the factories take children only"
+    : "only UI elements (or falsy values, skipped) can be children"
+  const what = typeof node === "object" ? (node.constructor?.name || "object") : typeof node
+  console.error(`${parent.type}: a child is not a UI element (${what}) — skipped. ${hint}`)
+  return false
+}
 
+export class ContainerElement<T extends string> extends Element<T> {
   constructor(type: T, style: any, children: any[] | ChildrenFn) {
     super(type, style)
     if (typeof children === "function") {
       this._bindChildren(children)
-    } else {
-      this.children = children
+    } else if (children && children.length > 0) {
+      this.append(...children)
     }
   }
 
+  /** The children — a snapshot read from the runtime (falsy entries were never mounted). */
+  get children(): any[] {
+    if (this._h.id === 0) return []
+    return elementsOf(tree().children(this._h.id))
+  }
+
   /** @internal Reactive children: re-runs when a signal read inside `fn` changes and reconciles
    *  the result against the mounted children with minimal insert/remove ops. */
   _bindChildren(fn: ChildrenFn) {
@@ -744,100 +825,71 @@ export class ContainerElement<T extends string> extends Element<T> {
    *  A moved node is remove+insert — it remounts. Falsy entries are compacted away. */
   _reconcile(next: UINodeChild[]) {
     const target: any[] = []
-    for (const c of next) if (c) target.push(c)
-
-    if (this._id === 0) {
-      this.children.length = 0
-      this.children.push(...target)
-      return
-    }
-
-    // compact holes left by a previous static children array (falsy entries were never mounted)
-    for (let i = this.children.length - 1; i >= 0; i--) {
-      if (!this.children[i]) this.children.splice(i, 1)
-    }
+    for (const c of next) if (acceptChild(this, c)) target.push(c)
+    if (this._h.id === 0) return
 
+    const current: any[] = this.children
     const targetSet = new Set(target)
-    const departed = this.children.filter(c => !targetSet.has(c))
+    const departed = current.filter(c => !targetSet.has(c))
     if (departed.length > 0) this.remove(...departed)
+    const cur: any[] = departed.length > 0 ? this.children : current
 
-    // this.children now mirrors the mounted order; walk the target and fix mismatches in place
+    // `cur` mirrors the mounted order; walk the target and fix mismatches in place
     for (let i = 0; i < target.length; i++) {
-      if (this.children[i] === target[i]) continue
+      if (cur[i] === target[i]) continue
       const node = target[i]
-      if (this.children.includes(node, i + 1)) {
+      const j = cur.indexOf(node, i + 1)
+      if (j >= 0) {
         this.remove(node)   // moved forward — remount at its new position
+        cur.splice(j, 1)
       }
-      this.insert(i, node)
+      this._insertAt(i, node)
+      cur.splice(i, 0, node)
     }
   }
 
-  /** Append children (falsy entries are kept in the array but never mounted). */
+  private _insertAt(index: number, node: any): void {
+    if (this._h.id === 0 || !node || node._h.id === 0) return
+    tree().insert(this._h.id, node._h.id, index)
+    pin(node)
+  }
+
+  /** Append children (falsy entries are skipped). */
   append(...nodes: UINodeChild[]): this {
-    if (this._id === 0) {
-      this.children.push(...nodes)
-      return this
-    }
-    let index = 0
-    for (let child of this.children) {
-      if (child) {
-        index++
-      }
-    }
-    for (let node of nodes) {
-      if (!node) continue
-      _creatorUI.insertNode(index, this._id, node) 
+    if (this._h.id === 0) return this
+    let index = tree().children(this._h.id).length
+    for (const node of nodes) {
+      if (!acceptChild(this, node)) continue
+      this._insertAt(index, node)
       index++
     }
-    this.children.push(...nodes)
     return this
   }
-  /** Insert children at `index` of the children array. */
+  /** Insert children at `index`. */
   insert(index: number, ...nodes: UINodeChild[]): this {
-    if (this._id === 0) {
-      this.children.splice(index, 0, ...nodes)
-      return this
-    }
-
-    let _index = 0
-    for (let i = 0; i < index; i++) {
-      if (this.children[i]) {
-        _index++
-      }
-    }
-    for (let node of nodes) {
-      if (!node) continue
-      _creatorUI.insertNode(_index, this._id, node) 
-      _index++
+    if (this._h.id === 0) return this
+    let at = index
+    for (const node of nodes) {
+      if (!acceptChild(this, node)) continue
+      this._insertAt(at, node)
+      at++
     }
-    this.children.splice(index, 0, ...nodes)
     return this
   }
-  /** Remove (unmount) the given children. */
-  remove(...nodesToDelete: UINode[]): this {
-    const set = new Set(nodesToDelete)
-
-    for (let i = 0; i < this.children.length; i++) {
-      if (set.has(this.children[i])) {
-        set.delete(this.children[i])
-        this.children.splice(i, 1)
-        i--
-
-        if (set.size === 0) {
-          break
-        }
-      }
-    }
-
-    if (this._id === 0) {
-      return this
-    }
-    for (let node of nodesToDelete) {
-      _creatorUI.removeNode(this._id, node)
+  /** Remove (unmount) the given children. The removed subtrees stay valid (re-appendable) as long
+   *  as you hold them; dropped ones are freed. */
+  remove(...nodesToDelete: UINodeChild[]): this {
+    if (this._h.id === 0) return this
+    for (const node of nodesToDelete) {
+      if (!(node instanceof Element)) continue   // falsy, or never mountable (see acceptChild)
+      const el = node as any
+      if (el._h.id === 0) continue
+      tree().remove(this._h.id, el._h.id)
+      unpin(el._h.id)
     }
     return this
   }
-  
+
   /** Replace all children — a plain array, or a function for reactive children. */
   setContent(children: UINodeChild[] | ChildrenFn): this {
     if (typeof children === "function") {
@@ -845,11 +897,9 @@ export class ContainerElement<T extends string> extends Element<T> {
       return this
     }
     disposeBinding(this, "#children")  // static content overrides a reactive binding
-    if (this._id !== 0) {
-      _creatorUI.setContent(this._id, this.children, children)
-    }
-    this.children.length = 0
-    this.children.push(...children)
+    const current = this.children
+    if (current.length > 0) this.remove(...current)
+    this.append(...children)
     return this
   }
-}
+}