@solidrt/core 0.0.50 → 0.0.52

package/AGENTS.md

@@ -1,12 +1,21 @@
 # @solidrt/core - agent notes
 
-Dense, self-contained facts for writing a SolidRT app.
-Full docs live in docs/ (and the website). When this conflicts with prose docs,
-trust this file and the types in src/types.d.ts and jsx-runtime.d.ts.
+Dense, self-contained facts for writing a SolidRT app. The prose lives in
+docs/ (also the website); when this conflicts with it, 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`.
 
+Two companion files carry the depth this one leaves out; read the one that
+matches the work before starting it:
+- agents/painting.md - what you paint with, and what replaces each CSS
+  reflex. Read before styling a screen: a background, a gradient, a shadow,
+  an effect, vector art, a chart.
+- agents/performance.md - the performance model, in order of leverage. Read
+  before writing any per-frame code, any animation, or anything that writes
+  properties in a loop.
+
 ## The window is device-sized - design fluid
 
 A SolidRT window is host-sized and resizable, and the SAME app runs on phones,
@@ -26,12 +35,19 @@ hardcode desktop pixels.
 
 Exception - fixed-aspect content. For content with fixed internal geometry
 (diagrams, slides, dashboards, games, emulators), do not branch on window size
-at all: author everything in one design space and let `viewBox` fit it.
-`<view flex={1} viewBox={[1280, 800]}>` uniformly scales and centers the
+at all: author everything in one design space and let `designSize` fit it.
+`<view flex={1} designSize={[1280, 800]}>` uniformly scales and centers the
 children (letterboxed), pointer events on them arrive in design coordinates,
-and the same code runs unchanged from a desktop window to a phone. Reach for
-`windowSizeClass` branching only when the layout genuinely reflows across form
-factors.
+and the same code runs unchanged from a desktop window to a phone. Laid-out
+children (flex, percentages, text wrap) resolve against the design size too,
+so a whole panel scales into a smaller box without reflowing; the view itself
+sizes like a replaced element whose intrinsic size is the design size. One
+trap from flexbox, not from designSize: in a flex row a width-only design-size view
+is stretched to the line's height under the default alignment, so give the
+view `alignSelf="flex-start"` (or the row a non-stretch `alignItems`) to get
+the design aspect - `aspectRatio` does not override stretch. Reach for
+`windowSizeClass` branching only when the layout genuinely reflows across
+form factors.
 
 `env` and `capabilities` (both exported from `@solidrt/core`) are the two
 objects that expose this. They are plain objects with REACTIVE GETTERS, not
@@ -64,7 +80,7 @@ you need the raw fact (e.g. `env.displayScale` for asset sizing below).
 Because the drawn size is fluid and the display DPI varies, asset format is a
 real design decision, not an afterthought:
 
-- Prefer VECTORS (`parseSvg` draws mapped to `<d-path>` in a `viewBox` view)
+- Prefer VECTORS (`parseSvg` draws mapped to `<d-path>` in a `designSize` view)
   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
@@ -79,8 +95,9 @@ bun add @solidrt/core        # the renderer
 bun add -d @solidrt/cli      # the `srt` tool (see its AGENTS.md)
 ```
 
-`@solidrt/components` is a separate, optional package of higher-level components
-(see its own AGENTS.md); core primitives alone are enough to build a full app.
+Core primitives alone are enough to build a full app. The optional extensions
+(each with its own AGENTS.md) build on it: `@solidrt/components` (themed
+widgets), `@solidrt/2d` (2D graphics and games), `@solidrt/3d` (scene graph).
 
 tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 
@@ -94,13 +111,23 @@ tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 ```
 
 Peer deps @solidjs/signals and @solidjs/universal must match (currently
-2.0.0-rc.0); bun resolves them from peerDependencies.
+2.0.0-rc.1); bun resolves them from peerDependencies.
 
 ## Element model (the parts that are easy to get wrong)
 
 - `render(() => <App />)`. The returned root MUST be a `<window>` or it throws.
   Call render once, at the top level.
 
+- Errors never halt the app. One thrown while computing an element's props or
+  a child expression is contained at that element: it keeps its last good
+  value, one `Contained error` log line names the node and the .tsx line,
+  and it recovers when the expression computes again. Anything unclaimed
+  beyond that (a throwing `createEffect`, an error while mounting) reaches
+  render()'s root boundary, which replaces the app's window with an error
+  window (message, stack, a Reset button that retries the failed
+  computations) and logs `Uncaught error`. `<Errored>` gives a subtree its
+  own in-place fallback.
+
 - Two kinds of element:
   - Containers - `<window>`, `<view>`. Do layout + transform + pointer events.
     THEY DO NOT PAINT. A `<view>` has no background/fill prop.
@@ -113,11 +140,13 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   Outlines: `drawStyle="stroke"` (or "stroke-and-fill") plus `strokeWidth`.
   Corner radius on draw primitives: `radius` (number or [tl, tr, br, bl]).
 
-- Registered JSX intrinsics: `window`, `view`, `text`, `rect`, `oval`, `line`,
-  `path`, `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`,
+- Registered JSX intrinsics: `window`, `view`, `text`, `span`, `rect`, `oval`,
+  `line`, `path`, `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`,
   `d-oval`, `d-line`, `d-path`, `d-texture`, `d-text`. Line endpoints
   (`x1`/`y1`/`x2`/`y2`) exist only on `d-line`; a laid-out `<line>` has no
-  endpoint props and spans its layout box corner to corner.
+  endpoint props and spans its layout box corner to corner. `points` (a flat
+  `[x0, y0, x1, y1, ...]` array, plus `closed`) turns either form into a
+  polyline and wins over the endpoints while set.
 
 - Plain vs `d-` variant (the `d-` prefix means "detached" - detached from the
   layout engine, Taffy): a plain element (e.g. `rect`) is `RectProps &
@@ -135,6 +164,8 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   box center; a d-view has no box). To scale a detached group around its
   content's center, set the origin explicitly in pixels, e.g.
   `originX={100} originY={50}` for content drawn in a 200x100 local space.
+  Avoid pct()/keyword origins on a d-view - they resolve against the box
+  inherited from the nearest laid-out ancestor.
 
 - Layout-affecting vs not (this matters for per-frame work). Props fall in three
   buckets, split by where they take effect:
@@ -154,13 +185,18 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   `position:absolute` at `left:0,top:0`, or just let normal flow place it) and
   then translate it with `x`/`y`.
 
+- Text `lineHeight` is a MULTIPLIER of fontSize (1.3-1.6 is typical), not
+  pixels. A CSS-reflex value like 22 makes each line box 22x the font size:
+  the text becomes blank space and the parent balloons.
+
 - JSX text children collapse whitespace (ordinary JSX semantics): runs of
   spaces become one, so space-padding a mono label collapses silently. An
   expression container preserves it - `<d-text>{"one    two"}</d-text>` - and
   `\n` inside one produces a hard line break.
 
 - Rich text: `<span>` inside `<text>` restyles a run (`color`, `fontFamily`,
-  `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`); spans nest and
+  `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`,
+  `textDecoration="underline"`); spans nest and
   inherit inward from the `<text>`. Never lay a paragraph out word by word in
   a wrapping row to mix styles - one `<text>` with spans wraps as a whole.
   A span is content, not a box (no layout or `d-` form, no size, no
@@ -206,9 +242,55 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   TRACKED compute that reads signals and returns a value, then an UNTRACKED
   effect that receives it - `createEffect(() => count(), (c) => ...)`. The 1.x
   single-callback form `createEffect(() => { ...count()... })` does NOT track
-  here. Per-frame work: `onFrame((tick, frame) => {})` (returns a cleanup;
-  auto-cleaned inside a reactive scope) or standard `requestAnimationFrame`.
-  Also onResize, onLayout, onWindowFocus, onWindowBlur.
+  here.
+  Reading a signal/prop/store at the top level of a component body (not
+  inside JSX, a `createMemo`, or an effect's compute phase) reads it
+  untracked: it silently freezes at the initial value.
+  Writing a signal or store from inside an owned scope (a component body, a
+  `createMemo`, an effect's compute phase) throws
+  `REACTIVE_WRITE_IN_OWNED_SCOPE` in dev; a loader called in the component
+  body that sets state is the classic React / Solid 1.x reflex that hits
+  this. Move the write into an event handler, an effect's apply phase,
+  `onSettled`, or an `untrack` block; opt in narrowly with
+  `createSignal(v, { ownedWrite: true })` for a signal that genuinely is
+  internal state.
+  Signal writes flush on a microtask: a handler that sets a signal and
+  immediately reads it back gets the OLD value. Read it in an effect, or
+  call `flush()` (from @solidjs/signals) to force it through.
+
+- An element-valued prop (children, a content/icon slot) compiles to a getter
+  that builds a fresh native subtree on EVERY read, and a subtree that is
+  never inserted is never freed - native nodes are not garbage collected, so
+  what is only wasted work in DOM Solid is a permanent memory leak here. Read
+  such props exactly once, at the place they are mounted. To inspect
+  children (a typeof probe, counting), resolve them first with the
+  `children()` helper (re-exported from @solidrt/core) and probe the resolved
+  memo - never `typeof props.children` on the raw prop.
+
+- Animation is target-shaped first: declare `transition` on the element and
+  write targets, and the runtime animates natively with no per-frame JS.
+  Reach for per-frame work only for genuinely procedural motion:
+  `onFrame((tick, frame) => {})` is the native hook (runtime-paced, returns a
+  cleanup, auto-cleaned inside a reactive scope); `requestAnimationFrame`
+  exists as a web-standard one-shot but is not the preferred driver. A JS
+  tween loop or an animation library pushing interpolated values through
+  signals is the single most expensive mistake available here - read
+  agents/performance.md before writing either.
+  Window state: onResize, onLayout, onWindowFocus, onWindowBlur exist, but
+  prefer the reactive reads (`env`/`capabilities` above, or the accessors
+  `windowSize()`, `safeArea()`, `displayScale()`, `windowFocused()`,
+  `keyboardHeight()`, `pointerLocked()`) for reading layout and window
+  state. For mouse look, `lockPointer(true)` enters relative mouse mode
+  (cursor hidden and confined, positions freeze) and pointer events keep
+  reporting motion through `movementX`/`movementY`.
+
+- `createPortal` cannot mount during the app's initial render (it throws
+  "no mount target"): gate portal content behind a signal that starts false
+  and open it after startup - overlay content is opened, not born open.
+  `createScroll` containers need an explicit main-axis size (a height, or
+  flex inside a sized parent); with neither they resolve to 0 and the
+  content silently vanishes (`maxHeight` alone does not size it). The
+  runtime warns when this happens.
 
 - Device/GPU access via subpath imports: @solidrt/core/camera, /microphone,
   /speech, /gpu. Image flow: `decodeImage(bytes)` ->
@@ -241,5 +323,4 @@ render(() => <App />)
 Note the two `<d-rect>` underlays: a `<view>`/`<window>` does not paint, so a
 background is a draw-primitive child placed behind the content.
 
-To run and verify (incl. headless), see @solidrt/cli (its AGENTS.md). For
-higher-level components, see @solidrt/components (its AGENTS.md).
+To run and verify (incl. headless), see @solidrt/cli (its AGENTS.md).

package/README.md

@@ -53,7 +53,7 @@ Optionally, create a `tsconfig.json` to enable type recognition for SolidRT elem
 
 ## API
 
-See [docs/core.md](https://github.com/wellawaretech/solidrt/blob/main/docs/core.md) for the full API reference.
+See [docs/](https://github.com/wellawaretech/solidrt/blob/main/packages/core/docs/index.md) (shipped in the package) for the full API reference.
 
 ## License
 

package/agents/painting.md

@@ -0,0 +1,61 @@
+# What you paint with (there is no CSS layer)
+
+Read this before building any screen whose look matters: a background, a
+decoration, an effect, a chart, anything you would have reached for CSS for.
+
+Layout and props are half the model. There is no stylesheet: no filters, no
+box-shadow, no keyframes, no canvas. The visual range a web app gets from CSS
+comes from the tiers below instead, and reaching past tier 1 is ordinary
+app-building here, not optimization - a screen built only from view
+backgrounds and text is using a fraction of the runtime. Pick the tier the
+CONTENT calls for, not the one that looks safest.
+
+1. Laid-out elements - `<view>`/`<text>`, with `<rect>` (or a filling
+   `<d-rect>` child) for background, border, radius. The structure of a
+   screen, not its finish.
+2. Vector art, detached from layout - `d-path`/`d-rect`/`d-oval`/`d-line`,
+   whose `color` takes a gradient (createLinearGradient /
+   createRadialGradient) and which honour `blendMode`, plus `parseSvg` to
+   draw a whole SVG document as one subtree. Free-form shapes, decoration,
+   diagrams, charts, anything positioned rather than flowed. Examples:
+   parse-svg, detached-positioning, text-paint-styling.
+3. GPU textures - `createShaderTexture` puts a fragment shader in a
+   `<texture>` (moving gradients, noise, glow, dissolves, a background that
+   is alive), `createPipelineTexture` draws geometry you generate yourself
+   (particles, point clouds, splats), and the `shader` prop post-processes
+   content that already exists: on a `<view>` it grades, warps or dissolves
+   that subtree, on `<window>` the whole frame. Stack `<texture>` elements
+   with `blendMode` to combine passes. Examples: gpu-shader, gpu-particles,
+   gpu-pipeline, gpu-instancing, gpu-texture-blend, view-shader,
+   window-shader.
+4. 3D scenes - add `@solidrt/3d` (not a scaffold dependency): meshes,
+   materials and a camera declared as Solid components, rendered into a
+   texture that sits in the UI tree like any other element.
+
+Tier 3 is cheaper than it looks. A shader costs one property write per frame
+no matter how complex the effect, which is why the performance model
+(agents/performance.md) reaches for it first rather than as a last resort.
+
+## Web reflexes and what replaces them
+
+- gradient background -> a gradient `color` on a `d-rect` (gradients are
+  paint values, usable anywhere a color is)
+- `filter: blur/grayscale/hue-rotate`, and any "make this look processed" ->
+  a `shader` on the view (requires repaintBoundary="snapshot"), or on
+  `<window>` for the whole frame
+- `box-shadow` / `text-shadow` / glow -> no shadow prop exists: draw an
+  offset `d-*` shape under the content, or a view shader with `outset` (the
+  transparent margin an effect bleeds into)
+- `backdrop-filter` -> no equivalent. A view shader sees only its own
+  subtree's pixels, never what is behind it. Frost the whole frame with a
+  window shader, or fake the layer with your own content
+- CSS `transition` -> the `transition` prop: declare it on the element and
+  keep writing targets; the runtime animates natively (performance rule 1)
+- `@keyframes` -> a `transition` prop when the motion is target-shaped;
+  `onFrame` writing a signal for genuinely procedural sequences; a `uTime`
+  uniform when the animation is continuous and visual
+- `<canvas>` 2D -> `d-*` primitives (rebuild one `d-path` string per frame
+  rather than animating N elements)
+- `<canvas>` WebGL, three.js -> `createPipelineTexture`, or `@solidrt/3d`
+- video background, animated hero, particle field -> a shader texture; this
+  is the case the runtime is built for

package/agents/performance.md

@@ -0,0 +1,216 @@
+# Performance model (JS is the slow lane)
+
+Read this before writing any per-frame code, any animation, or anything that
+writes properties in a loop.
+
+The JS engine is interpreted and every property write crosses an FFI boundary
+into the runtime, so per-frame JS work is the expensive path while GPU work is
+nearly free. That holds on desktop and on current mobile hardware; "Where GPU
+work stops being free" below is where it does not. The design answer is not
+"write less JS" but "keep JS off the per-frame path": the platform animates
+(transitions), caches (repaint boundaries), shades (GPU) and computes
+(isolates, wasm) natively, and JS stays the coordinator that sets targets.
+Rules, in order of leverage:
+
+1. Motion between states (position, size, opacity, transform components,
+   solid colors, enter/exit) belongs in a native transition, never in
+   per-frame JS. Declare `transition` on the element and keep writing
+   targets the ordinary way; the runtime interpolates every frame on the
+   Rust side, so JS runs only when a target changes and the running
+   animation costs no JS and no property writes per frame, however many
+   elements move. Flat spec, ms durations, kind inferred:
+   `{ duration }` / `{ duration, bounce }` is a spring (the default kind;
+   springs carry velocity, so a retarget mid-flight stays continuous -
+   use them for anything interactive), `{ duration, curve }` is a tween
+   (`linear | ease | ease-in | ease-out | ease-in-out` or a cubic-bezier
+   array; tweens restart from the current value on retarget, CSS
+   semantics). Keys are property names plus `all` as catch-all; a string
+   is shorthand (`transition="300ms ease-out"`); `delay` holds each
+   write, `from` animates the first attach in (enter), `exit` animates
+   removal out before the node frees, `stagger` on a parent cascades its
+   children's enters/exits, and `onTransitionEnd` fires per settled
+   property. The initial value never animates without `from`; a write to
+   a property without a transition snaps, as always. A JS tween loop or
+   animation library pushing interpolated values through signals pays the
+   whole write path per element per frame - port it to this.
+2. Continuous effects (snow, particles, animated backgrounds) belong in a
+   fragment shader: createShaderTexture (from @solidrt/core/gpu) + `<texture
+   params={{ uTime }}>` (the shader declares `uniform float uTime;` itself -
+   the preamble declares only what the runtime fills). The whole effect then
+   costs one setProperty per frame - the uTime write - regardless of visual
+   complexity. Shader output
+   must be premultiplied alpha (white flakes are `vec4(vec3(a), a)`);
+   straight alpha (`vec4(1,1,1,a)`) composites as opaque white. A source that
+   starts with `#version 300 es` is compiled exactly as written - no preamble
+   is injected, though the built-in vertex stage still supplies `vUV` - so a
+   shader ported from elsewhere keeps its own uniform names without dropping
+   to compileShader/linkProgram. Params drive any uniform type: a number
+   fills a `float`/`int` scalar, a flat number array fills `vec2`/`vec3`/
+   `vec4` (2/3/4 numbers) or `mat4` (16, column-major), dispatched by the
+   shader's own declaration - a ported shader's `vec2 uCenter` or
+   `vec3 iResolution` needs no splitting into scalars. To combine several
+   GPU passes, stack `<texture>` elements and set `blendMode` (e.g. a base
+   pass plus an additive `blendMode="plus"` pass) rather than writing a
+   compositing shader. Within one pipeline draw, createPipelineTexture's
+   `blend: "add"` accumulates overlapping geometry additively (soft point
+   splats, glow) - pair it with `depthWrite: false` when depth-tested;
+   neither option implies the other. A pipeline's own vertex stage writes
+   into a y-down clip space: `gl_Position` y = -1 is the top row of the
+   target and +1 the bottom, so camera-up geometry must negate y (or fold
+   the flip into its projection) or it draws upside down. Sampling is a
+   create-time option on every texture: `{ filter: "nearest" }` for
+   hard-pixel upscaling (render a small target, display it big - the
+   retro/pixel-art path) and `{ wrap: "repeat" }` to tile outside 0..1 in
+   shaders; the defaults are linear and clamp, and the choice applies both
+   on screen and to shaders sampling the texture.
+3. Reduce setProperty calls wherever possible: one path string rebuilt per
+   frame beats N elements with N animated positions; a shader beats the path
+   string. get_stats' setPropsPerFrame is the counter to watch. Compiled JSX
+   attribute expressions diff before writing, so a per-frame expression that
+   returns an unchanged value costs no property write - setPropsPerFrame
+   counts values that actually changed, not expressions re-run.
+4. Never leave onFrame registered while nothing animates: a pending onFrame
+   is a standing frame request, so the runtime renders and presents every
+   vsync even when the callback body does nothing - an invisible 60fps GPU
+   burn that also drags the OS compositor along with it. Tweens and
+   springs need no pump at all - that is rule 1, and the runtime requests
+   frames only while tracks run. For genuinely procedural per-frame motion,
+   use a self-rechaining one-shot requestAnimationFrame that stops
+   re-requesting when its work list empties. (Registering onFrame outside a
+   component body also warns NO_OWNER_CLEANUP - it assumes a reactive owner.)
+5. repaintBoundary works like Flutter's: transforms and opacity on the
+   boundary node itself (or any ancestor) are hoisted out of the cache and
+   applied at composite time, so animating x/y/scale/rotate/opacity of a
+   boundary does NOT re-raster it (verified by A/B measurement - the damage
+   system classifies these as Transform and keeps the node's own cache).
+   What DOES invalidate the cache is any paint or content change inside the
+   subtree - colors, path data, text, a Show toggling - so drive animation
+   with transforms and keep the cached content itself static. Off a boundary,
+   `opacity` on a view is NOT cheap: it wraps the subtree in a compositing
+   layer (save_layer) for as long as it is below 1. To fade a single
+   primitive, put the alpha in its `color` (`rgba(...)`) - paint alpha is
+   free; reserve view `opacity` for fading a genuine group as a whole.
+   Placement rule for animation-heavy screens: a boundary around a node
+   that animates its own paint (a moving d-*, a changing color) is useless
+   - its interior is damaged every frame, so the cache never survives. The
+   win is a boundary around the static bulk NEXT TO the animators: the
+   frame then re-records only the moving nodes and replays the fenced
+   content as one cached draw, an order-of-magnitude cut when static
+   content dominates the node count. get_stats' nodesPainted shows exactly
+   what the paint walk still enters. The exception where a boundary on the
+   animator itself pays is transform/opacity animation of the boundary
+   node - the hoisting described above.
+6. "snapshot" boundaries pay first-frame texture allocation + raster:
+   creating many at once (dealing a board of 64 sprites) is a visible
+   one-frame hiccup - pool or pre-warm if that moment matters.
+7. Shading pixels the app already drew is a different mechanism from rule 2's
+   generated textures, and both forms are a `shader` prop taking a linked
+   program from compileShader/linkProgram (@solidrt/core/gpu), not a
+   createShaderTexture source. On `<window>`, `shader={{ program, params }}`
+   runs the finished frame through the program as the last step before it
+   reaches the screen: the frame binds as `uniform sampler2D uSource`,
+   `iResolution` fills by name, and `previous: true` retains the last frame as
+   `uPrevious` for motion echo or frame differencing. On a `<view>` the same
+   prop shades that subtree in place and REQUIRES repaintBoundary="snapshot"
+   (without it the shader is ignored with a warning); the pass sees only the
+   subtree's own pixels - grading, warping or dissolving the panel works,
+   anything needing what is behind it does not - and is split from content
+   invalidation, so a params-only change re-runs the pass against the cached
+   snapshot instead of re-rasterizing. A window shader's output is invisible
+   to get_snapshot and every other MCP tool; `bunx srt render` is the only
+   way to see it (see @solidrt/cli AGENTS.md).
+8. `flux:wasm` runs a pure interpreter (wasmi, no JIT), so temper browser
+   expectations - but do not write it off for compute. A genuinely numeric
+   kernel (typed-array math, tight inner loops, no host calls inside the
+   loop) compiled from a systems language can come out a real multiple
+   faster than the same loop in interpreted JavaScript, and when profiling
+   shows such a kernel is what the app is spending its time on, that
+   multiple is worth having: measure the JS loop, port the kernel, measure
+   again, keep whichever wins. What wasm does not do is speed up
+   render-path work (rules 1-3 are that leverage), and every host call
+   costs marshalling, so batch at the boundary - one call over a byte
+   buffer, not a call per element. It is also the way to ship one compiled
+   module across every target with no native toolchain, and it pairs with
+   an isolate when a call runs long enough to block.
+9. `flux:ffi` (dlopen of a native library) is a binding tool, not a
+   performance tool. It needs a shared library compiled per platform and
+   architecture and shipped under each target's packing rules (Android
+   loads only what arrives inside the APK as a lib*.so), so reaching for
+   it "to make something fast" buys a build-and-packaging problem on every
+   platform the app targets. Use it when the app must call a native
+   library that already exists and already ships for those targets; for
+   speed, everything above comes first.
+
+## Isolates: heavy work off the JS thread
+
+A long synchronous computation (a big parse, a simulation step, a blocking
+`flux:ffi`/`flux:wasm` call) freezes rendering and input for its duration.
+Move it into an isolate module: a file whose first statement is the
+`"use isolate"` directive runs in a second runtime on its own thread, and
+main calls its exports as async functions.
+
+```ts
+// src/worker.ts
+"use isolate"
+export function crunch(data: Uint8Array): number { /* ... */ }
+```
+
+```ts
+// src/index.tsx
+import { isolate } from "flux:isolate"
+import type * as Worker from "./worker"
+let worker = isolate<typeof Worker>("worker")   // id = path from src/, no extension
+let n = await worker.crunch(bytes)              // main keeps rendering meanwhile
+```
+
+The bundler builds each such module as its own bundle and ships it with the
+app (dev pushes and `srt pack` alike). Rules: main may only `import type`
+from an isolate module (a value import is a build error); arguments and
+results are copies (numbers, strings, byte buffers, arrays, plain objects -
+no functions, no class instances); the child has the non-gui `flux:*`
+modules only, so it never touches the render tree; module state persists
+between calls and each `isolate()` call is its own instance. An
+`async function*` export is a stream: `for await (let p of worker.progress())`
+pulls one item per step (progress, ticks, a subscription), `break` ends it in
+the isolate, and streams never block plain calls. Full contract:
+node_modules/@solidrt/flux-types/modules/isolate.d.ts.
+
+## Where GPU work stops being free
+
+"GPU work is nearly free" is a property of the hardware, not of the engine, and
+the spread is wide enough to design against rather than discover late. The same
+app - two point-cloud pipelines, 233,600 vertices, one params write each per
+onFrame, i.e. exactly what rule 2 recommends - measured 16.7 ms/frame (60 fps,
+vsync-locked) on both desktop and a mid-range 2020 tablet, and 120 ms/frame
+(8.3 fps) on a 2017 Android TV. Roughly 8x for identical work, with the tablet
+indistinguishable from desktop. Measure on a target device if it matters; do
+not infer it from the desktop number.
+
+- **On a tiled GPU the budget is primitive count, not pixels.** Every point or
+  triangle costs the tiler regardless of how few pixels it covers. On that TV,
+  frame time against total vertices with a trivial vertex shader: 20k -> 80 ms,
+  35k -> 100 ms, 100k -> 380 ms. Meanwhile `gl_PointSize = 3.0` - nine times
+  the fill - measured within one vsync of 1.0, and rendering into a
+  quarter-size target measured identical to full size. So for a heavy pass the
+  lever is fewer primitives; shrinking the target or the splat usually is not,
+  and coverage is far cheaper bought with point size than with more points.
+- **A device's compositor can set the frame budget outright**, in which case
+  none of the above moves. That TV never presents faster than every 80 ms -
+  four refresh periods blocked inside `eglSwapBuffers` - even for a near-empty
+  scene, so its ceiling is ~12 fps whatever you draw. Recognise it by a
+  content-independent floor: if a trivial scene and a heavy one present at
+  nearly the same rate, you are compositor-bound and tuning the scene is
+  wasted effort.
+- **Per-frame writes are gated on the raster thread, not on vsync**, so a pass
+  that costs more than a refresh period does not silently pile up. If
+  `rasterQueue` climbs across queries while fps drops the raster thread is
+  behind; if `fenceTimeoutsPerSec` (in get_stats' window block) is nonzero,
+  the GPU is over its pacing budget right now.
+
+Finding your own numbers: `get_stats` gives fps, frameMs, setPropsPerFrame,
+the window summary (worst frame, percentiles, GPU rates), rasterQueue and
+fenceTimeouts. When those disagree with what the screen is
+visibly doing, ground truth on Android is
+`adb shell dumpsys SurfaceFlinger --latency <layer>` for real present
+timestamps - engine-reported phase timings can each be honest and still not add
+up to the frame period, because work outside the frame call is not in them.

package/docs/index.md

@@ -0,0 +1,154 @@
+# Core
+
+`@solidrt/core` is the spine of SolidRT. It links SolidJS reactivity
+to the native rendertree: an element vocabulary, layout, input, frames, and
+the environment model for adapting to the device you are running on.
+
+If you only learn one layer, learn this one. Extensions and tools are built
+on it and are replaceable; Core is the part that changes least (SolidRT is
+in alpha, so "least" is not "never").
+
+## Elements
+
+There is no DOM. JSX elements are native rendertree nodes, and the
+vocabulary is deliberately small:
+
+| Element | Purpose |
+| --- | --- |
+| `window` | The app window. One per app, the root of the tree. |
+| `view` | Layout and input. Boxes, flex containers, hit targets. |
+| `text`, `span` | A shaped paragraph, and a styled run inside it. |
+| `rect`, `oval`, `line`, `path` | Painted shapes. |
+| `texture` | A GPU texture: a decoded image, a camera frame, a shader target. |
+
+Layout and paint are separate jobs, which is the one place the vocabulary
+diverges sharply from HTML. A `view` never paints, so there is no
+`backgroundColor`; you put a `rect` behind the content, and by default a
+shape fills the layout box it sits in:
+
+```tsx
+<view padding={16} alignItems="center">
+  <rect color="#1b2440" radius={12} />
+  <text color="white">Boxed</text>
+</view>
+```
+
+Each painting element also has a detached twin: `d-view`, `d-rect`,
+`d-path`, `d-text`, and so on. Detached elements are positioned by their
+parent's coordinate system rather than by layout, so changing one costs no
+reflow. Use them for anything that moves at animation frequency.
+
+## Reactivity
+
+Props are reactive values, not snapshots. A signal read inside JSX
+subscribes exactly one native property to exactly one signal, and an update
+writes that property directly. Nothing re-renders, and there is no virtual
+DOM to diff:
+
+```tsx
+let [x, setX] = createSignal(0)
+
+<d-rect x={x()} w={40} h={40} color="tomato" />
+```
+
+The reactive and control-flow vocabulary comes from SolidJS 2.0 and is
+re-exported from `@solidrt/core`, so an app imports everything from one
+place: `createSignal`, `createMemo`, `createEffect`, `createStore`,
+`onCleanup`, and the control-flow components `For`, `Show`, `Switch`,
+`Match`, `Loading`, `Errored`.
+
+Because props are values rather than accessors, the usual Solid rules apply:
+do not destructure props, and read reactive values inside the expression
+that uses them.
+
+An error thrown while computing an element's props or a child expression is
+contained at that element: it keeps its last good value, the error is logged
+once with the node and source line, and the element recovers when the
+expression computes again. An error nothing claims (a throwing effect, an
+error during mount) replaces the app's window with an error window showing
+the message and stack, with a Reset that retries; the reactive system keeps
+running either way. `<Errored>` gives a subtree its own fallback.
+
+## Layout
+
+Layout is flexbox, plus a line-based subset of CSS grid, over the whole
+element tree. Prop names match CSS: `flexDirection`, `alignItems`,
+`justifyContent`, `gap`, `padding`, `width`, `position`, `top`.
+
+Units are simpler than CSS. A bare number is pixels; a percentage is
+`pct(50)`, a branded value rather than a parsed string:
+
+```tsx
+<view flexDirection="row" gap={8} padding={16}>
+  <view width={pct(50)} />
+</view>
+```
+
+`position` has `relative` and `absolute` only, and an absolute element does
+not itself become a containing block: it resolves against the nearest
+ancestor with `position="relative"`.
+
+## Input
+
+Pointer, wheel, and key events are props on any element:
+`onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerEnter`,
+`onPointerLeave`, `onWheel`, `onKeyDown`, `onKeyUp`. Events travel from the
+hit leaf up to the root, and `stopPropagation()` ends the walk. Key events
+bubble the same way, starting at the focused node - or at the window root
+when nothing is focused, so `onKeyDown` on the window is where app-global
+shortcuts live.
+
+Text entry goes to the focused node's `onTextInput`. Focusing a field never
+raises the on-screen keyboard by itself - a tap on the field (or an explicit
+`startTextInput()`) does, and never while a physical keyboard is attached.
+
+Coordinates are logical points, so a handler reads the same numbers on a
+high-density phone screen as on a desktop monitor.
+
+## Frames and animation
+
+`onFrame(callback)` runs before every painted frame with the frame time in
+ms, the frame count, and the display refresh rate; it returns a disposer and
+cleans itself up with the reactive scope it was called in. Rendering is
+demand-driven: the runtime does not spin a render loop when nothing changed,
+so an idle app is genuinely idle.
+
+```tsx
+let [t, setT] = createSignal(0)
+onFrame((tick) => setT(tick))
+
+<d-view rotate={t() / 1000}>...</d-view>
+```
+
+## Environment and devices
+
+`env` and `capabilities` describe where the app is running: `env` is what
+is observed (system theme, text scale, orientation, visibility, connected
+input devices), `capabilities` what follows from it for behavior (hover,
+touch, precise pointer, keyboard navigation, window size class). Which
+runtime features exist on this build is `Flux.capabilities`, by name, never
+by guessing from the OS.
+
+Window-shaped values are reactive too: `windowSize()`, `safeArea()`,
+`displayScale()`, `keyboardHeight()`, `windowFocused()`.
+
+Device access follows the same reactive shape, as `create*` primitives
+imported from Core subpaths rather than an imperative API:
+
+```tsx
+import { createCamera } from "@solidrt/core/camera"
+
+let camera = createCamera()
+
+<texture src={camera.texture()} fit="cover" />
+```
+
+The same pattern covers `@solidrt/core/microphone`, `/sound`,
+`/speech-recognition`, `/text-input`, `/image`, `/color`, and `/gpu`.
+
+## Reference
+
+The [reference](/core/reference/) covers the API by subject: the element
+vocabulary, drawing, text, detached elements, layout, transforms, input,
+shaders, the GPU module, and the shared types. It shows the shipped declarations themselves,
+so it says exactly what your editor says.