@solidrt/core 0.0.51 → 0.0.52

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 />)

package/examples/{view-viewbox.tsx → view-design-size.tsx}

@@ -1,21 +1,26 @@
-// `viewBox` on a <view> is the fixed-aspect answer to "many screen sizes": you
-// author the whole scene once, in your own made-up design units, and the view
-// scales that space to fit its box. It is SVG's viewBox generalized to any
-// subtree, not an SVG-only thing.
+// `designSize` on a <view> is the fixed-aspect answer to "many screen sizes":
+// you author the whole scene once, in your own made-up design units, and the
+// view scales that space to fit its box. It is SVG's viewBox generalized off
+// the graphics format and onto a layout element - the design size is the only
+// irreducible half of it, since a transform already does what min-x/min-y did.
 //
 // Four facts, each demonstrated below:
-// 1. It NEVER sizes the element. `viewBox` is a pure fit transform; the box
-//    still takes its size from layout (here `flex={1}`). A view with only a
-//    viewBox and no layout size is zero-sized and paints nothing.
+// 1. The view sizes like a REPLACED element (think <img>): its intrinsic size
+//    is the design size, one sized axis derives the other from the design
+//    aspect, and layout props override it as usual - here `flex={1}` takes
+//    the whole window. It never refuses to shrink: a design has no size it
+//    cannot scale below.
 // 2. It fits UNIFORMLY and centers - one scale for both axes, SVG's default
 //    preserveAspectRatio. Content never stretches; the leftover on the loose
 //    axis is letterbox, showing the window background through it.
-// 3. Children live in DESIGN space. Their x/y, w/h, fontSize, stroke widths -
-//    everything resolves against the design size, not the box. The box a child
-//    inherits IS the design size, so a bare `d-rect` fills the design space
-//    and detached text wraps at its width.
+// 3. Children live in DESIGN space, laid-out ones included. x/y, w/h,
+//    fontSize, stroke widths, flex, percentages, text wrapping - everything
+//    resolves against the design size, not the box. The box a child inherits
+//    IS the design size, so a bare `d-rect` fills the design space, detached
+//    text wraps at its width, and a flex row is laid out at the design width
+//    whatever the window - nothing reflows on resize, the fit does the work.
 // 4. Pointer coordinates arrive in design space too. localX/localY on the
-//    viewBox view (and on anything under it) read in design units, so no
+//    design-size view (and on anything under it) read in design units, so no
 //    scale factor is threaded through the app's hit math.
 //
 // The payoff: no `windowSizeClass` branching, no per-breakpoint sizes, no
@@ -44,14 +49,15 @@ function App() {
     <window>
       <d-rect color="#0b0f17" />
 
-      {/* flex={1} sizes the box; viewBox only maps content into it (fact 1). */}
+      {/* flex={1} overrides the intrinsic design size: the box is the whole
+          window, and the fit maps the design into it (fact 1). */}
       <view
         flex={1}
-        viewBox={[DESIGN_W, DESIGN_H]}
+        designSize={[DESIGN_W, DESIGN_H]}
         onPointerMove={(e) => setAt({ x: e.localX, y: e.localY })}
         onPointerLeave={() => setAt(null)}
       >
-        {/* No w/h, so it fills the box it inherits - which under a viewBox is
+        {/* No w/h, so it fills the box it inherits - which under a design size is
             the design space (fact 3). Its edges are the letterbox edges. */}
         <d-rect color="#151b28" />
 
@@ -78,6 +84,18 @@ function App() {
         <Show when={at()}>
           {(a) => <d-oval x={a().x - 8} y={a().y - 8} w={16} h={16} color="#f85149" />}
         </Show>
+
+        {/* A laid-out row under the design size (fact 3): positioned and sized in
+            design units, the bar flexing against the design width. Resize the
+            window: it scales with the scene instead of reflowing. */}
+        <view position="absolute" left={40} right={40} top={364} flexDirection="row" alignItems="center" gap={12}>
+          <text fontSize={16} color="#8b949e">
+            flex row, laid out in design units
+          </text>
+          <view flex={1} height={10}>
+            <d-rect radius={5} color="#1f6feb" />
+          </view>
+        </view>
       </view>
     </window>
   )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -25,14 +25,15 @@
     "examples/",
     "jsx-runtime.d.ts",
     "agents/",
+    "docs/",
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.51"
+    "@solidrt/flux-types": "0.0.52"
   },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.0",
-    "@solidjs/universal": "2.0.0-rc.0",
-    "solid-js": "2.0.0-rc.0"
+    "@solidjs/signals": "2.0.0-rc.1",
+    "@solidjs/universal": "2.0.0-rc.1",
+    "solid-js": "2.0.0-rc.1"
   }
 }

package/src/core.ts

@@ -1,4 +1,5 @@
 import * as tree from "flux:rendertree"
+import type { TextureId } from "flux:gpu"
 import { createSignal, onCleanup } from "@solidjs/signals"
 import { on } from "srt:events"
 
@@ -310,7 +311,8 @@ export interface BoundingBox {
  * reactive: call it inside `onLayout` (or an event handler) to get values for
  * the current frame. Transforms anywhere in the chain (including the node's
  * own) compose fully; the box is the axis-aligned bounds of the transformed
- * quad.
+ * quad. A detached node reports its painted box: its own w/h (or the
+ * inherited box), or for `d-line` and `d-path` the geometry plus its stroke.
  */
 export function getBoundingBox(node: { id: number }): BoundingBox | null {
   return tree.getBoundingBox(node.id)
@@ -324,6 +326,22 @@ export function getBoundingBoxViewport(node: { id: number }): BoundingBox | null
   return tree.getBoundingBoxViewport(node.id)
 }
 
+/**
+ * The texture id of a snapshot boundary's retained rasterization
+ * (`repaintBoundary="snapshot"`): the subtree's pixels as a live texture any
+ * GPU consumer - a `<texture>`, a shader or draw target binding, a 3d
+ * material - samples by id. Allocated on the first call and stable for the
+ * node's lifetime; the runtime re-points it at the current pixels after every
+ * rasterization, and only when the subtree changes (a static panel on an
+ * animated consumer costs no repaint). Empty until the first paint. Owned by
+ * the boundary: `destroyTexture` throws on it, and unmounting the boundary
+ * releases it. Throws if the node is not a snapshot boundary. Not a readback:
+ * for pixels on the CPU use `captureSnapshot`.
+ */
+export function snapshotTexture(node: { id: number }): TextureId {
+  return tree.snapshotTexture(node.id)
+}
+
 /**
  * Measures the rendered size of `text` in layout pixels under the given font
  * options (family, size, weight, style, maxLines), without adding it to the