@solidrt/core 0.0.36 → 0.0.38

package/examples/README.md

@@ -16,6 +16,9 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `frame-animation.tsx` - `onFrame` driving a transform animation each frame.
 - `on-layout-connect.tsx` - `onLayout` + `getBoundingBox` connecting laid-out boxes with a `d-path`.
 
+## Pointer input
+- `pointer-local-coords.tsx` - the three pointer coordinate frames (`clientX` window, `localX` the handling node's own frame, `parentX` its path-parent's frame - where the node's x/y live) and the transform-proof drag idiom: grab offset from `localX` at down, place with `parentX - offset` on moves. Exact inside rotated/scaled ancestors and when the pointer leaves the node mid-drag.
+
 ## Performance
 - `repaint-boundary.tsx` - `repaintBoundary` on a `<view>` to keep static content from rebuilding while a neighbor animates: `{true}` retains the recorded draw list, `"snapshot"` also retains the rasterized pixels as a GPU texture (for raster-expensive, screen-aligned, static subtrees).
 

package/examples/pointer-local-coords.tsx

@@ -0,0 +1,53 @@
+// Pointer events carry the pointer position in three coordinate frames,
+// resolved per node as the event bubbles:
+// - clientX/clientY - the window frame.
+// - localX/localY - the frame of the node whose handler is running, its whole
+//   transform chain undone. Exact even when the pointer is not over the node:
+//   after a pointer down, moves route along the frozen down path and keep
+//   reporting true locals (a fast drag cannot escape the chip below).
+// - parentX/parentY - the frame of the node's path parent, which is the frame
+//   the node's own x/y props live in.
+// The drag idiom needs no transform math in the app: take the grab offset from
+// localX/localY at pointer down, place with parentX/parentY - offset during
+// moves. The surface here is rotated and scaled to prove the point - the chip
+// still tracks the pointer exactly. Keying the grab by pointerId keeps
+// concurrent touches (each routed along its own down path) independent.
+import { render, createSignal } from "@solidrt/core"
+
+function App() {
+  let [pos, setPos] = createSignal({ x: 40, y: 40 })
+  let grab: { pointer: number; dx: number; dy: number } | null = null
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view width={360} height={240} rotate={0.3} scale={1.2}>
+        <d-rect radius={16} color="#2a2f3a" />
+        <view
+          position="absolute"
+          width={100}
+          height={64}
+          x={pos().x}
+          y={pos().y}
+          justifyContent="center"
+          alignItems="center"
+          onPointerDown={(e) => {
+            if (grab) return
+            grab = { pointer: e.pointerId, dx: e.localX, dy: e.localY }
+          }}
+          onPointerMove={(e) => {
+            if (!grab || e.pointerId !== grab.pointer) return
+            setPos({ x: e.parentX - grab.dx, y: e.parentY - grab.dy })
+          }}
+          onPointerUp={() => {
+            grab = null
+          }}
+        >
+          <d-rect radius={12} color="#3366b3" />
+          <text color="white">drag me</text>
+        </view>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

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

package/src/environment.ts

@@ -28,6 +28,8 @@ export interface InputDevices {
 
 export type SystemTheme = "dark" | "light" | "unknown"
 
+export type Visibility = "visible" | "hidden"
+
 export type Orientation = "portrait" | "portraitFlipped" | "landscape" | "landscapeFlipped" | "unknown"
 
 let devicesAccessor: (() => InputDevices | undefined) | undefined
@@ -52,6 +54,18 @@ function ensureSystemThemeState() {
   systemThemeAccessor = theme
 }
 
+let visibilityAccessor: (() => Visibility) | undefined
+
+function ensureVisibilityState() {
+  if (visibilityAccessor) return
+  let [visibility, setVisibility] = createSignal<Visibility>("visible", { ownedWrite: true })
+  // Sticky. The runtime may report the same state through several platform
+  // paths; the signal's equality check turns repeats into no-ops for
+  // reactive consumers.
+  on("visibility", (e: { state?: Visibility }) => setVisibility(e.state === "hidden" ? "hidden" : "visible"))
+  visibilityAccessor = visibility
+}
+
 let orientationAccessor: (() => Orientation) | undefined
 
 function ensureOrientationState() {
@@ -167,6 +181,21 @@ export let env = {
     ensureTextScaleState()
     return textScaleAccessor!()
   },
+  /**
+   * Whether the app is on screen: "hidden" while backgrounded (Android) or
+   * minimized (desktop), "visible" again on return. The web's
+   * `visibilityState` vocabulary without the `document` machinery - react
+   * to it in a tracked scope (JSX, memo, effect).
+   *
+   * This is the persistence moment: there is no close event on any
+   * platform (Android gives no time, desktop window close never enters
+   * JS), so save state when this goes "hidden". While hidden, timers keep
+   * running but no frames are produced.
+   */
+  get visibility(): Visibility {
+    ensureVisibilityState()
+    return visibilityAccessor!()
+  },
   /** Orientation of the display the window is on. */
   get orientation(): Orientation {
     ensureOrientationState()

package/src/index.ts

@@ -3,10 +3,11 @@ export { setFocus, getFocusedNodeId, measureText, getBoundingBox, getBoundingBox
 export type { BoundingBox } from "./core"
 export { parseColor, mixColors, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
-export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
+export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, exit } from "./window"
+export type { BackEvent } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
 export { env } from "./environment"
-export type { InputDevices, SystemTheme, Orientation } from "./environment"
+export type { InputDevices, SystemTheme, Orientation, Visibility } from "./environment"
 export { gamepads } from "./gamepad"
 export type { GamepadState } from "./gamepad"
 export { capabilities } from "./capabilities"

package/src/renderer.ts

@@ -97,14 +97,14 @@ function removeNode(parent: ProxyNode, node: ProxyNode): void {
 // bookkeeping on the hot create/insert paths, orphans are derived from the
 // proxy map itself: parentless, not the window root, and not awaiting the
 // destroy sweep. window.ts runs the scan on a rendered frame every few
-// seconds; dev bundles only (srt always defines process.env.NODE_ENV, so a
+// seconds; dev bundles only (srt always defines import.meta.env.DEV, so a
 // production bundle folds the check into a constant early return).
 const SENTINEL_INTERVAL_MS = 5000
 let sentinelDue = 0
 let warnedLeakTypes = new Set<string>()
 
 export function scanForOrphans(now: number): void {
-  if (process.env.NODE_ENV === "production") return
+  if (!import.meta.env.DEV) return
   if (now < sentinelDue) return
   sentinelDue = now + SENTINEL_INTERVAL_MS
   let counts = new Map<string, number>()

package/src/runtime-modules.d.ts

@@ -23,6 +23,14 @@ declare module "*.jpeg" {
   const bytes: Uint8Array
   export default bytes
 }
+declare module "*.wav" {
+  const bytes: Uint8Array
+  export default bytes
+}
+declare module "*.ogg" {
+  const bytes: Uint8Array
+  export default bytes
+}
 
 // UI event bus (lattice), provided by the runtime as a builtin module.
 // on/once return an unsubscribe function.
@@ -31,12 +39,29 @@ declare module "srt:events" {
   export function once(event: string, callback: (data: any) => void): () => void
 }
 
+// The running application's own surface (lattice), present in every build.
+declare module "srt:app" {
+  /**
+   * Leave the current app, unconditionally: back to the launcher in a dev
+   * client, quit when standalone or at the launcher root (on Android the
+   * client backgrounds instead of dying). The default action of an
+   * unprevented `back` event; prefer the @solidrt/core re-export.
+   */
+  export function exit(): void
+}
+
 // Dev-server control surface (lattice). Present only in dev/go builds; in other
 // builds `available` is false and the functions are no-ops.
 declare module "srt:dev" {
   export const available: boolean
   export const canDiscover: boolean
   export const recents: string[]
+  /**
+   * The dev-server address the client was launched with (so the launcher can
+   * auto-connect without on-device interaction), or null when launched without
+   * one.
+   */
+  export const launchAddress: string | null
   export function connect(address: string): void
   export function discover(): void
   export function stop(): void
@@ -63,8 +88,13 @@ declare module "srt:apps" {
   export type InstalledApp = { id: string; name: string; version: string }
   /** Installed apps, sorted by name. */
   export function list(): InstalledApp[]
-  /** A stored version: id (manifest hash), bytes on disk, whether it is the current one. */
-  export type AppVersion = { id: string; size: number; current: boolean }
+  /**
+   * A stored version: id (manifest hash), bytes on disk, whether it is the
+   * current one, and the SolidRT (CLI) release that built it per its
+   * manifest ("unknown" from an in-repo CLI or when the manifest predates
+   * the field).
+   */
+  export type AppVersion = { id: string; size: number; current: boolean; solidrtVersion: string }
   /** One file in a listing: a relative path and its size in bytes. */
   export type AppFile = { path: string; size: number }
   /**

package/src/text-input.ts

@@ -82,7 +82,7 @@ export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
   }
 
   // Ordered selection bounds [start, end).
-  let range = () => {
+  let range = (): [number, number] => {
     let { anchor, focus } = selection()
     return anchor <= focus ? [anchor, focus] : [focus, anchor]
   }

package/src/types.d.ts

@@ -9,6 +9,16 @@ import type { Element } from "solid-js"
 // non-module declaration file, and this file is a module.
 
 declare global {
+  interface ImportMeta {
+    /**
+     * Build-mode constants, substituted textually by the srt bundler (Vite
+     * vocabulary). `DEV` is true in dev bundles and false in production
+     * bundles, where the substituted constant lets the minifier fold
+     * dev-only code away entirely.
+     */
+    readonly env: { readonly DEV: boolean }
+  }
+
   let image: {
     decodeImage(bytes: Uint8Array): { data: Uint8Array, width: number, height: number }
   }
@@ -180,6 +190,29 @@ export interface TransformProps {
 export interface PointerEvent {
   clientX: number
   clientY: number
+  /**
+   * Pointer position in the coordinate frame of the node whose handler is
+   * running (its transform chain undone), so it differs per node as the event
+   * bubbles. Exact even when the pointer is not over the node: a drag routed
+   * along the frozen down-path keeps reporting true local coordinates after
+   * leaving it.
+   */
+  localX: number
+  localY: number
+  /**
+   * Pointer position in the frame the running node's own x/y coordinates live
+   * in: its parent on the hit path (the window for the root). The drag idiom
+   * is `x = parentX - grab offset`, with the grab offset taken from
+   * localX/localY at pointer down. The path parent skips
+   * pointerEvents="none" ancestors, so it is the layout parent in ordinary
+   * trees.
+   */
+  parentX: number
+  parentY: number
+  /** Node id whose handler is currently running (bubbling changes it per call). */
+  currentTarget: number
+  /** Deepest node id of the event's path (the hit leaf). */
+  target: number
   pointerId: number
   pointerType: "mouse" | "touch" | "pen" | (string & {})
   button?: number
@@ -198,8 +231,18 @@ export interface WheelEvent extends PointerEvent {
   deltaY: number
 }
 
+// Key events use the W3C UI Events vocabulary: `key` is the logical,
+// 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.
 export interface KeyEvent {
   key: string
+  code: string
+  repeat: boolean
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
 }
 
 export interface TextEvent {
@@ -322,6 +365,14 @@ export interface TextProps extends Position, PaintProps, PointerProps {
 
 export interface TextureProps extends Position, PointerProps {
   src?: number
+  /**
+   * How the texture's pixels map to the element box (CSS object-fit).
+   * "fill" (default) stretches; "cover" and "none" crop; "contain" and
+   * "scale-down" letterbox. Everything centers - there is no object-position.
+   * Paint-only: the element box itself is unaffected, so "contain" letterbox
+   * bars and "cover" cropped edges still hit-test as part of the element.
+   */
+  fit?: "fill" | "cover" | "contain" | "none" | "scale-down"
   w?: number
   h?: number
   srcX?: number

package/src/window.ts

@@ -2,20 +2,27 @@ import { createSignal, onCleanup, onSettled, flush } from "@solidjs/signals"
 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"
 
+/**
+ * Leaves the current app, unconditionally: back to the launcher in a dev
+ * client, quitting when standalone or at the launcher itself (on Android the
+ * client backgrounds instead of dying). The default action of an unprevented
+ * `back` event; call it directly to exit programmatically, e.g. after
+ * intercepting back for an unsaved-changes dialog.
+ */
+export { exit }
+
 // ------ Pointer routing -----------------
 
-// Hit path frozen at pointerDown, pointerId -> targets. While a pointer has an
-// active down, its moves and up dispatch along this path (same leaf-to-root
-// bubble) no matter where the pointer currently is, so every node under the
-// original down observes the whole gesture: a drag keeps working off-element,
-// and an ancestor recognizer (a scroller's pan) sees the moves it needs to
-// take over mid-gesture via the arena. There is no exclusive pointer capture;
-// gesture ownership is claim-based, above this layer. Enter/leave stay
-// hover-driven, and moves with no active down follow the live hit path.
-let downPaths = new Map<number, number[]>()
+// Routing lives in the engine: the runtime freezes each pointer's hit path at
+// pointerDown and delivers every event with its exact targets plus per-node
+// local/parent-frame coordinate arrays (see PointerEvent in types.d.ts). This
+// side only walks the delivered path, resolving the per-node scalars before
+// each handler. There is no exclusive pointer capture; gesture ownership is
+// claim-based, above this layer.
 
 // ------ Animation frames ----------------
 
@@ -179,6 +186,30 @@ export function onWindowBlur(fn: () => void) {
   return unsubscribe
 }
 
+// ------ Back ----------------
+
+export type BackEvent = { preventDefault: () => void }
+
+// App handlers for the window-level back event, run in registration order.
+// Kept in a local registry (not per-handler bus subscriptions) so the default
+// action runs exactly once, after every handler has had its say.
+let backHandlers = new Set<(e: BackEvent) => void>()
+
+/**
+ * Calls `fn` on the user's back intent (Android back button/gesture, the
+ * desktop dev chord). Call `e.preventDefault()` when back means in-app
+ * navigation right now (close a modal, previous screen); unprevented, the
+ * default action runs: exit(). Apps without a handler exit on back
+ * everywhere, which is the correct zero-effort default.
+ * Returns a cleanup function; also auto-cleans within a reactive scope.
+ */
+export function onBack(fn: (e: BackEvent) => void) {
+  backHandlers.add(fn)
+  let cleanup = () => backHandlers.delete(fn)
+  onCleanup(cleanup)
+  return cleanup
+}
+
 // ------ Window ----------------
 
 export function attachWindow(_nodeId: number) {
@@ -191,6 +222,7 @@ export function attachWindow(_nodeId: number) {
   let unsubWheel: () => void = null!
   let unsubKeyDown: () => void = null!
   let unsubKeyUp: () => void = null!
+  let unsubBack: () => void = null!
   let unsubTextInput: () => void = null!
   let unsubKeyboardVisibility: () => void = null!
   let unsubRefreshRate: () => void = null!
@@ -217,77 +249,71 @@ 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) => {
+    // Dispatch an event to every node on the delivered path, resolving the
+    // per-node fields from the parallel wire arrays before each handler:
+    // localX/localY is the pointer in that node's own frame, parentX/parentY
+    // in its path-parent's frame (the frame the node's x/y live in), and
+    // currentTarget the node whose handler is running. `reverse` walks the
+    // root->leaf array leaf-first (bubbling), so a child handler can call
+    // e.stopPropagation() to keep the event from reaching its ancestors;
+    // enter/leave arrive pre-ordered and walk forward.
+    interface RawPointer {
+      targets: number[]
+      localX: number[]
+      localY: number[]
+      parentX: number[]
+      parentY: number[]
+      [k: string]: any
+    }
+    let dispatchPath = (raw: RawPointer, handler: string, reverse: boolean) => {
+      let { targets, localX, localY, parentX, parentY, ...e } = raw
       let stopped = false
       e.stopPropagation = () => {
         stopped = true
       }
-      for (let i = targets.length - 1; i >= 0; i--) {
+      let n = targets.length
+      for (let k = 0; k < n; k++) {
+        let i = reverse ? n - 1 - k : k
+        e.currentTarget = targets[i]!
+        e.localX = localX[i]!
+        e.localY = localY[i]!
+        e.parentX = parentX[i]!
+        e.parentY = parentY[i]!
         getEventHandler(targets[i]!, handler)?.(e)
         if (stopped) break
       }
     }
+    let bubble = (raw: RawPointer, handler: string) => dispatchPath(raw, handler, true)
+    let dispatchOrdered = (raw: RawPointer, handler: string) => dispatchPath(raw, handler, false)
+
+    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()
+      if (focused != null && !raw.targets.includes(focused)) {
+        setFocus(null)
+      }
+    })
 
-    unsubDown = on(
-      "pointerDown",
-      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        downPaths.set(e.pointerId, targets)
-        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()
-        if (focused != null && !targets.includes(focused)) {
-          setFocus(null)
-        }
-      },
-    )
-
-    unsubUp = on("pointerUp", ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-      let frozen = downPaths.get(e.pointerId)
-      downPaths.delete(e.pointerId)
-      bubble(frozen ?? targets, "onPointerUp", e)
+    unsubUp = on("pointerUp", (raw: RawPointer) => {
+      bubble(raw, "onPointerUp")
     })
 
-    unsubMove = on(
-      "pointerMove",
-      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        bubble(downPaths.get(e.pointerId) ?? 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
-      }
-    }
+    unsubMove = on("pointerMove", (raw: RawPointer) => {
+      bubble(raw, "onPointerMove")
+    })
 
-    unsubEnter = on(
-      "pointerEnter",
-      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        dispatchOrdered(targets, "onPointerEnter", e)
-      },
-    )
-
-    unsubLeave = on(
-      "pointerLeave",
-      ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-        dispatchOrdered(targets, "onPointerLeave", e)
-      },
-    )
-
-    unsubWheel = on("wheel", ({ targets, ...e }: { targets: number[]; [k: string]: any }) => {
-      bubble(targets, "onWheel", e)
+    unsubEnter = on("pointerEnter", (raw: RawPointer) => {
+      dispatchOrdered(raw, "onPointerEnter")
+    })
+
+    unsubLeave = on("pointerLeave", (raw: RawPointer) => {
+      dispatchOrdered(raw, "onPointerLeave")
+    })
+
+    unsubWheel = on("wheel", (raw: RawPointer) => {
+      bubble(raw, "onWheel")
     })
 
     unsubKeyDown = on("keydown", (e: any) => {
@@ -304,6 +330,18 @@ export function attachWindow(_nodeId: number) {
       }
     })
 
+    unsubBack = on("back", () => {
+      let prevented = false
+      let e: BackEvent = {
+        preventDefault: () => {
+          prevented = true
+        },
+      }
+      // Copy first: a handler may unregister (itself or others) mid-dispatch.
+      for (let fn of [...backHandlers]) fn(e)
+      if (!prevented) exit()
+    })
+
     unsubTextInput = on("textInput", (e: any) => {
       let id = getFocusedNodeId()
       if (id != null) {
@@ -339,6 +377,7 @@ export function attachWindow(_nodeId: number) {
     if (unsubWheel) unsubWheel()
     if (unsubKeyDown) unsubKeyDown()
     if (unsubKeyUp) unsubKeyUp()
+    if (unsubBack) unsubBack()
     if (unsubTextInput) unsubTextInput()
     if (unsubKeyboardVisibility) unsubKeyboardVisibility()
     if (unsubRefreshRate) unsubRefreshRate()