@solidrt/core 0.0.37 → 0.0.39

package/AGENTS.md

@@ -84,7 +84,7 @@ tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 ```
 
 Peer deps @solidjs/signals and @solidjs/universal must match (currently
-2.0.0-beta.20); bun resolves them from peerDependencies.
+2.0.0-beta.26); bun resolves them from peerDependencies.
 
 ## Element model (the parts that are easy to get wrong)
 

package/examples/README.md

@@ -16,8 +16,11 @@ 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).
+- `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). `"snapshot-no-aa"` rasterizes without anti-aliasing: cheaper, fine for text and axis-aligned rects, hard-edged on vector content.
 
 ## Scrolling
 - `scroll.tsx` - `createScroll`, the headless scroll primitive: it owns only the clamped offset (re-clamped on layout); you supply the viewport/content nodes via refs, apply the offset to `scrollX`/`scrollY`, and wire input (e.g. `onWheel`) to `scrollBy` yourself.
@@ -33,6 +36,9 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `image.tsx` - `createImage` (async value: fetch + decode + upload) read inside a `<Loading>` boundary and shown with `<texture>`.
 - `inline-image.tsx` - bytes already in memory: `decodeImage` + `createTexture` (both synchronous) show an image with no `<Loading>` boundary. The sync counterpart to `image.tsx`.
 - `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture, animated by driving its `iTime` uniform declaratively through the `<texture params={{...}}>` prop.
+- `gpu-raw-program.tsx` - the raw shading layer: compileShader/linkProgram/createShaderTarget, one vertex stage shared by two programs, with and without the standard header.
+- `window-shader.tsx` - the `shader` prop on `<window>`: the finished frame drawn through a raw-linked warp program before present, click to toggle between warp and identity.
+- `window-shader-history.tsx` - the window shader's frame history: `previous` binds last frame as uPrevious, drawn as a one-frame motion echo behind an orbiting square; click toggles the echo term.
 
 ## Sound
 - `sound.tsx` - `createSound`: decode a clip once from bytes (here a binary import), replay cheaply; `overlap` stacking vs single-voice, `playing()` signal, release on unmount. Points to `createSoundStream` for long tracks streamed from a path.

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/examples/window-shader-history.tsx

@@ -0,0 +1,62 @@
+// `previous: true` on the window shader retains the last resolved frame as a
+// second layer the program samples as uPrevious, rotated each frame - a
+// one-frame history. Here it draws a motion echo behind the orbiting square;
+// click to toggle the echo term off and compare with the plain frame.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, destroyShader, linkProgram } from "@solidrt/core/gpu"
+
+let VERTEX = `#version 300 es
+precision highp float;
+out vec2 vUV;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  // uSource/uPrevious are top-left origin; flip v so the frame lands upright.
+  vUV = vec2(p.x, 1.0 - p.y);
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+`
+
+let ECHO = `
+uniform sampler2D uSource;
+uniform sampler2D uPrevious;
+uniform float uEcho;
+in vec2 vUV;
+void main() {
+  vec4 cur = texture(uSource, vUV);
+  vec4 prev = texture(uPrevious, vUV);
+  // Brightest of the current frame and the decayed previous one: motion
+  // leaves a one-frame ghost trailing it.
+  fragColor = max(cur, prev * uEcho);
+}
+`
+
+function App() {
+  let vs = compileShader("vertex", VERTEX)
+  let fs = compileShader("fragment", ECHO, { header: true })
+  let echoProgram = linkProgram(vs, fs)
+  destroyShader(vs)
+  destroyShader(fs)
+
+  let [angle, setAngle] = createSignal(0)
+  let [echo, setEcho] = createSignal(0.65)
+  onFrame(tick => setAngle(tick / 350))
+
+  return (
+    <window
+      shader={{ program: echoProgram, params: { uEcho: echo() }, previous: true }}
+      onPointerDown={() => setEcho(e => (e > 0 ? 0 : 0.65))}
+      alignItems="center"
+      justifyContent="center"
+    >
+      <rect position="absolute" top={0} right={0} bottom={0} left={0} color="#101826" />
+      <view width={70} height={70} x={Math.cos(angle()) * 150} y={Math.sin(angle()) * 150}>
+        <rect width={70} height={70} radius={16} color="#7ad0ff" />
+      </view>
+      <text position="absolute" bottom={24} fontSize={14} color="#99aabb">
+        Click to toggle the uPrevious echo
+      </text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/window-shader.tsx

@@ -0,0 +1,71 @@
+// The window shader: the finished frame renders into a runtime-owned layer
+// texture and a linked program draws over it into the window, as the last
+// step before present. The program samples the frame as uSource (top-left
+// origin - the vertex stage flips v when mapping onto the window), gets
+// iResolution in physical pixels, and draws attributeless at vertexCount
+// (default 3, the covering triangle).
+//
+// Click anywhere to toggle the warp amount between 0 and 1: at 0 the program
+// is an identity pass, which must be indistinguishable from no shader at all
+// (the orientation/half-pixel regression check from the plan).
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { compileShader, destroyShader, linkProgram } from "@solidrt/core/gpu"
+
+let VERTEX = `#version 300 es
+precision highp float;
+out vec2 vUV;
+void main() {
+  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  // uSource is top-left origin; flip v so the frame lands upright on the
+  // window (the one flip of the frame path, done here in the vertex stage).
+  vUV = vec2(p.x, 1.0 - p.y);
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+`
+
+// { header: true } declares #version, precision, iResolution/iTime and
+// fragColor; uSource, vUV, and the app's own uniforms are declared here.
+let WARP = `
+uniform sampler2D uSource;
+uniform float uAmount;
+in vec2 vUV;
+void main() {
+  vec2 uv = vUV;
+  uv.x += sin(uv.y * 24.0 + iTime * 3.0) * 0.012 * uAmount;
+  uv.y += sin(uv.x * 18.0 - iTime * 2.0) * 0.012 * uAmount;
+  fragColor = texture(uSource, uv);
+}
+`
+
+function App() {
+  let vs = compileShader("vertex", VERTEX)
+  let fs = compileShader("fragment", WARP, { header: true })
+  let warp = linkProgram(vs, fs)
+  destroyShader(vs)
+  destroyShader(fs)
+
+  let [time, setTime] = createSignal(0)
+  let [amount, setAmount] = createSignal(1)
+  onFrame(tick => setTime(tick / 1000))
+
+  return (
+    <window
+      shader={{ program: warp, params: { iTime: time(), uAmount: amount() } }}
+      onPointerDown={() => setAmount(a => (a > 0 ? 0 : 1))}
+      flexDirection="column"
+      gap={12}
+      alignItems="center"
+      justifyContent="center"
+    >
+      <text fontSize={28} color="#222">Window shader</text>
+      <view flexDirection="row" gap={12}>
+        <rect w={90} h={90} radius={12} color="#0077ff" />
+        <rect w={90} h={90} radius={12} color="#ff6a00" />
+        <rect w={90} h={90} radius={12} color="#00c46a" />
+      </view>
+      <text fontSize={14} color="#666">Click to toggle warp (identity at 0)</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,11 +27,11 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.37"
+    "@solidrt/flux-types": "0.0.39"
   },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-beta.20",
-    "@solidjs/universal": "2.0.0-beta.20",
-    "solid-js": "2.0.0-beta.20"
+    "@solidjs/signals": "2.0.0-beta.26",
+    "@solidjs/universal": "2.0.0-beta.26",
+    "solid-js": "2.0.0-beta.26"
   }
 }

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/gamepad.ts

@@ -15,6 +15,12 @@ import { on } from "srt:events"
  * "back", "guide", "leftShoulder", "rightShoulder", "leftStick",
  * "rightStick"). `axes` has sticks ("leftX", "leftY", "rightX", "rightY") in
  * -1..1 and triggers ("leftTrigger", "rightTrigger") in 0..1.
+ *
+ * The snapshot is a faithful report. Note that pressing "back" (select) on a
+ * mapped pad ALSO emits the `back` event (see onBack) - it is the pad-side
+ * sibling of Android's system back, the runtime's exit-to-launcher gesture.
+ * Apps that bind "back" for their own controls should preventDefault that
+ * event.
  */
 export interface GamepadState {
   /** Runtime instance id: unique per connection, not stable across reconnects. */

package/src/gpu.ts

@@ -44,11 +44,30 @@ export {
 export { destroyBuffer, setDrawCount } from "flux:gpu"
 export type { Topology, VertexAttribute } from "flux:gpu"
 
+// The raw shading layer, re-exported as-is - no reactive wrapper, the app
+// owns these lifetimes. compileShader compiles one stage from complete GLSL
+// ES (or with the standard header via { header: true }); linkProgram links a
+// vertex and a fragment stage into a program handle that backs any number of
+// createShaderTarget calls (and compiles nothing per target); destroyShader /
+// destroyProgram free by id space, either order safe against live targets.
+// createShader/createPipeline remain the fused conveniences on top.
+export { compileShader, destroyProgram, destroyShader, linkProgram } from "flux:gpu"
+
 // captureSnapshot renders a node to a texture and readTexture reads any
 // texture's bytes back. Re-exported raw (no reactive auto-cleanup wrapper):
 // captureSnapshot resolves asynchronously, by which point the reactive owner is
 // no longer current, so the caller owns the returned id and frees it with
 // destroyTexture (as with any texture created after an await).
+//
+// Together they are the one-shot bake path: draw something only the engine can
+// produce (shaped text, an SVG, a themed view), capture it, read the pixels and
+// process them on the CPU - baking a glyph atlas is the worked example. Not a
+// rendering path: a capture rasterizes the subtree offscreen, reads it back to
+// the CPU and re-uploads it, costing a full GPU -> CPU -> GPU round trip and a
+// paint pass of latency every call. Batch captures (one paint pass services
+// many), never run them per frame, and do not use them to feed live screen
+// content into a shader - for that the source has to update in place (another
+// pipeline's target, a camera texture).
 export { captureSnapshot, readTexture } from "flux:gpu"
 
 /**
@@ -111,6 +130,37 @@ export function createShader(
   return id
 }
 
+/**
+ * Creates a render target over a program from `linkProgram` and renders it
+ * once, returning the texture id (usable anywhere a normal texture id is,
+ * e.g. `<texture src>`; resize with `setShaderSize`, drive uniforms with
+ * `<texture params>` or `setShaderParams`). Many targets may share one
+ * program, and creating a target compiles nothing. The mesh options mirror
+ * `createPipeline`: a raw-linked program carries its own vertex stage, so a
+ * fullscreen pass is `{ vertexCount: 3 }` over a covering-triangle vertex
+ * stage. Frees the target when the reactive owner is disposed (opt out with
+ * `opts.manual`); the program is yours and outlives it.
+ */
+export function createShaderTarget(
+  program: number,
+  width: number,
+  height: number,
+  opts?: {
+    params?: Record<string, number>
+    textures?: Record<string, number>
+    attributes?: gpu.VertexAttribute[]
+    buffer?: number
+    topology?: gpu.Topology
+    vertexCount?: number
+    depth?: boolean
+    clearColor?: [number, number, number, number]
+  } & CreateOptions,
+): number {
+  let id = gpu.createShaderTarget(program, width, height, opts)
+  if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  return id
+}
+
 /** The reactive shader description `createShaderMemo` builds from. */
 export type ShaderSpec = {
   fragmentSrc: string

package/src/index.ts

@@ -7,7 +7,7 @@ export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, exit
 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"
@@ -27,6 +27,7 @@ export type {
   TextEvent,
   PaintProps,
   WindowProps,
+  WindowShaderProps,
   ViewProps,
   RectProps,
   OvalProps,

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.
@@ -48,6 +56,12 @@ 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
@@ -69,10 +83,24 @@ declare module "srt:apps" {
   export const available: boolean
   /**
    * An installed app: id, display name (the installed manifest's displayName,
-   * defaulting to the id) and current version id (manifest hash).
+   * defaulting to the id) and current version id (manifest hash). `updated` is
+   * when that version became current, in milliseconds since the epoch (0 when
+   * the store's timestamp is unreadable); a repush of an identical manifest
+   * installs nothing and leaves it alone. `size` is the version's
+   * manifest-declared size (bundle plus assets) - claimed rather than walked,
+   * so that listing stays cheap; `info()` reports what is actually on disk.
+   * `icon` is the manifest-declared icon's SVG source, ready for an `<svg>`
+   * src; absent when the app declares none (or the file is unreadable).
    */
-  export type InstalledApp = { id: string; name: string; version: string }
-  /** Installed apps, sorted by name. */
+  export type InstalledApp = {
+    id: string
+    name: string
+    icon?: string
+    version: string
+    updated: number
+    size: number
+  }
+  /** Installed apps, most recently updated first. */
   export function list(): InstalledApp[]
   /**
    * A stored version: id (manifest hash), bytes on disk, whether it is the

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
@@ -242,6 +275,45 @@ export interface WindowProps extends LayoutProps, PointerProps {
   children?: Children
   title?: string
   fullscreen?: boolean
+  /**
+   * Run the window's finished frame through a GPU program as the last step
+   * before it reaches the screen. While declared, the frame renders into a
+   * runtime-owned layer texture the program samples; removing the prop
+   * restores the direct path and frees the layer. Everything else about the
+   * program (compiling, linking, lifetime) is the raw shading layer's:
+   * see compileShader/linkProgram.
+   */
+  shader?: WindowShaderProps | null
+}
+
+/**
+ * A window shader declaration. The program reads the frame through
+ * `uniform sampler2D uSource` (top-left origin, like every sampled texture -
+ * so a vertex stage mapping it onto the window flips the v coordinate) and
+ * is drawn attributeless as triangles, `vertexCount` vertices fetched via
+ * gl_VertexID. `iResolution`, filled by name, is the window size in physical
+ * pixels (the pass covers exactly that). The window is cleared to opaque
+ * black first, so geometry that does not cover it still presents a defined
+ * frame.
+ */
+export interface WindowShaderProps {
+  /** Linked program handle from linkProgram. */
+  program: number
+  /** Float uniforms filled by name, paced to the next real repaint. */
+  params?: Record<string, number>
+  /** Extra sampler2D inputs: uniform name to texture id. */
+  textures?: Record<string, number>
+  /** Vertices drawn (attributeless triangles). Default 3, the covering triangle. */
+  vertexCount?: number
+  /**
+   * Retain the last frame as a second layer the program samples as
+   * `uniform sampler2D uPrevious` (one-frame history: motion echo, frame
+   * differencing). Costs one extra window-sized texture while declared.
+   * Until a second frame exists uPrevious samples opaque black. Only declare
+   * the uPrevious uniform together with this flag - without it the uniform
+   * stays at unit 0 and aliases uSource. Default false.
+   */
+  previous?: boolean
 }
 
 export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
@@ -264,8 +336,13 @@ export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
    * on layout-size or display-scale changes. Content painted outside the
    * element's layout box is cropped, and ancestor scale animations smear the
    * bitmap; best for screen-aligned, static, raster-expensive content.
+   *
+   * "snapshot-no-aa" is "snapshot" rasterized without anti-aliasing: cheaper
+   * (no multisampled scratch, one render pass), but vector content - svg
+   * paths, rounded corners, rotated edges - comes out hard-edged. Text and
+   * axis-aligned rects look identical, so prefer it for plain UI panels.
    */
-  repaintBoundary?: boolean | "snapshot"
+  repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
 }
 
 // draw primitives
@@ -330,8 +407,25 @@ export interface TextProps extends Position, PaintProps, PointerProps {
   maxLines?: number
 }
 
-export interface TextureProps extends Position, PointerProps {
+/**
+ * A raster draw uses only part of a paint. `blendMode` applies, which is how
+ * two GPU layers composite in the tree (a solid pass plus an additive pass)
+ * without a hand-written compositing shader. `color` contributes its alpha
+ * only, as an opacity multiplier; its RGB does not tint, and a gradient does
+ * not replace the texture. `drawStyle` and the stroke props have no effect.
+ * Texture alpha is premultiplied, so additive modes need no manual
+ * premultiplication.
+ */
+export interface TextureProps extends Position, PaintProps, 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

@@ -17,15 +17,12 @@ 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 ----------------
 
@@ -193,22 +190,38 @@ export function onWindowBlur(fn: () => void) {
 
 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>()
+// App handlers for the window-level back event, as a stack: the last one
+// registered is offered the event first, and the first to prevent ends the
+// dispatch. Back is a pop, so the thing most recently put on screen has to
+// answer for it - a dialog that opens over a screen registers after it and must
+// win, and registration order tracks mount order (a parent sets up before its
+// children), so reverse order also reads as innermost-first. Kept in a local
+// registry rather than per-handler bus subscriptions so the default action runs
+// exactly once, after the handlers have had their say.
+let backHandlers: ((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.
+ * event passes to the handler registered before this one, and if none of them
+ * prevents it either, to the default action: exit(). Apps without a handler
+ * exit on back everywhere, which is the correct zero-effort default.
+ *
+ * Handlers form a stack: the most recently registered runs first and the first
+ * to prevent ends the dispatch, so each screen or overlay owns one step of the
+ * back stack and none of them needs to know what the others are doing. A
+ * handler that does not prevent must not act either - the event is still on its
+ * way to whoever will handle it.
+ *
  * 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)
+  backHandlers.push(fn)
+  let cleanup = () => {
+    let i = backHandlers.lastIndexOf(fn)
+    if (i >= 0) backHandlers.splice(i, 1)
+  }
   onCleanup(cleanup)
   return cleanup
 }
@@ -252,77 +265,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", (raw: RawPointer) => {
+      dispatchOrdered(raw, "onPointerEnter")
+    })
+
+    unsubLeave = on("pointerLeave", (raw: RawPointer) => {
+      dispatchOrdered(raw, "onPointerLeave")
+    })
 
-    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)
+    unsubWheel = on("wheel", (raw: RawPointer) => {
+      bubble(raw, "onWheel")
     })
 
     unsubKeyDown = on("keydown", (e: any) => {
@@ -347,7 +354,9 @@ export function attachWindow(_nodeId: number) {
         },
       }
       // Copy first: a handler may unregister (itself or others) mid-dispatch.
-      for (let fn of [...backHandlers]) fn(e)
+      // Top of the stack down, stopping as soon as one takes the event.
+      let stack = [...backHandlers]
+      for (let i = stack.length - 1; i >= 0 && !prevented; i--) stack[i]!(e)
       if (!prevented) exit()
     })