lecodes-cli 0.8.2 → 0.9.1

package/package.json

@@ -1,42 +1,38 @@
 {
   "name": "lecodes-cli",
-  "version": "0.8.2",
-  "description": "Clone, edit and push LeCodes projects from your machine.",
-  "type": "module",
-  "license": "MIT",
-  "keywords": [
-    "lecodes",
-    "cli"
-  ],
+  "version": "0.9.1",
+  "dependencies": {
+    "@letary/chisel": "^0.5.1"
+  },
+  "devDependencies": {
+    "lecodes-design": "workspace:*",
+    "lecodes-renderer": "workspace:*",
+    "qrcode-terminal": "^0.12.0",
+    "lecodes-3d-editor": "workspace:*",
+    "sdk": "workspace:*"
+  },
+  "peerDependencies": {
+    "lecodes-design": "^0.3.2",
+    "lecodes-renderer": "^0.7.1",
+    "lecodes-3d-editor": "^0.1.0"
+  },
   "bin": {
     "lecodes": "dist/index.js"
   },
+  "description": "Clone, edit and push LeCodes projects from your machine.",
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "dist",
     "runtime",
     "README.md"
   ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "icon": "bun scripts/make-icon.ts",
-    "vendor-runtime": "bun scripts/vendor-runtime.ts",
-    "sync-peers": "bun scripts/sync-peer-versions.ts",
-    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --banner=\"#!/usr/bin/env node\"",
-    "build:bin": "bun scripts/build-bin.ts",
-    "typecheck": "tsc --noEmit",
-    "dev": "bun run src/index.ts",
-    "prepublishOnly": "bun run sync-peers && bun run build"
-  },
-  "dependencies": {
-    "@letary/chisel": "^0.4.1"
-  },
-  "peerDependencies": {
-    "lecodes-design": "^0.3.2",
-    "lecodes-renderer": "^0.6.2",
-    "lecodes-3d-editor": "^0.1.0"
-  },
+  "keywords": [
+    "lecodes",
+    "cli"
+  ],
+  "license": "MIT",
   "peerDependenciesMeta": {
     "lecodes-design": {
       "optional": true
@@ -48,11 +44,15 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "lecodes-design": "workspace:*",
-    "lecodes-renderer": "workspace:*",
-    "qrcode-terminal": "^0.12.0",
-    "lecodes-3d-editor": "workspace:*",
-    "sdk": "workspace:*"
-  }
+  "scripts": {
+    "icon": "bun scripts/make-icon.ts",
+    "vendor-runtime": "bun scripts/vendor-runtime.ts",
+    "sync-peers": "bun scripts/sync-peer-versions.ts",
+    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --banner=\"#!/usr/bin/env node\"",
+    "build:bin": "bun scripts/build-bin.ts",
+    "typecheck": "tsc --noEmit",
+    "dev": "bun run src/index.ts",
+    "prepublishOnly": "bun run sync-peers && bun run build"
+  },
+  "type": "module"
 }

package/runtime/sdk/inject.ts

@@ -54,7 +54,7 @@ export { Texture2D } from "./g2/Texture2D"
 
 // ---- UI (creator-ui) ----
 export {
-  UIScreen, type UIScreenStyle, type UIScrollableScreen,
+  UIScreen, type UIScreenStyle,
   UIRow, UIColumn, UIBox, type UIContainerStyle,
   UIText, type UITextStyle,
   UIButton, type UIButtonStyle,
@@ -65,6 +65,7 @@ export {
   UIPager, type UIPagerStyle,
   UIWidget, type UIWidgetStyle,
   UIModal, type UIModalStyle,
+  UIBottomSheet, type UIBottomSheetStyle,
   UIPopover, type UIPopoverStyle,
   UISpacer, type UISpacerStyle,
   UIVirtualizedList,

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, type UIScrollableScreen } from './UIScreen'
+export { UIScreen, type UIScreenStyle } from './UIScreen'
 export { UISpacer, type UISpacerStyle } from './UISpacer'
 export { UIText, type UITextStyle } from './UIText'
 export { registerFont } from './fonts'
@@ -11,6 +11,7 @@ export { UIInput, UITextArea, type UIInputStyle } from './UIInput'
 
 export { UIWidget, type UIWidgetStyle } from './UIWidget'
 export { UIModal, type UIModalStyle } from './UIModal'
+export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet'
 export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover'
 
 export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'

package/runtime/sdk/ui/UIBottomSheet.ts

@@ -0,0 +1,149 @@
+import { ModalElement, type UIModalStyle } from "./UIModal"
+import type { UIWidget } from "./UIWidget"
+import type { ChildrenFn, UINodeChild } from "./UINode"
+
+export type UIBottomSheetStyle = UIModalStyle
+
+const SHEET_ANIM_MS = 250
+
+/**
+ * A bottom sheet: a `UIWidget` pinned to the bottom edge. By default it is **content-sized** —
+ * as tall as what's inside (capped at the screen), one position, drag down to dismiss (the
+ * action-sheet shape). Call `detents()` for the multi-position map-app model instead: snap
+ * positions the user drags between on native hosts. Ships as a widget node on the wire (no new
+ * node type — docs/bottom-sheet-plan.md): hosts without sheet support show a static bottom panel.
+ *
+ * With detents, content lays out at the HIGHEST detent's size; lower detents show the top
+ * slice. The scrim, `onOpen`/`onClose`, back-button and scrim-tap dismissal all come from the
+ * modal machinery.
+ *
+ * ```ts
+ * const actions = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [rows])   // content-sized
+ *
+ * const mapSheet = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [results])
+ *   .detents([0.3, 0.6, 1])
+ *   .onDetentChange(i => map.setPadding(...))
+ * ```
+ */
+export interface UIBottomSheet extends UIWidget {
+  /** Snap positions as fractions of screen height, ascending. Also sizes the sheet: its box is
+   *  the last (highest) detent; set this before `show()`. Without a `detents()` call the sheet
+   *  is CONTENT-SIZED instead — one position, as tall as its children (up to the screen). */
+  detents(list: number[]): this,
+  /** Snap to a detent (animated). Clamped to the detents range; fires `onDetentChange`. */
+  setDetent(index: number): void,
+  /** Current detent index. */
+  readonly detent: number,
+  /** Fires on every settle: a finger snap on native hosts, or a `setDetent()` call. */
+  onDetentChange(callback: (index: number) => void): this,
+
+  /** Mount and slide in to the current detent. No-op while already open. */
+  show(): void,
+  /** Slide out, fade the scrim, then unmount. No-op while closed. */
+  hide(): void,
+  /** True from `show()` until `hide()` starts. */
+  readonly isOpen: boolean,
+
+  /** Called when `show()` mounts the sheet. */
+  onOpen(callback: () => void): this,
+  /** Called when the sheet starts closing — scrim tap, back button, drag-dismiss, or `hide()`. */
+  onClose(callback: () => void): this,
+  /** `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 {
+  _detents: number[] = [1]
+  _detent = 0
+  /** Host-facing (the `sl`/`otl` contract): hosts read `dtl` at mount and call it with the
+   *  settled detent index for GESTURE settles only — programmatic `setDetent` fires JS-side.
+   *  `-1` = dragged below the lowest detent while dismissible. */
+  readonly dtl: any[] = []
+  readonly _detentListeners: ((index: number) => void)[] = []
+
+  constructor(style: UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn) {
+    // No default height: an absolute node with only bottom set is CONTENT-sized by yoga. A
+    // single detent makes the geometry height-independent on every host (shown = offset 0,
+    // hidden = own height), so content mode needs no host support beyond the detents path.
+    super({ left: 0, right: 0, bottom: 0, maxHeight: "100%", sheetDetents: "1", ...style } as UIModalStyle, children)
+    // The inherited show/hide pose animates ONLY the scrim: sheet geometry rides the
+    // sheetDetent style key, never the pose system.
+    this._transition = { duration: SHEET_ANIM_MS }
+    this.dtl.push((index: number) => {
+      if (index < 0) { this.hide(); return }
+      this._detent = index
+      for (const callback of this._detentListeners) callback(index)
+    })
+  }
+
+  detents(list: number[]): this {
+    const sorted = [...list].filter(d => d > 0).sort((a, b) => a - b)
+    if (sorted.length === 0) return this
+    this._detents = sorted
+    if (this._detent >= sorted.length) this._detent = sorted.length - 1
+    this.style({
+      height: `${sorted[sorted.length - 1] * 100}%`,
+      sheetDetents: sorted.join(","),
+    } as UIBottomSheetStyle)
+    return this
+  }
+
+  get detent(): number {
+    return this._detent
+  }
+
+  setDetent(index: number): void {
+    const clamped = Math.max(0, Math.min(Math.floor(index), this._detents.length - 1))
+    this._detent = clamped
+    if (!this._open) return                     // applied by the next show()
+    this.style({ sheetDetent: clamped } as UIBottomSheetStyle)
+    for (const callback of this._detentListeners) callback(clamped)
+  }
+
+  onDetentChange(callback: (index: number) => void): this {
+    this._detentListeners.push(callback)
+    return this
+  }
+
+  show(): void {
+    if (this._open) return
+    // Before the mount, so the built node carries the target and hosts play the entrance to it.
+    this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
+    super.show()
+  }
+
+  hide(): void {
+    if (!this._open) return
+    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; unmount follows
+    super.hide()
+  }
+
+  dismissible(enabled: boolean): this {
+    super.dismissible(enabled)
+    this.style({ sheetDismissible: enabled ? 1 : 0 } as UIBottomSheetStyle)
+    return this
+  }
+}
+
+export function UIBottomSheet(): UIBottomSheet;
+export function UIBottomSheet(children: UINodeChild[] | ChildrenFn): UIBottomSheet;
+export function UIBottomSheet(style: UIBottomSheetStyle): UIBottomSheet;
+export function UIBottomSheet(style: UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn): UIBottomSheet;
+export function UIBottomSheet(...args: [] | [UINodeChild[] | ChildrenFn | UIBottomSheetStyle] | [UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn]): UIBottomSheet {
+  if (args.length === 0) {
+    return new BottomSheetElement({}, [])
+  } else if (args.length === 1) {
+    if (Array.isArray(args[0]) || typeof args[0] === "function") {
+      return new BottomSheetElement({}, args[0])
+    } else {
+      return new BottomSheetElement(args[0], [])
+    }
+  } else {
+    return new BottomSheetElement(args[0], args[1])
+  }
+}

package/runtime/sdk/ui/UIInput.ts

@@ -6,8 +6,14 @@ type InputStyle = {
   /**
    * Keyboard hint, NOT a validator — `number` does not block pasted letters; validate in your own
    * onChange. The phone-pad value is `phone` (LeCodes has no `tel`).
+   *
+   * `date` / `time` are PICKER kinds, not keyboards: the host opens its native picker in the
+   * keyboard slot (iOS wheels / browser calendar) and free typing is disabled. `value` is always
+   * canonical — `YYYY-MM-DD` for `date`, `HH:MM` (24h) for `time` — while the field displays a
+   * localized string; set/compare values in the canonical form only.
    */
-  type?: "text" | "password" | "search" | "phone" | "email" | "number" | "decimal" | "url",
+  type?: "text" | "password" | "search" | "phone" | "email" | "number" | "decimal" | "url"
+    | "date" | "time",
   /**
    * What the layout does while the keyboard is up (decided by the FOCUSED input). `true` (default):
    * the layout viewport shrinks to the area above the keyboard — one relayout. `false`: the keyboard
@@ -16,6 +22,15 @@ type InputStyle = {
    * reflow is worse than overlap.
    */
   keyboardShrink?: boolean,
+  /**
+   * Whether a tap on a non-interactive area dismisses the keyboard while THIS input is focused
+   * (like `keyboardShrink`, the policy of the focused input). `true` (default): tapping dead
+   * space blurs — but a tap on a button or another input NEVER dismisses; the control acts and
+   * focus stays. `false`: taps never dismiss — the chat-composer policy. `blur()`, the return
+   * key (per `enterKey`), and the platform's own gestures (iOS drag-down over the keyboard)
+   * still work in both modes. Scrolling never dismisses the keyboard on any setting.
+   */
+  keyboardDismiss?: boolean,
   /** Hard cap on the text length — enforced by the host while typing/pasting. */
   maxLength?: number,
   /** Auto-capitalization hint; omitted = platform default. */
@@ -148,6 +163,14 @@ export function UIInput(style?: UIInputStyle): UIInput {
   return new InputElement("input", { minHeight: "1.2em", ...style })
 }
 
+/**
+ * Multi-line text field. Enter is a newline (submit lives on UIInput / your own button).
+ *
+ * Auto-grow: with no explicit `height` the field measures its own content and grows line by
+ * line — clamp the range with `minHeight` / `maxHeight` (past `maxHeight` the text scrolls
+ * inside). A fixed `height` opts out and scrolls internally from the start. Chat composers are
+ * the canonical use: a bare textarea in a padded pill, `maxHeight` at ~5 lines.
+ */
 export function UITextArea(): UITextArea;
 export function UITextArea(style: UIInputStyle): UITextArea;
 export function UITextArea(style?: UIInputStyle): UITextArea {

package/runtime/sdk/ui/UINode.ts

@@ -68,11 +68,6 @@ export type ContainerStyle = {
   flexWrap?: "nowrap" | "wrap" | "wrap-reverse"
 }
 
-export type ScrollStyle = {
-  scrollX?: "auto" | "all" | "none",
-  scrollY?: "auto" | "all" | "none"
-}
-
 type UIValue = number |
   `${number}px` |
   `${number}vw` |
@@ -130,6 +125,8 @@ export type PositionStyle = {
   left?: UIValue | `${number}%` | 'safe-left' | 'comfort-left',
   bottom?: UIValue | `${number}%` | 'safe-bottom' | 'comfort-bottom',
   right?: UIValue | `${number}%` | 'safe-right' | 'comfort-right',
+  /** Shorthand for all four edges at one value. A longhand (`top`, `left`, …) overrides it. */
+  inset?: UIValue | `${number}%` | "auto",
   width?: UIValue | `${number}%` | "auto",
   height?: UIValue | `${number}%` | "auto",
   maxWidth?: UIValue | `${number}%` | "auto",
@@ -158,7 +155,11 @@ export type TextStyle =  {
   fontStyle?: "normal" | "italic",
   color?: Color,
   textDecoration?: "underline" | "line-through" | "none",
-  letterSpacing?: UIValue
+  letterSpacing?: UIValue,
+  /** Cap the text at N lines; the box is measured to the clamped height. 0 / omitted = unbounded. */
+  lineClamp?: number,
+  /** How a clamped line ends. Only meaningful together with `lineClamp`. Default "ellipsis". */
+  textOverflow?: "ellipsis" | "clip"
 }
 
 // Pulls function-valued props out of `style` (mutating it — they must never reach the host bridge)

package/runtime/sdk/ui/UIPager.ts

@@ -1,4 +1,5 @@
-import { ContainerElement, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style } from "./UINode"
+import { ContainerElement, type AnimateStyle, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style, type UINodeChild } from "./UINode"
+import { disposeBinding } from "../core/signals"
 import type { UIScreen } from "./UIScreen"
 
 // UIPager — the system's ONE screen-navigation element (docs/pager-component-plan.md): sibling
@@ -46,6 +47,11 @@ export interface UIPager {
   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;
+   *  screens that were already tabs keep their state. Pass a function for reactive tabs. */
+  setContent(tabs: UIScreen[] | (() => UIScreen[])): this,
+
   /** Switch to tab `index`. **Instant by default** — the tab-bar convention (tabs are parallel
    *  modes, not neighbors); pass `animated: true` for the direction-aware slide of top-tab /
    *  pager UIs. Out-of-range and same-index calls are no-ops. Tabs keep their stacks: selecting
@@ -182,6 +188,54 @@ export class PagerElement extends ContainerElement<"pager"> {
     return this
   }
 
+  // ── Children ARE the tabs ──────────────────────────────────────────────────────────────────
+  // Every inherited container mutation would send a generic setContent/insertNode/removeNode wire
+  // op, and a host must never run those on a pager: its children are page ROOTS the host owns
+  // (each laid out independently at the pager's box), not yoga children — the generic path frees
+  // the live pages and rebuilds them as ordinary children stacked on the first tab. So each one is
+  // overridden to mutate the element first (children, `_lens`, `_index`) and then notify over the
+  // same command channel every other pager op uses, where the host reconciles against the node.
+  //
+  // Content set this way is always one screen per tab: a per-tab STACK only ever grows through
+  // push/replace, so `_lens` resets to all-ones here.
+  private _rebuild(children: any[]): this {
+    const tabs = children.filter(Boolean)
+    const prevIndex = this._index
+    this.children.length = 0
+    this.children.push(...tabs)
+    this._lens = tabs.map(() => 1)
+    if (this._index >= tabs.length) this._index = Math.max(0, tabs.length - 1)
+    for (const s of tabs) this._track(s)
+    if (this._id !== 0) _creatorUI.command(this, "content")
+    if (this._index !== prevIndex) this._emitSelect()
+    this._emitChange()
+    return this
+  }
+
+  setContent(children: UINodeChild[] | ChildrenFn): this {
+    if (typeof children === "function") {
+      this._bindChildren(children)   // reactive children land in _reconcile below
+      return this
+    }
+    disposeBinding(this, "#children")   // static content overrides a reactive binding
+    return this._rebuild(children as any[])
+  }
+  append(...nodes: UINodeChild[]): this {
+    return this._rebuild([...this.children, ...nodes])
+  }
+  insert(index: number, ...nodes: UINodeChild[]): this {
+    const next = this.children.slice()
+    next.splice(index, 0, ...(nodes as any[]))
+    return this._rebuild(next)
+  }
+  remove(...nodesToDelete: UIScreen[]): this {
+    const drop = new Set<any>(nodesToDelete)
+    return this._rebuild(this.children.filter((c: any) => !drop.has(c)))
+  }
+  _reconcile(next: UINodeChild[]): void {
+    this._rebuild(next as any[])
+  }
+
   // Host-driven tab change (committed swipe): the native pager already moved — sync the logical
   // index + fire onSelect. Named `_*` so chisel keeps it (hosts call it).
   _hostDidSelect(index: number): void {
@@ -214,6 +268,7 @@ export class PagerElement extends ContainerElement<"pager"> {
   // top, this pager is active. The hook reads screen._pagerOwner LIVE (not a captured `this`), so
   // re-homing a screen into another pager activates the right one.
   private _track(screen: any): void {
+    console.log("_track()")
     screen._pagerOwner = this
     if (!screen._pagerHooked) {
       screen._pagerHooked = true
@@ -222,13 +277,18 @@ export class PagerElement extends ContainerElement<"pager"> {
     }
   }
   _activate(): void {
-    if (++this._openCount === 1 && _activeStack.indexOf(this) < 0) _activeStack.push(this)
+    console.log("openCount: " + this._openCount)
+    if (++this._openCount === 1 && _activeStack.indexOf(this) < 0) {
+      console.log("activate")
+      _activeStack.push(this)
+    }
   }
   _deactivate(): void {
     if (--this._openCount <= 0) {
       this._openCount = 0
       const i = _activeStack.indexOf(this)
       if (i >= 0) _activeStack.splice(i, 1)
+      console.log(`Deactivate. Curent stack is ${_activeStack.length}`)
     }
   }
 }
@@ -275,7 +335,7 @@ function pagerFactory(...args: any[]): UIPager {
  * tabs, a single screen becomes a plain stack. Navigate within it via `pager.push/pop/replace`
  * (per-tab) and `pager.select(i)` (between tabs), or from any child screen via the ambient
  * `UIPager.push` / `UIPager.pop` / `UIPager.current`. Pages are full `UIScreen`s (own
- * `onOpen`/`onClose`, `makeScrollable()`); give the pager `flexGrow: 1` or a size so it doesn't
+ * `onOpen`/`onClose`); give the pager `flexGrow: 1` or a size so it doesn't
  * collapse. `Router` stays the way to open a destination ON TOP of the pager.
  */
 export const UIPager = pagerFactory as unknown as UIPagerConstructor
@@ -289,6 +349,14 @@ const _resolveCurrent = (): UIPager | null => {
   return cur as unknown as UIPager
 }
 
+// The ambient statics. These are top-level statements in a `sideEffects: false` module, so they only
+// survive bundling because chisel treats a statement that *mutates a binding this module declares*
+// as part of that binding's declaration (`ItemKind::AttachedTo`, chisel >= 0.4.2) — kept iff
+// `UIPager` is reached, shaken away with it otherwise. Under chisel <= 0.4.1 they were dropped
+// outright and `UIPager.push` arrived as `undefined` at runtime, in bundled builds only; don't lower
+// the pinned `@letary/chisel` back past 0.4.2. Covered by sdk/tests/compile.test.ts.
+// `Object.defineProperty` for `current`, not `Object.assign({ get current() {} })` — Object.assign
+// *invokes* the getter and copies the resulting value, freezing it at null forever.
 Object.defineProperty(UIPager, "current", {
   get: () => (_activeStack[_activeStack.length - 1] ?? null) as unknown as UIPager | null,
 })

package/runtime/sdk/ui/UIScreen.ts

@@ -1,22 +1,16 @@
 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 BoundingClientRect, type PaddingStyle, type ScrollStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { ContainerElement, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
 
-export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & ScrollStyle & BaseStyle & ScrollStyle & { refreshControlColor?: Color }
+export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
-// 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` is accepted (router pages, `UIPager`), 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-`UIScreen<boolean>` bug. See the StyleFn
-// note in UINode.ts; the contract is pinned by tests/ui-types.test.ts.
+// A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
+// 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`) — see docs/scroll-forms-plan.md (the former
+// `makeScrollable()` screen mode was removed 2026-07-22).
 export interface UIScreen {
   readonly type: "screen",
-  readonly scrollable: boolean,
   style: Style<this, UIScreenStyle>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
@@ -33,8 +27,6 @@ export interface UIScreen {
 
   readonly children: UINodeChild[],
 
-  /** Upgrade this screen into a scroll view, unlocking `onScroll`/`onOverscroll`/`onRefresh`. */
-  makeScrollable(): UIScrollableScreen,
   onBackPressed(callback: () => void): this
 
   onOpen(callback: () => void): this
@@ -62,25 +54,7 @@ export interface UIScreen {
   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 is
- * (router pages, `UIPager`).
- */
-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
   open(options?: PresentOptions): void {
     _bumpNavEpoch()
     if (_navSupported()) {
@@ -140,35 +114,11 @@ export class ScreenElement extends ContainerElement<"screen"> {
     }
     return null
   }
-  makeScrollable(): UIScrollableScreen {
-    this.scrollable = true
-
-    Object.assign(this, {
-      sl: [] as any[],
-      osl: [] as any[],
-      onScroll(callback: any) {
-        this.sl.push(callback)
-        return this
-      },
-      onOverscroll(callback: any) {
-        this.osl.push(callback)
-        return this
-      },
-      onRefresh(callback: any) {
-        (this as any)._refreshCallback = callback
-        return this 
-      }
-    })
-
-    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
 }
 
 export function UIScreen(): UIScreen;

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,7 +1,16 @@
 import type { UIContainerStyle } from "./UIContainer"
-import { type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, ContainerElement } from "./UINode"
+import { type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type Color, ContainerElement } from "./UINode"
 
-export type ScrollStyle = { showScrollbar?: boolean, overscrollMode?: "none" | "absorb" | "default" }
+// refreshControlColor tints the native pull-to-refresh spinner (pairs with onRefresh).
+// keyboardDismissMode: how a scroll gesture in THIS scrollable dismisses the keyboard.
+// "interactive" (default) — dragging over the keyboard slides it away (chat composer feel);
+// "scroll" — any drag dismisses the moment it starts (search-results feel);
+// "none" — scrolling never dismisses (tap-outside policy still applies).
+// snap: paging — when the drag ends, rest on a direct child's boundary along the scroll axis
+// (a carousel/pager is a horizontal scrollable of full-width children + snap:"start"). The value
+// picks where the child sits in the viewport; "none" (default) is free scrolling. Snap targets
+// are the children themselves, so item widths can differ (card-carousel-with-peek).
+export type ScrollStyle = { showScrollbar?: boolean, overscrollMode?: "none" | "absorb" | "default", refreshControlColor?: Color, keyboardDismissMode?: "interactive" | "scroll" | "none", snap?: "none" | "start" | "center" | "end" }
 
 export type UIScrollableStyle = UIContainerStyle & ScrollStyle & { scrollDirection?: "horizontal" | "vertical" }
 
@@ -27,6 +36,9 @@ export interface UIScrollable {
   onScroll(callback: (scrollPosition: number) => void): UIScrollable,
   onScrollRelease(callback: () => void): UIScrollable,
   onOverscroll(callback: (delta: number) => void): UIScrollable
+  /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
+   *  node mounts (hosts read it at creation). Vertical only; native hosts — no-op on web. */
+  onRefresh(callback: () => void | Promise<void>): UIScrollable
 
   readonly children: UINodeChild[]
 }
@@ -55,6 +67,13 @@ class ScrollableElement extends ContainerElement<"scrollable"> {
     this.osl.push(callback)
     return this
   }
+
+  // Read by the host at mount (same contract the scrollable screen had before 2026-07-22).
+  declare _refreshCallback: any
+  onRefresh (callback: any): this {
+    this._refreshCallback = callback
+    return this
+  }
 }
 
 export function UIScrollable(): UIScrollable
@@ -62,15 +81,17 @@ export function UIScrollable(children: UINodeChild[] | ChildrenFn): UIScrollable
 export function UIScrollable(style: UIScrollableStyle): UIScrollable
 export function UIScrollable(style: UIScrollableStyle, children: UINodeChild[]): UIScrollable
 export function UIScrollable(...args: [] | [UINodeChild[] | ChildrenFn | UIScrollableStyle] | [UIScrollableStyle, children: UINodeChild[] | ChildrenFn]): UIScrollable {
+  // flexShrink: 1 default (SDK-owned, like UIRow's flexDirection): without it a scrollable in a
+  // flex parent grows to its content height and overflows instead of scrolling.
   if (args.length === 0) {
-    return new ScrollableElement("scrollable", {}, [])
+    return new ScrollableElement("scrollable", { flexShrink: 1 }, [])
   } else if (args.length === 1) {
     if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ScrollableElement("scrollable", {}, args[0])
+      return new ScrollableElement("scrollable", { flexShrink: 1 }, args[0])
     } else {
-      return new ScrollableElement("scrollable", args[0], [])
+      return new ScrollableElement("scrollable", { flexShrink: 1, ...args[0] }, [])
     }
   } else {
-    return new ScrollableElement("scrollable", args[0], args[1])
+    return new ScrollableElement("scrollable", { flexShrink: 1, ...args[0] }, args[1])
   }
 }