@solidrt/core 0.0.41 → 0.0.42

package/AGENTS.md

@@ -140,7 +140,17 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
 - 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.42",
   "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.42"
   },
   "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/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/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.
@@ -239,6 +242,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 +254,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 +282,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,12 +444,18 @@ 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 {}
 
 export interface LineProps extends PaintProps, PointerProps {

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()