@solidrt/core 0.0.38 → 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

@@ -20,7 +20,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `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.
@@ -36,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/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.38",
+  "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.38"
+    "@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/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

@@ -27,6 +27,7 @@ export type {
   TextEvent,
   PaintProps,
   WindowProps,
+  WindowShaderProps,
   ViewProps,
   RectProps,
   OvalProps,

package/src/runtime-modules.d.ts

@@ -83,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/types.d.ts

@@ -275,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 {
@@ -297,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
@@ -363,7 +407,16 @@ 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).

package/src/window.ts

@@ -190,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
 }
@@ -338,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()
     })