lecodes-cli 0.11.0 → 0.12.0

package/runtime/sdk/scene/grammar.ts

@@ -0,0 +1,85 @@
+// The scene-file literal grammar markers, shared by `.scene.ts` (defineScene, 3D) and
+// `.scene2d.ts` (defineScene2d, 2D): `use(Ctor, props)` aspect entries, `ref('name')` node
+// references, `make(fn, args)` code-built sources — plus the ref-resolution helpers both loaders
+// run. One implementation so the two formats can't drift; the engine-specific node/def types stay
+// in their own modules (defineScene.ts / defineScene2d.ts), which re-export these for user code.
+
+import type { Aspect, AspectCtor } from "../core/Aspect"
+import type { Node } from "../gl/Node"
+
+/** One aspect to attach, created by `use(Ctor, props)`. */
+export type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = {
+  /** @internal grammar marker. */
+  readonly __use: true
+  ctor: AspectCtor<A>
+  props?: Partial<A>
+}
+
+/** Reference an aspect in a scene file: `aspects: [use(Physics, { motion: 'static' })]`. Props are
+ *  typechecked against the aspect's fields, exactly like `node.aspect(Ctor, props)`. */
+export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> =>
+  ({ __use: true, ctor, props })
+
+/** A `make(fn, args)` source entry — see {@link make}. `N` is the node family the factory returns
+ *  (3D `Node` by default; a `.scene2d.ts` file's factories return `Node2D`). */
+export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>, N = Node> = {
+  /** @internal grammar marker. */
+  readonly __make: true
+  fn: (args: A) => N | Promise<N>
+  args?: A
+}
+
+/**
+ * A code-created source in a scene file: `tower: { make: make(buildTower, { floors: 5 }), … }`.
+ * The factory runs after every scene node exists (so `ref()` args resolve, forward references
+ * included) and its returned subtree mounts under the def node — the def's transform stays
+ * editor-owned, so moving the node never re-calls the factory. Args must be literal data (same
+ * grammar as aspect props); in the editor they edit as fields, and an arg change re-CALLS the
+ * factory live — the code is already in the bundle, so no compile happens. Keep factories pure
+ * builders: same args → same subtree, no side effects outside the returned nodes.
+ */
+export const make = <A extends Record<string, unknown>, N>(
+  fn: (args: A) => N | Promise<N>, args?: A,
+): MakeEntry<A, N> => ({ __make: true, fn, args })
+
+/**
+ * Reference another scene node by name in an aspect's props:
+ * `use(Road, { from: ref('pointA'), to: ref('pointB') })`. Resolves to the live node when aspects
+ * attach — after EVERY node of the scene exists, so forward references work. An unknown name
+ * resolves to `null` (type your aspect field `Node | null`). Scene files only — hand-written code
+ * passes nodes directly: `node.aspect(Road, { from: nodes.pointA })`.
+ */
+export const ref = <T = Node>(name: string): T => ({ $ref: name } as unknown as T)
+
+export const isNodeRef = (v: unknown): v is { $ref: string } =>
+  typeof v === "object" && v !== null && typeof (v as { $ref?: unknown }).$ref === "string"
+
+/** Swap `ref()` markers in aspect props for the live nodes (top level + one array level deep). */
+export const resolveRefs = <N>(
+  props: Record<string, unknown> | undefined, nodes: Record<string, N>,
+): Record<string, unknown> | undefined => {
+  if (!props) return props
+  let out: Record<string, unknown> | undefined
+  for (const [ k, v ] of Object.entries(props)) {
+    if (isNodeRef(v)) {
+      ;(out ??= { ...props })[k] = nodes[v.$ref] ?? null
+    } else if (Array.isArray(v) && v.some(isNodeRef)) {
+      ;(out ??= { ...props })[k] = v.map((el) => (isNodeRef(el) ? nodes[el.$ref] ?? null : el))
+    }
+  }
+  return out ?? props
+}
+
+/** Names of the nodes a props record's ref() values point at (editor dep tracking). */
+export const collectRefDeps = (props: Record<string, unknown>): Set<string> => {
+  const deps = new Set<string>()
+  for (const v of Object.values(props)) {
+    if (isNodeRef(v)) deps.add(v.$ref)
+    else if (Array.isArray(v)) for (const el of v) if (isNodeRef(el)) deps.add(el.$ref)
+  }
+  return deps
+}
+
+/** The edit-mode flag an editor host sets before running the bundle (shared by both formats). */
+export const EDIT_FLAG = "__lecodesSceneEdit"
+export const isEditMode = (): boolean => (globalThis as Record<string, unknown>)[EDIT_FLAG] === true

package/runtime/sdk/ui/NativeView.ts

@@ -11,29 +11,30 @@
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UINativeViewStyle = ElementStyle & DrawableStyle
 
 /** An instance of a host-registered platform view (map, QR scanner, camera preview, …) —
  *  embeddable among a screen's children AND fullscreen-presentable (`open()`); one instance lives
  *  in one place at a time. Talk to it via the `call`/`on` channel. */
-export interface NativeView {
+export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableStyle & BaseStyle> {
   readonly type: "native",
   /** The registered view kind this instance resolves to (the `registerView` name). */
   readonly viewName: string,
   /** Creation params, passed to the host factory (JSON-serializable). */
   readonly params: any,
-  style: Style<this, UINativeViewStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   /** Show fullscreen as the current destination (see Presentable). */
   open(options?: PresentOptions): void,
+  /** Dismiss if this is the visible destination. */
   close(): void,
 
+  /** Became the visible destination. */
   onOpen(callback: () => void): this
+  /** Stopped being the visible destination. */
   onClose(callback: () => void): this
+  /** Hardware/system back while current. */
   onBackPressed(callback: () => void): this
 
   /** Invoke a method on the native view (`map.call("setCenter", [lng, lat])`). Args and the
@@ -42,13 +43,6 @@ export interface NativeView {
   /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
   on(event: string, callback: (data?: any) => void): this
   off(event: string, callback: (data?: any) => void): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 }
 
 let nextViewId = 1

package/runtime/sdk/ui/UIBottomSheet.ts

@@ -51,10 +51,6 @@ export interface UIBottomSheet extends UIWidget {
   /** `dismissible(false)`: scrim taps, the back button and dragging below the lowest detent no
    *  longer close the sheet (a drag collapses to the lowest detent instead). Default `true`. */
   dismissible(enabled: boolean): this,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
 }
 
 export class BottomSheetElement extends ModalElement {

package/runtime/sdk/ui/UIButton.ts

@@ -1,18 +1,14 @@
 import { ClickEvent, TouchStartEvent, LongPressEvent } from "../runtime/touch"
 import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch"
-import { type ElementStyle, type ContainerStyle, type Classes, type Style, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
+import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
 
 /** A tappable container — row + centered children by default. Press feedback via the `onPressed`
  *  style block, the `$pressed` class, or `rippleColor`. */
-export interface UIButton {
+export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
   readonly type: "button",
 
-  style: Style<this, UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
-
   /** Fired on a completed tap/click. */
   onClick(callback: (ev: ClickEventType<UIButton>) => void): this,
   /** Fired when a touch begins; `ev.track(...)` takes over the rest of the gesture (dragging). */
@@ -23,21 +19,6 @@ export interface UIButton {
   onLongPress(callback: (ev: LongPressEventType<UIButton>) => void): this,
   /** Is a finger currently down on the button? */
   isPressed(): boolean,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
-
-  readonly children: UINodeChild[],
 }
 
 

package/runtime/sdk/ui/UIContainer.ts

@@ -1,28 +1,10 @@
-import { ContainerElement, buildUI, type AnimateStyle, type AppearStyle, type ChildrenFn, type ContainerStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type StyleFn, type UIChildArg, type UINode, type UINodeChild } from "./UINode"
+import { ContainerElement, buildUI, type ChildrenFn, type ContainerStyle, type DrawableStyle, type ElementStyle, type UIChildArg, type UIContainerBase, type UINodeChild } from "./UINode"
 
 export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle
 
 /** A vertical flex container — children stack top to bottom. */
-export interface UIColumn {
+export interface UIColumn extends UIContainerBase<UIContainerStyle> {
   readonly type: "column",
-  style: Style<this, UIContainerStyle>,
-  animateTo: AnimateStyle<this, UIContainerStyle>
-  animateFrom: AnimateStyle<this, UIContainerStyle>
-
-  append(...nodes: UINodeChild[]): UIColumn
-  insert(index: number, ...nodes: UINodeChild[]): UIColumn
-  remove(...nodes: UINodeChild[]): UIColumn
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-  
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
-
-  readonly children: UINodeChild[]
 }
 const makeColumn = (style: any, children: any) => new ContainerElement("column", style, children)
 
@@ -44,26 +26,8 @@ export function UIColumn(...args: any[]): UIColumn {
 }
 
 /** A horizontal flex container — children flow left to right. */
-export interface UIRow {
+export interface UIRow extends UIContainerBase<UIContainerStyle> {
   readonly type: "row",
-  style: Style<this, UIContainerStyle>,
-  animateTo: AnimateStyle<this, UIContainerStyle>,
-  animateFrom: AnimateStyle<this, UIContainerStyle>,
-
-  append(...nodes: UINodeChild[]): UIRow
-  insert(index: number, ...nodes: UINodeChild[]): UIRow
-  remove(...nodes: UINodeChild[]): UIRow
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
-
-  readonly children: UINodeChild[],
 }
 const ROW_DEFAULTS = { flexDirection: "row" } as const
 const makeRow = (style: any, children: any) => new ContainerElement("row", style, children)
@@ -78,26 +42,8 @@ export function UIRow(...args: any[]): UIRow {
 }
 
 /** A centering container — `justifyContent`/`alignItems` default to center. */
-export interface UIBox {
+export interface UIBox extends UIContainerBase<UIContainerStyle> {
   readonly type: "box",
-  style: Style<this, UIContainerStyle>,
-  animateTo: AnimateStyle<this, UIContainerStyle>,
-  animateFrom: AnimateStyle<this, UIContainerStyle>,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
-
-  readonly children: UINodeChild[],
 }
 const BOX_DEFAULTS = { justifyContent: "center", alignItems: "center" } as const
 

package/runtime/sdk/ui/UIImage.ts

@@ -2,7 +2,7 @@ import type { FetchResponse } from "../runtime/fetch"
 import type { SvgSourceValue as SvgSource } from "../runtime/misc"
 import type { File } from "../runtime/fetch"
 import { Canvas, isCanvas } from "../canvas/Canvas"
-import { Element, type AnimateStyle, type Color, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style } from "./UINode"
+import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
 
@@ -23,27 +23,16 @@ export type ResolvedImageSource = string | FetchResponse | File | SvgSource | Ca
 
 /** An image element. Sources: URL / `asset(...)`, fetch response / File, an SVG source
  *  (`assetIcon`), or a live Canvas (`canvas.update()` refreshes the node in place). */
-export interface UIImage {
+export interface UIImage extends UIElementBase<UIImageStyle> {
   readonly type: "image",
   /** The image source — writable to swap the picture in place. */
   get src(): ResolvedImageSource
   set src(value: ImageSource)
-  style: Style<this, UIImageStyle>
-  animateTo: AnimateStyle<this, UIImageStyle>
-  animateFrom: AnimateStyle<this, UIImageStyle>
 
   /** Render only a sub-rectangle of the source texture (texture pixels) — the atlas/spritesheet
    *  primitive: crop once, then swap the rect per frame for sprite animation. The rect's w/h
    *  become the node's intrinsic size and override `objectFit` — the cropped frame fills the box. */
   setSourceRect(x: number, y: number, w: number, h: number): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 }
 
 class ImageElement extends Element<"image"> {

package/runtime/sdk/ui/UIInput.ts

@@ -1,4 +1,4 @@
-import { type ElementStyle, type DrawableStyle, type Classes, type Style, Element, type TextStyle, type Color, type OnLayoutCallback, type BoundingClientRect, type BaseStyle, type AnimateStyle } from "./UINode";
+import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
 
 type InputStyle = {
   placeholder?: string,
@@ -51,7 +51,7 @@ type SubmitStyle = {
 
 /** A single-line text input. Keyboard/picker kind via the `type` style, return-key behavior via
  *  `enterKey` + `onSubmit`; keyboard policy on `keyboardShrink`/`keyboardDismiss`. */
-export interface UIInput {
+export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
   readonly type: "input",
 
   /**
@@ -62,51 +62,39 @@ export interface UIInput {
    */
   value: string
 
-  style: Style<this, UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
-
+  /** The text changed — fires on every user edit. */
   onChange(callback: (value: string) => void): UIInput
+  /** Gained focus (keyboard opens). */
   onFocus(callback: () => void): UIInput
+  /** Lost focus. */
   onBlur(callback: () => void): UIInput
   /** The keyboard's return key was pressed. `value` is the current text. See `enterKey`. */
   onSubmit(callback: (value: string) => void): UIInput
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
 
   /** Focus the input (opens the keyboard). No-op before mount. */
   focus(): void
   /** Release focus (dismisses the keyboard when this input held it). */
   blur(): 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>
 }
 
 /** A multi-line text field — see the {@link UITextArea} factory for the auto-grow contract. */
-export interface UITextArea {
+export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
   readonly type: "textarea",
 
   /** The field's text — same contract as {@link UIInput.value}: settable before mount to pre-fill. */
   value: string
 
-  style: Style<this, UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
-
+  /** The text changed — fires on every user edit. */
   onChange(callback: (value: string) => void): UITextArea
+  /** Gained focus (keyboard opens). */
   onFocus(callback: () => void): UITextArea
+  /** Lost focus. */
   onBlur(callback: () => void): UITextArea
 
   /** Focus the text area (opens the keyboard). No-op before mount. */
   focus(): void
   /** Release focus (dismisses the keyboard when this text area held it). */
   blur(): 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>
 }
 
 class InputElement<T extends "input" | "textarea"> extends Element<T> {

package/runtime/sdk/ui/UIModal.ts

@@ -50,10 +50,6 @@ export interface UIModal extends UIWidget {
   /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
    *  (forced-choice dialogs). Default `true`. */
   dismissible(enabled: boolean): this,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
 }
 
 export class ModalElement extends WidgetElement {

package/runtime/sdk/ui/UINode.ts

@@ -362,6 +362,43 @@ export type ClassValue = boolean | (() => boolean)
  *  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. */

package/runtime/sdk/ui/UIPager.ts

@@ -1,4 +1,4 @@
-import { ContainerElement, type AnimateStyle, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type UINodeChild } from "./UINode"
+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"
 
@@ -41,11 +41,8 @@ const _activeStack: PagerElement[] = []
  *
  * To open something over *everything* (above bars, above the pager), use `Router.push` instead.
  */
-export interface UIPager {
+export interface UIPager extends UIElementBase<UIPagerStyle, DrawableStyle & BaseStyle> {
   readonly type: "pager",
-  style: Style<this, UIPagerStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>,
 
   /** Replace the pager's tabs — one screen per tab, in order. Every tab becomes a fresh
    *  one-screen stack (pushed screens are dropped) and the selection is clamped into range;
@@ -80,14 +77,6 @@ export interface UIPager {
   readonly depth: number,
   /** Fires when the current tab's depth changes — push, pop, replace, or a back-swipe. */
   onChange(callback: (depth: number) => void): this,
-
-  onLayout(onLayout: OnLayoutCallback): this,
-  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>,
 }
 
 export class PagerElement extends ContainerElement<"pager"> {

package/runtime/sdk/ui/UIScreen.ts

@@ -1,6 +1,6 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { ContainerElement, buildUI, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UIChildArg, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { ContainerElement, buildUI, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, } from "./UINode"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
@@ -8,24 +8,15 @@ export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
  *  fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
  *  (`flexGrow: 1`). Scroll events and pull-to-refresh live on the scroll containers
  *  (`UIScrollable`, `UIVirtualizedList`). */
-export interface UIScreen {
+export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle & BaseStyle> {
   readonly type: "screen",
-  style: Style<this, UIScreenStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   /** Show this screen as the current destination (replaces whatever is visible — a screen, a
    *  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
 
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  readonly children: UINodeChild[],
-
   /** Hardware/system back while this screen is current. */
   onBackPressed(callback: () => void): this
 
@@ -45,14 +36,7 @@ export interface UIScreen {
   /** Free a `keepAlive()` screen's retained tree now. No-op unless it's currently detached-and-kept. */
   dispose(): this
 
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
-
+  /** Touch began on the screen; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
 }
 

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,5 +1,5 @@
 import type { UIContainerStyle } from "./UIContainer"
-import { type Classes, type Style, type AnimateStyle, type UIChildArg, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type Color, ContainerElement, buildUI } from "./UINode"
+import { type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type Color, ContainerElement, buildUI } from "./UINode"
 
 export type ScrollStyle = {
   showScrollbar?: boolean,
@@ -21,24 +21,8 @@ export type UIScrollableStyle = UIContainerStyle & ScrollStyle & { scrollDirecti
 
 /** A scroll container — vertical by default, `scrollDirection: "horizontal"` for carousels/chip
  *  rows. The scrolling body of a screen (screens themselves never scroll). */
-export interface UIScrollable {
+export interface UIScrollable extends UIContainerBase<UIScrollableStyle> {
   readonly type: "scrollable",
-  style: Style<this, UIScrollableStyle>,
-  animateTo: AnimateStyle<this, UIScrollableStyle>,
-  animateFrom: AnimateStyle<this, UIScrollableStyle>,
-  
-  append(...nodes: UINodeChild[]): UIScrollable
-  insert(index: number, ...nodes: UINodeChild[]): UIScrollable
-  remove(...nodes: UINodeChild[]): UIScrollable
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 
   /** Scroll position changed (px from the start edge). */
   onScroll(callback: (scrollPosition: number) => void): UIScrollable,
@@ -49,8 +33,6 @@ export interface 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. */
   onRefresh(callback: () => void | Promise<void>): UIScrollable
-
-  readonly children: UINodeChild[]
 }
 
 class ScrollableElement extends ContainerElement<"scrollable"> {

package/runtime/sdk/ui/UISpacer.ts

@@ -1,16 +1,10 @@
-import { Element, type ElementStyle, type Classes, type Style, type StyleFn } from "./UINode"
+import { Element, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UISpacerStyle = ElementStyle
 
 /** A flexible gap — `flexGrow: 1` by default, pushes its siblings apart. */
-export interface UISpacer {
+export interface UISpacer extends UIElementBase<UISpacerStyle> {
   readonly type: "spacer",
-  style: Style<this, UISpacerStyle>,
-
-  /** 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>
 }
 /** Create a flexible gap (`flexGrow: 1`) — e.g. between a header's title and its actions. */
 export function UISpacer(): UISpacer

package/runtime/sdk/ui/UIText.ts

@@ -1,24 +1,13 @@
 import { createBinding } from "../core/signals"
-import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type TextStyle } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type TextStyle, type UIElementBase } from "./UINode"
 
 export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
 
 /** A text label. */
-export interface UIText {
+export interface UIText extends UIElementBase<UITextStyle, DrawableStyle & BaseStyle & TextStyle> {
   readonly type: "text",
   /** The displayed string — writable at any time. */
   text: string,
-  style: Style<this, UITextStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 }
 
 export class TextElement extends Element<"text"> {