@solidrt/core 0.0.55 → 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.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
@@ -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
@@ -213,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.
@@ -269,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-
@@ -292,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.
@@ -330,7 +361,8 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   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
@@ -340,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

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/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/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.56",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -17,6 +17,7 @@
     "./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 +30,11 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.55"
+    "@solidrt/flux-types": "0.0.56"
   },
   "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"
   }
 }

package/src/core.ts

@@ -1,6 +1,6 @@
 import * as tree from "flux:rendertree"
 import type { TextureId } from "flux:gpu"
-import { createSignal, onCleanup } from "@solidjs/signals"
+import { createSignal, getOwner, onCleanup } from "@solidjs/signals"
 import { on } from "srt:events"
 
 let handlers = new Map<number, Map<string, Function>>()
@@ -93,7 +93,7 @@ export function onPointerMove(fn: (e: GlobalPointerEvent) => void): () => void {
       if (interestRoot != null) syncInterest(interestRoot)
     }
   }
-  onCleanup(cleanup)
+  if (getOwner()) onCleanup(cleanup)
   return cleanup
 }
 
@@ -326,6 +326,19 @@ export function getBoundingBoxViewport(node: { id: number }): BoundingBox | null
   return tree.getBoundingBoxViewport(node.id)
 }
 
+/**
+ * The node's laid-out box in its parent's frame: layout output before any
+ * transform composes (DOM offsetLeft/offsetTop/offsetWidth/offsetHeight
+ * semantics). The untransformed companion to getBoundingBox: pointer events
+ * report localX/localY in this box's units, whatever designSize fits or
+ * transforms sit on the ancestor chain. A snapshot read like getBoundingBox
+ * (call it inside `onLayout` or an event handler); `null` for detached nodes
+ * and before the first layout.
+ */
+export function getLayoutBox(node: { id: number }): BoundingBox | null {
+  return tree.getLayoutBox(node.id)
+}
+
 /**
  * The texture id of a snapshot boundary's retained rasterization
  * (`repaintBoundary="snapshot"`): the subtree's pixels as a live texture any