@solidrt/core 0.0.18 → 0.0.20

package/package.json

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

package/src/capabilities.ts

@@ -0,0 +1,48 @@
+import { env } from "./environment"
+
+// Capabilities: what interactions are possible in the current environment.
+// Derived from Environment State on every read - computed, never stored - so
+// they are reactive wherever env is. Capabilities describe what is possible,
+// not how the UI should behave; behavior lives in the policy layer on top.
+//
+// Device presence wins when the runtime reports it (so unplugging the mouse
+// drops hover); the traffic-inferred seen-flags are the fallback for runtimes
+// without device enumeration.
+
+export type WindowSizeClass = "compact" | "medium" | "expanded"
+
+export type Capabilities = {
+  /** A pointer can rest over content without pressing (mouse/trackpad). */
+  hover: boolean
+  /** Pixel-precise pointing (mouse/trackpad), as opposed to a finger. */
+  precisePointer: boolean
+  /** Direct touch input. */
+  touch: boolean
+  /** Hardware-key navigation (tab/arrow traversal, shortcuts). */
+  keyboardNav: boolean
+  /** How much horizontal room the window offers (Material breakpoints). */
+  windowSizeClass: WindowSizeClass
+}
+
+// Material 3 width breakpoints, in logical pixels.
+const MEDIUM_MIN_WIDTH = 600
+const EXPANDED_MIN_WIDTH = 840
+
+export let capabilities: Capabilities = {
+  get hover() {
+    return env.inputDevices?.mouse ?? env.mouseSeen
+  },
+  get precisePointer() {
+    return env.inputDevices?.mouse ?? env.mouseSeen
+  },
+  get touch() {
+    return env.inputDevices?.touch ?? env.touchSeen
+  },
+  get keyboardNav() {
+    return env.inputDevices?.keyboard ?? env.keyboardSeen
+  },
+  get windowSizeClass(): WindowSizeClass {
+    let w = env.windowSize.width
+    return w >= EXPANDED_MIN_WIDTH ? "expanded" : w >= MEDIUM_MIN_WIDTH ? "medium" : "compact"
+  },
+}

package/src/environment.ts

@@ -0,0 +1,155 @@
+import { createSignal } from "@solidjs/signals"
+import { on } from "srt:events"
+import { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
+
+// Environment State: reactive facts about the current execution environment.
+//
+// Device presence comes from the runtime's sticky "inputDevices" event (init +
+// hotplug). Runtimes that do not emit it leave `inputDevices` undefined, and
+// the seen-flags below act as the fallback: a pointer type or key press has
+// been seen this session. Seen-flags only ever go from false to true, so a
+// capability derived from them can appear mid-session (e.g. the first mouse
+// move) but never flickers away.
+
+/** Connected input device classes, as reported by the runtime. */
+export interface InputDevices {
+  keyboard: boolean
+  mouse: boolean
+  touch: boolean
+}
+
+export type SystemTheme = "dark" | "light" | "unknown"
+
+export type Orientation = "portrait" | "portraitFlipped" | "landscape" | "landscapeFlipped" | "unknown"
+
+let devicesAccessor: (() => InputDevices | undefined) | undefined
+
+function ensureDevicesState() {
+  if (devicesAccessor) return
+  let [devices, setDevices] = createSignal<InputDevices | undefined>(undefined)
+  // 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 })
+  })
+  devicesAccessor = devices
+}
+
+let systemThemeAccessor: (() => SystemTheme) | undefined
+
+function ensureSystemThemeState() {
+  if (systemThemeAccessor) return
+  let [theme, setTheme] = createSignal<SystemTheme>("unknown")
+  on("systemTheme", (e: { theme?: SystemTheme }) => setTheme(e.theme ?? "unknown"))
+  systemThemeAccessor = theme
+}
+
+let orientationAccessor: (() => Orientation) | undefined
+
+function ensureOrientationState() {
+  if (orientationAccessor) return
+  let [orientation, setOrientation] = createSignal<Orientation>("unknown")
+  on("displayOrientation", (e: { orientation?: Orientation }) => {
+    setOrientation(e.orientation ?? "unknown")
+  })
+  orientationAccessor = orientation
+}
+
+let mouseSeenAccessor: (() => boolean) | undefined
+let touchSeenAccessor: (() => boolean) | undefined
+
+function ensurePointerState() {
+  if (mouseSeenAccessor) return
+  let [mouse, setMouse] = createSignal(false)
+  let [touch, setTouch] = createSignal(false)
+  let sawMouse = false
+  let sawTouch = false
+  let unsubs: (() => void)[] = []
+  let note = (e: { pointerType?: string }) => {
+    if (e.pointerType === "mouse" && !sawMouse) {
+      sawMouse = true
+      setMouse(true)
+    } else if (e.pointerType === "touch" && !sawTouch) {
+      sawTouch = true
+      setTouch(true)
+    }
+    // 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))
+  mouseSeenAccessor = mouse
+  touchSeenAccessor = touch
+}
+
+let keyboardSeenAccessor: (() => boolean) | undefined
+
+function ensureKeyboardState() {
+  if (keyboardSeenAccessor) return
+  let [keyboard, setKeyboard] = createSignal(false)
+  // Soft keyboards also deliver some keydowns (Backspace, Return), so this can
+  // read true on a touch-only device once the user types in a field. Only a
+  // fallback: capabilities prefer runtime-reported device presence.
+  let unsub = on("keydown", () => {
+    setKeyboard(true)
+    unsub()
+  })
+  keyboardSeenAccessor = keyboard
+}
+
+/**
+ * Reactive Environment State: what the framework observes about where it is
+ * running. Read properties inside a tracked scope (JSX, memo, effect) to re-run
+ * when they change. Behavior decisions should go through `capabilities` and the
+ * policy layer; read `env` directly only when the raw fact itself is needed.
+ */
+export let env = {
+  get windowSize() {
+    return windowSize()
+  },
+  get safeArea() {
+    return safeArea()
+  },
+  get displayScale() {
+    return displayScale()
+  },
+  get windowFocused() {
+    return windowFocused()
+  },
+  get keyboardHeight() {
+    return keyboardHeight()
+  },
+  /**
+   * Connected input device classes, or undefined until the runtime reports
+   * them (it does so at startup, so undefined normally means the runtime has
+   * no device enumeration).
+   */
+  get inputDevices(): InputDevices | undefined {
+    ensureDevicesState()
+    return devicesAccessor!()
+  },
+  /** The OS-level dark/light preference. */
+  get systemTheme(): SystemTheme {
+    ensureSystemThemeState()
+    return systemThemeAccessor!()
+  },
+  /** Orientation of the display the window is on. */
+  get orientation(): Orientation {
+    ensureOrientationState()
+    return orientationAccessor!()
+  },
+  /** A mouse (or trackpad) pointer has produced events this session. */
+  get mouseSeen(): boolean {
+    ensurePointerState()
+    return mouseSeenAccessor!()
+  },
+  /** A touch pointer has produced events this session. */
+  get touchSeen(): boolean {
+    ensurePointerState()
+    return touchSeenAccessor!()
+  },
+  /** A key press has been delivered this session. */
+  get keyboardSeen(): boolean {
+    ensureKeyboardState()
+    return keyboardSeenAccessor!()
+  },
+}

package/src/index.ts

@@ -4,7 +4,12 @@ export type { BoundingBox } from "./core"
 export { parseColor, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
 export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
+export { setPointerCapture, releasePointerCapture } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
+export { env } from "./environment"
+export type { InputDevices, SystemTheme, Orientation } from "./environment"
+export { capabilities } from "./capabilities"
+export type { Capabilities, WindowSizeClass } from "./capabilities"
 export { createTexture } from "./gpu"
 export { createImage, decodeImage } from "./image"
 export type { DecodedImage, ImageSource } from "./image"

package/src/renderer.ts

@@ -30,9 +30,42 @@ function createProxyNode(elementType: ElementType): ProxyNode {
   return node
 }
 
-// Detaches `node` from `parent` and destroys it (and all descendants) on both
-// the JS and native sides. Hoisted out of the renderer config so createPortal
-// can reuse it (createRenderer does not return its removeNode hook).
+// 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>()
+let destroyScheduled = false
+
+// Frees a detached node and its subtree on both sides. Descendants that were
+// moved out (their parent no longer points here) are left alone. Clear focus
+// before dropping handlers so onBlur still fires for a focused descendant.
+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)
+    nodes.delete(n.id)
+    cleanupNodeHandlers(n.id)
+  }
+  cleanup(node)
+}
+
+// End-of-tick sweep: destroy every still-detached pending node. A node that was
+// re-inserted this tick had its entry removed by insertNode (it moved, not
+// died); one still parentless here is genuinely gone.
+function flushDestroy(): void {
+  destroyScheduled = false
+  let batch = pendingDestroy
+  pendingDestroy = new Map()
+  for (let node of batch.values()) {
+    if (node.parent === undefined) destroyNode(node)
+  }
+}
+
+// Detaches `node` from `parent`, keeping the subtree alive so it can be
+// re-inserted elsewhere (a move) - matching DOM removeChild. Destruction is
+// deferred to an end-of-tick sweep; if nothing re-attaches the node by then it
+// is freed. Hoisted out of the renderer config so createPortal can reuse it
+// (createRenderer does not return its removeNode hook).
 function removeNode(parent: ProxyNode, node: ProxyNode): void {
   if (!node || !parent) return
 
@@ -45,17 +78,13 @@ function removeNode(parent: ProxyNode, node: ProxyNode): void {
   }
   node.parent = undefined
 
-  tree.deleteNode(parent.id, node.id)
+  tree.detachNode(parent.id, node.id)
 
-  // Recursively clean up node and all descendants. Clear focus before
-  // dropping handlers so onBlur still fires for a focused descendant.
-  let cleanup = (n: ProxyNode) => {
-    for (let child of n.children) cleanup(child)
-    if (n.id === getFocusedNodeId()) setFocus(null)
-    nodes.delete(n.id)
-    cleanupNodeHandlers(n.id)
+  pendingDestroy.set(node.id, node)
+  if (!destroyScheduled) {
+    destroyScheduled = true
+    Promise.resolve().then(flushDestroy)
   }
-  cleanup(node)
 }
 
 export let {
@@ -123,6 +152,10 @@ export let {
   insertNode: (parent: ProxyNode, node: ProxyNode, anchor?: ProxyNode): void => {
     if (!node) return
 
+    // A re-inserted node is being moved, not destroyed: cancel its pending
+    // destroy so the end-of-tick sweep leaves it (and its subtree) alone.
+    pendingDestroy.delete(node.id)
+
     if (parent) {
       node.parent = parent
 

package/src/types.d.ts

@@ -153,6 +153,10 @@ export interface PointerEvent {
   ctrlKey: boolean
   altKey: boolean
   metaKey: boolean
+  // Stops the event from reaching ancestor handlers. Events dispatch leaf->root
+  // (bubbling), so calling this in a child prevents the enclosing node from
+  // seeing it (e.g. a slider claiming a drag so an ancestor scroller ignores it).
+  stopPropagation: () => void
 }
 
 export interface WheelEvent extends PointerEvent {
@@ -264,8 +268,13 @@ export interface SvgProps extends Position, PointerProps {
   color?: Color
 }
 
-export interface TextProps extends PaintProps, PointerProps {
+export interface TextProps extends Position, PaintProps, PointerProps {
   children?: Children
+  // Shaping (wrap) width. Detached text wraps at the inherited ancestor size
+  // by default; set w for an unwrapped natural line or an explicit wrap width.
+  w?: number
+  // Reported-bounds height only; paragraph height always falls out of the text.
+  h?: number
   fontFamily?: "sans" | "mono" | (string & {})
   fontSize?: number
   lineHeight?: number

package/src/window.ts

@@ -4,6 +4,28 @@ import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
 import { getEventHandler, getFocusedNodeId, setFocus } from "./core"
 
+// ------ Pointer capture -----------------
+
+// Active pointer captures, pointerId -> nodeId. While a pointer is captured, its
+// move/up events dispatch straight to the captured node (bypassing hit testing),
+// so a drag keeps working when the pointer drifts off the element. Modeled on the
+// web setPointerCapture; capture auto-releases on pointerUp.
+let pointerCaptures = new Map<number, number>()
+
+/**
+ * Routes all further move/up events for `pointerId` to `nodeId` until release,
+ * regardless of what is under the pointer. Call from a pointerdown handler to own
+ * a drag (e.g. a slider). Auto-releases on the matching pointerup.
+ */
+export function setPointerCapture(nodeId: number, pointerId: number) {
+  pointerCaptures.set(pointerId, nodeId)
+}
+
+/** Ends a capture early. Not needed for the common case (pointerup releases it). */
+export function releasePointerCapture(pointerId: number) {
+  pointerCaptures.delete(pointerId)
+}
+
 // ------ Animation frames ----------------
 
 let nextFrameId = 1
@@ -201,12 +223,24 @@ export function attachWindow(_nodeId: number) {
       runFrame(time * 1000, frame)
     })
 
+    // Dispatch an event to every node on the hit path, leaf->root (bubbling), so
+    // a child handler can call e.stopPropagation() to keep the event from
+    // reaching its ancestors. `targets` arrives root->leaf, hence the reverse.
+    let bubble = (targets: number[], handler: string, e: any) => {
+      let stopped = false
+      e.stopPropagation = () => {
+        stopped = true
+      }
+      for (let i = targets.length - 1; i >= 0; i--) {
+        getEventHandler(targets[i]!, handler)?.(e)
+        if (stopped) break
+      }
+    }
+
     unsubDown = on(
       "pointerDown",
       ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        for (let nodeId of targets) {
-          getEventHandler(nodeId, "onPointerDown")?.(e)
-        }
+        bubble(targets, "onPointerDown", e)
         // 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()
@@ -217,42 +251,61 @@ export function attachWindow(_nodeId: number) {
     )
 
     unsubUp = on("pointerUp", ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-      for (let nodeId of targets) {
-        getEventHandler(nodeId, "onPointerUp")?.(e)
+      let captured = pointerCaptures.get(e.pointerId)
+      if (captured != null) {
+        // Deliver to the captured node, then release (web auto-release on up).
+        e.stopPropagation = () => {}
+        getEventHandler(captured, "onPointerUp")?.(e)
+        pointerCaptures.delete(e.pointerId)
+        return
       }
+      bubble(targets, "onPointerUp", e)
     })
 
     unsubMove = on(
       "pointerMove",
       ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        for (let nodeId of targets) {
-          getEventHandler(nodeId, "onPointerMove")?.(e)
+        let captured = pointerCaptures.get(e.pointerId)
+        if (captured != null) {
+          // Captured drags get moves anywhere over the window, bypassing hit test.
+          e.stopPropagation = () => {}
+          getEventHandler(captured, "onPointerMove")?.(e)
+          return
         }
+        bubble(targets, "onPointerMove", e)
       },
     )
 
+    // Enter/leave keep their hover-diff order (already leaf->root for leave,
+    // root->leaf for enter), but still honor stopPropagation for a consistent
+    // event shape.
+    let dispatchOrdered = (targets: number[], handler: string, e: any) => {
+      let stopped = false
+      e.stopPropagation = () => {
+        stopped = true
+      }
+      for (let nodeId of targets) {
+        getEventHandler(nodeId, handler)?.(e)
+        if (stopped) break
+      }
+    }
+
     unsubEnter = on(
       "pointerEnter",
       ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        for (let nodeId of targets) {
-          getEventHandler(nodeId, "onPointerEnter")?.(e)
-        }
+        dispatchOrdered(targets, "onPointerEnter", e)
       },
     )
 
     unsubLeave = on(
       "pointerLeave",
       ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        for (let nodeId of targets) {
-          getEventHandler(nodeId, "onPointerLeave")?.(e)
-        }
+        dispatchOrdered(targets, "onPointerLeave", e)
       },
     )
 
     unsubWheel = on("wheel", ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-      for (let nodeId of targets) {
-        getEventHandler(nodeId, "onWheel")?.(e)
-      }
+      bubble(targets, "onWheel", e)
     })
 
     unsubKeyDown = on("keydown", (e: any) => {