@solidrt/core 0.0.22 → 0.0.24

package/AGENTS.md

@@ -7,6 +7,61 @@ trust this file and the types in src/types.d.ts and jsx-runtime.d.ts.
 SolidRT is a custom SolidJS renderer: it paints through a Rust runtime, not the
 DOM. There is no HTML, no CSS cascade, no `className`.
 
+## The window is device-sized - design fluid
+
+A SolidRT window is host-sized and resizable, and the SAME app runs on phones,
+tablets, and desktops. There is no default "desktop" size to design against.
+Design fluid by default: derive sizing and layout from the live window, do not
+hardcode desktop pixels.
+
+- Size the layout from `windowSize()` / `capabilities.windowSizeClass`, not from
+  fixed pixel widths. Let flex (`flex`, `flexWrap`, `gap`) and percentages carry
+  the layout so it reflows on resize instead of clipping or leaving dead space.
+- Gate hover-only affordances on `capabilities.hover`. Hover-zoom, hover-reveal,
+  and tooltips are dead on a touch device with no pointer that can rest. When
+  `capabilities.touch`, provide a tap/press path to the same action.
+- `windowSizeClass` uses Material 3 width breakpoints (logical px): `compact`
+  (<600), `medium` (600-840), `expanded` (>=840). Drive column counts / layout
+  switches off it (see the responsive-grid example).
+
+`env` and `capabilities` (both exported from `@solidrt/core`) are the two
+objects that expose this. They are plain objects with REACTIVE GETTERS, not
+functions - read them as `capabilities.windowSizeClass`, `env.displayScale`
+(NOT `capabilities()`); the getter reads reactive state underneath, so a read
+inside JSX / a memo / an effect re-runs when it changes. (`windowSize()` and
+`safeArea()` from `./window` ARE functions - call those.)
+
+```ts
+import { env, capabilities } from "@solidrt/core"
+
+env.windowSize        // { width, height } (same value as windowSize())
+env.displayScale      // device pixel ratio (hi-DPI factor)
+env.safeArea          // inset distances from each edge
+env.systemTheme       // "dark" | "light" | "unknown" (resolves after startup)
+env.orientation       // "portrait" | "landscape" | ... | "unknown"
+
+capabilities.windowSizeClass   // "compact" | "medium" | "expanded"
+capabilities.hover             // a pointer can rest over content (mouse/trackpad)
+capabilities.touch             // direct touch input present
+capabilities.precisePointer    // pixel-precise pointing (mouse/trackpad)
+capabilities.keyboardNav       // hardware-key navigation available
+```
+
+Read behavior decisions through `capabilities`; read `env` directly only when
+you need the raw fact (e.g. `env.displayScale` for asset sizing below).
+
+### Vectors vs raster, and hi-DPI
+
+Because the drawn size is fluid and the display DPI varies, asset format is a
+real design decision, not an afterthought:
+
+- Prefer VECTORS (`<svg>`, `<d-path>`) whenever the render size is fluid or DPI
+  varies - they stay crisp at any size x `displayScale()`.
+- RASTER (`<texture>` / `createImage`) needs source resolution >= displayed size
+  x `env.displayScale`, or it softens on hi-DPI. Author raster at 2-3x the
+  largest size you will ever draw it. A 256px PNG blown up large on a hi-DPI
+  tablet will look soft; the same art as SVG will not.
+
 ## Setup
 
 ```sh

package/examples/README.md

@@ -16,18 +16,26 @@ 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`.
 
+## 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).
+
+## 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.
+
 ## 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.
 
 ## Overlays
 - `portal.tsx` - `createPortal` relocating content to the window root to escape clipping.
 
 ## Images and GPU
 - `image.tsx` - `createImage` (async value: fetch + decode + upload) read inside a `<Loading>` boundary and shown with `<texture>`.
-- `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture, animated via `setShaderParams`.
+- `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.
 
 ## Vector graphics
 - `svg.tsx` - `<svg src={...}>` draws a whole SVG *document string* (not HTML/JSX children); multi-color fills vs a `currentColor` icon recolored by the `color` prop. This is how to use existing icon libraries (Lucide, Heroicons, etc.) - hand their SVG source to `src`.
 
 ## Bundling assets
-- `binary-import.tsx` - `import bytes from "./file" with { type: "binary" }` inlines a file's bytes into the bundle as a `Uint8Array` (combine with `image.tsx` to display an inlined image). `with { type: "text" }` works the same way for a string.
+- `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). `with { type: "text" }` works the same way for a string.

package/examples/binary-import.tsx

@@ -6,8 +6,10 @@
 //
 // This example shows only the binary import itself: it reports the imported
 // file's length and leading bytes. What you do with the bytes afterwards is a
-// separate concern - e.g. hand them to createImage to decode and display an
-// image (see image.tsx), or to decodeImage/createTexture for manual control.
+// separate concern. Since inlined bytes are already in memory, the synchronous
+// path fits: decodeImage(bytes) + createTexture (no fetch, no <Loading>) - see
+// inline-image.tsx. Reach for createImage instead when the source is a string
+// URL loaded at runtime, or when you want the source to swap reactively.
 import { render } from "@solidrt/core"
 import bytes from "./logo.png" with { type: "binary" }
 

package/examples/gpu-shader.tsx

@@ -6,10 +6,11 @@
 // disposed.
 //
 // iResolution is filled in for you, but iTime is NOT - drive it (and any other
-// uniform) yourself with setShaderParams from onFrame to animate. The shader's
-// size is baked in at creation.
-import { render, onFrame } from "@solidrt/core"
-import { createShader, setShaderParams } from "@solidrt/core/gpu"
+// uniform) declaratively via the <texture> element's params prop; it applies at
+// the next repaint, so a signal updated every frame stays paced to actual frames.
+// The shader's size is baked in at creation.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createShader } from "@solidrt/core/gpu"
 
 let FRAGMENT = `
 void main() {
@@ -24,11 +25,12 @@ void main() {
 
 function App() {
   let id = createShader(FRAGMENT, 512, 512, { iTime: 0 })
-  onFrame((tick) => setShaderParams(id, { iTime: tick / 1000 }))
+  let [time, setTime] = createSignal(0)
+  onFrame((tick) => setTime(tick / 1000))
 
   return (
     <window alignItems="center" justifyContent="center">
-      <texture src={id} width={400} height={400} />
+      <texture src={id} params={{ iTime: time() }} width={400} height={400} />
     </window>
   )
 }

package/examples/image.tsx

@@ -8,8 +8,19 @@
 // (this is the 2.0 async mechanic, not a manual undefined-signal + <Show>); a
 // load failure surfaces to <Errored>. Pass an accessor (createImage(() => src()))
 // to make the source reactive - the image reloads and the old texture is freed.
-// For manual control, decodeImage + createTexture (from @solidrt/core/gpu) are
-// the primitives underneath.
+//
+// The rule: createImage always suspends (needs <Loading>), because it is an
+// async value. For bytes you already hold - a `with { type: "binary" }` import
+// or anything in memory - skip it: decodeImage(bytes) + createTexture (both
+// synchronous) build the texture with no boundary at all. See inline-image.tsx.
+// createImage earns its async only when it fetches a string URL or swaps source
+// reactively; decodeImage + createTexture are the primitives underneath.
+//
+// Raster vs vector: a texture has a fixed source resolution, so it softens when
+// drawn larger than (displayed size x env.displayScale) on a hi-DPI display.
+// Author raster at 2-3x the largest size you will draw it. When the render size
+// is fluid or DPI varies, prefer a vector (svg.tsx / <d-path>) instead - it
+// stays crisp at any size.
 import { render, createImage, Loading } from "@solidrt/core"
 
 function App() {

package/examples/inline-image.tsx

@@ -0,0 +1,27 @@
+// Displaying an image whose bytes are already in memory - here a
+// `with { type: "binary" }` import that inlines the file into the bundle. Because
+// the bytes are on hand, the whole path is synchronous: decodeImage(bytes) turns
+// the encoded PNG into raw RGBA8 pixels, and createTexture uploads them to the
+// GPU and returns an id. No fetch, no async value, so no <Loading> boundary - the
+// texture is ready in the same tick the component builds.
+//
+// Contrast image.tsx, which uses createImage for a string URL: that fetches at
+// runtime, so it suspends and must be read inside <Loading>. The rule: createImage
+// (async) for URLs or reactive sources; decodeImage + createTexture (sync) for
+// bytes you already hold. Called here in the component body, the texture is freed
+// automatically when the owner is disposed.
+import { render, decodeImage, createTexture } from "@solidrt/core"
+import bytes from "./logo.png" with { type: "binary" }
+
+function App() {
+  let { data, width, height } = decodeImage(bytes)
+  let id = createTexture(data, width, height)
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/repaint-boundary.tsx

@@ -0,0 +1,56 @@
+// repaintBoundary marks a <view> subtree as its own retained cache, so nearby
+// frequently changing content does not force it to rebuild every frame. It has
+// two modes - both shown here, next to a square that spins every frame:
+//
+//  - repaintBoundary={true}  retains the recorded DRAW LIST: the subtree is
+//    recorded once and the commands are replayed until something inside changes.
+//    Skips re-recording. The default choice for static content next to animation.
+//
+//  - repaintBoundary="snapshot" additionally retains the RASTERIZED PIXELS as a
+//    GPU texture, so replay skips rasterization too. Worth the texture memory
+//    only for raster-expensive static content (many glyphs, blurs, dense vector).
+//    It re-rasters on layout-size / display-scale changes, crops anything painted
+//    outside the layout box, and an ancestor scale animation smears the bitmap -
+//    so reach for it only for screen-aligned, static, raster-heavy subtrees.
+//
+// Rule of thumb: start with {true}; upgrade to "snapshot" only when the cached
+// content is expensive to rasterize and stays screen-aligned and static.
+import { render, onFrame, createSignal, For } from "@solidrt/core"
+
+// Raster-expensive static content: a dense grid of rects. Cheap to replay from a
+// draw list, but re-rasterizing it every frame would be wasteful - the case
+// "snapshot" is built for.
+function Grid(props: { boundary: true | "snapshot" }) {
+  let cells = Array.from({ length: 64 }, (_, i) => i)
+  return (
+    <view
+      repaintBoundary={props.boundary}
+      width={200}
+      height={200}
+      flexDirection="row"
+      flexWrap="wrap"
+      gap={3}
+    >
+      <For each={cells}>
+        {(i) => <rect width={22} height={22} radius={3} color={i % 2 ? "#2a3f5f" : "#3366b3"} />}
+      </For>
+    </view>
+  )
+}
+
+function App() {
+  let [angle, setAngle] = createSignal(0)
+  onFrame((tick) => setAngle(tick / 1000))
+
+  return (
+    <window flexDirection="row" alignItems="center" justifyContent="center" gap={32}>
+      <Grid boundary={true} />
+      <Grid boundary="snapshot" />
+      <view width={120} height={120} rotate={angle()}>
+        <rect width={120} height={120} radius={16} color="#e0245e" />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/responsive-grid.tsx

@@ -0,0 +1,42 @@
+// Responsive layout: the SAME app on a phone, tablet, or desktop. The window is
+// host-sized and resizable, so drive the layout from the live window instead of
+// hardcoding pixels. Here the column count comes from
+// `capabilities.windowSizeClass` (Material 3 width breakpoints: compact <600,
+// medium 600-840, expanded >=840). Resize the window and the grid reflows.
+//
+// `capabilities` and `env` are plain objects with reactive GETTERS, not
+// functions - read `capabilities.windowSizeClass` (no call). Reading it inside
+// JSX tracks, so the memo below re-runs on every resize. `windowSize()` IS a
+// function (call it) - we read its width to size each card exactly.
+import { render, capabilities, windowSize, createMemo, For } from "@solidrt/core"
+
+const GAP = 16
+const PAD = 24
+const COLORS = ["#1f6feb", "#3fb950", "#db6d28", "#a371f7", "#e3b341", "#f778ba", "#2dd4bf", "#f85149"]
+
+function App() {
+  // Column count from the size class; card width derived so N fit per row.
+  let cols = createMemo(() => (capabilities.windowSizeClass === "expanded" ? 3 : capabilities.windowSizeClass === "medium" ? 2 : 1))
+  let cardWidth = createMemo(() => (windowSize().width - PAD * 2 - GAP * (cols() - 1)) / cols())
+
+  return (
+    <window>
+      <d-rect color="#0b0f17" />
+      <view flex={1} flexDirection="column" gap={GAP} padding={PAD}>
+        <text color="#e6e6e6" fontSize={18}>{capabilities.windowSizeClass} - {cols()} column{cols() === 1 ? "" : "s"}</text>
+        <view flexDirection="row" flexWrap="wrap" gap={GAP}>
+          <For each={COLORS}>
+            {(c) => (
+              <view width={cardWidth()} height={96} alignItems="center" justifyContent="center">
+                <d-rect color={c} radius={12} />
+                <text color="#0b0f17" fontSize={16} fontWeight={700}>card</text>
+              </view>
+            )}
+          </For>
+        </view>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/scroll.tsx

@@ -0,0 +1,56 @@
+// createScroll is a HEADLESS scroll primitive: it owns only the geometry - the
+// clamped offset, re-clamped in onLayout against the measured content-vs-viewport
+// overflow - and nothing with a UI opinion. Input handling, momentum, and
+// scrollbars are policy you supply. (@solidrt/components ScrollView is one such
+// skin built on top of this.)
+//
+// The shape it expects:
+//  - a VIEWPORT node: the clipping box, overflow="hidden".
+//  - a CONTENT node inside it: an inner wrapper that takes the children's natural
+//    size (flexShrink={0} so it can exceed the viewport).
+// 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.
+import { render, For, createScroll } from "@solidrt/core"
+import type { WheelEvent } from "@solidrt/core"
+
+function App() {
+  let viewport: { id: number } | undefined
+  let content: { id: number } | undefined
+
+  // 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 rows = Array.from({ length: 30 }, (_, i) => i)
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view
+        ref={(n: { id: number }) => (viewport = n)}
+        width={220}
+        height={280}
+        overflow="hidden"
+        clipRadius={12}
+        scrollY={scroll.offset().y}
+        onWheel={onWheel}
+      >
+        <d-rect color="#1a2233" radius={12} />
+        <view ref={(n: { id: number }) => (content = n)} flexShrink={0} padding={12} gap={8}>
+          <For each={rows}>
+            {(i) => (
+              <view height={40} justifyContent="center" paddingLeft={12}>
+                <rect height={40} radius={6} color={i % 2 ? "#2a3f5f" : "#3366b3"} />
+                <text color="#ffffff">Row {i}</text>
+              </view>
+            )}
+          </For>
+        </view>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/svg.tsx

@@ -10,6 +10,10 @@
 // "currentColor" is recolored by the host `color` prop. For per-shape authored
 // or animated vector art, compose <d-path> instead of this document layer.
 //
+// Being a vector, an <svg> is resolution-independent: it stays crisp at any
+// drawn size x displayScale(). Prefer it over a raster <texture> (image.tsx)
+// whenever the render size is fluid or the display DPI varies.
+//
 // This is how you use an existing icon library (Lucide, Heroicons, Feather,
 // Material, etc.): those ship SVG source, so import/inline the icon string and
 // hand it to `src`. The `currentColor` convention they follow means the `color`

package/jsx-runtime.d.ts

@@ -7,7 +7,6 @@ import type {
   ViewProps,
   TextProps,
   TextureProps,
-  AudioProps,
   LayoutProps,
   Element as CoreElement,
   ElementChildrenAttribute as CoreElementChildrenAttribute
@@ -23,26 +22,29 @@ export namespace JSX {
   type RefCallback<T> = (el: T) => unknown
   type Ref<T> = T | RefCallback<T>
 
-  interface IntrinsicAttributes {
+  // ref lives on the element prop types (intersected into every entry below)
+  // rather than in IntrinsicAttributes: under our config, declaring it only in
+  // IntrinsicAttributes did not make it reach intrinsic elements, so `ref` on a
+  // host element was reported as an excess property.
+  interface ElementRef {
     ref?: Ref<{ id: number }> | undefined
   }
 
   interface IntrinsicElements {
-    window: WindowProps
-    view: ViewProps
-    text: TextProps & LayoutProps
-    rect: RectProps & LayoutProps
-    oval: OvalProps & LayoutProps
-    path: PathProps & LayoutProps
-    svg: SvgProps & LayoutProps
-    texture: TextureProps & LayoutProps
-    audio: AudioProps
-    "d-view": ViewProps
-    "d-rect": RectProps
-    "d-oval": OvalProps
-    "d-path": PathProps
-    "d-svg": SvgProps
-    "d-texture": TextureProps
-    "d-text": TextProps
+    window: WindowProps & ElementRef
+    view: ViewProps & ElementRef
+    text: TextProps & LayoutProps & ElementRef
+    rect: RectProps & LayoutProps & ElementRef
+    oval: OvalProps & LayoutProps & ElementRef
+    path: PathProps & LayoutProps & ElementRef
+    svg: SvgProps & LayoutProps & ElementRef
+    texture: TextureProps & LayoutProps & ElementRef
+    "d-view": ViewProps & ElementRef
+    "d-rect": RectProps & ElementRef
+    "d-oval": OvalProps & ElementRef
+    "d-path": PathProps & ElementRef
+    "d-svg": SvgProps & ElementRef
+    "d-texture": TextureProps & ElementRef
+    "d-text": TextProps & ElementRef
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -11,7 +11,6 @@
     "./gpu": "./src/gpu.ts",
     "./image": "./src/image.ts",
     "./microphone": "./src/microphone.ts",
-    "./scroll": "./src/scroll.ts",
     "./speech-recognition": "./src/speech-recognition.ts",
     "./text-input": "./src/text-input.ts",
     "./jsx-runtime": "./jsx-runtime.d.ts",
@@ -27,7 +26,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.22"
+    "@solidrt/flux-types": "0.0.24"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.15",

package/src/color.ts

@@ -43,6 +43,11 @@ type Stop = { offset: number; color: number }
 // element's box), so one gradient can be reused on elements of any size. Branded
 // so the renderer can tell it from a solid color string. The object crosses to
 // the runtime as-is and is decoded by key (see properties/paint.rs).
+//
+// These 0..1 coords are deliberately their own normalized space, NOT the pixel/
+// `pct()` length vocabulary used by layout and transformOrigin: a gradient's
+// position is naturally a fraction (like a stop offset), so 0..1 reads cleaner
+// than pct(0)..pct(100). Do not "unify" them onto pct().
 export type Gradient =
   | { readonly __gradient: "linear"; x0: number; y0: number; x1: number; y1: number; stops: Stop[] }
   | { readonly __gradient: "radial"; cx: number; cy: number; r: number; circle: boolean; stops: Stop[] }

package/src/environment.ts

@@ -10,6 +10,14 @@ import { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } fro
 // been seen this session. Seen-flags only ever go from false to true, so a
 // capability derived from them can appear mid-session (e.g. the first mouse
 // move) but never flickers away.
+//
+// `ownedWrite: true` on the signals below: each is lazily created the first
+// time its ensure* function runs, which can happen inside a tracked scope
+// (e.g. a memo's first read of env.inputDevices). Sticky events replay their
+// cached value synchronously on subscribe (srt:events' on()), so that same
+// call can immediately write the signal it just created. That's a legitimate
+// internal-state write, not a stray write escaping a computation, so it opts
+// out of the write-in-owned-scope guard.
 
 /** Connected input device classes, as reported by the runtime. */
 export interface InputDevices {
@@ -26,7 +34,7 @@ let devicesAccessor: (() => InputDevices | undefined) | undefined
 
 function ensureDevicesState() {
   if (devicesAccessor) return
-  let [devices, setDevices] = createSignal<InputDevices | undefined>(undefined)
+  let [devices, setDevices] = createSignal<InputDevices | undefined>(undefined, { ownedWrite: true })
   // Sticky: the current state replays on subscribe, so the first read already
   // sees it on runtimes that report devices.
   on("inputDevices", (d: InputDevices) => {
@@ -39,7 +47,7 @@ let systemThemeAccessor: (() => SystemTheme) | undefined
 
 function ensureSystemThemeState() {
   if (systemThemeAccessor) return
-  let [theme, setTheme] = createSignal<SystemTheme>("unknown")
+  let [theme, setTheme] = createSignal<SystemTheme>("unknown", { ownedWrite: true })
   on("systemTheme", (e: { theme?: SystemTheme }) => setTheme(e.theme ?? "unknown"))
   systemThemeAccessor = theme
 }
@@ -48,7 +56,7 @@ let orientationAccessor: (() => Orientation) | undefined
 
 function ensureOrientationState() {
   if (orientationAccessor) return
-  let [orientation, setOrientation] = createSignal<Orientation>("unknown")
+  let [orientation, setOrientation] = createSignal<Orientation>("unknown", { ownedWrite: true })
   on("displayOrientation", (e: { orientation?: Orientation }) => {
     setOrientation(e.orientation ?? "unknown")
   })
@@ -59,7 +67,7 @@ let textScaleAccessor: (() => number) | undefined
 
 function ensureTextScaleState() {
   if (textScaleAccessor) return
-  let [scale, setScale] = createSignal(1)
+  let [scale, setScale] = createSignal(1, { ownedWrite: true })
   // Sticky, like systemTheme. Guard nonsense values: a runtime bug reporting
   // 0 or a negative would otherwise collapse all text.
   on("textScale", (e: { scale?: number }) => {

package/src/gpu.ts

@@ -1,17 +1,22 @@
 // GPU textures and shaders, reactive (SolidJS) layer: the create* helpers free
-// their texture automatically when the reactive owner is disposed. The imperative
-// primitive lives in the `flux:gpu` module; import { uploadTexture,
-// setShaderParams, destroyTexture, ... } from "flux:gpu" for non-reactive use.
+// their texture automatically when the reactive owner is disposed. Drive a
+// shader's uniforms declaratively with `<texture src={id} params={{...}} />`
+// (see TextureProps) - the preferred way, deferred to the next real repaint so
+// a fast-changing signal stays paced to actual frames. setShaderParams is the
+// imperative exception: reach for it only when there is no `<texture>` element
+// to hold a params prop, e.g. a shader that only feeds another shader as a
+// sampler2D input. The imperative primitives (uploadTexture, setShaderParams,
+// destroyTexture, ...) live in the `flux:gpu` module.
 
 import { getOwner, onCleanup } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
 
-// Imperative companions to the reactive create* helpers, re-exported so callers
-// that depend on @solidrt/core -- like @solidrt/components -- need not import flux
-// directly: destroyTexture for the manual-cleanup path (textures made outside a
-// reactive scope, e.g. after an await, are not auto-freed), setShaderParams to
-// drive a shader's uniforms over time, and uploadTexture to push new pixels into
-// a mutable texture.
+// Re-exported so callers that depend on @solidrt/core -- like @solidrt/components
+// -- need not import flux directly: destroyTexture for the manual-cleanup path
+// (textures made outside a reactive scope, e.g. after an await, are not
+// auto-freed), uploadTexture to push new pixels into a mutable texture, and
+// setShaderParams as the non-reactive exception described above - prefer
+// `<texture params={...}>` when a `<texture>` element is already in the tree.
 export { destroyTexture, setShaderParams, uploadTexture } from "flux:gpu"
 
 /**
@@ -48,12 +53,14 @@ export function createMutableTexture(data: Uint8Array, width: number, height: nu
  * Compiles a GLSL ES 3.00 fragment shader and renders it into a texture,
  * returning the texture id (usable anywhere a normal texture id is, e.g.
  * `<texture src>`). The fragment body may reference `vUV` (0..1, top-left
- * origin), `iResolution`, `iTime`, and any `uniform float` it declares; pass
- * their values via `params`. `textures` binds each declared `uniform sampler2D`
- * to an existing texture id (e.g. a camera or decoded image) so the shader can
- * read it; those inputs are re-sampled on every `setShaderParams` call, so live
- * sources stay current. Frees the texture and shader program when the reactive
- * owner is disposed; create outside any reactive scope for app-lifetime shaders.
+ * origin), `iResolution`, `iTime`, and any `uniform float` it declares; drive
+ * their values with `<texture src={id} params={{...}} />` (preferred) or, when
+ * there is no `<texture>` element for it, imperatively with `setShaderParams`.
+ * `textures` binds each declared `uniform sampler2D` to an existing texture id
+ * (e.g. a camera or decoded image) so the shader can read it; those inputs are
+ * re-sampled on every params update, so live sources stay current. Frees the
+ * texture and shader program when the reactive owner is disposed; create
+ * outside any reactive scope for app-lifetime shaders.
  */
 export function createShader(
   fragmentSrc: string,

package/src/image.ts

@@ -34,6 +34,12 @@ export type ImageSource = string | Uint8Array
  * current texture is freed when the owner is disposed. Display it with
  * `<texture src={id()} />`; the texture carries its own pixel size, so no
  * width/height is needed unless you want to scale it.
+ *
+ * For bytes you already hold (a `with { type: "binary" }` import, or anything in
+ * memory) this suspends needlessly: `decodeImage` + `createTexture` are both
+ * synchronous, so reach for them directly and skip the `<Loading>` boundary.
+ * `createImage` earns its async only for a fetched string URL or a reactive
+ * source.
  */
 export function createImage(src: ImageSource | (() => ImageSource)): () => number {
   let getSrc = typeof src === "function" ? src : () => src

package/src/index.ts

@@ -13,6 +13,8 @@ export type { Capabilities, WindowSizeClass } from "./capabilities"
 export { createTexture } from "./gpu"
 export { createImage, decodeImage } from "./image"
 export type { DecodedImage, ImageSource } from "./image"
+export { createScroll } from "./scroll"
+export type { Scroll, ScrollAxis, ScrollOffset, ScrollOptions } from "./scroll"
 export type {
   LayoutProps,
   TransformProps,
@@ -30,11 +32,16 @@ export type {
   PathProps,
   TextProps,
   TextureProps,
-  AudioProps,
   Color,
+  Pct,
 } from "./types"
 export type { MeasureTextOptions } from "flux:rendertree"
 
+// A percentage value for dimensional props (e.g. transformOrigin): `pct(50)` is
+// half the element box. Keeps percentages a first-class branded value rather
+// than a string that has to be parsed - a bare number stays pixels.
+export let pct = (v: number): import("./types").Pct => ({ __unit: "pct", v })
+
 // --- Authoring-surface re-exports -------------------------------------------
 // A SolidRT app is built from three substrate packages: @solidjs/signals
 // (reactivity), solid-js (control-flow components), and @solidjs/universal (the

package/src/types.d.ts

@@ -37,10 +37,17 @@ export interface ElementChildrenAttribute {
 
 type Children = Element
 
+// Doc-comment policy for this file: JSX props mostly mirror CSS/DOM, which any
+// developer or agent already knows, so a comment restating standard semantics
+// is noise. Add one only where a prop deviates from that standard, is bespoke
+// to this engine, or has an interaction that isn't decidable from the type
+// alone (e.g. shorthand-vs-longhand precedence, a subsetted value range).
+
 interface FlexboxProps {
-  gap?: number
-  rowGap?: number
-  columnGap?: number
+  gap?: LengthPercentage
+  rowGap?: LengthPercentage
+  columnGap?: LengthPercentage
+  /** Shorthand; overridden by flexGrow/flexShrink/flexBasis when they're also set. */
   flex?: number | "none" | "auto" | (string & {})
   flexGrow?: number
   flexShrink?: number
@@ -54,6 +61,7 @@ interface FlexboxProps {
   justifyContent?: "start" | "end" | "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-evenly" | "space-around"
 }
 
+/** CSS grid subset: line-based placement only, no named lines, no grid-template-areas, and auto tracks take a fixed size (no minmax/fr/keyword). */
 interface GridProps {
   gridAutoFlow?: "row" | "column" | "row-dense" | "column-dense"
   gridAutoColumns?: number
@@ -66,10 +74,23 @@ interface GridProps {
   gridTemplateRows?: string
 }
 
-type Dimension = number | "auto" | `${number}%`
+/**
+ * A layout length: a bare number is pixels, `pct(n)` is a percentage of the
+ * containing block, plus "auto" and the `"50%"` string form (kept for paste).
+ */
+type Dimension = number | Pct | "auto" | `${number}%`
+
+/** Like {@link Dimension} without "auto" (e.g. gap, which has no auto value). */
+type LengthPercentage = number | Pct | `${number}%`
 
 export interface LayoutProps extends FlexboxProps, GridProps {
   display?: "block" | "flex" | "grid" | "none"
+  /**
+   * No "fixed" or "sticky". Unlike CSS, `absolute` does not itself become a
+   * containing block: an absolute element resolves against the nearest
+   * ancestor with `position: relative`, so a chain of absolute elements
+   * resolves against whatever relative element is above all of them.
+   */
   position?: "relative" | "absolute"
 
   top?: Dimension
@@ -116,6 +137,16 @@ export interface PaintProps {
   strokeWidth?: number
 }
 
+/** A percentage value, from `pct(50)`. Resolves against the element box. */
+export type Pct = { readonly __unit: "pct"; v: number }
+
+// One axis of the transform origin (the point rotate/scale/3D pivot around),
+// split per axis to match the engine's x/y prop convention. A bare number is
+// pixels; `pct(50)` is a fraction of the box, so a percentage origin tracks the
+// layout size with no reactive wiring. Unset defaults to the axis center.
+type OriginX = number | Pct | "left" | "center" | "right"
+type OriginY = number | Pct | "top" | "center" | "bottom"
+
 export interface TransformProps {
   rotate?: number
   scale?: number
@@ -134,8 +165,8 @@ export interface TransformProps {
   perspective?: number
   x?: number
   y?: number
-  cx?: number
-  cy?: number
+  originX?: OriginX
+  originY?: OriginY
   // Group opacity in 0..1: children are composited together, then faded as a
   // whole (CSS `opacity`). Does not affect hit testing.
   opacity?: number
@@ -197,12 +228,10 @@ interface Position {
 
 // Primitives
 
-export interface WindowProps extends LayoutProps {
+export interface WindowProps extends LayoutProps, PointerProps {
   children?: Children
   title?: string
   fullscreen?: boolean
-  vsync?: boolean
-  fps?: boolean
 }
 
 export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
@@ -229,11 +258,6 @@ export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
   repaintBoundary?: boolean | "snapshot"
 }
 
-export interface AudioProps {
-  src?: Uint8Array
-  play?: number
-}
-
 // draw primitives
 
 export interface RectProps extends Position, PaintProps, PointerProps {
@@ -245,7 +269,9 @@ export interface RectProps extends Position, PaintProps, PointerProps {
 }
 
 export interface OvalProps extends Position, PaintProps, PointerProps {
+  /** Bounding box width of the ellipse (not a radius); defaults to the layout box. */
   w?: number
+  /** Bounding box height of the ellipse (not a radius); defaults to the layout box. */
   h?: number
 }
 
@@ -254,7 +280,9 @@ export interface LineProps extends PaintProps, PointerProps {
   y1?: number
   x2?: number
   y2?: number
+  /** Dash pattern in local units: the drawn segment length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
   onLength?: number
+  /** Dash pattern in local units: the gap length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
   offLength?: number
 }
 
@@ -287,13 +315,16 @@ export interface TextProps extends Position, PaintProps, PointerProps {
   maxLines?: number
 }
 
-export interface TextureProps extends Position {
+export interface TextureProps extends Position, PointerProps {
   src?: number
-  imageWidth?: number
-  imageHeight?: number
+  w?: number
+  h?: number
   srcX?: number
   srcY?: number
   srcW?: number
   srcH?: number
+  // Shader uniform values, when src names a shader texture. Applied at the
+  // next repaint (not synchronously), so a fast-changing signal stays paced
+  // to real frames rather than triggering a GL render pass per write.
   params?: Record<string, number>
 }

package/src/window.ts

@@ -93,7 +93,9 @@ export function onResize(fn: (data: ResizeEvent) => void) {
 // Singleton accessors over the same events as onResize / onWindowFocus. There
 // is one window, so these are bare accessors rather than a createX instance.
 // Lazily subscribed on first read (resize is sticky, so the first read sees the
-// current value); app-lifetime, so no onCleanup.
+// current value); app-lifetime, so no onCleanup. `ownedWrite: true` on the
+// signals below is the sticky-replay-into-a-tracked-scope case explained on
+// the ensure* functions in environment.ts.
 
 let sizeAccessor: (() => { width: number; height: number }) | undefined
 let safeAreaAccessor: (() => SafeArea) | undefined
@@ -101,9 +103,9 @@ let displayScaleAccessor: (() => number) | undefined
 
 function ensureResizeState() {
   if (sizeAccessor) return
-  let [size, setSize] = createSignal({ width: 0, height: 0 })
-  let [safe, setSafe] = createSignal<SafeArea>({ top: 0, left: 0, right: 0, bottom: 0 })
-  let [scale, setScale] = createSignal(1)
+  let [size, setSize] = createSignal({ width: 0, height: 0 }, { ownedWrite: true })
+  let [safe, setSafe] = createSignal<SafeArea>({ top: 0, left: 0, right: 0, bottom: 0 }, { ownedWrite: true })
+  let [scale, setScale] = createSignal(1, { ownedWrite: true })
   on("resize", (e: ResizeEvent) => {
     setSize({ width: e.width, height: e.height })
     setSafe(e.safeArea)