@solidrt/core 0.0.54 → 0.0.56

package/AGENTS.md

@@ -111,7 +111,7 @@ tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 ```
 
 Peer deps @solidjs/signals and @solidjs/universal must match (currently
-2.0.0-rc.3); bun resolves them from peerDependencies. On a version bump,
+2.0.0-rc.6); bun resolves them from peerDependencies. On a version bump,
 `bun install` only warns ("incorrect peer dependency") and keeps the old
 ones, and `bun update solid-js @solidjs/signals @solidjs/universal` does
 not read the pin either: it adds all three to package.json at registry
@@ -165,10 +165,19 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   LayoutProps`, so it draws AND is laid out by Taffy. The detached variant
   (`d-rect`) is `RectProps` only - it draws but is NOT in the layout pass; you
   place it yourself with `x`/`y` (omit them and it fills the parent, which is
-  how backgrounds work). Reach for `d-` whenever you want explicit coordinate
-  positioning instead of layout. It is also a performance lever: for many
-  directly-positioned, often-animating elements (e.g. hundreds of balls), `d-`
-  skips the per-element layout that plain elements would incur.
+  how backgrounds work). Laid-out elements are the DEFAULT for building a
+  screen: structure, cards, panels, labels - anything flex/gap/padding
+  should place - is `<view>`/`<text>` and plain primitives. Reach for `d-`
+  only with a concrete reason: a background/underlay, free-form drawn
+  geometry (a chart's marks, a diagram, vector art), an overlay pinned at
+  coordinates, or as a performance lever for many directly-positioned,
+  often-animating elements (e.g. hundreds of balls), where `d-` skips the
+  per-element layout plain elements would incur. Hand-positioning what flex
+  would place - a card built from d-rects and d-texts at computed offsets -
+  forfeits wrapping, sizing and resize behavior for nothing: inside a chart
+  the marks and axis labels are d-*, but the card around it is a `<view>`.
+  A `designSize` view is NOT a reason to go detached - laid-out children
+  resolve in design units too.
 
 - Transform origin on a `d-view`: with `originX`/`originY` unset, scale/rotate
   pivot at the view's local (0,0) - the origin its children's coordinates are
@@ -179,6 +188,22 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   Avoid pct()/keyword origins on a d-view - they resolve against the box
   inherited from the nearest laid-out ancestor.
 
+- Transforms live on views only. A draw primitive (`d-rect`, `d-text`,
+  `d-path`, ...) paints in its parent's space and has no `rotate`, `scale`
+  or origin of its own; to spin or scale one in place, wrap it in a `d-view`
+  carrying the transform, with the origin set in pixels as above. So a
+  rotating glyph is two nodes, the view at the pivot and the text placed
+  around it - `<d-view x={cx} y={cy} rotate={r}><d-text anchor="middle"
+  y={-h / 2}>{ch}</d-text></d-view>`.
+
+- A `d-text` label is anchored, not boxed: `anchor="start" | "middle" |
+  "end"` makes `x` a point on the line (SVG's text-anchor), the text shapes
+  at its natural width (no wrap) and its lines align to the anchor's side.
+  Without `anchor` a d-text is a paragraph box wrapping at `w` or at the
+  inherited box, and `textAlign` aligns inside that width - so
+  `textAlign="right"` on a `w`-less d-text aligns to the ancestor's right
+  edge, not to `x`. Reach for `anchor` on chart, axis and diagram labels.
+
 - Layout-affecting vs not (this matters for per-frame work). Props fall in three
   buckets, split by where they take effect:
   - `LayoutProps` - width/height, min/max sizes, margin, padding, `position` and
@@ -197,6 +222,22 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   `position:absolute` at `left:0,top:0`, or just let normal flow place it) and
   then translate it with `x`/`y`.
 
+- Measuring layout: never re-derive an element's position with your own
+  arithmetic - the layout engine already knows, so ask it.
+  `getBoundingBox(ref)` returns the node's laid-out box
+  ({x, y, width, height}, transforms composed, relative to the nearest
+  `position="relative"` ancestor, else the window);
+  `getBoundingBoxViewport(ref)` is always window-relative (the space pointer
+  `clientX`/`clientY` report in). Both are snapshot reads of the last
+  computed layout, not reactive - read them in `onLayout(fn)` (fires after
+  layout, before paint) or in an event handler. The canonical shape: let
+  flex place the boxes, measure them in onLayout, and drive DETACHED drawing
+  from the result - a d-path connector between two cards, a badge pinned to
+  a bar. Two rules keep it one pass: write the measurement only to props
+  that do not affect layout (a `d` string, a d-* position, a transform), and
+  call `flush()` after the write so it lands in this frame's display list.
+  See examples/on-layout-connect.tsx.
+
 - 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.
@@ -218,6 +259,23 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   inline atom flowing with the words as one unbreakable box on the baseline;
   give it margins for spacing, since JSX trims the whitespace around it.
 
+- App-side line breaking, for text a `<text>` box cannot express: text
+  poured into a shape, parting around an obstacle that is not in the flow,
+  continued across columns, fitted to a box by size, or placed glyph by
+  glyph. `prepareText(text, font)` shapes the words once (through the
+  shared word cache) into `units` carrying advance, ink width, ascent and
+  descent; `layoutNextLine(prepared, cursor, width)` is the greedy breaker,
+  returning one line and the `cursor` for the next, at whatever width you
+  hand it per call (a chord of a circle, a slot beside an obstacle, the next
+  column). Draw each line as a `<d-text>` of exactly its text with the same
+  font. Re-breaking every frame is arithmetic plus cache hits, so a moving
+  or breathing shape re-flows at frame rate; only the first shaping cost
+  anything. `carets: true` adds each unit's per-grapheme x positions - the
+  ONLY kerned per-glyph source; per-character `measureText` drops kerning
+  and visibly drifts on pairs like AV/TA. Styled runs come from `runs` (draw
+  such a line with a `<span>` per run). See examples/text-flow.tsx and
+  examples/text-glyphs.tsx.
+
 - Events: there is NO `onClick`/`onPress`. A "button" is a `<view>`/`<rect>`
   with `onPointerDown`. Handlers: onPointerDown/Up/Move/Enter/Leave, onWheel,
   onKeyDown/Up, onTextInput, onFocus/onBlur. Text entry: focus a node with an
@@ -236,7 +294,12 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
 - Gesture recognizers, shared by every package: `createPan` (single-pointer
   drag, axis-aware slop, per-event dx/dy) and `createTransform` (merged
   pan + pinch + rotate over the whole pointer set, Flutter-Scale style: streams
-  `{ dx, dy, scale, rotation, x, y, pointers }` once per FRAME - positions
+  `{ dx, dy, scale, rotation, x, y, pointers }` once per FRAME. Frames, both
+  recognizers: slop and span gates are finger travel and measure in window
+  pixels; dx/dy are measured in the handler node's PARENT frame (the frame
+  its own x/y live in) so they apply 1:1 to the node or to content inside
+  it under any scaled ancestor (a designSize fit); the transform's focal
+  x/y is in the node's LOCAL frame, the zoom-about anchor. Positions
   update per event, but the cross-pointer measure waits for the
   `pointerFrame` batch terminator, when every pointer is the same age; one
   finger degrades to a plain pan, and `pointers` is how a consumer gives one-
@@ -259,13 +322,14 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   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.
+  `createMemo`, an effect's compute phase, a `ref` callback) throws
+  `REACTIVE_WRITE_IN_OWNED_SCOPE` in dev; a loader kicked off in the
+  component body or a ref that reports progress through a signal is the
+  classic reflex that hits this. `untrack` does NOT exempt a write (the
+  guard is owner-based, and untrack only stops tracking). Move the write
+  into an event handler, an effect's apply phase, or `onSettled`; 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.
@@ -286,9 +350,19 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   session in seconds) and it is what keeps per-frame work cheap.
 - Animation is target-shaped first: declare `transition` on the element and
   write targets, and the runtime animates natively with no per-frame JS.
+  Enter and exit are per-property entries on that same spec: `from` is the
+  value the property animates in from at first attach, `exit` the value it
+  animates to on removal (the node stays painted until it settles, then
+  frees - no AnimatePresence equivalent needed). `stagger` (ms) goes on an
+  ANCESTOR, never on the animating elements: it delays each descendant's
+  enter/exit by `index * stagger`, and cascades nothing unless the
+  descendants declare `from`/`exit`. An enter plays once per mount; to
+  replay it, remount the subtree (`<Show when={epoch()} keyed>` around it,
+  then bump `epoch`). See examples/stagger.tsx.
   Reach for per-frame work only for genuinely procedural motion:
   `onFrame((tick, frame, rate) => {})` is the native hook (runtime-paced,
-  returns a cleanup, auto-cleaned inside a reactive scope); `rate` is the
+  returns a cleanup, auto-cleaned inside an owned scope; from an effect's
+  apply, return it so the loop runs only while the condition holds); `rate` is the
   display's nominal refresh rate in Hz, which a fixed-timestep loop needs
   (see @solidrt/cli agents/debugging.md on stepping); `requestAnimationFrame`
   exists as a web-standard one-shot but is not the preferred driver. A JS
@@ -298,10 +372,11 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   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`.
+  `keyboardHeight()`, `pointerLocked()`) for reading window state;
+  onLayout's real job is the measure-then-draw pattern above. 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
@@ -313,10 +388,13 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
 
 - Device/GPU access via subpath imports: @solidrt/core/camera, /microphone,
   /speech, /gpu. Image flow: `decodeImage(bytes)` ->
-  `createTexture(data,w,h)` -> `<texture src={id} />`. Pixels are
-  premultiplied alpha from decode onward (the GPU contract); `decodeImage(bytes,
-  { alpha: "straight" })` keeps the file's color under transparent pixels for
-  CPU work, and `encodeImage` converts back to straight for the file.
+  `createTexture(data,w,h)` -> `<texture src={id} />`. Sampling (`filter`,
+  `wrap`, `mipmap`) is fixed at creation on every create* helper and follows
+  the id everywhere; agents/performance.md rule 2 says when to set which.
+  Pixels are premultiplied alpha from decode onward (the GPU contract);
+  `decodeImage(bytes, { alpha: "straight" })` keeps the file's color under
+  transparent pixels for CPU work, and `encodeImage` converts back to
+  straight for the file.
 
 ## Minimal app, core primitives only (verified to render)
 

package/agents/painting.md

@@ -3,12 +3,15 @@
 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
+Layout and props are half the model. There is no stylesheet: no selectors, 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.
+CONTENT calls for, not the one that looks safest. The tiers compose per
+ELEMENT, not per screen: a dashboard's cards, rows and labels stay tier-1
+laid-out structure even when every card holds a tier-2 chart or a tier-3
+shader. Escalate the element the content calls for, never the whole screen.
 
 1. Laid-out elements - `<view>`/`<text>`, with `<rect>` (or a filling
    `<d-rect>` child) for background, border, radius. The structure of a
@@ -38,17 +41,32 @@ no matter how complex the effect, which is why the performance model
 
 ## Web reflexes and what replaces them
 
+- `color-mix()`, `oklch()`, `lab()` -> not in the color grammar (hex,
+  `rgb()`, `hsl()`, `hwb()`, named colors only; the prop throws `Invalid
+  color` otherwise). Mix in JS with `mixColors(a, b, t)` from @solidrt/core
+  (oklab, so a ramp between two colors stays perceptually even) and pass
+  the result; `withAlpha(color, a)` gives any color at an opacity (do not
+  rebuild `rgba()` strings by hand from a hex); `brightness(color)` picks
+  readable text over any fill.
 - 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
+- `filter: blur/grayscale/hue-rotate/...` -> the `filter` prop on a view
+  (object form: `filter={{ blur: 4, grayscale: 1 }}`; hueRotate in radians).
+  For processing beyond the CSS filter functions, a `shader` on the view
+  (requires repaintBoundary="snapshot"), or on `<window>` for the whole frame
+- `box-shadow` -> the `shadow` prop on the shape that IS the surface:
+  `<rect radius={12} color="white" shadow={{ y: 4, blur: 16, color:
+  "#0006" }}/>` (also on oval and path; fields are CSS box-shadow's, color
+  required). `text-shadow` / glow -> still no prop: draw an offset `d-*`
+  shape under the content, or a view shader with `outset` (the transparent
+  margin an effect bleeds into)
+- `backdrop-filter` -> the `backdropFilter` prop on a view (same keys as
+  `filter`): frosted glass with real see-through semantics. It reads the
+  pixels already painted beneath, so it costs an offscreen capture - a
+  deliberate panel, not a casual style - and inside a
+  repaintBoundary="snapshot" subtree it sees only that boundary's own
+  content. A view `shader` cannot do this at all (it sees only its own
+  subtree's pixels)
 - 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;
@@ -56,6 +74,12 @@ no matter how complex the effect, which is why the performance model
   uniform when the animation is continuous and visual
 - `<canvas>` 2D -> `d-*` primitives (rebuild one `d-path` string per frame
   rather than animating N elements)
+- leader lines, connectors, an annotation or badge hugging an element, any
+  drawing that must align with laid-out content -> measure, do not
+  calculate: read the boxes with `getBoundingBox` inside `onLayout` and
+  drive the `d-*` overlay from the result (core AGENTS.md "Measuring
+  layout", examples/on-layout-connect.tsx). Mirroring the layout math in JS
+  to predict where an element ends up is always wrong somewhere
 - `<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

@@ -60,9 +60,21 @@ Rules, in order of leverage:
    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.
+   retro/pixel-art path), `{ wrap: "repeat" }` to tile outside 0..1 in
+   shaders, and `{ mipmap: true }` wherever a shader samples the texture
+   smaller than it is (a 3d surface receding into the distance, a target
+   read at a fraction of its size): without a mip chain minification skips
+   texels and aliases. The chain is regenerated by the runtime after every
+   upload and every target render, nothing to schedule, but it is one GPU
+   pass each time, so a per-frame texture pays it per frame. Add
+   `anisotropy: 8` (any level; the device clamps) beside `mipmap: true` on a
+   tiled surface seen at a grazing angle - a road or floor receding to the
+   horizon - where trilinear alone smears the far half into the mip its
+   long axis chose; it does nothing without the chain. The defaults
+   are linear, clamp, no mips and anisotropy 1; the choice is fixed at creation (a change
+   means a new id) and applies both on screen and to shaders sampling the
+   texture, except that the `<texture>` display draw samples the full-size
+   level only, so mips never help a texture merely shown smaller.
 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
@@ -76,8 +88,11 @@ Rules, in order of leverage:
    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.)
+   re-requesting when its work list empties. A loop that should run only
+   while a condition holds is an effect returning it:
+   `createEffect(() => active(), on => { if (!on) return; return onFrame(...) })`
+   - the apply phase has no owner, so onFrame registers nothing there and
+   the returned cleanup is the handle the effect disposes.
 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
@@ -102,7 +117,15 @@ Rules, in order of leverage:
    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.
+   one-frame hiccup - pool or pre-warm if that moment matters. The texture
+   is sized by the view's box: the layout box on a view, the inherited
+   frame on a d-view (so a d-view directly under the window snapshots the
+   whole window - box it tighter when the content is small). Confirm a
+   boundary actually engaged rather than trusting the prop: get_render_tree
+   props reads
+   repaintBoundary back, get_stats' nodesPainted drops when the fenced
+   subtree stops being walked, and the dev overlay's BND/SNP lines count
+   boundary reuse per frame.
 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
@@ -140,6 +163,13 @@ Rules, in order of leverage:
    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.
+10. Text costs shaping, once per word per style, through a shared word cache;
+   line breaking is arithmetic over the shaped words. So re-breaking text
+   every frame with prepareText + layoutNextLine (a shape that breathes, an
+   obstacle that moves, an editor on every keystroke) is cheap - the lines'
+   d-texts hit the same cache - while changing a text's font, size or
+   weight re-shapes it. Animate text with transforms and paint (rule 5), or
+   by re-breaking; not by resizing it per frame.
 
 ## Isolates: heavy work off the JS thread
 

package/docs/reference/detached.md

@@ -21,11 +21,14 @@ because there is nothing in the layout to reflow. The same content as a
 laid-out `<rect>` with `left={x()}` would put the layout engine on the path of
 every frame.
 
-**Reach for the detached form first for anything that moves at animation
-frequency**, and for content authored in fixed design units - a chart, a
-diagram, an svg drawing, a particle field. Reach for the layout form when you
-want the element to participate in a flex or grid arrangement, which is most
-static UI.
+**The layout form is the default: most of a screen - structure, panels,
+labels, anything a flex or grid arrangement should place - is laid-out
+elements.** Reach for the detached form for anything that moves at animation
+frequency, and for free-form geometry drawn at coordinates - a chart's marks,
+a diagram, an svg drawing, a particle field. A `designSize` view is not such
+a reason: laid-out children resolve in design units too, so even a
+fixed-design screen is built from laid-out elements, with detached geometry
+only where content is genuinely drawn rather than arranged.
 
 ## What changes
 
@@ -49,7 +52,10 @@ to detach from.
 
 ## Geometry
 
-Detached geometry is paint-space pixels and never affects layout.
+Detached geometry is paint-space pixels and never affects layout. The
+reverse holds too: a laid-out tile holding only detached geometry must not
+be allowed to flex-shrink (wrap the row, or give it `flexShrink={0}`),
+since the box shrinks and the geometry does not.
 
 {{ decl packages/core/src/types.d.ts PositionProps }}
 
@@ -62,15 +68,19 @@ ancestor, so a `d-rect` with only `x`/`y` still has something to draw:
 
 {{ decl packages/core/src/types.d.ts OvalGeometryProps }}
 
-For `d-text`, width is the shaping width and height is reported bounds only,
-since a paragraph's height always falls out of the text itself:
+`d-text` is boxed or anchored. Boxed, it wraps at `w` or at the inherited
+box, and `textAlign` aligns lines inside that width. Anchored, `x` is a point
+on the line (SVG's `text-anchor`) and the text does not wrap unless given a
+`w`; that is the form for labels. Its reported bounds are the laid-out
+paragraph, with `w`/`h` overriding a side each:
 
 {{ decl packages/core/src/types.d.ts TextGeometryProps }}
 
 `d-path` takes only a position, since its size is whatever its `d` string
 draws. `d-line` has no width and height either: its geometry is its two
-endpoints (or, as a polyline, its `points`), which is what makes it the
-primitive to reach for when the geometry moves. Both report their bounds
+endpoints (or, as a polyline, its `points`), offset as a whole by `x`/`y`,
+which is what makes it the primitive to reach for when the geometry moves.
+Both report their bounds
 (getBoundingBox, the tree, a capture) as that geometry plus the stroke, not
 the inherited box:
 

package/docs/reference/drawing.md

@@ -27,12 +27,13 @@ stroke rather than a box.
 
 ## Dashing
 
-A stroke's dash pattern, on `line` and `path`:
+A stroke's dash pattern, on every stroked primitive:
 
 {{ decl packages/core/src/types.d.ts DashProps }}
 
 The pattern is walked along the geometry itself: through a polyline's
-vertices and along a path's curves, restarting at each subpath of a path.
+vertices, along a path's curves (restarting at each subpath), and around a
+rect's or oval's inset outline (inside the box, like the solid stroke).
 `dashOffset` slides it - write it every frame for marching ants, or
 transition it for a one-shot slide. A dashed stroke keeps its caps on every
 dash, and a stroke-and-fill path dashes only the stroke.
@@ -47,10 +48,16 @@ the length).
 
 {{ decl packages/core/src/types.d.ts RectProps }}
 
+A dashed rect (a selection marquee, a drop zone) is the dash props on the
+rect itself; see Dashing above. The pattern starts on the top edge after
+the top-left corner and runs clockwise.
+
 ## oval
 
 {{ decl packages/core/src/types.d.ts OvalProps }}
 
+Dashes like a rect; the pattern starts at 3 o'clock and runs clockwise.
+
 ## line
 
 {{ decl packages/core/src/types.d.ts LineProps }}
@@ -84,7 +91,7 @@ for every pixel source in the engine.
 ## Logo
 
 The SolidRT brand mark, the same seven-segment puzzle the scaffold's welcome
-screen and the launcher draw, as a component: a square `view` of `size`
+screen and the player draw, as a component: a square `view` of `size`
 pixels with the segments as gradient-filled `d-path`s.
 
 {{ decl packages/core/src/logo.tsx LogoProps }}

package/docs/reference/elements.md

@@ -51,6 +51,8 @@ Three of those props are worth knowing before you need them:
   reflow.
 - `repaintBoundary` retains the subtree's display list, and in its
   `"snapshot"` forms its rasterized pixels too. It is the lever for putting
-  heavy static content next to content that changes every frame.
+  heavy static content next to content that changes every frame. On a
+  `d-view` the snapshot boxes the inherited frame: the nearest laid-out
+  ancestor's box, or the design size under a `designSize` view.
 - `clipRadius` rounds the clip, and only does anything when `overflow` is
   non-visible.

package/docs/reference/gpu.md

@@ -59,6 +59,8 @@ the dev tooling's GPU inventory and in engine log messages.
 
 {{ decl packages/core/src/gpu.ts createTexture }}
 
+{{ decl packages/core/src/gpu.ts createCubeTexture }}
+
 {{ decl packages/core/src/gpu.ts createMutableTexture }}
 
 {{ decl packages/core/src/gpu.ts createShaderTexture }}
@@ -147,6 +149,14 @@ clamped target in one consumer. The texture's own state stays what
 `<texture>` paints and what every other binding uses. `mipmap` is not
 overridable: the chain either exists on the id or it does not.
 
+A cube map (`createCubeTexture`) is the same id currency with a different
+sampler: declare `uniform samplerCube` and look it up by direction. The
+declared sampler type is what a binding is checked against - a cube map on
+a `sampler2D` throws, as does a 2D texture on a `samplerCube` - and a cube
+map is sampler-only: nothing displays, reads back, copies or re-uploads it.
+`wrap` does not apply to it (cube filtering is seamless across faces);
+`filter`, `mipmap` and `anisotropy` do.
+
 ## Blending
 
 Combining passes is a render-tree job: stack `<texture>` elements and set
@@ -202,6 +212,7 @@ instead - for a UI subtree, `snapshotTexture`.
 ## Limits
 
 `limits` holds the device ceilings queried at startup: maximum texture and
-target size, sampler inputs per pass, vertex attributes per pipeline. Creates
+target size, cube map face size, sampler inputs per pass, vertex attributes
+per pipeline. Creates
 and binds validate against them and throw naming the limit; read them to
 size within the device instead.

package/docs/reference/layout.md

@@ -42,3 +42,31 @@ wrap around.
 ## Grid
 
 {{ decl packages/core/src/types.d.ts GridProps }}
+
+## Measuring
+
+Positions come from the engine, not from arithmetic mirrored in app code.
+`getBoundingBox(node)` returns the box from the most recently computed layout
+as `{ x, y, width, height }`, transforms composed, relative to the nearest
+`position="relative"` ancestor (falling back to the window), or `null` before
+the first layout. `getBoundingBoxViewport(node)` is the same box always
+window-relative, the space pointer `clientX`/`clientY` report in. Both are
+snapshot reads, not reactive.
+
+The moment to read them is `onLayout(fn)`: it fires after layout is computed
+but before paint, so a measurement can still shape what the current frame
+draws - the pattern for a connector between two laid-out cards, or an
+annotation pinned to a bar the layout placed. Write the result to something
+that does not affect layout (detached geometry, a `d` string, a transform)
+and call `flush()` so the write lands before the display list is built;
+writing a layout prop from `onLayout` costs an extra layout pass.
+
+```tsx
+onLayout(() => {
+  let a = getBoundingBox(boxA)
+  let b = getBoundingBox(boxB)
+  if (!a || !b) return
+  setD(`M ${a.x + a.width / 2} ${a.y + a.height / 2} L ${b.x} ${b.y}`)
+  flush()
+})
+```

package/docs/reference/text.md

@@ -44,3 +44,37 @@ Inline only: its children are text and other spans, and it has no layout box,
 which is why it is the one element with no detached form. Pointer handlers on
 a span fire for the boxes its text occupies on each line it spans, and bubble
 to the enclosing spans and the text.
+
+## Line breaking in app code
+
+A `<text>` wraps in a box. For anything else - text poured into a shape,
+parting around an obstacle that is not in the flow, continued across columns,
+fitted to a box by size, or placed glyph by glyph - the app does the breaking
+itself over words the engine shaped once:
+
+```tsx
+let prepared = prepareText(article, { fontSize: 16, lineHeight: 1.4 })
+let cursor = 0
+for (let band of bands) {                        // any widths, in any order
+  let line = layoutNextLine(prepared, cursor, band.w)
+  if (!line) break
+  lines.push({ ...band, w: line.width, text: prepared.text.slice(line.start, line.end) })
+  cursor = line.cursor                            // the next box continues here
+}
+```
+
+`prepareText` returns the paragraph's wrap units (a word and its trailing
+whitespace) with their advance, ink width, ascent and descent. `layoutNextLine`
+is a greedy breaker over those numbers: it fills one line to the width you hand
+it and returns the cursor for the next, so a circle is a stack of chords, a
+column is the same loop with a new box, and a headline that must fit is a loop
+over sizes. Each line is drawn as a `<d-text>` of exactly its own text in the
+same font.
+
+The split is what makes it usable: shaping happened once, through the shared
+word cache the drawn lines hit again, so re-breaking three paragraphs every
+frame as a shape moves costs arithmetic, not layout. `carets: true` adds each
+unit's per-grapheme x positions from that same shaping - the kerned source for
+per-glyph placement and animation, which measuring characters one at a time
+cannot give. `runs` restyles ranges, with a unit crossing a run boundary coming
+back as glued pieces that always land on one line.

package/examples/README.md

@@ -13,9 +13,14 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `detached-positioning.tsx` - the `d-` prefix: x/y placement, no reflow, detached-only children.
 - `text-paint-styling.tsx` - the uniform `color` prop; `drawStyle="stroke"` vs fill.
 
+## Text
+- `text-flow.tsx` - app-side line breaking: `prepareText` shapes a paragraph's words once, `layoutNextLine` breaks one line per call at any width. Poured band by band into a circle (each band the chord at its height), then the cursor continues in a column beside it; every line is a `d-text` of its own text. Re-breaks fully on resize for arithmetic plus word-cache hits.
+- `text-glyphs.tsx` - per-glyph positions: `prepareText(text, { carets: true })` reports each unit's kerned grapheme x positions from the shaping that is drawn. One `d-text` per glyph placed from carets sits exactly on the whole headline; the same glyphs placed by per-character `measureText` drift on every kerning pair.
+
 ## Frame and lifecycle
 - `frame-animation.tsx` - `onFrame` driving a transform animation each frame.
 - `on-layout-connect.tsx` - `onLayout` + `getBoundingBox` connecting laid-out boxes with a `d-path`.
+- `stagger.tsx` - enter/exit/stagger with no per-frame JS: `from` and `exit` per property on each row's own `transition`, `stagger` on the ANCESTOR cascading them in occurrence order, and the replay idiom - a keyed `<Show>` remounts the subtree when its `when` value changes, so bumping an epoch replays the whole cascade. Exiting rows stay painted until they settle.
 
 ## Pointer input
 - `pointer-local-coords.tsx` - the three pointer coordinate frames (`clientX` window, `localX` the handling node's own frame, `parentX` its path-parent's frame - where the node's x/y live) and the transform-proof drag idiom: grab offset from `localX` at down, place with `parentX - offset` on moves. Exact inside rotated/scaled ancestors and when the pointer leaves the node mid-drag.

package/examples/detached-positioning.tsx

@@ -2,7 +2,9 @@
 // you place it yourself with x/y. Because a detached node does not participate in
 // layout, moving it (animating x/y) does not reflow its siblings - which makes
 // d- elements the right choice for overlays, badges, and anything that moves
-// independently. The rule: a detached node can only contain other detached
+// independently. They are the exception, not the default: screen structure
+// (panels, cards, labels) stays laid out with <view>/<text>; a d- subtree is
+// for drawn or moving content. The rule: a detached node can only contain other detached
 // nodes. Everything under a d- element must itself be a d- element (here d-rect +
 // d-text) - nesting a plain <view> or <text> inside a d- element is an error.
 import { render } from "@solidrt/core"

package/examples/line-points.tsx

@@ -19,6 +19,9 @@
 //    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.
+// 6. Dashed boxes: the same props on d-rect and d-oval dash the inset
+//    outline the solid stroke draws, so a marquee or a drop zone is one
+//    element and its dashes never leave the box.
 // 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"
@@ -115,6 +118,24 @@ function App() {
         </view>
       </view>
 
+      <text fontSize={16} color="#8b949e">
+        dashed boxes: a rounded marquee, a stroke-and-fill rect, an oval drawing on
+      </text>
+      <view flexDirection="row" flexWrap="wrap" gap={20}>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-rect x={20} y={20} w={100} h={80} radius={12} drawStyle="stroke" onLength={8} offLength={6} dashOffset={-ants()} color="#e3b341" strokeWidth={3} />
+        </view>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-rect x={20} y={20} w={100} h={80} drawStyle="stroke-and-fill" onLength={10} offLength={6} color="#f8514966" strokeWidth={6} strokeCap="round" />
+        </view>
+        <view width={140} height={120}>
+          <d-rect radius={8} color="#151b28" />
+          <d-oval x={20} y={20} w={100} h={80} drawStyle="stroke" pathLength={1} onLength={drawn()} offLength={1} color="#3fb950" strokeWidth={4} 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>