@solidrt/core 0.0.13 → 0.0.14

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "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",
@@ -25,11 +26,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,13 @@
 import { getOwner, onCleanup } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
 
+// The imperative destroy, surfaced here for the manual-cleanup path documented
+// on the create* helpers (textures made outside a reactive scope, e.g. after an
+// await, are not auto-freed). Re-exported so callers that depend on
+// @solidrt/core -- like @solidrt/components -- can free textures without
+// importing flux directly.
+export { destroyTexture } 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/index.ts

@@ -29,3 +29,54 @@ 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,
+  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
 }