@solidrt/core 0.0.50 → 0.0.52

package/docs/reference/text.md

@@ -0,0 +1,46 @@
+# Text
+
+`<text>` is a shaped paragraph, and `<span>` is a styled run inside it. Text is
+laid out by the engine's own layout and shaping, not by a browser: a paragraph
+is one element that wraps, aligns and truncates as a unit.
+
+```tsx
+<text fontSize={16} maxLines={2} textOverflow="ellipsis">
+  Weather for <span fontWeight={700}>Tuesday</span>
+</text>
+```
+
+## Run style
+
+The style props of a run: paragraph defaults on `<text>`, overrides on
+`<span>`.
+
+{{ decl packages/core/src/types.d.ts TextRunProps }}
+
+The cascade is intra-paragraph only. A span inherits from its enclosing span
+and then from the `<text>`; nothing inherits across the element tree, so there
+is no ambient font size to chase.
+
+`lineHeight` is the one prop with a CSS reflex worth unlearning: it is a
+multiplier of `fontSize`, not a pixel value.
+
+## text
+
+{{ decl packages/core/src/types.d.ts TextProps }}
+
+Paragraph-level behavior lives here: `textAlign`, `maxLines` with
+`textOverflow`, `textIndent`, and `textWrap` for line-breaking quality
+(`"balance"` for headings, `"pretty"` to avoid a lone last word).
+
+An element child of a `<text>` is an inline atom, which is where the
+[layout](/core/reference/layout/) props `float` and `clear` apply: a floated
+atom leaves the flow and the lines it overlaps wrap around it.
+
+## span
+
+{{ decl packages/core/src/types.d.ts SpanProps }}
+
+Inline only: its children are text and other spans, and it has no layout box,
+which is why it is the one element with no detached form. Pointer handlers on
+a span fire for the boxes its text occupies on each line it spans, and bubble
+to the enclosing spans and the text.

package/docs/reference/transforms.md

@@ -0,0 +1,35 @@
+# Transforms
+
+Transform props apply after layout, at composite time. Nothing re-records and
+nothing reflows, on a laid-out `view` as much as on a `d-view`, so these are
+the props to animate.
+
+They live on `ViewOwnProps`, which means both `view` and `d-view` have them;
+see [elements](/core/reference/elements/).
+
+{{ decl packages/core/src/types.d.ts TransformProps }}
+
+## Origin
+
+`originX` and `originY` are the point rotation and scale pivot around, split
+per axis to match the engine's `x`/`y` prop convention.
+
+{{ decl packages/core/src/types.d.ts OriginX }}
+
+{{ decl packages/core/src/types.d.ts OriginY }}
+
+A percentage origin tracks the layout size with no reactive wiring of your
+own. On a `d-view` there is no box, so the origin defaults to the view's local
+`(0,0)` - the origin its children's coordinates are authored against - and
+`pct()` or keyword origins resolve against the inherited box, which is rarely
+what you want. Pivot a `d-view` around its content by setting the origin in
+pixels.
+
+## Opacity
+
+`opacity` is group opacity: the children composite together and then fade as a
+whole, like CSS. It costs a compositing layer while below 1, unless the view
+is a `repaintBoundary`, where it is hoisted to composite time for free.
+
+To fade a single primitive, put the alpha in its `color` instead. Paint alpha
+costs nothing.

package/docs/reference/types.md

@@ -0,0 +1,34 @@
+# Types
+
+The shared aliases the element props refer to.
+
+## Color
+
+{{ decl packages/core/src/types.d.ts Color }}
+
+Anywhere a `color` prop is accepted, a `Gradient` from
+`createLinearGradient` or `createRadialGradient` is accepted too. Gradient
+stops are positions in 0..1, not percentages.
+
+## Percentages
+
+{{ decl packages/core/src/types.d.ts Pct }}
+
+`pct(50)` is the only way to write a percentage as a value. It is branded, so
+a percentage cannot be confused with a pixel count by accident, and it
+resolves against the element box wherever it is used - layout dimensions,
+gaps, and transform origins alike.
+
+## Children
+
+{{ decl packages/core/src/types.d.ts Children }}
+
+The element type is SolidJS's own, so the control-flow components (`For`,
+`Show`, `Switch`) return something the JSX types accept.
+
+## JSX plumbing
+
+One declaration exists purely to tell TypeScript which prop receives JSX
+children. It is not something an app refers to:
+
+{{ decl packages/core/src/types.d.ts ElementChildrenAttribute }}

package/examples/README.md

@@ -8,7 +8,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 ## Host elements and layout
 - `window-root.tsx` - the minimal app; the root must be `<window>`.
 - `view-layout.tsx` - `<view>` as a flex container; containers do not paint.
-- `view-viewbox.tsx` - `viewBox` on a `<view>`: author a scene once in fixed design units and let the view uniformly scale-and-center (letterbox) that space into its box. A pure fit transform - it never sizes the element (layout still does); children live in design space (the box they inherit IS the design size, so a bare `d-rect` fills it); pointer `localX`/`localY` arrive in design units. The fixed-aspect alternative to `windowSizeClass` reflow for diagrams, slides, dashboards, game boards.
+- `view-design-size.tsx` - `designSize` on a `<view>`: author a scene once in fixed design units and let the view uniformly scale-and-center (letterbox) that space into its box. Children live in design space for layout as well as paint (the box they inherit IS the design size, so a bare `d-rect` fills it and a flex row lays out against the design width, never reflowing on resize); the view itself sizes like a replaced element whose intrinsic size is the design size; pointer `localX`/`localY` arrive in design units. The fixed-aspect alternative to `windowSizeClass` reflow for diagrams, slides, dashboards, game boards, scaled panels.
 - `background-rect.tsx` - a `d-rect` filling its parent as a background.
 - `detached-positioning.tsx` - the `d-` prefix: x/y placement, no reflow, detached-only children.
 - `text-paint-styling.tsx` - the uniform `color` prop; `drawStyle="stroke"` vs fill.
@@ -21,6 +21,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
+- `snapshot-texture.tsx` - `snapshotTexture(ref)`: a `repaintBoundary="snapshot"` view's rasterized pixels as a live texture id; a shader texture samples the panel and a sibling `<texture>` shows the warped copy. The boundary re-rasterizes only when its content changes.
 - `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
@@ -28,7 +29,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 
 ## Window state
 - `window-signals.tsx` - reactive `windowSize()` / `safeArea()` accessors (prefer over `onResize`).
-- `responsive-grid.tsx` - one app across phone/tablet/desktop: `capabilities.windowSizeClass` (Material 3 breakpoints, a reactive getter) drives the column count and `windowSize()` sizes each card; reflows on resize. The reflow answer; for fixed-aspect content use `view-viewbox.tsx` instead.
+- `responsive-grid.tsx` - one app across phone/tablet/desktop: `capabilities.windowSizeClass` (Material 3 breakpoints, a reactive getter) drives the column count and `windowSize()` sizes each card; reflows on resize. The reflow answer; for fixed-aspect content use `view-design-size.tsx` instead.
 
 ## Overlays
 - `portal.tsx` - `createPortal` relocating content to the window root to escape clipping.
@@ -47,11 +48,12 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `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. `createPcmSound` for a synthesised clip from raw samples (a generated sine sweep). Points to `createSoundStream` for long tracks streamed from a path.
+## Audio
+- `audio.tsx` - `createSound`: decode a clip once from bytes (here a binary import), replay cheaply; `overlap` stacking vs single-voice, `playing()` signal, release on unmount. `createPcmSound` for a synthesised clip from raw samples (a generated sine sweep). Points to `createSoundStream` for long tracks streamed from a path.
 
 ## Vector graphics
-- `parse-svg.tsx` - `parseSvg` turns a whole SVG *document string* (not HTML/JSX children) into plain draw data mapped to `<d-path>` inside a `viewBox`-fitted view; per-shape hover highlighting shows the payoff (exact-outline hit testing, recolor without re-parse), plus a `currentColor` icon recolored via the `color` option. This is how to use existing icon libraries (Lucide, Heroicons, etc.) - hand their SVG source to `parseSvg`.
+- `line-points.tsx` - `points` on `line`/`d-line`: a flat `[x0, y0, x1, y1, ...]` array (or `Float32Array`) makes the polyline whose geometry is numbers - a live trace rewritten every frame with no `d` string to parse, `closed` outlines, `drawStyle="fill"` polygons (a line's paint defaults to stroke), per-segment dashing, and a laid-out `<line points>` measuring its box from the points.
+- `parse-svg.tsx` - `parseSvg` turns a whole SVG *document string* (not HTML/JSX children) into plain draw data mapped to `<d-path>` inside a `designSize`-fitted view; per-shape hover highlighting shows the payoff (exact-outline hit testing, recolor without re-parse), plus a `currentColor` icon recolored via the `color` option. This is how to use existing icon libraries (Lucide, Heroicons, etc.) - hand their SVG source to `parseSvg`.
 
 ## Bundling assets
 - `binary-import.tsx` - `import bytes from "./file" with { type: "binary" }` inlines a file's bytes into the bundle as a `Uint8Array` (the bytes are in memory, so `inline-image.tsx` displays them with the synchronous `decodeImage` + `createTexture` path).

package/examples/{sound.tsx → audio.tsx}

@@ -23,7 +23,7 @@
 // demand and stays off the heap. Same play()/stop()/playing() surface,
 // always single-voice.
 import { render } from "@solidrt/core"
-import { createPcmSound, createSound } from "@solidrt/core/sound"
+import { createPcmSound, createSound } from "@solidrt/core/audio"
 import blipBytes from "./blip.wav" with { type: "binary" }
 
 const RATE = 44100

package/examples/gpu-pipeline.tsx

@@ -101,11 +101,11 @@ function App() {
   let [time, setTime] = createSignal(0)
   onFrame((tick) => setTime(tick / 1000))
 
-  // Fill the window: the viewBox fits and centers the square content into
+  // Fill the window: the design-size fits and centers the square content into
   // the full-window view, so the projection is never stretched.
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[1024, 1024]}>
+      <view width={pct(100)} height={pct(100)} designSize={[1024, 1024]}>
         <texture src={id} params={{ uTime: time() }} width={1024} height={1024} />
       </view>
     </window>

package/examples/gpu-sprites.tsx

@@ -0,0 +1,102 @@
+// The zero-copy per-frame geometry path: instanced quads whose records are
+// rewritten every frame through a buffer write lease. beginBufferWrite hands
+// back a Float32Array over runtime-owned memory (contents unspecified - fill
+// everything you publish), the frame callback writes every live record into
+// it, and endBufferWrite publishes by MOVING the block to the raster thread:
+// no data copy anywhere on the CPU path, and no per-sprite property writes.
+// Compare gpu-instancing.tsx, where the records are static and only the draw
+// range changes; here the records themselves are the animation.
+//
+// The buffer is created from a byte LENGTH (zeroed storage) - the natural
+// create when every byte arrives through the lease. Publishing a prefix and
+// setDraw({ instanceCount }) keep buffer capacity and live population
+// independent: reserve the max up front, publish what exists this frame.
+import { render, onFrame } from "@solidrt/core"
+import { beginBufferWrite, createBuffer, createPipelineTexture, endBufferWrite, glsl, setDraw } from "@solidrt/core/gpu"
+
+const MAX_SPRITES = 2000
+// floats per record: center vec2, half-size f32, tint vec3.
+const RECORD = 6
+
+let VERTEX = glsl`
+  in vec2 aPos;
+  in vec2 iCenter;
+  in float iSize;
+  in vec3 iTint;
+  out vec3 vTint;
+
+  void main() {
+    gl_Position = vec4(iCenter + aPos * iSize, 0.0, 1.0);
+    vTint = iTint;
+  }
+`
+
+let FRAGMENT = glsl`
+  in vec3 vTint;
+
+  void main() {
+    fragColor = vec4(vTint, 1.0);
+  }
+`
+
+// Simulation state lives in plain arrays; the instance buffer holds only
+// this frame's published snapshot of it.
+let x = new Float32Array(MAX_SPRITES)
+let y = new Float32Array(MAX_SPRITES)
+let vx = new Float32Array(MAX_SPRITES)
+let vy = new Float32Array(MAX_SPRITES)
+for (let i = 0; i < MAX_SPRITES; i++) {
+  x[i] = Math.random() * 1.9 - 0.95
+  y[i] = Math.random() * 1.9 - 0.95
+  vx[i] = (Math.random() * 2 - 1) * 0.01
+  vy[i] = (Math.random() * 2 - 1) * 0.01
+}
+
+function App() {
+  // One unit quad (triangle strip), reused by every instance.
+  let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), { label: "sprite-quad" })
+  let records = createBuffer(MAX_SPRITES * RECORD * 4, { label: "sprite-records" })
+  let id = createPipelineTexture(VERTEX, FRAGMENT, 720, 720, null, {
+    label: "sprites",
+    topology: "triangle-strip",
+    vertexCount: 4,
+    attributes: [{ name: "aPos", format: "vec2" }],
+    buffer: quad,
+    instanceAttributes: [
+      { name: "iCenter", format: "vec2" },
+      { name: "iSize", format: "f32" },
+      { name: "iTint", format: "vec3" },
+    ],
+    instanceBuffer: records,
+    instanceCount: MAX_SPRITES,
+    clearColor: [0.03, 0.03, 0.06, 1],
+  })
+
+  onFrame(() => {
+    let out = beginBufferWrite(records)
+    for (let i = 0; i < MAX_SPRITES; i++) {
+      let nx = x[i]! + vx[i]!
+      let ny = y[i]! + vy[i]!
+      if (nx < -0.95 || nx > 0.95) vx[i] = -vx[i]!
+      else x[i] = nx
+      if (ny < -0.95 || ny > 0.95) vy[i] = -vy[i]!
+      else y[i] = ny
+      let at = i * RECORD
+      out[at] = x[i]!
+      out[at + 1] = y[i]!
+      out[at + 2] = 0.01 + 0.008 * (i % 5)
+      out[at + 3] = 0.5 + 0.5 * Math.cos(i * 0.11)
+      out[at + 4] = 0.5 + 0.5 * Math.cos(i * 0.13 + 2.1)
+      out[at + 5] = 0.5 + 0.5 * Math.cos(i * 0.17 + 4.2)
+    }
+    endBufferWrite(records)
+  })
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} width={480} height={480} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/line-points.tsx

@@ -0,0 +1,145 @@
+// `points` turns a line into a polyline: a flat [x0, y0, x1, y1, ...] array in
+// the element's local space, so geometry that changes every frame is one
+// array write - no `d` string to format and re-parse. Three uses below:
+// 1. A live trace: a Float32Array rebuilt each frame in onFrame and set as
+//    `points`. Typed arrays marshal like number[]; nothing is parsed.
+// 2. A closed outline: `closed` strokes the segment back to the first point
+//    and joins there instead of capping both ends; the join style shows at
+//    the apex. A line's paint defaults to stroke; drawStyle="fill" fills the
+//    polygon instead (implicitly closed), "stroke-and-fill" does both.
+//    Dashing runs along the whole stroke, through the vertices.
+// 3. Marching ants: `dashOffset` slides the dash pattern, so writing it every
+//    frame animates the dashes. The ring is dense (6 px segments under
+//    12 px dashes), which only works because the phase carries across
+//    vertices; the two-point d-line and the d-path go through the same
+//    walker (a path's dashes are pieces of its curves, stroked as curves).
+// 4. Partial draw: `pathLength={1}` makes the dash units fractions of the
+//    geometry's length, so `onLength={0.77} offLength={1}` draws the first
+//    77% and an `onLength` written from 0 to 1 draws the geometry on, without
+//    knowing its length.
+// 5. A laid-out <line points>: the points are content (like a path's `d`), so
+//    the box measures from their extent and takes part in the row.
+// The two-endpoint form (x1..y2, on d-line only) is unchanged; while `points`
+// is set it takes precedence over the endpoints.
+import { render, onFrame, createSignal } from "@solidrt/core"
+
+const SAMPLES = 200
+const TRACE_W = 560
+const TRACE_H = 160
+const TRIANGLE = [20, 100, 70, 20, 120, 100]
+const ZIGZAG = [0, 0, 30, 24, 60, 0, 90, 24, 120, 0]
+const RING = ring(70, 60, 45, 48)
+const CURVE = "M20 60 C 60 0, 100 120, 140 60 S 200 20, 200 60"
+const ANTS_SPEED = 40 // local units per second
+const DRAW_PERIOD = 3 // seconds per draw-on cycle
+
+function ring(cx: number, cy: number, r: number, n: number): number[] {
+  let pts: number[] = []
+  for (let i = 0; i < n; i++) {
+    let a = (i / n) * Math.PI * 2
+    pts.push(cx + Math.cos(a) * r, cy + Math.sin(a) * r)
+  }
+  return pts
+}
+
+// A travelling wave inside a sine envelope, sampled into x, y pairs.
+function wave(t: number): Float32Array {
+  let pts = new Float32Array(SAMPLES * 2)
+  for (let i = 0; i < SAMPLES; i++) {
+    let u = i / (SAMPLES - 1)
+    pts[2 * i] = u * TRACE_W
+    pts[2 * i + 1] = TRACE_H / 2 + Math.sin(u * 14 - t * 4) * Math.sin(u * Math.PI) * (TRACE_H / 2 - 8)
+  }
+  return pts
+}
+
+function App() {
+  let [trace, setTrace] = createSignal<Float32Array>(wave(0))
+  let [ants, setAnts] = createSignal(0)
+  let [drawn, setDrawn] = createSignal(0)
+  onFrame((tick) => {
+    setTrace(wave(tick / 1000))
+    setAnts((tick / 1000) * ANTS_SPEED)
+    setDrawn(((tick / 1000) % DRAW_PERIOD) / DRAW_PERIOD)
+  })
+
+  return (
+    <window padding={24} gap={20}>
+      <d-rect color="#0b0f17" />
+
+      <text fontSize={16} color="#8b949e">
+        live trace: a Float32Array of {SAMPLES} points written every frame
+      </text>
+      <view width={TRACE_W} height={TRACE_H} flexShrink={0}>
+        <d-rect radius={8} color="#151b28" />
+        <d-line points={trace()} color="#3fb950" strokeWidth={3} strokeJoin="round" />
+      </view>
+
+      <text fontSize={16} color="#8b949e">
+        closed (round join), open (round caps), filled, stroke-and-fill dashed
+      </text>
+      <view flexDirection="row" flexWrap="wrap" gap={20}>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line points={TRIANGLE} closed color="#e3b341" strokeWidth={8} strokeJoin="round" />
+        </view>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line points={TRIANGLE} color="#e3b341" strokeWidth={8} strokeCap="round" />
+        </view>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line points={TRIANGLE} drawStyle="fill" color="#a371f7" />
+        </view>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line points={TRIANGLE} closed drawStyle="stroke-and-fill" onLength={12} offLength={8} color="#f85149" strokeWidth={3} />
+        </view>
+      </view>
+
+      <text fontSize={16} color="#8b949e">
+        marching ants: dashOffset written every frame, on a dense ring, a segment and a path
+      </text>
+      <view flexDirection="row" flexWrap="wrap" gap={20}>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line points={RING} closed onLength={12} offLength={8} dashOffset={ants()} color="#e3b341" strokeWidth={3} />
+        </view>
+        <view width={300} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line x1={20} y1={60} x2={280} y2={60} onLength={0} offLength={14} dashOffset={-ants()} color="#79c0ff" strokeWidth={6} strokeCap="round" />
+        </view>
+        <view width={220} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-path d={CURVE} drawStyle="stroke" onLength={10} offLength={6} dashOffset={ants()} color="#f778ba" strokeWidth={3} strokeCap="round" />
+        </view>
+      </view>
+
+      <text fontSize={16} color="#8b949e">
+        partial draw: pathLength=1 makes the pattern fractional, 77% of the curve and a triangle drawing on
+      </text>
+      <view flexDirection="row" flexWrap="wrap" gap={20}>
+        <view width={220} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-path d={CURVE} drawStyle="stroke" pathLength={1} onLength={0.77} offLength={1} color="#3fb950" strokeWidth={4} strokeCap="round" />
+        </view>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-line points={TRIANGLE} closed pathLength={1} onLength={drawn()} offLength={1} color="#79c0ff" strokeWidth={4} strokeCap="round" strokeJoin="round" />
+        </view>
+      </view>
+
+      <view flexDirection="row" alignItems="center" gap={12}>
+        <text fontSize={16} color="#8b949e">
+          laid out:
+        </text>
+        <line points={ZIGZAG} color="#1f6feb" strokeWidth={3} strokeJoin="round" />
+        <text fontSize={16} color="#8b949e">
+          the box measures from the points
+        </text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/parse-svg.tsx

@@ -3,7 +3,7 @@
 // it the source text (a string you import, fetch, or inline) and get back the
 // document's intrinsic size plus a flat list of draws whose keys match the
 // path element's props - so rendering is a map to <d-path>, wrapped in a view
-// whose `viewBox` fits the document's coordinate space into the box.
+// whose `designSize` fits the document's coordinate space into the box.
 //
 // The point of draws-as-data over an opaque document element: every shape is
 // a real node you own. Below, the house highlights the shape under the
@@ -28,7 +28,7 @@ import { render, parseSvg, svg, createMemo, createSignal, For } from "@solidrt/c
 // the string unchanged; it exists so editors highlight the markup (like `glsl`
 // for shader sources).
 const HOUSE = svg`
-<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+<svg designSize="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
   <rect x="20" y="45" width="60" height="45" fill="#457b9d"/>
   <path d="M10 50 L50 15 L90 50 Z" fill="#e63946"/>
   <rect x="42" y="62" width="16" height="28" fill="#f1faee"/>
@@ -37,7 +37,7 @@ const HOUSE = svg`
 
 // Monochrome icon (Lucide arrow-right) drawn with currentColor, recolored below.
 const ARROW = svg`
-<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
+<svg designSize="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
      stroke-linecap="round" stroke-linejoin="round">
   <path d="M5 12h14"/>
   <path d="M12 5l7 7-7 7"/>
@@ -54,7 +54,7 @@ function InteractiveHouse() {
   // re-records only when a draw inside it changes (hover), never because a
   // sibling elsewhere on the screen did.
   return (
-    <view repaintBoundary width={240} height={240} viewBox={[doc().width, doc().height]}>
+    <view repaintBoundary width={240} height={240} designSize={[doc().width, doc().height]}>
       <For each={doc().draws}>
         {(draw, i) => (
           <d-path
@@ -69,14 +69,14 @@ function InteractiveHouse() {
   )
 }
 
-// The plain pattern: memoized parse, viewBox-fitted box, draws mapped to
+// The plain pattern: memoized parse, designSize-fitted box, draws mapped to
 // <d-path>, and a plain repaintBoundary (the DL-reuse tier, not "snapshot")
 // so the static subtree never re-records alongside animating siblings. The
 // components-package Icon is this plus theming.
 function Svg(props: { src: string; size: number; color?: string }) {
   let doc = createMemo(() => parseSvg(props.src, { color: props.color }))
   return (
-    <view repaintBoundary width={props.size} height={props.size} viewBox={[doc().width, doc().height]}>
+    <view repaintBoundary width={props.size} height={props.size} designSize={[doc().width, doc().height]}>
       <For each={doc().draws}>{(draw) => <d-path {...draw} />}</For>
     </view>
   )

package/examples/responsive-grid.tsx

@@ -12,7 +12,7 @@
 // This is the REFLOW answer, for layouts that genuinely rearrange across form
 // factors. For content with fixed internal geometry (diagrams, slides,
 // dashboards, game boards) do not branch on window size at all: author one
-// design space and let `viewBox` scale it to fit - see view-viewbox.tsx.
+// design space and let `designSize` scale it to fit - see view-design-size.tsx.
 import { render, capabilities, windowSize, createMemo, For } from "@solidrt/core"
 
 const GAP = 16

package/examples/scroll.tsx

@@ -11,7 +11,7 @@
 // Capture both with refs, pass their accessors to createScroll, then apply the
 // returned offset to the viewport's scrollX/scrollY. createScroll does no input,
 // so wire an event (here onWheel) to scroll.scrollBy - positive dy moves content
-// up. scrollTo(x, y) jumps to an absolute, clamped offset.
+// up. scrollTo({ x, y }) jumps to an absolute, clamped offset.
 import { render, For, createScroll } from "@solidrt/core"
 import type { WheelEvent } from "@solidrt/core"
 
@@ -22,7 +22,7 @@ function App() {
   // Default axis is "vertical"; pass { axis: "horizontal" } or "both" for others.
   let scroll = createScroll(() => viewport, () => content)
 
-  let onWheel = (e: WheelEvent) => scroll.scrollBy(e.deltaX, e.deltaY)
+  let onWheel = (e: WheelEvent) => scroll.scrollBy({ x: e.deltaX, y: e.deltaY })
 
   let rows = Array.from({ length: 30 }, (_, i) => i)
 

package/examples/snapshot-texture.tsx

@@ -0,0 +1,72 @@
+// A UI subtree as a live texture. snapshotTexture(ref) returns the texture id
+// behind a repaintBoundary="snapshot" view: its rasterized pixels, as an
+// ordinary texture id any GPU consumer samples. Here a shader texture binds
+// it as uPanel and a sibling <texture> shows the result, so the panel on the
+// left and its warped twin on the right are the same pixels. The id is
+// stable; the runtime re-points it after every re-rasterization, and the
+// boundary only re-rasterizes when its subtree changes - so the warp
+// animates every frame while the panel's text is painted once per edit.
+//
+// Tap the panel to count. Both copies update, the mirror through the GPU.
+import { render, onFrame, createSignal, snapshotTexture, Show } from "@solidrt/core"
+import { createShaderTexture, glsl } from "@solidrt/core/gpu"
+
+let MIRROR = glsl`
+  uniform sampler2D uPanel;
+  uniform float uTime;
+  void main() {
+    vec2 uv = vUV;
+    uv.x += sin(uv.y * 20.0 + uTime * 3.0) * 0.02;
+    vec4 panel = texture(uPanel, uv);
+    // Premultiplied source: tint the color, keep the alpha.
+    float glow = 0.5 + 0.5 * sin(uTime * 2.0 + uv.y * 6.0);
+    fragColor = vec4(panel.rgb * vec3(1.0, 0.7 + 0.3 * glow, 0.6), panel.a);
+  }
+`
+
+function App() {
+  let [count, setCount] = createSignal(0)
+  let [time, setTime] = createSignal(0)
+  onFrame(tick => setTime(tick / 1000))
+
+  let [panel, setPanel] = createSignal<{ id: number }>()
+
+  return (
+    <window alignItems="center" justifyContent="center" gap={40} flexDirection="row">
+      <view
+        ref={(n: { id: number }) => setPanel(n)}
+        repaintBoundary="snapshot"
+        onPointerDown={() => setCount(c => c + 1)}
+        width={240}
+        height={160}
+        padding={20}
+        gap={12}
+        flexDirection="column"
+      >
+        <rect position="absolute" width="100%" height="100%" radius={12} color="#1e2a44" />
+        <text fontSize={20} color="#ffffff">
+          Live panel
+        </text>
+        <text fontSize={40} color="#ffd166">
+          {String(count())}
+        </text>
+        <text fontSize={14} color="#9fb3d9">
+          tap to count
+        </text>
+      </view>
+      <Show when={panel()} keyed>
+        {p => {
+          // The id is valid as soon as the boundary exists; the texture is
+          // empty until its first paint, then live.
+          let mirror = createShaderTexture(MIRROR, 480, 320, { uTime: 0 }, {
+            textures: { uPanel: snapshotTexture(p) },
+            label: "panel-mirror",
+          })
+          return <texture src={mirror} width={240} height={160} params={{ uTime: time() }} />
+        }}
+      </Show>
+    </window>
+  )
+}
+
+render(() => <App />)