@solidrt/core 0.0.13 → 0.0.16

package/AGENTS.md

@@ -29,7 +29,7 @@ tsconfig.json - the two load-bearing lines are jsx + jsxImportSource:
 ```
 
 Peer deps @solidjs/signals and @solidjs/universal must match (currently
-2.0.0-beta.14); bun resolves them from peerDependencies.
+2.0.0-beta.15); bun resolves them from peerDependencies.
 
 ## Element model (the parts that are easy to get wrong)
 
@@ -63,6 +63,24 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   directly-positioned, often-animating elements (e.g. hundreds of balls), `d-`
   skips the per-element layout that plain elements would incur.
 
+- 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
+    its `top`/`right`/`bottom`/`left` offsets, flex*/gap/display, grid*,
+    aspectRatio, overflow. Changing ANY of these triggers a Taffy reflow of the
+    node and its subtree.
+  - `TransformProps` - x, y, scale/scaleX/scaleY, rotate/rotateX/rotateY,
+    perspective, cx/cy, scrollX/scrollY. Applied at paint/composite; NO reflow.
+  - `PaintProps` - color, drawStyle, strokeWidth, blendMode, radius. Also no
+    reflow.
+  So to MOVE or animate an element - dragging, transitions, per-frame motion -
+  translate it with the transform `x`/`y` (or scale/rotate), never by animating
+  `left`/`top`/`margin`/`width`. Common trap: `left`/`top` read like "position"
+  but they are LAYOUT offsets (for `position:absolute`), so driving them every
+  frame reflows the tree. Anchor the element once with layout (e.g.
+  `position:absolute` at `left:0,top:0`, or just let normal flow place it) and
+  then translate it with `x`/`y`.
+
 - 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

package/examples/README.md

@@ -0,0 +1,27 @@
+# @solidrt/core examples
+
+Single-concept SolidRT patterns. Each file is a complete, runnable app (ends in
+`render(() => <App />)`) demonstrating exactly one thing - copy one and adapt it.
+For the SolidJS 2.0 reactivity/control-flow model see `solid-js/CHEATSHEET.md`;
+for the element/prop model see `@solidrt/core/AGENTS.md`.
+
+## Host elements and layout
+- `window-root.tsx` - the minimal app; the root must be `<window>`.
+- `view-layout.tsx` - `<view>` as a flex container; containers do not paint.
+- `background-rect.tsx` - a `d-rect` filling its parent as a background.
+- `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.
+
+## 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`.
+
+## Window state
+- `window-signals.tsx` - reactive `windowSize()` / `safeArea()` accessors (prefer over `onResize`).
+
+## Overlays
+- `portal.tsx` - `createPortal` relocating content to the window root to escape clipping.
+
+## Images and GPU
+- `image.tsx` - `createImage` (async value: fetch + decode + upload) read inside a `<Loading>` boundary and shown with `<texture>`.
+- `gpu-shader.tsx` - a GLSL fragment shader rendered to a texture, animated via `setShaderParams`.

package/examples/background-rect.tsx

@@ -0,0 +1,15 @@
+// Containers do not paint, so a background is just a draw primitive placed behind
+// the content. A d- primitive with no x/y/w/h fills its parent, which is exactly
+// what you want for a background. Put it FIRST so siblings paint on top of it.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window alignItems="center" justifyContent="center">
+      <d-rect color="#1a3380" />
+      <text fontSize={28} color="#ffffff">Content on a full-bleed background</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/detached-positioning.tsx

@@ -0,0 +1,21 @@
+// The d- prefix means "detached from layout": the layout engine ignores it and
+// 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
+// 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"
+
+function App() {
+  return (
+    <window>
+      <d-view x={40} y={60}>
+        <d-rect w={160} h={64} radius={12} color="#3366b3" />
+        <d-text x={16} y={20} fontSize={18} color="#ffffff">Badge</d-text>
+      </d-view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/frame-animation.tsx

@@ -0,0 +1,26 @@
+// onFrame(fn) is the per-frame animation hook. tick is runtime-paced time in ms
+// (smooth even when frame times jitter), frame is the present count, rate is the
+// refresh rate in Hz. Drive a signal from the tick and read it in JSX - the graph
+// repaints each frame. A pending onFrame is a standing request for the next
+// frame, so the loop runs only while something is animating and stops when the
+// callback is cleaned up (automatic within a reactive scope).
+//
+// Animate a transform (rotate / scale / x / y on a <view>), not a layout prop:
+// transforms are applied at paint time, while animating width/margin/etc would
+// re-run layout every frame.
+import { render, onFrame, createSignal } from "@solidrt/core"
+
+function App() {
+  let [angle, setAngle] = createSignal(0)
+  onFrame((tick) => setAngle(tick / 1000)) // radians; ~1 turn every 6.3s
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view width={120} height={120} rotate={angle()}>
+        <rect width={120} height={120} radius={16} color="#3366b3" />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/gpu-shader.tsx

@@ -0,0 +1,36 @@
+// createShader compiles a GLSL ES 3.00 fragment shader and renders it into a
+// texture, returning a texture id you display with <texture src={id}>. The
+// fragment body may reference vUV (0..1, top-left origin), iResolution, iTime, and
+// any `uniform float` it declares; there is no #version line - the runtime injects
+// the preamble. The texture is freed automatically when the reactive owner is
+// disposed.
+//
+// iResolution is filled in for you, but iTime is NOT - drive it (and any other
+// uniform) yourself with setShaderParams from onFrame to animate. The shader's
+// size is baked in at creation.
+import { render, onFrame } from "@solidrt/core"
+import { createShader, setShaderParams } from "@solidrt/core/gpu"
+
+let FRAGMENT = `
+void main() {
+  vec2 uv = vUV;
+  float t = iTime * 2.0;
+  float a = 0.5 + 0.5 * sin(uv.x * 10.0 + t);
+  float b = 0.5 + 0.5 * sin(uv.y * 10.0 - t * 1.3);
+  float c = 0.5 + 0.5 * sin((uv.x + uv.y) * 8.0 + t * 0.7);
+  fragColor = vec4(a, b, c, 1.0);
+}
+`
+
+function App() {
+  let id = createShader(FRAGMENT, 512, 512, { iTime: 0 })
+  onFrame((tick) => setShaderParams(id, { iTime: tick / 1000 }))
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} width={400} height={400} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/image.tsx

@@ -0,0 +1,27 @@
+// createImage loads an image as a SolidJS 2.0 async value and returns an accessor
+// for its GPU texture id. It handles fetch, decode, GPU upload, and cleanup for
+// you. A string source is fetched; a Uint8Array is decoded directly. The texture
+// carries its own pixel size, so <texture> needs no width/height to show it at
+// natural size - pass them only to scale it.
+//
+// Reading img() suspends until ready, so read it inside a <Loading> boundary
+// (this is the 2.0 async mechanic, not a manual undefined-signal + <Show>); a
+// load failure surfaces to <Errored>. Pass an accessor (createImage(() => src()))
+// to make the source reactive - the image reloads and the old texture is freed.
+// For manual control, decodeImage + createTexture (from @solidrt/core/gpu) are
+// the primitives underneath.
+import { render, createImage, Loading } from "@solidrt/core"
+
+function App() {
+  let img = createImage("https://picsum.photos/seed/solidrt/400/300")
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <Loading fallback={<text color="#888">loading...</text>}>
+        <texture src={img()} />
+      </Loading>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/on-layout-connect.tsx

@@ -0,0 +1,39 @@
+// onLayout(fn) fires after layout is computed but before paint - the one point
+// where measured geometry is available via getBoundingBox (a window-relative
+// snapshot, valid only here or in an event handler). Its canonical use is to
+// connect or annotate laid-out elements with detached drawing: let the layout
+// engine place the boxes, read their boxes, then draw a d-path between them.
+//
+// Two rules make it safe:
+//  1. Write the result to something that does NOT affect layout - a d-path's `d`,
+//     a detached node's position. Writing a layout-affecting prop here forces an
+//     extra layout pass every frame.
+//  2. Call flush() after the write so it lands before the display list is built
+//     (onLayout runs after the frame's normal flush).
+import { render, onLayout, getBoundingBox, createSignal, flush } from "@solidrt/core"
+
+function App() {
+  let boxA!: { id: number }
+  let boxB!: { id: number }
+  let [d, setD] = createSignal("")
+
+  onLayout(() => {
+    let a = getBoundingBox(boxA)
+    let b = getBoundingBox(boxB)
+    if (!a || !b) return
+    let ax = a.x + a.width / 2, ay = a.y + a.height / 2
+    let bx = b.x + b.width / 2, by = b.y + b.height / 2
+    setD(`M ${ax} ${ay} L ${bx} ${by}`)
+    flush()
+  })
+
+  return (
+    <window flexDirection="row" justifyContent="space-between" alignItems="center" padding={48}>
+      <rect ref={n => (boxA = n)} width={80} height={80} radius={8} color="#3366b3" />
+      <rect ref={n => (boxB = n)} width={80} height={80} radius={8} color="#6699e6" />
+      <d-path d={d()} color="#e0245e" drawStyle="stroke" strokeWidth={3} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/portal.tsx

@@ -0,0 +1,38 @@
+// createPortal relocates an already-built node to the window root (or a given
+// mount), so content declared deep in the tree can escape the layout, clipping,
+// and stacking of its surroundings - the primitive behind overlays like modals,
+// menus, and tooltips. It moves one concrete node and removes it again when the
+// surrounding reactive scope disposes.
+//
+// Key points:
+//  - A JSX element's runtime value IS the built node, so pass the JSX straight to
+//    createPortal. It returns void, so `return createPortal(...)` renders nothing
+//    in place while the content lives at the mount.
+//  - The default mount is the window's flex root, so the portaled node must be
+//    position="absolute" - otherwise it takes flow space and displaces content.
+//  - Pass a second argument (a node captured from a ref) to mount elsewhere.
+import { render, createPortal } from "@solidrt/core"
+
+// Declared inside the clipped card below, but drawn at the window root, on top of
+// everything and outside the card's overflow clip.
+function Banner() {
+  return createPortal(
+    <view position="absolute" top={0} left={0} right={0} padding={12}>
+      <d-rect color="#e0245e" />
+      <text color="#ffffff">Portaled banner - escaped the card</text>
+    </view>
+  )
+}
+
+function App() {
+  return (
+    <window padding={40}>
+      <view flex={1} overflow="hidden" alignItems="center" justifyContent="center">
+        <rect width={140} height={140} radius={8} color="#3366b3" />
+        <Banner />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/text-paint-styling.tsx

@@ -0,0 +1,18 @@
+// Painting is uniform across primitives: the `color` prop sets the paint (a CSS
+// color string or a gradient). There is no fill / stroke / background prop. To
+// outline instead of fill, set drawStyle="stroke" and strokeWidth; "stroke-and-
+// fill" does both. The same color prop styles <text>, alongside fontSize /
+// fontWeight / fontFamily.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window flexDirection="column" gap={16} padding={24} alignItems="center" justifyContent="center">
+      <text fontSize={28} fontWeight={700} color="#1a3380">Filled text</text>
+      <rect width={160} height={64} radius={12} color="#3366b3" />
+      <oval width={120} height={64} drawStyle="stroke" strokeWidth={4} color="#1a3380" />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/view-layout.tsx

@@ -0,0 +1,20 @@
+// <view> is the layout container: a flexbox box positioned by the layout engine.
+// It does NOT paint anything itself - it has no color. To make a box visible you
+// place a draw primitive inside it (here an attached <rect>, which is both laid
+// out and painted). Flex props (flexDirection, gap, padding, alignItems) work as
+// in CSS.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window>
+      <view flex={1} flexDirection="column" gap={12} padding={24} justifyContent="center">
+        <rect height={48} radius={8} color="#3366b3" />
+        <rect height={48} radius={8} color="#6699e6" />
+        <rect height={48} radius={8} color="#99c2f0" />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/window-root.tsx

@@ -0,0 +1,14 @@
+// The minimal valid app. render() is called once at the top level and the root
+// element MUST be <window> - anything else throws. <window> takes layout props
+// (it is a flex container), so children can be centered here directly.
+import { render } from "@solidrt/core"
+
+function App() {
+  return (
+    <window title="Hello" alignItems="center" justifyContent="center">
+      <text fontSize={24} color="#222">Hello SolidRT</text>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/window-signals.tsx

@@ -0,0 +1,29 @@
+// Window state is exposed as reactive accessors - read them in JSX and the UI
+// updates when the window changes. Prefer these over the onResize event callback:
+// they are reactive, sticky (the first read sees the current value), and live for
+// the whole app.
+//
+//   windowSize()   -> { width, height }
+//   safeArea()     -> { top, left, right, bottom } inset distances from each edge
+//   displayScale() -> device pixel ratio
+//
+// safeArea is mostly an interactivity boundary: the platform may intercept
+// touches/gestures inside the insets (system bars, notch, home indicator), so do
+// not place interactive content there. For plain drawing it is usually fine to
+// extend into the left/right insets (full-bleed backgrounds); top and bottom are
+// what matter, since content there - text especially - can be covered. So pad the
+// top/bottom by the inset and let the background fill the whole window.
+import { render, windowSize, safeArea } from "@solidrt/core"
+
+function App() {
+  return (
+    <window>
+      <d-rect color="#101418" />
+      <view flex={1} flexDirection="column" gap={8} paddingTop={safeArea().top} paddingBottom={safeArea().bottom}>
+        <text fontSize={18} color="#e6e6e6">{windowSize().width} x {windowSize().height}</text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.13",
+  "version": "0.0.16",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -11,6 +11,7 @@
     "./gpu": "./src/gpu.ts",
     "./image": "./src/image.ts",
     "./microphone": "./src/microphone.ts",
+    "./scroll": "./src/scroll.ts",
     "./speech-recognition": "./src/speech-recognition.ts",
     "./text-input": "./src/text-input.ts",
     "./jsx-runtime": "./jsx-runtime.d.ts",
@@ -18,6 +19,7 @@
   },
   "files": [
     "src/",
+    "examples/",
     "jsx-runtime.d.ts",
     "AGENTS.md"
   ],
@@ -25,11 +27,11 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.13"
+    "@solidrt/flux-types": "0.0.0"
   },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-beta.14",
-    "@solidjs/universal": "2.0.0-beta.14",
-    "solid-js": "2.0.0-beta.14"
+    "@solidjs/signals": "2.0.0-beta.15",
+    "@solidjs/universal": "2.0.0-beta.15",
+    "solid-js": "2.0.0-beta.15"
   }
 }

package/src/gpu.ts

@@ -6,6 +6,14 @@
 import { getOwner, onCleanup } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
 
+// Imperative companions to the reactive create* helpers, re-exported so callers
+// that depend on @solidrt/core -- like @solidrt/components -- need not import flux
+// directly: destroyTexture for the manual-cleanup path (textures made outside a
+// reactive scope, e.g. after an await, are not auto-freed), setShaderParams to
+// drive a shader's uniforms over time, and uploadTexture to push new pixels into
+// a mutable texture.
+export { destroyTexture, setShaderParams, uploadTexture } from "flux:gpu"
+
 /**
  * Uploads raw RGBA8 pixels to an immutable GPU texture and returns its id (use
  * it as `<texture src={id} />`). `data` must be exactly `width * height * 4`

package/src/image.ts

@@ -1,7 +1,10 @@
-// CPU image codec: decode encoded image bytes into raw RGBA8 pixels (and, in
-// future, encode them back). Kept separate from the GPU/texture APIs because no
-// GPU is involved; pair decodeImage with createTexture from "@solidrt/core/gpu"
-// to upload the result.
+// CPU image codec plus the reactive load-and-upload convenience. decodeImage is
+// the raw primitive (no GPU involved); createImage is the owner-aware layer on
+// top that fetches/decodes/uploads for you and swaps the texture when the source
+// changes - the same relationship createTexture/createShader have to flux:gpu.
+
+import { createMemo, onCleanup, NotReadyError } from "@solidjs/signals"
+import { createTexture, destroyTexture } from "./gpu"
 
 export type DecodedImage = {
   data: Uint8Array
@@ -12,8 +15,51 @@ export type DecodedImage = {
 /**
  * Decodes encoded image bytes (PNG, JPEG, and the other formats the runtime's
  * image decoder supports) into raw, tightly-packed RGBA8 pixels plus the
- * decoded dimensions. Feed the result straight into `createTexture`.
+ * decoded dimensions. Feed the result straight into `createTexture`. Use this
+ * when you want manual control; for the common case reach for `createImage`.
  */
 export function decodeImage(bytes: Uint8Array): DecodedImage {
   return image.decodeImage(bytes)
+}
+
+export type ImageSource = string | Uint8Array
+
+/**
+ * Loads an image as an async computation and returns a reactive accessor for its
+ * GPU texture id. This is a SolidJS 2.0 async value: reading it suspends until
+ * the image is ready, so read it inside a `<Loading>` boundary (a load failure
+ * surfaces to `<Errored>`). A string source is fetched; a Uint8Array is decoded
+ * directly. Pass an accessor instead of a value to make the source reactive -
+ * the image reloads and the old texture is freed whenever it changes; the
+ * current texture is freed when the owner is disposed. Display it with
+ * `<texture src={id()} />`; the texture carries its own pixel size, so no
+ * width/height is needed unless you want to scale it.
+ */
+export function createImage(src: ImageSource | (() => ImageSource)): () => number {
+  let getSrc = typeof src === "function" ? src : () => src
+  let generation = 0
+
+  return createMemo<number>(async () => {
+    let source = getSrc()
+    let mine = ++generation
+
+    // Register cleanup synchronously, before the await: an onCleanup added after
+    // an await is orphaned because the reactive owner is not restored across it.
+    // The holder is filled in once the texture exists.
+    let holder = { id: -1 }
+    onCleanup(() => {
+      if (holder.id >= 0) destroyTexture(holder.id)
+    })
+
+    let bytes = typeof source === "string" ? await (await fetch(source)).bytes() : source
+
+    // If the source changed while we were loading, this run is superseded. Skip
+    // the GPU upload and stay pending: a texture created here would leak, since
+    // superseded async runs are not otherwise cleaned up. The newer run wins.
+    if (mine !== generation) throw new NotReadyError()
+
+    let { data, width, height } = decodeImage(bytes)
+    holder.id = createTexture(data, width, height)
+    return holder.id
+  })
 }

package/src/index.ts

@@ -6,8 +6,8 @@ export type { Gradient, GradientStop } from "./color"
 export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
 export { createTexture } from "./gpu"
-export { decodeImage } from "./image"
-export type { DecodedImage } from "./image"
+export { createImage, decodeImage } from "./image"
+export type { DecodedImage, ImageSource } from "./image"
 export type {
   LayoutProps,
   TransformProps,
@@ -29,3 +29,55 @@ export type {
   Color,
 } from "./types"
 export type { MeasureTextOptions } from "flux:rendertree"
+
+// --- Authoring-surface re-exports -------------------------------------------
+// A SolidRT app is built from three substrate packages: @solidjs/signals
+// (reactivity), solid-js (control-flow components), and @solidjs/universal (the
+// renderer factory, surfaced via ./renderer). Forwarding the app-facing pieces
+// here means an app imports its whole vocabulary from "@solidrt/core" instead of
+// having to know which substrate package each symbol lives in. These are already
+// peerDependencies, so this adds no new dependency. Curated on purpose - do not
+// `export *` from solid-js, which would leak DOM/hydration-only helpers that are
+// meaningless on the flux runtime.
+
+// Reactivity (from @solidjs/signals).
+export {
+  createSignal,
+  createMemo,
+  createEffect,
+  createRenderEffect,
+  createRoot,
+  createStore,
+  reconcile,
+  mapArray,
+  repeat,
+  untrack,
+  flush,
+  onCleanup,
+  onSettled,
+} from "@solidjs/signals"
+export type { Accessor, Setter, Signal, Store, StoreSetter } from "@solidjs/signals"
+
+// Control flow, components, and context (from solid-js).
+export {
+  For,
+  Show,
+  Switch,
+  Match,
+  Repeat,
+  Loading,
+  Errored,
+  Reveal,
+  lazy,
+  createUniqueId,
+  createContext,
+  useContext,
+  children,
+} from "solid-js"
+export type {
+  Component,
+  ParentComponent,
+  FlowComponent,
+  VoidComponent,
+  ComponentProps,
+} from "solid-js"

package/src/renderer.ts

@@ -1,4 +1,4 @@
-import { createRoot } from "@solidjs/signals"
+import { createRoot, onCleanup } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
 import * as tree from "flux:rendertree"
 import { attachWindow } from "./window"
@@ -30,6 +30,34 @@ function createProxyNode(elementType: ElementType): ProxyNode {
   return node
 }
 
+// Detaches `node` from `parent` and destroys it (and all descendants) on both
+// the JS and native sides. Hoisted out of the renderer config so createPortal
+// can reuse it (createRenderer does not return its removeNode hook).
+function removeNode(parent: ProxyNode, node: ProxyNode): void {
+  if (!node || !parent) return
+
+  // console.debug("[srt] removeNode", parent.id, node.id)
+
+  // Update JS tree references
+  let index = parent.children.indexOf(node)
+  if (index !== -1) {
+    parent.children.splice(index, 1)
+  }
+  node.parent = undefined
+
+  tree.deleteNode(parent.id, node.id)
+
+  // Recursively clean up node and all descendants. Clear focus before
+  // dropping handlers so onBlur still fires for a focused descendant.
+  let cleanup = (n: ProxyNode) => {
+    for (let child of n.children) cleanup(child)
+    if (n.id === getFocusedNodeId()) setFocus(null)
+    nodes.delete(n.id)
+    cleanupNodeHandlers(n.id)
+  }
+  cleanup(node)
+}
+
 export let {
   effect,
   memo,
@@ -116,30 +144,7 @@ export let {
     }
   },
 
-  removeNode: (parent: ProxyNode, node: ProxyNode): void => {
-    if (!node || !parent) return
-
-    // console.debug("[srt] removeNode", parent.id, node.id)
-
-    // Update JS tree references
-    let index = parent.children.indexOf(node)
-    if (index !== -1) {
-      parent.children.splice(index, 1)
-    }
-    node.parent = undefined
-
-    tree.deleteNode(parent.id, node.id)
-
-    // Recursively clean up node and all descendants. Clear focus before
-    // dropping handlers so onBlur still fires for a focused descendant.
-    let cleanup = (n: ProxyNode) => {
-      for (let child of n.children) cleanup(child)
-      if (n.id === getFocusedNodeId()) setFocus(null)
-      nodes.delete(n.id)
-      cleanupNodeHandlers(n.id)
-    }
-    cleanup(node)
-  },
+  removeNode,
 
   getParentNode: (node: ProxyNode) => node?.parent,
   getFirstChild: (node: ProxyNode) => node?.children[0],
@@ -152,6 +157,10 @@ export let {
   },
 })
 
+// The app's single <window> node, set by render(). Serves as the default mount
+// target for createPortal (single window by design, so one ambient ref).
+let windowRoot: ProxyNode | undefined
+
 /**
  * Mounts a SolidRT app. Call once at the top level: `render(() => <App />)`.
  * The element returned by `code` MUST be a `<window>` (it becomes the native
@@ -164,7 +173,32 @@ export function render(code: () => any) {
     if (!root || root.elementType !== "window") {
       throw new Error("render() root must be a <window> element")
     }
+    windowRoot = root
     attachWindow(root.id)
     insert(null, root)
   })
 }
+
+/**
+ * Relocates an already-built node out of its lexical position to `mount` (the
+ * window root by default), then removes it again when the surrounding reactive
+ * scope disposes. The low-level portal primitive: it moves a single node and
+ * nothing more. Conveniences (an overlay layer, centering, a backdrop) belong
+ * in higher packages built on top of it.
+ *
+ * `node` is a concrete node, not an accessor: its own children (including any
+ * reactive content) are already wired by the JSX that built it and keep working
+ * wherever it is mounted. We only move the root.
+ *
+ * The default mount is the window's flex root, so a portaled node that is not
+ * `position: "absolute"` will take flow space and displace app content. Position
+ * the portal root absolutely, or pass a `mount` target that does it for you.
+ */
+export function createPortal(node: ProxyNode, mount?: ProxyNode): void {
+  let target = mount ?? windowRoot
+  if (!target) {
+    throw new Error("createPortal: no mount target (called before render()?)")
+  }
+  insertNode(target, node)
+  onCleanup(() => removeNode(target, node))
+}

package/src/scroll.ts

@@ -0,0 +1,93 @@
+// Headless scroll mechanism. This primitive owns the objective part of a
+// scrollable region -- the offset and its clamping against the measured content
+// and viewport sizes -- and nothing with a UI opinion. Wheel/drag input,
+// momentum, scrollbars and styling are policy and belong to the component (the
+// "skin") that composes this, the same way createCaretScroll backs TextInput.
+
+import { createSignal, flush } from "@solidjs/signals"
+import { getBoundingBox } from "./core"
+import { onLayout } from "./window"
+
+export type ScrollAxis = "vertical" | "horizontal" | "both"
+
+export type ScrollOffset = { x: number; y: number }
+
+export type ScrollOptions = {
+  /** Which axes can scroll. Locked axes are pinned to 0. Default "vertical". */
+  axis?: ScrollAxis
+}
+
+export type Scroll = {
+  /** Current clamped offset, as a reactive accessor. */
+  offset(): ScrollOffset
+  /** Scroll by a delta (positive moves content up/left), clamped to range. */
+  scrollBy(dx: number, dy: number): void
+  /** Scroll to an absolute offset, clamped to range. */
+  scrollTo(x: number, y: number): void
+}
+
+/**
+ * Returns the scroll offset for a viewport node given its content node. The
+ * offset is retained between frames and re-clamped in onLayout against the
+ * current content-vs-viewport overflow, so the view stays valid when content
+ * grows or shrinks (e.g. an offset that scrolled to the bottom snaps up when the
+ * list gets shorter). scrollBy/scrollTo clamp against the most recently measured
+ * range. Pure geometry: no input handling and no visual policy.
+ *
+ * The viewport node is the clipping box (overflow hidden); the content node is
+ * the inner wrapper that holds the children and takes their natural size. Apply
+ * the returned offset to the viewport's scrollX/scrollY.
+ */
+export function createScroll(
+  viewport: () => { id: number } | undefined,
+  content: () => { id: number } | undefined,
+  options: ScrollOptions = {},
+): Scroll {
+  let axis = options.axis ?? "vertical"
+  let canX = axis === "horizontal" || axis === "both"
+  let canY = axis === "vertical" || axis === "both"
+
+  let [offset, setOffset] = createSignal<ScrollOffset>({ x: 0, y: 0 })
+
+  // Last measured overflow, refreshed each layout. scrollBy/scrollTo clamp
+  // against these between layouts; onLayout re-clamps once new sizes are known.
+  let maxX = 0
+  let maxY = 0
+
+  let clamp = (x: number, y: number): ScrollOffset => ({
+    x: canX ? Math.max(0, Math.min(x, maxX)) : 0,
+    y: canY ? Math.max(0, Math.min(y, maxY)) : 0,
+  })
+
+  let set = (x: number, y: number) => {
+    let cur = offset()
+    let next = clamp(x, y)
+    if (next.x !== cur.x || next.y !== cur.y) setOffset(next)
+  }
+
+  onLayout(() => {
+    let vp = viewport()
+    let ct = content()
+    if (!vp || !ct) return
+    let vb = getBoundingBox(vp)
+    let cb = getBoundingBox(ct)
+    if (!vb || !cb) return
+    maxX = Math.max(0, cb.width - vb.width)
+    maxY = Math.max(0, cb.height - vb.height)
+    let cur = offset()
+    let next = clamp(cur.x, cur.y)
+    if (next.x !== cur.x || next.y !== cur.y) {
+      setOffset(next)
+      flush()
+    }
+  })
+
+  return {
+    offset,
+    scrollBy: (dx, dy) => {
+      let cur = offset()
+      set(cur.x + dx, cur.y + dy)
+    },
+    scrollTo: (x, y) => set(x, y),
+  }
+}

package/src/types.d.ts

@@ -153,14 +153,22 @@ export interface TransformProps {
   scrollY?: number
 }
 
+// Window-relative pointer coordinates are reported as clientX/clientY (matching
+// the DOM MouseEvent). pointerType distinguishes mouse from touch; button is the
+// pressed button on down/up (0 = primary); the modifier flags mirror the DOM.
 export interface PointerEvent {
-  x: number
-  y: number
+  clientX: number
+  clientY: number
+  pointerId: number
+  pointerType: "mouse" | "touch" | "pen" | (string & {})
+  button?: number
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
 }
 
-export interface WheelEvent {
-  x: number
-  y: number
+export interface WheelEvent extends PointerEvent {
   deltaX: number
   deltaY: number
 }