lecodes-cli 0.6.4 → 0.7.1

package/runtime/sdk/scene/editorPlugins.ts

@@ -0,0 +1,86 @@
+// Editor plugins: `registerEditorWindow` / `registerEditorTool` (docs/scene-editor-plan.md,
+// phase 11). Registrations live in `*.editor.ts` files — compiled and executed ONLY in
+// scene-editor bundles (phase 10), so none of this reaches shipped app.js (nothing references it
+// there, and method-granular DCE drops it).
+//
+// The scene-editor harness (packages/projects/src/scene-editor) reads the registry through the
+// injected `__editorPlugins` global — the harness, the scene, and the editor files compile into
+// ONE bundle, so they share this module instance. Windows and tools describe their UI through the
+// same immediate-mode `InspectorUI` protocol custom inspector cards use (one widget vocabulary,
+// three mount points), and mutate the scene ONLY through the `editor` doc API — every plugin write
+// lands in the scene document (undoable, diffable), never in live engine state.
+
+import type { InspectorUI } from "../core/InspectorUI"
+
+/** A geometry hit under the viewport pointer, handed to tools. Physics builds raycast the scene's
+ *  meshes (precise); otherwise (and on misses) the hit falls back to the ground plane (y = 0). */
+export type EditorRayHit = {
+  point: [number, number, number]
+  normal: [number, number, number]
+  /** The scene-file node the hit belongs to — null for ground-plane fallback hits. */
+  node: string | null
+}
+
+/**
+ * The editor scripting API handed to windows and tools. Doc-op methods write the scene DOCUMENT
+ * through the editor's normal commit path (undo, file, live patching all included); they return
+ * false / no-op when the document can't take the edit (duplicate name, unknown node).
+ */
+export type EditorApi = {
+  /** The currently selected node name (or `model::part` key), null when nothing is selected. */
+  readonly selection: string | null
+  select(name: string | null): void
+  /** The scene document's nodes (name + source kind: mesh / model / light / group). */
+  nodes(): { name: string, kind: string }[]
+  /** First unused "base", "base2", "base3", … node name. */
+  uniqueName(base: string): string
+  /** Add a node from plain def data (scene-file grammar; a string `model` value means an asset
+   *  path). One undo step unless grouped by `transact`. */
+  addNode(name: string, def: Record<string, unknown>): boolean
+  /** Write one def prop (transforms apply live; anything else patches/re-runs the node). */
+  setProp(name: string, key: string, value: unknown): boolean
+  removeNode(name: string): void
+  /** Duplicate a node; returns the copy's name (null when it can't). */
+  duplicate(name: string): string | null
+  /** Raycast the scene under a viewport pixel (same hit rules as tool clicks). */
+  raycast(screenX: number, screenY: number): EditorRayHit | null
+  /** Group every doc edit inside `fn` into ONE undo step. */
+  transact(fn: () => void): void
+}
+
+export type EditorWindowFn = (ui: InspectorUI, editor: EditorApi) => void
+
+export type EditorToolHooks = {
+  /** CSS cursor for the viewport while this tool is active (default "crosshair"). */
+  cursor?: string
+  /** A short glyph (one character / emoji) for the tool's toolbar button — tools without one all
+   *  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. */
+  onViewportClick?(hit: EditorRayHit, editor: EditorApi): void
+}
+
+/** @internal The registry the scene-editor harness reads (windows/tools in registration order). */
+export const __editorPlugins = {
+  windows: [] as { title: string, render: EditorWindowFn }[],
+  tools: [] as { name: string, hooks: EditorToolHooks }[],
+}
+
+/** Register an editor panel — a collapsible overlay docked over the viewport (the inspector rail
+ *  stays selection-scoped). A window that emits `ui.toolButton` for a tool becomes that tool's
+ *  settings panel: activating the tool expands and highlights it. `render` re-runs immediate-mode
+ *  on every interaction — same protocol as `static inspector` cards. */
+export const registerEditorWindow = (title: string, render: EditorWindowFn): void => {
+  const existing = __editorPlugins.windows.find((w) => w.title === title)
+  if (existing) existing.render = render
+  else __editorPlugins.windows.push({ title, render })
+}
+
+/** Register a viewport tool — a toolbar entry beside move/rotate/scale (activate it there or via
+ *  `ui.toolButton(label, name)`). While active, viewport clicks arrive as raycast hits. */
+export const registerEditorTool = (name: string, hooks: EditorToolHooks): void => {
+  const existing = __editorPlugins.tools.find((t) => t.name === name)
+  if (existing) existing.hooks = hooks
+  else __editorPlugins.tools.push({ name, hooks })
+}

package/runtime/sdk/ui/NativeView.ts

@@ -0,0 +1,144 @@
+// A host-registered platform view (map, QR scanner, camera preview, …) — the plugin surface of
+// the Presentable model (docs/navigation-presentable-plan.md). The host registers a *capability*
+// (`engine.registerView("map") { params, channel -> MapView(...) }`); when and with what to show
+// it is app code. Dual-natured like every Presentable: a fullscreen destination
+// (`Router.push(map)` / `map.open()`) AND an embeddable layout node (wire type `"native"` — place
+// it among a screen's children, sized by its styles). One instance lives in one place at a time;
+// pushing a mounted instance fullscreen is promotion (the native view reparents, state intact).
+//
+// Plugins ship a typed TS wrapper over the raw `call`/`on` channel — see QRScanner for the
+// wrapper convention.
+
+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 Style } from "./UINode"
+
+export type UINativeViewStyle = ElementStyle & DrawableStyle
+
+export interface NativeView {
+  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,
+  close(): void,
+
+  onOpen(callback: () => void): this
+  onClose(callback: () => void): this
+  onBackPressed(callback: () => void): this
+
+  /** Invoke a method on the native view (`map.call("setCenter", [lng, lat])`). Args and the
+   *  result are JSON-serialized. Rejects if the host has no such view/method. */
+  call(method: string, ...args: any[]): Promise<any>
+  /** 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
+  setClass(name: string, enabled: boolean): this
+  toggleClass(name: string): this
+  hasClass(name: string): boolean
+  bindClass(name: string, fn: () => boolean): this
+}
+
+let nextViewId = 1
+
+/** @internal Base for typed plugin wrappers (QRScanner, CameraView — src/plugins/): subclass it,
+ *  pin the viewName/params, and layer typed methods over the raw `call`/`on` channel. Not a
+ *  public global — apps use the `NativeView(name)` factory below. */
+export class NativeViewElement extends Element<"native"> implements Presentable {
+  readonly viewName: string
+  readonly params: any
+  /** @internal stable per-instance handle for the viewCall channel + promotion identity. */
+  readonly _viewId: number
+  /** @internal event listeners by event name — the host invokes these (vlist pcl/psl convention)
+   *  or calls _emitViewEvent. */
+  readonly nvl: ChannelListeners = {}
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  constructor(viewName: string, params: any) {
+    super("native", {})
+    this.viewName = viewName
+    this.params = params
+    this._viewId = nextViewId++
+  }
+
+  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "native", viewName: this.viewName, params: this.params, viewId: this._viewId, _p: this }
+  }
+
+  open(options?: PresentOptions): void {
+    if (!_navSupported()) {
+      throw new Error(`NativeView("${this.viewName}") is not supported on this host (requires _creatorUI.openView)`)
+    }
+    _bumpNavEpoch()
+    _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    _setCurrent(this)
+  }
+  close(): void {
+    _bumpNavEpoch()
+    if (_navSupported()) _creatorUI.closeView!()
+    if (Presentable.current === this) _setCurrent(null)
+  }
+
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+
+  call(method: string, ...args: any[]): Promise<any> {
+    return _channelCall(
+      typeof _creatorUI !== "undefined" ? _creatorUI.viewCall : undefined,
+      `NativeView("${this.viewName}") is not supported on this host (requires _creatorUI.viewCall)`,
+      this._viewId, method, args)
+  }
+
+  on(event: string, callback: (data?: any) => void): this {
+    _channelOn(this.nvl, event, callback)
+    return this
+  }
+  off(event: string, callback: (data?: any) => void): this {
+    _channelOff(this.nvl, event, callback)
+    return this
+  }
+  /** @internal host entry: deliver a native event (payload as a JSON string, or omitted). */
+  _emitViewEvent(event: string, dataJson?: string): void {
+    _channelEmit(this.nvl, event, dataJson)
+  }
+}
+
+/**
+ * Create an instance of a host-registered platform view. `NativeView.isSupported(name)` reports
+ * whether this host registered a factory for it. Style via the chained `.style()`.
+ */
+// PURE IIFE (not a plain function + expando assignment) so an app that never uses NativeView
+// tree-shakes it away — top-level property assignments read as side effects to the bundler.
+export const NativeView: {
+  (name: string, params?: object): NativeView
+  /** Whether this host registered a `registerView` factory under `name`. */
+  isSupported(name: string): boolean
+} = /*#__PURE__*/ (() => {
+  const factory = (name: string, params: object = {}): NativeView =>
+    new NativeViewElement(name, params) as unknown as NativeView
+  factory.isSupported = (name: string): boolean =>
+    typeof _creatorUI !== "undefined" && typeof _creatorUI.isViewSupported === "function" && _creatorUI.isViewSupported(name)
+  return factory
+})()

package/runtime/sdk/ui/UI.ts

@@ -1,7 +1,7 @@
 // Renderer-side contract + per-renderer status (DOM / canvas-ui / desktop) for every component
 // below is tracked in packages/canvas-ui/COMPONENTS.md.
 export { UIButton, type UIButtonStyle } from './UIButton'
-export { UIScreen, type UIScreenStyle } from './UIScreen'
+export { UIScreen, type UIScreenStyle, type UIScrollableScreen } from './UIScreen'
 export { UISpacer, type UISpacerStyle } from './UISpacer'
 export { UIText, type UITextStyle } from './UIText'
 export { registerFont } from './fonts'
@@ -13,10 +13,15 @@ export { UIWidget, type UIWidgetStyle } from './UIWidget'
 
 export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
 export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
+export { UIScreenHost, type UIScreenHostStyle } from './UIScreenHost'
 
 export { UIVirtualizedList } from './UIVirtualizedList'
 
 export { Router } from './router'
+export { NativeView, type UINativeViewStyle } from './NativeView'
+// Presentable is both the interface and its runtime companion (Presentable.current).
+export { Presentable } from './presentable'
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from './presentable'
 
 // Internal: memoized map for reactive children — the chisel `reactiveUi` pass rewrites
 // `list.map(fn)` inside children bindings to `__uiMap(list, fn, slot)` calls.

package/runtime/sdk/ui/UIButton.ts

@@ -1,5 +1,5 @@
-import { ClickEvent, TouchStartEvent } from "../runtime/touch"
-import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType } from "../runtime/touch"
+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 Style, ContainerElement, type DrawableStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
@@ -7,12 +7,16 @@ export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { ri
 export interface UIButton {
   readonly type: "button",
 
-  style: Style<this, UIButtonStyle & { onPressed?: DrawableStyle & BaseStyle & { duration?: number } }>,
+  style: Style<this, UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   onClick(callback: (ev: ClickEventType<UIButton>) => void): this,
   onTouchStart(callback: (ev: TouchStartEventType<UIButton>) => void): this,
+  /** Fired when a finger is held on the button past the long-press threshold. The event can
+   *  `ev.track(...)` the rest of the gesture (like `onTouchStart`), so a hold can flow straight into
+   *  dragging the element. A handled long-press suppresses the click that would follow the release. */
+  onLongPress(callback: (ev: LongPressEventType<UIButton>) => void): this,
   isPressed(): boolean,
 
   append(...nodes: UINodeChild[]): this
@@ -35,6 +39,7 @@ class ButtonElement extends ContainerElement<"button"> {
 
   readonly clickListeners: any[] = []
   readonly touchStartListeners: any[] = []
+  readonly longPressListeners: any[] = []
 
   onClick (callback: any): this {
     this.clickListeners.push(callback)
@@ -65,6 +70,24 @@ class ButtonElement extends ContainerElement<"button"> {
     return null
   }
 
+  onLongPress (callback: any): this {
+    this.longPressListeners.push(callback)
+    return this
+  }
+  // Fired by the host when the finger is held past the long-press threshold. Returns null when
+  // nothing is listening — the host then lets the trailing click through as usual. Otherwise it
+  // returns an object whose presence tells the host to swallow that click, carrying the optional
+  // drag handler a listener registered via `ev.track(...)` for the host to drive the gesture.
+  _emitLongPress(pointerId: number, clientX: number, clientY: number): any {
+    if (this.longPressListeners.length === 0) return null
+    const longPressEvent = new LongPressEvent(clientX, clientY, pointerId)
+    longPressEvent.target = this
+    for (let callback of this.longPressListeners) {
+      callback(longPressEvent)
+    }
+    return { track: (longPressEvent as any)._trackHandler ?? null }
+  }
+
   isPressed(): boolean {
     if (!this._id) return false
     return _creatorUI.isButtonPressed(this._id)

package/runtime/sdk/ui/UIInput.ts

@@ -8,7 +8,7 @@ export interface UIInput {
 
   value: string
 
-  style: Style<this, UIInputStyle & { onFocused?: DrawableStyle & BaseStyle & { duration?: number } }>,
+  style: Style<this, UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
@@ -28,7 +28,7 @@ export interface UITextArea {
 
   value: string
 
-  style: Style<this, UIInputStyle & { onFocused?: DrawableStyle & BaseStyle & { duration?: number } }>,
+  style: Style<this, UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
   // styleV: StyleFn<this, UIInputStyle>,
   // styleH: StyleFn<this, UIInputStyle>,
 

package/runtime/sdk/ui/UINode.ts

@@ -245,13 +245,33 @@ export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T
 
 // User-defined style classes: any `$`-prefixed key in .style() declares a state block (like
 // onPressed, but with any name), toggled from code via setClass/toggleClass. `duration`/`delay`
-// make the swap transition.
+// make the swap transition. Instantiate with the node's own style `T` (see StyleFn below) — a class
+// block accepts everything the node's `.style()` does (e.g. `color` on text, layout on any node),
+// exactly like `onLandscape`/`onPortrait`. Narrowing it (it once was `DrawableStyle & BaseStyle`)
+// wrongly rejected valid props such as `$active: { color }`. Guarded by tests/ui-types.test.ts.
 export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number } }
 
-export type StyleFn <R, T extends object> = ((this: R, style: Reactive<T> & { onLandscape?: T, onPortait?: T } & ClassStyles<DrawableStyle & BaseStyle>) => R)
-export type Style <R, T extends object> = StyleFn<R,T> & T & { onLandscape?: T, onPortait?: T } & ClassStyles<DrawableStyle & BaseStyle>
+// NB: do NOT annotate `this: R` here. `this` is a parameter position, so it makes R contravariant,
+// which makes every node type INVARIANT in its own type params (and in `this`). That is what made
+// `UIScreen<false>` unassignable to `UIScreen<boolean>` / `HostedScreen`, and would block any
+// UINode subtype from being assignable to its base. Runtime `this` is already fixed by the
+// `styleFunction.bind(this)` in the `style` getter — the annotation bought nothing and cost variance.
+// R stays only in the (covariant) return, so `.style()` still returns the concrete node type for
+// chaining. Guarded by the type tests in tests/ui-types.test-d.ts.
+// Orientation state blocks — override props applied only in landscape / portrait (like a `$`-class,
+// keyed by device orientation instead of setClass). 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,
+}
+
+export type StyleFn <R, T extends object> = ((style: Reactive<T> & OrientationStyles<T> & ClassStyles<T>) => R)
+export type Style <R, T extends object> = StyleFn<R,T> & T & OrientationStyles<T> & ClassStyles<T>
 
-export type AnimateStyle<R, T extends object> = ((this: R, style: T & { duration?: number, delay?: number, layer?: number, commit?: boolean }) => R)
+export type AnimateStyle<R, T extends object> = ((style: T & { duration?: number, delay?: number, layer?: number, commit?: boolean }) => R)
 
 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

package/runtime/sdk/ui/UIScreen.ts

@@ -1,39 +1,56 @@
 import { TouchStartEvent } from "../runtime/touch"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
 import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type PaddingStyle, type ScrollStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & ScrollStyle & BaseStyle & ScrollStyle & { refreshControlColor?: Color }
 
-// Default to `false`: a bare `UIScreen` means the non-scrollable screen the `UIScreen(...)`
-// constructor returns, so `const s: UIScreen = UIScreen([...])` type-checks. The type is invariant
-// in `Scrollable` (the fluent `style()` puts `this` in a contravariant position), so a `boolean`
-// default wouldn't accept the constructor's `UIScreen<false>`. Opt into scrolling via
-// `.makeScrollable(): UIScreen<true>`; write `UIScreen<boolean>` explicitly when you need the union.
-export interface UIScreen <Scrollable extends boolean = false> {
+// A screen — the root the router/host mounts, sized to its slot. Two flavours share one contract: a
+// plain `UIScreen`, and a `UIScrollableScreen` (a screen that also scrolls). `makeScrollable()`
+// upgrades a plain screen to the scrollable one, where `onScroll`/`onOverscroll`/`onRefresh` live —
+// they mean nothing without scrolling. `UIScrollableScreen extends UIScreen`, so anywhere a
+// `UIScreen` / `HostedScreen` is accepted, a scrollable one works too.
+//
+// This is a subtype split, NOT a `UIScreen<Scrollable>` generic: a generic can't work while `style`
+// is `Style<this,…>`, because `this` is then contravariant and the type becomes invariant in its own
+// params — that was the old `UIScreen<false>`-not-assignable-to-`HostedScreen` bug. See the StyleFn
+// note in UINode.ts; the contract is pinned by tests/ui-types.test.ts.
+export interface UIScreen {
   readonly type: "screen",
-  scrollable: Scrollable,
+  readonly scrollable: boolean,
   style: Style<this, UIScreenStyle>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
-  open(): void,
+  /** 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,
   close(): void
 
   append(...nodes: UINodeChild[]): this
   insert(index: number, ...nodes: UINodeChild[]): this
   remove(...nodes: UINodeChild[]): this
   setContent(nodes: UINodeChild[] | ChildrenFn): this
-  
+
   readonly children: UINodeChild[],
 
-  makeScrollable(): UIScreen<true>,
-  onScroll: Scrollable extends true? (callback: (scrollPosition: number) => void) => void: never,
-  onOverscroll: Scrollable extends true? (callback: (scrollPosition: number) => void) => void: never,
+  /** Upgrade this screen into a scroll view, unlocking `onScroll`/`onOverscroll`/`onRefresh`. */
+  makeScrollable(): UIScrollableScreen,
   onBackPressed(callback: () => void): this
-  onRefresh: Scrollable extends true? ((callback: () => void | Promise<void>) => this): never,
 
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
 
+  /**
+   * Keep this screen's built native tree alive when a UIScreenHost detaches it (replace / remove /
+   * pop): instead of being destroyed, its views + layout + live state (scroll position, input text)
+   * are retained, so re-hosting the SAME screen object restores it in place rather than rebuilding.
+   * `onClose`/`onOpen` still fire on detach/re-attach. You own the lifetime — a kept tree is freed
+   * only by `dispose()` or when the project unloads. (Native-only today; web rebuilds.)
+   */
+  keepAlive(enabled?: boolean): this
+  /** Free a `keepAlive()` screen's retained tree now. No-op unless it's currently detached-and-kept. */
+  dispose(): this
+
   onLayout(onLayout: OnLayoutCallback): this
 
   setClass(name: string, enabled: boolean): this
@@ -41,16 +58,46 @@ export interface UIScreen <Scrollable extends boolean = false> {
   hasClass(name: string): boolean
   bindClass(name: string, fn: () => boolean): this
 
-  onTouchStart(callback: (ev: TouchStartEvent<UIScreen<boolean>>) => void): this,
+  onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
+}
+
+/**
+ * A `UIScreen` in scroll mode — what `makeScrollable()` returns. Adds the scroll lifecycle that a
+ * plain screen doesn't carry. A subtype of `UIScreen`, so it's accepted anywhere a screen /
+ * `HostedScreen` is (router pages, `UIScreenHost`, `UITabs`).
+ */
+export interface UIScrollableScreen extends UIScreen {
+  readonly scrollable: true,
+  /** Fires as the content scrolls; the offset is logical px from the start edge. Chainable. */
+  onScroll(callback: (scrollPosition: number) => void): this,
+  /** Fires while the user drags past an edge (rubber-band). Chainable. */
+  onOverscroll(callback: (scrollPosition: number) => void): this,
+  /** Pull-to-refresh: the spinner stays until the returned promise resolves. Chainable. */
+  onRefresh(callback: () => void | Promise<void>): this,
+  /** Already scrollable — returns itself. */
+  makeScrollable(): UIScrollableScreen,
 }
 
 export class ScreenElement extends ContainerElement<"screen"> {
-  scrollable = false as const
-  open(): void {
-    _creatorUI.openScreen(this) 
+  scrollable = false
+  open(options?: PresentOptions): void {
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.openView!(this, options?.transition ?? "none")
+    } else {
+      // Legacy host: no destination navigation — transition is dropped.
+      _creatorUI.openScreen(this)
+    }
+    _setCurrent(this as any)
   }
   close(): void {
-    _creatorUI.closeScreen()
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.closeView!()
+    } else {
+      _creatorUI.closeScreen()
+    }
+    if (Presentable.current === (this as any)) _setCurrent(null)
   }
   protected ol: (() => void)[] = []
   onOpen(callback: () => void): this {
@@ -62,6 +109,18 @@ export class ScreenElement extends ContainerElement<"screen"> {
     this.cl.push(callback)
     return this
   }
+  // Read by the host at detach time (a plain flag on the node, like _interactive).
+  _keepAlive = false
+  keepAlive(enabled = true): this {
+    this._keepAlive = enabled
+    return this
+  }
+  dispose(): this {
+    // Rides the generic command channel (no dedicated bridge). No-op while _id is 0 (never mounted)
+    // or when the tree isn't currently detached-and-kept — the host ignores it then.
+    if (this._id !== 0) _creatorUI.command(this, "disposeKeepAlive")
+    return this
+  }
   readonly touchStartListeners: any[] = []
   _interactive = false
   onTouchStart (callback: any): this {
@@ -80,8 +139,8 @@ export class ScreenElement extends ContainerElement<"screen"> {
     }
     return null
   }
-  makeScrollable(): UIScreen<true> {
-    this.scrollable = true as any
+  makeScrollable(): UIScrollableScreen {
+    this.scrollable = true
 
     Object.assign(this, {
       sl: [] as any[],
@@ -100,24 +159,22 @@ export class ScreenElement extends ContainerElement<"screen"> {
       }
     })
 
-    return this as any as UIScreen<true>
+    return this as any as UIScrollableScreen
   }
   _backButtonCallback?: () => void
   onBackPressed(callback: any): this {
     this._backButtonCallback = callback
     return this
   }
+  // Set by the onRefresh method that makeScrollable() grafts on; read by the host at mount.
   declare _refreshCallback: any
-  declare onRefresh: never
-  declare onScroll: never
-  declare onOverscroll: never
 }
 
-export function UIScreen(): UIScreen<false>;
-export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen<false>;
-export function UIScreen(style: UIScreenStyle): UIScreen<false>;
-export function UIScreen(style: UIScreenStyle, children: UINodeChild[]): UIScreen<false>;
-export function UIScreen(...args: [] | [UINodeChild[] | ChildrenFn | UIScreenStyle] | [UIScreenStyle, children: UINodeChild[] | ChildrenFn]): UIScreen<false> {
+export function UIScreen(): UIScreen;
+export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen;
+export function UIScreen(style: UIScreenStyle): UIScreen;
+export function UIScreen(style: UIScreenStyle, children: UINodeChild[]): UIScreen;
+export function UIScreen(...args: [] | [UINodeChild[] | ChildrenFn | UIScreenStyle] | [UIScreenStyle, children: UINodeChild[] | ChildrenFn]): UIScreen {
   if (args.length === 0) {
     return new ScreenElement("screen", {}, [])
   } else if (args.length === 1) {