@solidrt/core 0.0.41 → 0.0.43

package/AGENTS.md

@@ -24,6 +24,15 @@ hardcode desktop pixels.
   (<600), `medium` (600-840), `expanded` (>=840). Drive column counts / layout
   switches off it (see the responsive-grid example).
 
+Exception - fixed-aspect content. For content with fixed internal geometry
+(diagrams, slides, dashboards, games, emulators), do not branch on window size
+at all: author everything in one design space and let `viewBox` fit it.
+`<view flex={1} viewBox={[1280, 800]}>` uniformly scales and centers the
+children (letterboxed), pointer events on them arrive in design coordinates,
+and the same code runs unchanged from a desktop window to a phone. Reach for
+`windowSizeClass` branching only when the layout genuinely reflows across form
+factors.
+
 `env` and `capabilities` (both exported from `@solidrt/core`) are the two
 objects that expose this. They are plain objects with REACTIVE GETTERS, not
 functions - read them as `capabilities.windowSizeClass`, `env.displayScale`
@@ -104,10 +113,11 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   Outlines: `drawStyle="stroke"` (or "stroke-and-fill") plus `strokeWidth`.
   Corner radius on draw primitives: `radius` (number or [tl, tr, br, bl]).
 
-- Registered JSX intrinsics: `window`, `view`, `text`, `rect`, `oval`, `path`,
-  `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`, `d-oval`,
-  `d-path`, `d-texture`, `d-text`. NOTE: `<line>` has a LineProps type but is
-  NOT a registered intrinsic - it will not typecheck.
+- Registered JSX intrinsics: `window`, `view`, `text`, `rect`, `oval`, `line`,
+  `path`, `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`,
+  `d-oval`, `d-line`, `d-path`, `d-texture`, `d-text`. Line endpoints
+  (`x1`/`y1`/`x2`/`y2`) exist only on `d-line`; a laid-out `<line>` has no
+  endpoint props and spans its layout box corner to corner.
 
 - Plain vs `d-` variant (the `d-` prefix means "detached" - detached from the
   layout engine, Taffy): a plain element (e.g. `rect`) is `RectProps &
@@ -119,6 +129,13 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   directly-positioned, often-animating elements (e.g. hundreds of balls), `d-`
   skips the per-element layout that plain elements would incur.
 
+- Transform origin on a `d-view`: with `originX`/`originY` unset, scale/rotate
+  pivot at the view's local (0,0) - the origin its children's coordinates are
+  authored against - not at a box center (a laid-out view pivots at its own
+  box center; a d-view has no box). To scale a detached group around its
+  content's center, set the origin explicitly in pixels, e.g.
+  `originX={100} originY={50}` for content drawn in a 200x100 local space.
+
 - Layout-affecting vs not (this matters for per-frame work). Props fall in three
   buckets, split by where they take effect:
   - `LayoutProps` - width/height, min/max sizes, margin, padding, `position` and
@@ -137,10 +154,25 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   `position:absolute` at `left:0,top:0`, or just let normal flow place it) and
   then translate it with `x`/`y`.
 
+- JSX text children collapse whitespace (ordinary JSX semantics): runs of
+  spaces become one, so space-padding a mono label collapses silently. An
+  expression container preserves it - `<d-text>{"one    two"}</d-text>` - and
+  `\n` inside one produces a hard line break.
+
 - Events: there is NO `onClick`/`onPress`. A "button" is a `<view>`/`<rect>`
   with `onPointerDown`. Handlers: onPointerDown/Up/Move/Enter/Leave, onWheel,
   onKeyDown/Up, onTextInput, onFocus/onBlur. Text entry: focus a node with an
-  `onTextInput` handler (setFocus activates the on-screen keyboard).
+  `onTextInput` handler. Focus alone never raises the on-screen keyboard: a
+  tap on the focused node (or explicit startTextInput()) does, and never
+  while a physical keyboard is attached; on keyboard-equipped platforms the
+  session starts invisibly at focus so text flows immediately.
+  `textInputHints` on the node configures the IME (type/capitalize/
+  autocorrect) - identifier fields and terminals want
+  `{ capitalize: "none", autocorrect: false }` (OS default auto-capitalizes). Key
+  events start at the focused node and bubble leaf->root to the window (with
+  nothing focused, the window alone), so `<window onKeyDown>` is the
+  app-global shortcut point; `stopPropagation()` ends the walk. `focusable`
+  declares focus-navigation candidacy (enumerate via getFocusables()).
 
 - Reactivity is SolidJS 2.0 (`@solidjs/signals`), NOT Solid 1.x. `createSignal`
   is as you expect, but `createEffect` takes the 2.0 two-function shape: a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.41"
+    "@solidrt/flux-types": "0.0.43"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.26",

package/src/core.ts

@@ -1,10 +1,113 @@
 import * as tree from "flux:rendertree"
+import { createSignal, onCleanup } from "@solidjs/signals"
+import { on } from "srt:events"
 
 let handlers = new Map<number, Map<string, Function>>()
 
+// Pointer-handler presence mirrored into the render tree, so the runtime can
+// skip building deliveries that would reach nobody (moves over static content
+// are the flood case). Bits match alloy's EventInterest (rendertree/hit.rs);
+// keep the two in sync. Down/up are recorded but the runtime never gates
+// them: focus and gesture side effects hang off them regardless of handlers.
+const MOVE_BIT = 1
+const POINTER_INTEREST: Record<string, number> = {
+  onPointerMove: MOVE_BIT,
+  onPointerDown: 2,
+  onPointerUp: 4,
+  onPointerEnter: 8,
+  onPointerLeave: 16,
+  onWheel: 32,
+}
+
+let interests = new Map<number, number>()
+
+function syncInterest(nodeId: number): void {
+  let mask = 0
+  let nodeHandlers = handlers.get(nodeId)
+  if (nodeHandlers) for (let name of nodeHandlers.keys()) mask |= POINTER_INTEREST[name] ?? 0
+  // Ambient onPointerMove subscribers park a move bit on the window root: it
+  // sits on every hit path, so moves keep emitting wherever the pointer is.
+  if (nodeId === interestRoot && globalMoveSubs.size > 0) mask |= MOVE_BIT
+  if ((interests.get(nodeId) ?? 0) === mask) return
+  if (mask === 0) interests.delete(nodeId)
+  else interests.set(nodeId, mask)
+  tree.setEventInterest(nodeId, mask)
+}
+
+/**
+ * A pointer fact with no per-node fields: window coordinates plus pointer
+ * identity and modifiers. `target` is the deepest node under the pointer
+ * (0 when nothing is hit).
+ */
+export interface GlobalPointerEvent {
+  clientX: number
+  clientY: number
+  target: number
+  pointerId: number
+  pointerType: "mouse" | "touch" | "pen" | (string & {})
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
+}
+
+let globalMoveSubs = new Set<(e: GlobalPointerEvent) => void>()
+let globalMoveUnsub: (() => void) | null = null
+// The window root's node id while a window is attached (see attachWindow):
+// where the ambient move-interest bit lands.
+let interestRoot: number | null = null
+
+/**
+ * Observe every pointer move, unattached to any node - for ambient tracking
+ * (cursor followers, idle detection, overlays). Element interaction belongs
+ * in per-node handlers: they carry exact local coordinates, and during a drag
+ * moves already follow the frozen down-path off-element. Cleans up with the
+ * owning scope; also returns its unsubscribe.
+ */
+export function onPointerMove(fn: (e: GlobalPointerEvent) => void): () => void {
+  globalMoveSubs.add(fn)
+  if (globalMoveSubs.size === 1) {
+    globalMoveUnsub = on("pointerMove", (raw: any) => {
+      let e: GlobalPointerEvent = {
+        clientX: raw.clientX,
+        clientY: raw.clientY,
+        target: raw.target,
+        pointerId: raw.pointerId,
+        pointerType: raw.pointerType,
+        shiftKey: raw.shiftKey,
+        ctrlKey: raw.ctrlKey,
+        altKey: raw.altKey,
+        metaKey: raw.metaKey,
+      }
+      // Copy first: a subscriber may unsubscribe (itself or others) mid-dispatch.
+      for (let sub of [...globalMoveSubs]) sub(e)
+    })
+    if (interestRoot != null) syncInterest(interestRoot)
+  }
+  let cleanup = () => {
+    if (!globalMoveSubs.delete(fn)) return
+    if (globalMoveSubs.size === 0) {
+      globalMoveUnsub?.()
+      globalMoveUnsub = null
+      if (interestRoot != null) syncInterest(interestRoot)
+    }
+  }
+  onCleanup(cleanup)
+  return cleanup
+}
+
+// Called by attachWindow with the window root's id (null on teardown). No
+// interest write on clear: the root node is being destroyed with its window,
+// and cleanupNode drops the cached mask.
+export function setInterestRoot(nodeId: number | null): void {
+  interestRoot = nodeId
+  if (nodeId != null) syncInterest(nodeId)
+}
+
 export function setEventHandler(nodeId: number, name: string, fn: Function | null | undefined): void {
   if (fn == null) {
     handlers.get(nodeId)?.delete(name)
+    if (name in POINTER_INTEREST) syncInterest(nodeId)
     return
   }
   let nodeHandlers = handlers.get(nodeId)
@@ -13,49 +116,185 @@ export function setEventHandler(nodeId: number, name: string, fn: Function | nul
     handlers.set(nodeId, nodeHandlers)
   }
   nodeHandlers.set(name, fn)
+  if (name in POINTER_INTEREST) syncInterest(nodeId)
 }
 
 export function getEventHandler(nodeId: number, name: string): Function | undefined {
   return handlers.get(nodeId)?.get(name)
 }
 
-export function cleanupNodeHandlers(nodeId: number): void {
+// Cleans up every per-node registry entry (handlers, focus candidacy, text
+// hints) when a node is destroyed.
+export function cleanupNode(nodeId: number): void {
   handlers.delete(nodeId)
+  // No setEventInterest call: the tree node is being destroyed with us.
+  interests.delete(nodeId)
+  focusables.delete(nodeId)
+  textHints.delete(nodeId)
+}
+
+// Per-node IME hints, declared by the `textInputHints` prop (renderer.ts)
+// and read when the node's text session starts.
+let textHints = new Map<number, tree.TextInputHints>()
+
+export function setTextInputHints(nodeId: number, hints: tree.TextInputHints | null | undefined): void {
+  if (hints == null) textHints.delete(nodeId)
+  else textHints.set(nodeId, hints)
 }
 
-// Currently-focused node id. Reset to null automatically across engine
-// reloads because the JS environment is rebuilt from scratch.
+// Currently-focused node id and text-session state. Each is a plain field
+// paired with a signal: signal writes flush on the microtask, so a read
+// through the signal alone is stale within the very dispatch that wrote it -
+// and focus logic reads what it just moved (a tap handler focusing a field,
+// then the dispatcher deciding on that focus). The plain field is the
+// always-current truth; the signal exists only to make tracked scopes re-run.
+// Reset across engine reloads for free: the JS environment is rebuilt.
 let focusedNodeId: number | null = null
-let textInputActive = false
+let [trackFocusedNode, setFocusedNodeSignal] = createSignal<number | null>(null)
+let textInputActiveNow = false
+let [trackTextInputActive, setTextInputActiveSignal] = createSignal(false)
+
+/**
+ * The focused node id, or null - as a reactive accessor: read it inside a
+ * tracked scope (JSX, memo, effect) to re-run when focus moves; any read
+ * (including in the same dispatch as a setFocus) sees the current value.
+ * setFocus is the only writer.
+ */
+export function focusedNode(): number | null {
+  trackFocusedNode()
+  return focusedNodeId
+}
+
+/**
+ * Whether a text-entry session is active on the focused node (text events
+ * flowing; the on-screen keyboard up, where one is used), as a reactive
+ * accessor. Distinct from focus: a field focused by navigation is not
+ * editing until a tap or startTextInput() begins the session. Lets a text
+ * field tell its focused and editing states apart (Enter starts editing in
+ * the former, submits in the latter).
+ */
+export function textInputActive(): boolean {
+  trackTextInputActive()
+  return textInputActiveNow
+}
+
+// The native window outlives engine reloads, so a previous session may have
+// left its text input active; assert the known boot state.
+tree.setTextInputActive(false)
+
+// Facts for the text-session policy, from the sticky inputDevices event
+// (init + hotplug). Conservative defaults until it arrives: assume a screen
+// keyboard could appear, so an eager session start is never visibly wrong.
+let screenKeyboard = true
+let physicalKeyboard = false
+on("inputDevices", (d: { keyboard?: boolean; screenKeyboard?: boolean }) => {
+  physicalKeyboard = !!d.keyboard
+  screenKeyboard = !!d.screenKeyboard
+  // Facts can arrive after a node was focused (boot ordering) or change under
+  // it (keyboard hotplug): re-evaluate the eager session so e.g. a
+  // mount-focused terminal starts receiving text without a tap.
+  syncTextInput(textInputEligible() && (textInputActive() || textInputInvisible()))
+})
+
+// Focus candidacy, declared by the `focusable` prop (routed in renderer.ts).
+// Candidacy only: navigation schemes enumerate candidates and move focus
+// themselves via setFocus.
+let focusables = new Set<number>()
+
+export function setFocusable(nodeId: number, focusable: boolean): void {
+  if (focusable) focusables.add(nodeId)
+  else focusables.delete(nodeId)
+}
+
+/**
+ * Node ids currently declaring `focusable`, for building focus navigation
+ * (spatial/D-pad movement, tab order). A snapshot, not reactive; pair with
+ * getBoundingBoxViewport for their geometry.
+ */
+export function getFocusables(): number[] {
+  return [...focusables]
+}
+
+function textInputEligible(): boolean {
+  return focusedNodeId != null && getEventHandler(focusedNodeId, "onTextInput") != null
+}
+
+// Whether starting a text session shows nothing on screen: the platform has
+// no screen keyboard, or a physical keyboard is attached (the runtime keeps
+// the screen keyboard down natively then too). Invisible sessions start
+// eagerly at focus, so desktops and keyboard-equipped devices deliver text
+// from the moment a node is focused; visible ones wait for an interaction so
+// a keyboard never appears without one (the pointerDown dispatch in
+// window.ts, or an explicit startTextInput).
+function textInputInvisible(): boolean {
+  return !screenKeyboard || physicalKeyboard
+}
+
+// The node whose session is running: a session that stays active while focus
+// hops between text fields must restart on the new node so its IME hints
+// (keyboard type, capitalization) take effect.
+let sessionNodeId: number | null = null
+
+function syncTextInput(active: boolean): void {
+  let target = active ? focusedNodeId : null
+  if (active === textInputActiveNow && target === sessionNodeId) return
+  textInputActiveNow = active
+  sessionNodeId = target
+  setTextInputActiveSignal(active)
+  if (active) tree.setTextInputActive(true, textHints.get(target!))
+  else tree.setTextInputActive(false)
+}
 
 /**
  * Moves keyboard focus to `nodeId`, or clears it with `null`. Fires `onBlur` on
- * the previously focused node and `onFocus` on the new one. As a side effect,
- * the on-screen keyboard is activated when the newly focused node has an
- * `onTextInput` handler and deactivated otherwise. No-op if the node is already
- * focused.
+ * the previously focused node and `onFocus` on the new one. No-op if the node
+ * is already focused.
+ *
+ * Focus also scopes the text-entry session of a node with an `onTextInput`
+ * handler: where starting one is invisible (no screen keyboard, or a physical
+ * keyboard attached) it begins at focus; where it would raise an on-screen
+ * keyboard it waits for an interaction - a tap on the focused node, or
+ * startTextInput() - so focus alone never summons a keyboard. Focus moving
+ * between text nodes carries an active session along; focus leaving them ends
+ * it (and hides the keyboard).
  */
 export function setFocus(nodeId: number | null): void {
   if (nodeId === focusedNodeId) return
   let oldId = focusedNodeId
   focusedNodeId = nodeId
+  setFocusedNodeSignal(nodeId)
   if (oldId != null) {
     getEventHandler(oldId, "onBlur")?.()
   }
   if (nodeId != null) {
     getEventHandler(nodeId, "onFocus")?.()
   }
-  let wantActive = nodeId != null && getEventHandler(nodeId, "onTextInput") != null
-  if (wantActive !== textInputActive) {
-    textInputActive = wantActive
-    tree.setTextInputActive(wantActive)
-  }
+  syncTextInput(textInputEligible() && (textInputActiveNow || textInputInvisible()))
 }
 
-export function getFocusedNodeId(): number | null {
-  return focusedNodeId
+// Interactive trigger: pointer dispatch calls this when a tap lands on the
+// focused node (window.ts), the moment a pending session may raise the
+// on-screen keyboard.
+export function activateTextInput(): void {
+  if (textInputEligible()) syncTextInput(true)
 }
 
+/**
+ * Begins text entry on the focused node: enables text-event delivery and, on
+ * platforms that use one (and with no physical keyboard attached), raises the
+ * on-screen keyboard. Focus alone never raises it; a tap on the focused node
+ * triggers this automatically, so call it only for other interactions that
+ * should (a remote's select on a focused field, a search button). Throws when
+ * the focused node has no onTextInput handler.
+ */
+export function startTextInput(): void {
+  if (!textInputEligible()) {
+    throw new Error("startTextInput: no focused node with an onTextInput handler")
+  }
+  syncTextInput(true)
+}
+
+
 export interface BoundingBox {
   x: number
   y: number

package/src/environment.ts

@@ -1,5 +1,6 @@
-import { createSignal } from "@solidjs/signals"
+import { createRoot, createSignal } from "@solidjs/signals"
 import { on } from "srt:events"
+import { onPointerMove } from "./core"
 import { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
 
 // Environment State: reactive facts about the current execution environment.
@@ -24,6 +25,8 @@ export interface InputDevices {
   keyboard: boolean
   mouse: boolean
   touch: boolean
+  /** Whether the platform can present an on-screen keyboard. */
+  screenKeyboard: boolean
 }
 
 export type SystemTheme = "dark" | "light" | "unknown"
@@ -40,7 +43,7 @@ function ensureDevicesState() {
   // Sticky: the current state replays on subscribe, so the first read already
   // sees it on runtimes that report devices.
   on("inputDevices", (d: InputDevices) => {
-    setDevices({ keyboard: !!d.keyboard, mouse: !!d.mouse, touch: !!d.touch })
+    setDevices({ keyboard: !!d.keyboard, mouse: !!d.mouse, touch: !!d.touch, screenKeyboard: !!d.screenKeyboard })
   })
   devicesAccessor = devices
 }
@@ -100,10 +103,15 @@ function ensurePointerState() {
   let sawMouse = false
   let sawTouch = false
   let unsubs: (() => void)[] = []
+  let unsubMove: () => void = null!
   let note = (e: { pointerType?: string }) => {
     if (e.pointerType === "mouse" && !sawMouse) {
       sawMouse = true
       setMouse(true)
+      // Moves have nothing left to teach: touch is learned from downs (a
+      // touch never moves without one), so drop the move subscription and
+      // with it the ambient interest bit that forces move deliveries.
+      unsubMove()
     } else if (e.pointerType === "touch" && !sawTouch) {
       sawTouch = true
       setTouch(true)
@@ -111,7 +119,12 @@ function ensurePointerState() {
     // Both types observed: nothing left to learn, stop listening.
     if (sawMouse && sawTouch) for (let u of unsubs) u()
   }
-  unsubs.push(on("pointerMove", note), on("pointerDown", note))
+  // Downs always deliver, so the raw bus tap suffices; moves are gated when
+  // nobody listens, so they go through onPointerMove, whose subscription
+  // keeps them flowing. The probe is app-lifetime: createRoot detaches its
+  // scope cleanup from whatever computation first read the accessor.
+  unsubMove = createRoot(() => onPointerMove(note))
+  unsubs.push(unsubMove, on("pointerDown", note))
   mouseSeenAccessor = mouse
   touchSeenAccessor = touch
 }

package/src/gpu.ts

@@ -60,6 +60,13 @@ export type CreateOptions = { manual?: boolean; label?: string }
 export type SamplerOptions = { filter?: gpu.FilterMode; wrap?: gpu.WrapMode }
 export type { FilterMode, WrapMode } from "flux:gpu"
 
+// Pixel format option for the pixel-upload creates (createTexture,
+// createMutableTexture), fixed for the id's lifetime like the sampler state.
+// "rgba8" (default) or "r8" - see TextureFormat in flux:gpu for the r8
+// contract (1 byte/pixel, sampled as `(v, 0, 0, 1)`, any width).
+export type TextureFormatOptions = { format?: gpu.TextureFormat }
+export type { TextureFormat } from "flux:gpu"
+
 // The branded id types, one per id space (see flux:gpu): plain numbers at
 // runtime, distinct types to the checker, so a cross-space slip like
 // destroyBuffer(textureId) fails to compile. Exported so apps can annotate
@@ -166,21 +173,22 @@ export let glsl = String.raw
 export { captureSnapshot, readTexture } from "flux:gpu"
 
 /**
- * Uploads raw RGBA8 pixels to an immutable GPU texture and returns its id (use
- * it as `<texture src={id} />`). `data` must be exactly `width * height * 4`
- * bytes; a mismatch throws. For pixels you intend to mutate and re-upload, use
- * `createMutableTexture` instead. When called inside a reactive scope the
- * texture is freed automatically once that owner is disposed; when called
- * outside one (e.g. after an `await`, where the owner is no longer current)
- * nothing is registered and you must call `destroyTexture` (from flux:gpu)
- * yourself. Pass `{ manual: true }` to skip the auto-free and own the
- * disposal yourself even inside a reactive scope.
+ * Uploads raw pixels to an immutable GPU texture and returns its id (use it
+ * as `<texture src={id} />`). `data` must be exactly `width * height` pixels
+ * at the declared format's size (`* 4` bytes for the default "rgba8", `* 1`
+ * for "r8"); a mismatch throws. For pixels you intend to mutate and
+ * re-upload, use `createMutableTexture` instead. When called inside a
+ * reactive scope the texture is freed automatically once that owner is
+ * disposed; when called outside one (e.g. after an `await`, where the owner
+ * is no longer current) nothing is registered and you must call
+ * `destroyTexture` (from flux:gpu) yourself. Pass `{ manual: true }` to skip
+ * the auto-free and own the disposal yourself even inside a reactive scope.
  */
 export function createTexture(
   data: Uint8Array,
   width: number,
   height: number,
-  opts?: CreateOptions & SamplerOptions,
+  opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
 ): gpu.TextureId {
   let id = gpu.createTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
@@ -189,18 +197,19 @@ export function createTexture(
 
 /**
  * Creates a GPU texture you intend to update over time: seed it with `data`,
- * then call `uploadTexture(id, data)` (from flux:gpu) to push new pixels. `data`
- * is RGBA8 and must hold at least `width * height * 4` bytes (it may hold several
- * frames). Like `createTexture`, the texture is freed automatically when the
- * reactive owner is disposed (opt out with `{ manual: true }`); created
- * outside a reactive scope you must call `destroyTexture` (from flux:gpu)
- * yourself.
+ * then call `uploadTexture(id, data)` (from flux:gpu) to push new pixels.
+ * `data` must hold at least `width * height` pixels at the declared format's
+ * size (`* 4` bytes for the default "rgba8", `* 1` for "r8"; it may hold
+ * several frames). Like `createTexture`, the texture is freed automatically
+ * when the reactive owner is disposed (opt out with `{ manual: true }`);
+ * created outside a reactive scope you must call `destroyTexture` (from
+ * flux:gpu) yourself.
  */
 export function createMutableTexture(
   data: Uint8Array,
   width: number,
   height: number,
-  opts?: CreateOptions & SamplerOptions,
+  opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
 ): gpu.TextureId {
   let id = gpu.createMutableTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
@@ -237,7 +246,9 @@ export function createMutableTexture(
  * as written, so a shader carrying its own uniform names - one ported from
  * elsewhere - runs unchanged here without dropping to compileShader /
  * linkProgram. The built-in vertex stage still supplies `vUV`; declare
- * `in vec2 vUV;` yourself to read it.
+ * `in vec2 vUV;` yourself to read it. One naming trap: GLSL ES reserves
+ * `packed` as a keyword, so `vec4 packed = texture(...)` fails with a syntax
+ * error that does not name the identifier - pick another name.
  */
 export function createShaderTexture(
   fragmentSrc: string,

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from "./renderer"
-export { setFocus, getFocusedNodeId, measureText, getBoundingBox, getBoundingBoxViewport } from "./core"
-export type { BoundingBox } from "./core"
+export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, getBoundingBox, getBoundingBoxViewport, onPointerMove } from "./core"
+export type { BoundingBox, GlobalPointerEvent } from "./core"
 export { parseColor, mixColors, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
 export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, exit } from "./window"
@@ -28,6 +28,7 @@ export type {
   WheelEvent,
   KeyEvent,
   TextEvent,
+  TextInputHints,
   PaintProps,
   WindowProps,
   WindowShaderProps,

package/src/renderer.ts

@@ -3,7 +3,7 @@ import { createRenderer } from "@solidjs/universal"
 import type { Element } from "solid-js"
 import * as tree from "flux:rendertree"
 import { attachWindow } from "./window"
-import { setEventHandler, cleanupNodeHandlers, getFocusedNodeId, setFocus } from "./core"
+import { setEventHandler, setFocusable, setTextInputHints, cleanupNode, focusedNode, setFocus } from "./core"
 import { parseColor, isGradient } from "./color"
 
 export { getEventHandler } from "./core"
@@ -31,6 +31,16 @@ function createProxyNode(elementType: ElementType): ProxyNode {
   return node
 }
 
+// Ancestor chain for event dispatch: node ids from `id` (inclusive) to the
+// root, following the mount tree (a portaled node reports its mount point's
+// chain, not its lexical one). Empty when the id is unknown.
+export function getNodePath(id: number): number[] {
+  let path: number[] = []
+  let node: ProxyNode | undefined = nodes.get(id)
+  for (; node; node = node.parent) path.push(node.id)
+  return path
+}
+
 // Nodes detached this tick and awaiting the destroy sweep, keyed by id so a
 // re-insert can cancel one. See removeNode / flushDestroy.
 let pendingDestroy = new Map<number, ProxyNode>()
@@ -43,9 +53,9 @@ function destroyNode(node: ProxyNode): void {
   tree.destroyNode(node.id)
   let cleanup = (n: ProxyNode) => {
     for (let child of n.children) if (child.parent === n) cleanup(child)
-    if (n.id === getFocusedNodeId()) setFocus(null)
+    if (n.id === focusedNode()) setFocus(null)
     nodes.delete(n.id)
-    cleanupNodeHandlers(n.id)
+    cleanupNode(n.id)
   }
   cleanup(node)
 }
@@ -163,6 +173,16 @@ function applyProp<T>(node: ProxyNode, name: string, value: T): void {
     return
   }
 
+  if (name === "focusable") {
+    setFocusable(node.id, value === true)
+    return
+  }
+
+  if (name === "textInputHints") {
+    setTextInputHints(node.id, value as any)
+    return
+  }
+
   if (name === "color" && isGradient(value)) {
     setTreeProperty(node, name, value)
     return

package/src/sound.ts

@@ -5,7 +5,7 @@
 // a large track from a file path on demand instead of decoding it into memory.
 //
 // The imperative primitive lives in the `flux:audio` module; import
-// { play, load, stream } from "flux:audio" for non-reactive use.
+// { play, load, loadPcm, stream } from "flux:audio" for non-reactive use.
 
 import { createSignal, onCleanup } from "@solidjs/signals"
 import { load, stream } from "flux:audio"
@@ -13,13 +13,19 @@ import { file } from "flux:fs"
 
 type FluxFile = ReturnType<typeof file>
 
-type LoadedSound = ReturnType<typeof load>
+type Clip = ReturnType<typeof load>
+type Playback = ReturnType<Clip["play"]>
 
 export type SoundOptions = {
   /** Repeat the clip until stopped. Defaults to false. */
   loop?: boolean
   /** Volume scale, 1.0 leaves the clip unchanged. Defaults to 1.0. */
   gain?: number
+  /**
+   * Stereo position in [-1, 1], -1 = left, 0 = center, 1 = right (equal-power).
+   * Omitted means unspatialized.
+   */
+  pan?: number
   /**
    * Let play() stack overlapping voices instead of restarting. Defaults to
    * true: rapid triggers overlap. Set false for a single-voice sound where each
@@ -34,6 +40,8 @@ export type SoundStreamOptions = {
   loop?: boolean
   /** Volume scale, 1.0 leaves the track unchanged. Defaults to 1.0. */
   gain?: number
+  /** Stereo position in [-1, 1] (see {@link SoundOptions.pan}). */
+  pan?: number
 }
 
 /** A decoded sound with reactive lifecycle. */
@@ -42,30 +50,45 @@ export type Sound = {
   play(): void
   /** Stop every voice started from this sound. */
   stop(): void
+  /** Set the volume of every live voice, and of voices started later. */
+  setGain(gain: number): void
+  /** Set the stereo position of every live voice, and of voices started later. */
+  setPan(pan: number): void
   /** True after play() until stop() (does not track natural completion). */
   playing(): boolean
   /** Set if loading failed. */
   error(): Error | undefined
 }
 
-// Shared reactive wrapper: owns the loaded handle, tracks live voices, and
+// Shared reactive wrapper: owns the loaded clip, tracks live voices, and
 // disposes both on cleanup. `loader` runs once (may throw -> error signal).
+// Gain and pan are remembered so later voices start where setGain/setPan left
+// the sound, not back at the initial options.
 function reactiveSound(
-  loader: () => LoadedSound,
+  loader: () => Clip,
   overlap: boolean,
-  playOptions: { loop?: boolean; gain?: number },
+  initial: { loop?: boolean; gain?: number; pan?: number },
 ): Sound {
   let [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true })
   let [playing, setPlaying] = createSignal(false, { ownedWrite: true })
 
-  let handle: LoadedSound | undefined
-  let voices: { stop(): void }[] = []
+  let clip: Clip | undefined
+  let voices: Playback[] = []
+  let loop = initial.loop
+  let gain = initial.gain
+  let pan = initial.pan
   try {
-    handle = loader()
+    clip = loader()
   } catch (e) {
     setError(e instanceof Error ? e : new Error(String(e)))
   }
 
+  // Voices that finished on their own keep a dead handle in `voices` until the
+  // next call here; ended() lets each touch point clear them out.
+  let prune = () => {
+    voices = voices.filter((v) => !v.ended())
+  }
+
   let stopAll = () => {
     for (let v of voices) v.stop()
     voices = []
@@ -74,20 +97,31 @@ function reactiveSound(
 
   onCleanup(() => {
     stopAll()
-    if (handle) {
-      handle.unload()
-      handle = undefined
+    if (clip) {
+      clip.unload()
+      clip = undefined
     }
   })
 
   return {
     play() {
-      if (!handle) return
-      if (!overlap) stopAll()
-      voices.push(handle.play(playOptions))
+      if (!clip) return
+      if (overlap) prune()
+      else stopAll()
+      voices.push(clip.play({ loop, gain, pan }))
       setPlaying(true)
     },
     stop: stopAll,
+    setGain(value) {
+      gain = value
+      prune()
+      for (let v of voices) v.setGain(value)
+    },
+    setPan(value) {
+      pan = value
+      prune()
+      for (let v of voices) v.setPan(value)
+    },
     playing,
     error,
   }
@@ -102,6 +136,7 @@ export function createSound(source: Uint8Array, options: SoundOptions = {}): Sou
   return reactiveSound(() => load(source), options.overlap ?? true, {
     loop: options.loop,
     gain: options.gain,
+    pan: options.pan,
   })
 }
 
@@ -115,5 +150,5 @@ export function createSound(source: Uint8Array, options: SoundOptions = {}): Sou
  */
 export function createSoundStream(source: string | FluxFile, options: SoundStreamOptions = {}): Sound {
   let src = typeof source === "string" ? file(source) : source
-  return reactiveSound(() => stream(src), false, { loop: options.loop, gain: options.gain })
+  return reactiveSound(() => stream(src), false, { loop: options.loop, gain: options.gain, pan: options.pan })
 }

package/src/types.d.ts

@@ -3,8 +3,11 @@
 
 import type { Gradient } from "./color"
 import type { ProgramId, TextureId } from "flux:gpu"
+import type { TextInputHints } from "flux:rendertree"
 import type { Element } from "solid-js"
 
+export type { TextInputHints }
+
 // The "srt:*" lattice runner modules are declared in ./runtime-modules.d.ts
 // (referenced above) - ambient `declare module` only reaches consumers from a
 // non-module declaration file, and this file is a module.
@@ -154,7 +157,12 @@ export type Pct = { readonly __unit: "pct"; v: number }
 // One axis of the transform origin (the point rotate/scale/3D pivot around),
 // split per axis to match the engine's x/y prop convention. A bare number is
 // pixels; `pct(50)` is a fraction of the box, so a percentage origin tracks the
-// layout size with no reactive wiring. Unset defaults to the axis center.
+// layout size with no reactive wiring. Unset defaults to the axis center on a
+// laid-out view; on a d-view (no box of its own) it defaults to the view's
+// local (0,0) - the origin its children's coordinates are authored against, so
+// the pivot never depends on the inherited box. To pivot a d-view around its
+// content's center, set the origin explicitly in pixels; pct()/keywords on a
+// d-view resolve against the inherited box, which is rarely what you want.
 type OriginX = number | Pct | "left" | "center" | "right"
 type OriginY = number | Pct | "top" | "center" | "bottom"
 
@@ -182,7 +190,11 @@ export interface TransformProps {
   originX?: OriginX
   originY?: OriginY
   // Group opacity in 0..1: children are composited together, then faded as a
-  // whole (CSS `opacity`). Does not affect hit testing.
+  // whole (CSS `opacity`). Does not affect hit testing. Costs a compositing
+  // layer (save_layer around the subtree) while below 1, except on a
+  // repaintBoundary view, where it is hoisted to composite time for free. To
+  // fade a single primitive, put the alpha in its `color` (rgba) instead -
+  // paint alpha costs nothing.
   opacity?: number
   scrollX?: number
   scrollY?: number
@@ -239,6 +251,10 @@ export interface WheelEvent extends PointerEvent {
 // layout-dependent value ("a", "!", "Enter", "ArrowLeft"); `code` is the
 // physical, layout-independent key position ("KeyA", "Digit1", "NumpadEnter").
 // Printable characters for text entry arrive via onTextInput, not here.
+// Routing: keydown/keyup dispatch along the focused node's ancestor chain,
+// leaf->root, always ending at the window root; with nothing focused they go
+// to the window root alone. <window onKeyDown> is therefore the app-global
+// shortcut point.
 export interface KeyEvent {
   key: string
   code: string
@@ -247,6 +263,16 @@ export interface KeyEvent {
   ctrlKey: boolean
   altKey: boolean
   metaKey: boolean
+  /** Node id whose handler is currently running (bubbling changes it per call). */
+  currentTarget: number
+  /** Node id the dispatch started at: the focused node, or the window root when nothing is focused. */
+  target: number
+  /**
+   * Stops the event from reaching ancestor handlers. A component that consumed
+   * the key calls this so enclosing handlers (and app-global shortcuts on the
+   * window) do not also act on it.
+   */
+  stopPropagation: () => void
 }
 
 export interface TextEvent {
@@ -265,6 +291,20 @@ export interface PointerProps {
   onKeyDown?: (event: KeyEvent) => void
   onKeyUp?: (event: KeyEvent) => void
   onTextInput?: (event: TextEvent) => void
+  /**
+   * IME behavior for this node's text-entry sessions (keyboard type,
+   * capitalization, autocorrect); read when a session starts. Without it the
+   * OS defaults apply - notably sentence auto-capitalization, which
+   * identifier fields and terminals want off:
+   * `textInputHints={{ capitalize: "none", autocorrect: false }}`.
+   */
+  textInputHints?: TextInputHints
+  /**
+   * Declares the element a candidate for focus navigation, enumerable via
+   * getFocusables(). Candidacy only - it changes no behavior by itself; focus
+   * still moves through setFocus.
+   */
+  focusable?: boolean
   pointerEvents?: "auto" | "none" | "all"
 }
 
@@ -413,14 +453,27 @@ export interface ViewProps extends ViewOwnProps, LayoutProps {}
 
 // draw primitives
 
+// A stroked rect paints inside its box, like a CSS border: the stroke's outer
+// edge sits on the box edge rather than straddling it, so nothing bleeds past
+// the box for a clip to cut. `path` and `line` strokes stay centered on their
+// geometry - there the geometry is the stroke, not a box.
 export interface RectProps extends PaintProps, PointerProps {
-  // Corner radius. A single number applies to all four corners; an array is
-  // [top-left, top-right, bottom-right, bottom-left] (CSS border-radius order).
+  // Corner radius, measured on the box (the stroke's outer edge). A single
+  // number applies to all four corners; an array is [top-left, top-right,
+  // bottom-right, bottom-left] (CSS border-radius order).
   radius?: number | [number, number, number, number]
 }
 
+// Strokes paint inside the box, same as `RectProps`.
 export interface OvalProps extends PaintProps, PointerProps {}
 
+// A line's geometry is numbers, not a path string: the segment primitive to
+// reach for when endpoints move (each endpoint is one property write; a path
+// animates by rebuilding its `d` string). Endpoints (x1/y1/x2/y2) exist on
+// the detached `d-line` only. A laid-out `<line>` is practically a rule -
+// give it a thin box (length x strokeWidth); in general it draws its layout
+// box's top-left-to-bottom-right diagonal. For arbitrary angles and
+// connectors use `d-line`; for polylines and curves, a path.
 export interface LineProps extends PaintProps, PointerProps {
   /** Dash pattern in local units: the drawn segment length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
   onLength?: number

package/src/window.ts

@@ -3,8 +3,8 @@ import { requestFrame } from "flux:rendertree"
 import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
 import { exit } from "srt:app"
-import { getEventHandler, getFocusedNodeId, setFocus } from "./core"
-import { scanForOrphans } from "./renderer"
+import { getEventHandler, focusedNode, setFocus, activateTextInput, setInterestRoot } from "./core"
+import { scanForOrphans, getNodePath } from "./renderer"
 
 /**
  * Leaves the current app, unconditionally: back to the launcher in a dev
@@ -228,7 +228,10 @@ export function onBack(fn: (e: BackEvent) => void) {
 
 // ------ Window ----------------
 
-export function attachWindow(_nodeId: number) {
+export function attachWindow(nodeId: number) {
+  // The root carries the ambient move-interest bit for global onPointerMove
+  // subscribers (it is on every hit path); see core.setInterestRoot.
+  setInterestRoot(nodeId)
   let unsubscribe: () => void = null!
   let unsubDown: () => void = null!
   let unsubUp: () => void = null!
@@ -304,11 +307,16 @@ export function attachWindow(_nodeId: number) {
 
     unsubDown = on("pointerDown", (raw: RawPointer) => {
       bubble(raw, "onPointerDown")
-      // Outside-tap blur. Read focus AFTER per-node handlers so a tap that
-      // moves focus to a new node is not immediately blurred again.
-      let focused = getFocusedNodeId()
+      // Read focus AFTER per-node handlers so a tap that moves focus to a new
+      // node is not immediately blurred again.
+      let focused = focusedNode()
       if (focused != null && !raw.targets.includes(focused)) {
+        // Outside-tap blur.
         setFocus(null)
+      } else if (focused != null) {
+        // A tap on the focused node is the interaction that lets a pending
+        // text session raise the on-screen keyboard.
+        activateTextInput()
       }
     })
 
@@ -332,19 +340,31 @@ export function attachWindow(_nodeId: number) {
       bubble(raw, "onWheel")
     })
 
-    unsubKeyDown = on("keydown", (e: any) => {
-      let id = getFocusedNodeId()
-      if (id != null) {
-        getEventHandler(id, "onKeyDown")?.(e)
+    // Key events dispatch along the focused node's ancestor chain, leaf->root
+    // (the pointer bubbling contract), so a container hears keys from focused
+    // descendants and the window root hears everything: <window onKeyDown> is
+    // the app-global shortcut point. With nothing focused the path is the
+    // window root alone - key events are never dropped. The path is resolved
+    // at dispatch time from current focus (nothing to freeze: keyup follows
+    // focus, as in the DOM).
+    let dispatchKey = (raw: any, handler: string) => {
+      let target = focusedNode() ?? nodeId
+      let stopped = false
+      let e = { ...raw, target, stopPropagation: () => (stopped = true) }
+      let path = getNodePath(target)
+      // A focused node detached this tick has no chain to the root; the
+      // window root must still hear the key.
+      if (path[path.length - 1] !== nodeId) path.push(nodeId)
+      for (let id of path) {
+        e.currentTarget = id
+        getEventHandler(id, handler)?.(e)
+        if (stopped) break
       }
-    })
+    }
 
-    unsubKeyUp = on("keyup", (e: any) => {
-      let id = getFocusedNodeId()
-      if (id != null) {
-        getEventHandler(id, "onKeyUp")?.(e)
-      }
-    })
+    unsubKeyDown = on("keydown", (raw: any) => dispatchKey(raw, "onKeyDown"))
+
+    unsubKeyUp = on("keyup", (raw: any) => dispatchKey(raw, "onKeyUp"))
 
     unsubBack = on("back", () => {
       let prevented = false
@@ -361,7 +381,7 @@ export function attachWindow(_nodeId: number) {
     })
 
     unsubTextInput = on("textInput", (e: any) => {
-      let id = getFocusedNodeId()
+      let id = focusedNode()
       if (id != null) {
         getEventHandler(id, "onTextInput")?.(e)
       }
@@ -386,6 +406,7 @@ export function attachWindow(_nodeId: number) {
   })
 
   onCleanup(() => {
+    setInterestRoot(null)
     if (unsubscribe) unsubscribe()
     if (unsubDown) unsubDown()
     if (unsubUp) unsubUp()