@solidrt/core 0.0.55 → 0.0.57

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.4); 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
@@ -132,6 +132,14 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   window (message, stack, a Reset button that retries the failed
   computations) and logs `Uncaught error`. `<Errored>` gives a subtree its
   own in-place fallback.
+  An `onFrame` callback is its own boundary, event-listener style: a throw
+  is caught and logged (`Error in onFrame callback`, repeating every
+  frame), the subscription stays, and THE REST OF THAT CALLBACK IS
+  ABANDONED - what it wrote before the throw lands, what came after never
+  does, frame after frame while the app keeps presenting. A partial frame
+  is therefore a live possibility: every sprite drawn after the throwing
+  line simply stops appearing, which reads on screen as a logic bug, not a
+  crash. Check the logs before reasoning about a rendering symptom.
 
 - Two kinds of element:
   - Containers - `<window>`, `<view>`. Do layout + transform + pointer events.
@@ -165,10 +173,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
@@ -213,6 +230,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.
@@ -269,7 +302,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-
@@ -282,6 +320,87 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   rather than track pointers ad hoc, or they will double-handle against
   scrollers and pressables.
 
+- The input map (input-map.ts) is how anything drives a control:
+  ARCHITECTURE.md's rule is that a control (a camera, a character
+  controller) consumes a device-free abstraction and never handles events
+  or reads a device itself, and the map is the named, typed layer between
+  devices and consumers - Godot's InputMap and Unity's action maps in
+  reactive form. `createInputMap({ look: "vec2", move: "vec2", zoom:
+  "axis", jump: "button" })` declares the app's actions once; devices bind
+  to them by name (`input.bind("look", pointer.drag, gamepad(0).rightStick)`,
+  `input.bind("move", keyboard.wasd, gamepad(0).leftStick)`); consumers
+  read the action, never the device. Every axis/vec2 action carries TWO
+  channels: the RATE (the sum of every bound source's current value,
+  clamped - an axis to -1..1, a vec2 to unit length - reactive, sampled per
+  frame by the consumer and integrated over dt at its own speed) and the
+  DELTAS (immediate amounts a gesture produced, in device-free units: a
+  drag in element heights, a wheel notch or a pinch in octaves, a twist in
+  turns, with begin/end brackets around a finger's gesture and the focal
+  point as a fraction of the element). Values use the screen convention
+  throughout: x right, y down, a stick pushed up reads y = -1, and a
+  consumer that means "forward" by a vec2 reads -y. A button source may
+  bind to an axis action (1 while pressed); a vec2 source on an axis
+  action throws.
+  Devices are the nouns: `keyboard.key("Space")`, `keyboard.axis("KeyQ",
+  "KeyE")`, `keyboard.vec2({ up, down, left, right })`, `keyboard.wasd`,
+  `keyboard.arrows`, a spec with modifiers ahead of the key
+  ("Shift+Tab", "Ctrl+KeyS": the most specific spec in a source wins a
+  down, an up releases on the bare key) (key events reach them through
+  `input.handlers`, spread on `<window>` for app-global keys or on the
+  leaf that should hold focus for them - keys bubble to the window, so a
+  TextInput's consumed keys never arrive); `gamepad(slot)`, `gamepad()`
+  for every pad, or `gamepad.next()` for the next unclaimed pad to press
+  any button (split screen seats players in pick-up order; its `slot`
+  resolves reactively and frees when the creating scope is disposed),
+  with `leftStick`, `rightStick`, `dpad`, `triggers` (right minus left),
+  `shoulders`, `axis(name)`, `button(name)`, reactive over gamepads() so a
+  stick wakes a control's frame loop; `createPointerFeed()` for the one
+  device that is not global - a pointer event belongs to the element
+  under it, so the feed is per element: spread `feed.handlers` on the
+  leaf (`<Scene pointer>`, `<View3d pointer>`, `<SpriteLayer pointer>` and
+  `<View2d pointer>` take a feed and spread it on their built-in leaf) and
+  bind its gestures `drag` (one pointer), `pan` (two), `pinch`, `twist`,
+  `wheel` and `mouseDelta` (raw motion while pointerLocked()). One
+  merged recognizer serves them, so they arbitrate in the arena as one. A
+  detached d-* leaf has no layout box: give the feed `{ layout }` or it
+  throws at the first press. `invert(source)` and `scale(source, k)` are
+  the two processors: keys and sticks move the CAMERA where a drag moves
+  the content, so a preset binds arrows or a stick to `pan`/`rotate`
+  through invert() and the action keeps one meaning.
+  Consumers with the axes contract (`createAxes({ rotate: "vec2", zoom:
+  "axis" }, { onNudge, onBegin, onEnd })`, what every camera control
+  exposes as `.axes`) are connected by name with `input.drive(control.axes,
+  names?)`: each axis takes the action of the same name, or the one
+  `names` gives it (null skips one), both channels; the camera components
+  take the map as their `input` prop and do exactly that. Injection by
+  name is the wire for scripts, debug commands, peers and replays:
+  `input.set("move", [0, -1])` holds a rate, `press`/`release` a button,
+  `nudge`/`begin`/`end` feed the delta channel. `bindings()` lists what is
+  bound (source labels are display strings), `unbind` removes one, and a
+  preset (`orbitBindings`, `firstPersonBindings` in @solidrt/3d,
+  `camera2dBindings` in @solidrt/2d) is a plain bindings list the app
+  applies and edits - nothing binds unless the app says so (the one
+  built-in default is the UI set inside components' createFocusNav, the
+  platform's own layer). The map is an instance: two pads on two views is
+  two maps. Contexts are a switch per action: `input.disable("move",
+  "jump")` / `enable(...)` (a set is a list of names, so
+  `disable(...Object.keys(gameActions))` when a menu opens); a disabled
+  action reads neutral, drops its deltas and closes the gesture it had
+  open, while its sources keep their state so a key still held when it
+  comes back reads at once; `enabled(name)` is reactive. Create maps and
+  feeds in an owned scope (a component body): onPress/onRelease run
+  effects under it and the feed's recognizer registers its cleanup there. The vocabulary the
+  controls share, one kind and unit per word: `pan` vec2 (view heights),
+  `zoom` axis (octaves, positive in), `rotate` vec2 (orbit turns), `roll`
+  axis (turns about the view axis), `look` vec2 (turns), `move` vec2
+  ([right, forward], forward = -y), `rise` axis (up). The runtime-free
+  half (`createInputMap`, `createAxes`, `keyboard`, the processors) is
+  importable as `@solidrt/core/input` for headless checks;
+  checks/input-map-check.ts runs it on the bare flux binary, and
+  checks/input-gamepad-check.ts drives the gamepad device and the join
+  order over a signal of pad snapshots (input-gamepad-device.ts is
+  runtime-free; input-gamepad.ts hands it gamepads()).
+
 - Reactivity is SolidJS 2.0 (`@solidjs/signals`), NOT Solid 1.x. `createSignal`
   is as you expect, but `createEffect` takes the 2.0 two-function shape: a
   TRACKED compute that reads signals and returns a value, then an UNTRACKED
@@ -292,13 +411,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.
@@ -316,7 +436,11 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   TypeScript with no @solidrt imports, with the JSX reading it and the
   per-frame hook doing one state step plus a handful of property writes.
   That shape runs under bun with no window (tests, audits, replaying a whole
-  session in seconds) and it is what keeps per-frame work cheap.
+  session in seconds) and it is what keeps per-frame work cheap. For a game
+  it is the tuning loop itself: minutes of play run headless in a fraction
+  of a second, so a difficulty curve or a spawn table is tuned against
+  scripted policies in seconds instead of by playing, and the design bugs
+  that only show at scale surface there first.
 - 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
@@ -328,9 +452,14 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   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:
+  Per-frame work is for genuinely procedural motion, and a game or a
+  simulation is that in full: its natural shape is ONE `onFrame` doing one
+  sim step and N property (or sprite) writes, which is not a smell but the
+  budget the runtime is built for - agents/performance.md rule 4 has the
+  rules, @solidrt/2d's notes the measured write costs at scale.
   `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
@@ -340,10 +469,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

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
@@ -47,15 +50,23 @@ no matter how complex the effect, which is why the performance model
   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;
@@ -63,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

@@ -88,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
@@ -114,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

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
 

package/docs/reference/drawing.md

@@ -91,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/examples/README.md

@@ -25,6 +25,9 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 ## 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.
 
+## Gamepads
+- `gamepad.tsx` - the pad test bed: every connected pad's raw `gamepads()` snapshot (slots, buttons, axes) and two players seated by `gamepad.next()` - press any button on a pad to join player 1, another pad joins player 2 - each an input map (`move` on the left stick and dpad, `zoom` on the triggers, `jump` on south) printing its values live and walking a marker with `move`. Nothing moves until a pad does.
+
 ## Performance
 - `snapshot-texture.tsx` - `snapshotTexture(ref)`: a `repaintBoundary="snapshot"` view's rasterized pixels as a live texture id; a shader texture samples the panel and a sibling `<texture>` shows the warped copy. The boundary re-rasterizes only when its content changes.
 - `repaint-boundary.tsx` - `repaintBoundary` on a `<view>` to keep static content from rebuilding while a neighbor animates: `{true}` retains the recorded draw list, `"snapshot"` also retains the rasterized pixels as a GPU texture (for raster-expensive, screen-aligned, static subtrees). `"snapshot-no-aa"` rasterizes without anti-aliasing: cheaper, fine for text and axis-aligned rects, hard-edged on vector content.

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/gamepad.tsx

@@ -0,0 +1,94 @@
+// Gamepad test bed: every connected pad's raw snapshot (gamepads()) at the
+// top, and two players seated by gamepad.next() below - press any button
+// on a pad and it joins player 1, another pad joins player 2. Each player
+// is an input map (`move` vec2 on the left stick and the dpad, `zoom` axis
+// on the triggers, `jump` button on south) whose values print live, plus
+// a marker that walks with `move`, so what a pad does is on screen.
+// Nothing moves until a pad does.
+import { createInputMap, createSignal, gamepad, gamepads, onFrame, render, untrack, windowSize, For } from "@solidrt/core"
+import type { Vec2 } from "@solidrt/core"
+
+const PLAYERS = 2
+// Marker travel at full stick deflection, pixels per second.
+const SPEED = 300
+const MARKER = 28
+const COLORS = ["#ffcc4d", "#66e6ff"]
+
+let fmt = (v: number) => (v < 0 ? "" : " ") + v.toFixed(2)
+let clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+
+function App() {
+  let players = Array.from({ length: PLAYERS }, (_, i) => {
+    let pad = gamepad.next()
+    let input = createInputMap({ move: "vec2", zoom: "axis", jump: "button" })
+    input.bind("move", pad.leftStick, pad.dpad)
+    input.bind("zoom", pad.triggers)
+    input.bind("jump", pad.button("south"))
+    // The marker: plain numbers stepped per frame, a signal to redraw.
+    let x = 80 + i * 120
+    let y = 260
+    let [pos, setPos] = createSignal<Vec2>([x, y])
+    let [jumps, setJumps] = createSignal(0)
+    input.onPress("jump", () => setJumps(n => n + 1))
+    let step = (dt: number) => {
+      let [mx, my] = untrack(() => input.value("move"))
+      if (mx === 0 && my === 0) return
+      let size = untrack(windowSize)
+      x = clamp(x + mx * SPEED * dt, 0, Math.max(0, size.width - MARKER))
+      y = clamp(y + my * SPEED * dt, 0, Math.max(0, size.height - MARKER))
+      setPos([x, y])
+    }
+    return { pad, input, pos, jumps, step }
+  })
+  let last: number | null = null
+  onFrame(tick => {
+    let dt = last === null ? 0 : (tick - last) / 1000
+    last = tick
+    for (let p of players) p.step(dt)
+  })
+  let padLine = (slot: number, pad: { name: string; buttons: string[]; axes: Record<string, number> } | null) => {
+    if (!pad) return `slot ${slot}: empty`
+    let a = pad.axes
+    return `slot ${slot}: ${pad.name} - buttons [${pad.buttons.join(" ")}] left${fmt(a.leftX ?? 0)},${fmt(a.leftY ?? 0)} right${fmt(a.rightX ?? 0)},${fmt(a.rightY ?? 0)} triggers${fmt(a.leftTrigger ?? 0)},${fmt(a.rightTrigger ?? 0)}`
+  }
+  return (
+    <window>
+      <d-rect color="#181820" />
+      <view flexDirection="column" gap={10} padding={24}>
+        <text color="#eef4ff" fontSize={22} fontWeight={700}>
+          Gamepads
+        </text>
+        <text color="#a9bcd6" fontSize={14}>
+          press any button on a pad to join as player 1, another pad for player 2 - left stick or dpad walks the marker, triggers read zoom, south counts jumps
+        </text>
+        <view flexDirection="column" gap={2}>
+          <text color="#a9bcd6" fontSize={14}>
+            connected: {String(gamepads().filter(p => p !== null).length)}
+          </text>
+          <For each={gamepads()} keyed={false}>
+            {(pad, i) => (
+              <text color="#eef4ff" fontSize={14}>
+                {padLine(i, pad())}
+              </text>
+            )}
+          </For>
+        </view>
+        <For each={players}>
+          {(p, i) => (
+            <view flexDirection="column" gap={2}>
+              <text color={COLORS[i()]} fontSize={16} fontWeight={700}>
+                player {String(i() + 1)}: {p.pad.slot === undefined ? "press any button on a pad to join" : `pad ${p.pad.slot}`}
+              </text>
+              <text color="#eef4ff" fontSize={14}>
+                move{fmt(p.input.value("move")[0])},{fmt(p.input.value("move")[1])} zoom{fmt(p.input.value("zoom"))} jump {p.input.pressed("jump") ? "down" : "up"} (x{String(p.jumps())})
+              </text>
+            </view>
+          )}
+        </For>
+      </view>
+      <For each={players}>{(p, i) => <d-rect x={p.pos()[0]} y={p.pos()[1]} w={MARKER} h={MARKER} radius={6} color={COLORS[i()]} />}</For>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/view-design-size.tsx

@@ -30,6 +30,11 @@
 // geometry - diagrams, slides, dashboards, game boards, emulator screens - fit
 // one design space instead.
 //
+// Design space changes the units, not the element choice: laid-out views and
+// text stay the default under a designSize (fact 3). The d-* scene below is
+// free-form drawn geometry; panels, cards and labels would still be built
+// from laid-out elements, as the flex row at the bottom shows.
+//
 // Resize the window and watch: the scene keeps its aspect ratio, everything
 // including text scales together, and the readout reports the same design
 // coordinates for the same spot on the scene at any window size.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -13,10 +13,12 @@
     "./data": "./src/data.ts",
     "./gpu": "./src/gpu.ts",
     "./image": "./src/image.ts",
+    "./input": "./src/input.ts",
     "./audio": "./src/audio.ts",
     "./microphone": "./src/microphone.ts",
     "./speech-recognition": "./src/speech-recognition.ts",
     "./text-input": "./src/text-input.ts",
+    "./video": "./src/video.ts",
     "./jsx-runtime": "./jsx-runtime.d.ts",
     "./jsx-runtime-dev": "./jsx-runtime.d.ts"
   },
@@ -29,11 +31,11 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.55"
+    "@solidrt/flux-types": "0.0.57"
   },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.4",
-    "@solidjs/universal": "2.0.0-rc.4",
-    "solid-js": "2.0.0-rc.4"
+    "@solidjs/signals": "2.0.0-rc.6",
+    "@solidjs/universal": "2.0.0-rc.6",
+    "solid-js": "2.0.0-rc.6"
   }
 }