lecodes-cli 0.11.0 → 0.13.0

package/runtime/sdk/scene/defineScene.ts

@@ -34,10 +34,15 @@
 
 import { Aspect, type AspectCtor, type With } from "../core/Aspect"
 import { describeAspect, describeFields, type AspectClassInfo } from "../core/fields"
+import {
+  collectRefDeps, isEditMode, isNodeRef, resolveRefs, use, ref, make, EDIT_FLAG,
+  type AspectEntry, type MakeEntry as SharedMakeEntry,
+} from "./grammar"
 import { InspectorUI, type InspectorEvent, type InspectorWidget } from "../core/InspectorUI"
 import type { ColorInput } from "../core/color"
 import type { Vec3Like } from "../math/vec"
 import { Scene, type SceneOptions } from "../gl/Scene"
+import { CAMERA_DEFAULTS } from "../gl/Camera"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
@@ -63,65 +68,13 @@ export type MaterialDef =
   // An imported/shared Material instance — valid at runtime; the editor shows it read-only.
   | Material
 
-/** 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}. */
-export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>> = {
-  /** @internal grammar marker. */
-  readonly __make: true
-  fn: (args: A) => Node | Promise<Node>
-  args?: A
-}
+// The grammar markers (`use`/`ref`/`make`) live in ./grammar.ts, shared with defineScene2d —
+// re-exported here so this module remains the one import site for scene-file machinery.
+export { use, ref, make }
+export type { AspectEntry }
 
-/**
- * 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>>(
-  fn: (args: A) => Node | Promise<Node>, args?: A,
-): MakeEntry<A> => ({ __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 extends Node = Node>(name: string): T => ({ $ref: name } as unknown as T)
-
-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). */
-const resolveRefs = (props: Record<string, unknown> | undefined, nodes: Record<string, Node>): 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
-}
+/** A `make(fn, args)` source entry whose factory returns a 3D {@link Node}. */
+export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>> = SharedMakeEntry<A, Node>
 
 /** Transform overrides for one INTERNAL node of a GLB model or a prefab instance
  *  (`overrides` on a model/prefab node, keyed by part path). */
@@ -132,8 +85,19 @@ export type ModelOverrideDef = {
   visible?: boolean
 }
 
-/** The `camera: {}` source block — reserved for projection settings (fov, …) later. */
-export type CameraNodeDef = Record<string, never>
+/** Camera projection settings, shared by the `camera:` source block and the top-level `camera:`
+ *  block. All optional — an omitted key keeps the host default (60° / 0.01 / 1000). */
+export type CameraProjectionDef = {
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov?: number
+  /** Near clip distance (default 0.01). */
+  near?: number
+  /** Far clip distance = view range (default 1000); geometry past it is culled. */
+  far?: number
+}
+
+/** The `camera: {}` source block — projection settings for the node that drives the view. */
+export type CameraNodeDef = CameraProjectionDef
 
 export type SceneNodeDef = {
   // -- source (at most one; none = plain group node) --
@@ -163,7 +127,7 @@ export type SceneNodeDef = {
   eulerAngles?: Vec3Like
   scale?: Vec3Like | number
   visible?: boolean
-  /** Editor-only: the transform gizmo won't target this node (fields still edit). No runtime effect. */
+  /** Editor-only: viewport manipulation won't target this node (fields still edit). No runtime effect. */
   locked?: boolean
   castShadows?: boolean
   receiveShadows?: boolean
@@ -172,7 +136,7 @@ export type SceneNodeDef = {
   children?: Record<string, SceneNodeDef>
 }
 
-export type SceneCameraDef = {
+export type SceneCameraDef = CameraProjectionDef & {
   position?: Vec3Like
   /** Point the camera looks at. */
   target?: Vec3Like
@@ -272,9 +236,6 @@ const applyModelOverrides = (root: Node, overrides: Record<string, ModelOverride
 
 // ---- runtime -------------------------------------------------------------------
 
-const EDIT_FLAG = "__lecodesSceneEdit"
-const isEditMode = (): boolean => (globalThis as Record<string, unknown>)[EDIT_FLAG] === true
-
 const resolveMaterial = (def: MaterialDef): Material => {
   if (def instanceof Material) return def
   if ("lit" in def) return Material.lit(def.lit)
@@ -309,7 +270,7 @@ const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
   if (def.eulerAngles) node.eulerAngles = def.eulerAngles
   if (def.scale !== undefined) node.scale = def.scale
   if (def.visible !== undefined) node.visible = def.visible
-  // editor-only flag (the harness reads it when targeting the gizmo); inert at runtime
+  // editor-only flag (the harness's manipulation layer consults it); inert at runtime
   if (def.locked !== undefined) (node as { _sceneLocked?: boolean })._sceneLocked = def.locked
   if (def.camera !== undefined) (node as { _sceneCamera?: boolean })._sceneCamera = true
   // waypoint/def order for aspects that read children (FollowPath) — the engine's live child
@@ -368,16 +329,27 @@ class CameraRig extends Aspect<"__cameraRig"> {
   }
 }
 
-/** The first camera-source def in file order (depth-first), or null. */
-const findCameraName = (defs?: Record<string, SceneNodeDef>): string | null => {
+/** The first camera-source def in file order (depth-first) — its name and block — or null. */
+const findCamera = (defs?: Record<string, SceneNodeDef>): { name: string, def: CameraNodeDef } | null => {
   for (const [ name, nd ] of Object.entries(defs ?? {})) {
-    if (nd.camera !== undefined) return name
-    const inner = findCameraName(nd.children)
+    if (nd.camera !== undefined) return { name, def: nd.camera }
+    const inner = findCamera(nd.children)
     if (inner) return inner
   }
   return null
 }
 
+/** fov / near / far from a camera block onto the live camera. The build path leaves an empty block
+ *  alone (a host may run with its own configured fov); `reset` — the editor's live patch — fills
+ *  omitted keys with the defaults instead, so clearing a field in the inspector takes effect. */
+const applyCameraProjection = (scene: Scene, def: CameraProjectionDef, reset = false): void => {
+  const { fov, near, far } = def
+  if (!reset && fov === undefined && near === undefined && far === undefined) return
+  scene.camera.setProjection(reset
+    ? { fov: fov ?? CAMERA_DEFAULTS.fov, near: near ?? CAMERA_DEFAULTS.near, far: far ?? CAMERA_DEFAULTS.far }
+    : { fov, near, far })
+}
+
 // ---- editor-run aspects (generators) ------------------------------------------------------------
 // A class with `static editor = { rebuild: true }` runs while a scene is edited: the loader
 // constructs it (refs resolved, node + `generated` set — NEVER onAttach) and calls rebuild(); the
@@ -429,15 +401,6 @@ type EditorRun = {
   deps: Set<string>
 }
 
-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
-}
-
 const safeRebuild = (run: EditorRun): void => {
   // a throwing generator must not take the editor session down with it
   try { run.inst.rebuild?.() } catch (e) { console.error(`[scene] editor aspect rebuild failed on "${run.hostName}":`, e) }
@@ -626,18 +589,22 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]))
 
   // a camera NODE wins over the top-level `camera:` block; in play mode it keeps driving the view
-  // (CameraRig), in edit mode it only seeds the editor's starting viewpoint
-  const camName = findCameraName(def.nodes)
-  const camNode = camName ? nodes[camName] : undefined
-  if (camNode) {
+  // (CameraRig), in edit mode it only seeds the editor's starting viewpoint. The PROJECTION applies
+  // in both modes — it is a property of the scene, not of the viewpoint, so the editor shows the
+  // lens the running app will use.
+  const cam = findCamera(def.nodes)
+  const camNode = cam ? nodes[cam.name] : undefined
+  if (cam && camNode) {
     scene.camera.position = camNode.worldPosition
     scene.camera.quaternion = camNode.worldQuaternion
+    applyCameraProjection(scene, cam.def)
     if (!isEditMode()) {
       ;(camNode as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(CameraRig, { _scene: scene })
     }
   } else if (def.camera) {
     if (def.camera.position) scene.camera.position = def.camera.position
     if (def.camera.target) scene.camera.lookAt(def.camera.target)
+    applyCameraProjection(scene, def.camera)
   }
 
   return { scene, nodes }
@@ -734,6 +701,9 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       dispose(old)               // fresh already replaced nodes[name] in build(), so it survives
       nodes[name] = fresh
     }
+    // the projection lives on the scene camera, not on the node — re-apply it here so an inspector
+    // fov/near/far edit lands live (a rebuilt node alone would carry none of it)
+    if (def.camera !== undefined) applyCameraProjection(scene, def.camera, true)
     return fresh
   }
 

package/runtime/sdk/scene/editorPlugins.ts

@@ -57,7 +57,7 @@ export type EditorToolHooks = {
    *  share the generic wand icon, so any editor with two or more tools should set it. */
   icon?: string
   /** A viewport click while the tool is active — `hit` is the raycast result under the pointer.
-   *  Selection clicks and the transform gizmo are suspended while a tool is active. */
+   *  Viewport clicks route to the tool while it is active. */
   onViewportClick?(hit: EditorRayHit, editor: EditorApi): void
 }
 

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 {