@solidrt/core 0.0.26 → 0.0.28

package/examples/gpu-pipeline.tsx

@@ -0,0 +1,82 @@
+// createPipeline compiles a custom GLSL ES 3.00 vertex+fragment pair that draws
+// an interleaved vertex buffer into a texture, here a spinning cube with depth
+// testing. The vertex shader declares `in` attributes matching the pipeline's
+// attribute list (locations are resolved by name) and its own varyings; the
+// fragment preamble provides fragColor/iResolution/iTime but no vUV. Uniforms
+// are driven exactly like createShader: declaratively via the <texture> params
+// prop, applied at the next repaint.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createBuffer, createPipeline } from "@solidrt/core/gpu"
+
+let VERTEX = `
+in vec3 aPos;
+in vec3 aColor;
+out vec3 vColor;
+uniform float uTime;
+
+void main() {
+  float cy = cos(uTime), sy = sin(uTime);
+  float cx = cos(uTime * 0.7), sx = sin(uTime * 0.7);
+  mat3 rotY = mat3(cy, 0.0, -sy, 0.0, 1.0, 0.0, sy, 0.0, cy);
+  mat3 rotX = mat3(1.0, 0.0, 0.0, 0.0, cx, sx, 0.0, -sx, cx);
+  vec3 p = rotX * (rotY * aPos);
+  p.z += 2.5;
+
+  // Perspective projection (near 1, far 10). Clip y is negated: the target's
+  // memory row 0 is clip y = -1, and Impeller samples row 0 as the top, so
+  // camera-up needs the flip to be displayed up.
+  float f = 2.0;
+  float a = 11.0 / 9.0;
+  float b = -20.0 / 9.0;
+  gl_Position = vec4(p.x * f, -p.y * f, p.z * a + b, p.z);
+  vColor = aColor;
+}
+`
+
+let FRAGMENT = `
+in vec3 vColor;
+void main() {
+  fragColor = vec4(vColor, 1.0);
+}
+`
+
+// Interleaved [pos vec3, color vec3], 6 faces x 2 triangles, one color per face.
+function cube(): Float32Array {
+  type Vec3 = [number, number, number]
+  let verts: number[] = []
+  let quad = (a: Vec3, b: Vec3, c: Vec3, d: Vec3, color: Vec3) => {
+    for (let p of [a, b, c, a, c, d]) verts.push(p[0], p[1], p[2], color[0], color[1], color[2])
+  }
+  let s = 0.5
+  quad([-s, -s, s], [s, -s, s], [s, s, s], [-s, s, s], [0.9, 0.3, 0.3]) // front
+  quad([s, -s, -s], [-s, -s, -s], [-s, s, -s], [s, s, -s], [0.3, 0.9, 0.4]) // back
+  quad([s, -s, s], [s, -s, -s], [s, s, -s], [s, s, s], [0.3, 0.5, 0.9]) // right
+  quad([-s, -s, -s], [-s, -s, s], [-s, s, s], [-s, s, -s], [0.9, 0.8, 0.3]) // left
+  quad([-s, s, s], [s, s, s], [s, s, -s], [-s, s, -s], [0.8, 0.4, 0.9]) // top
+  quad([-s, -s, -s], [s, -s, -s], [s, -s, s], [-s, -s, s], [0.4, 0.9, 0.9]) // bottom
+  return new Float32Array(verts)
+}
+
+function App() {
+  let bufferId = createBuffer(cube())
+  let id = createPipeline(VERTEX, FRAGMENT, 512, 512, {
+    params: { uTime: 0 },
+    attributes: [
+      { name: "aPos", format: "vec3" },
+      { name: "aColor", format: "vec3" },
+    ],
+    buffer: bufferId,
+    depth: true,
+    clearColor: [0.08, 0.08, 0.12, 1],
+  })
+  let [time, setTime] = createSignal(0)
+  onFrame((tick) => setTime(tick / 1000))
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={id} params={{ uTime: time() }} width={400} height={400} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.26"
+    "@solidrt/flux-types": "0.0.28"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.17",

package/src/gamepad.ts

@@ -0,0 +1,56 @@
+import { createSignal } from "@solidjs/signals"
+import { on } from "srt:events"
+
+// Gamepad State: a reactive mirror of the runtime's sticky "gamepads" event.
+//
+// The runtime coalesces pad activity to at most one snapshot per main-loop
+// iteration and replays the latest one on subscribe, so the first read
+// already sees any connected pads. Runtimes without gamepad support never
+// emit the event and the accessor stays [].
+
+/**
+ * One connected gamepad's current state. `buttons` holds the names of the
+ * currently-pressed buttons, using SDL3's positional names ("south", "east",
+ * "west", "north", "dpadUp", "dpadDown", "dpadLeft", "dpadRight", "start",
+ * "back", "guide", "leftShoulder", "rightShoulder", "leftStick",
+ * "rightStick"). `axes` has sticks ("leftX", "leftY", "rightX", "rightY") in
+ * -1..1 and triggers ("leftTrigger", "rightTrigger") in 0..1.
+ */
+export interface GamepadState {
+  /** Runtime instance id: unique per connection, not stable across reconnects. */
+  id: number
+  name: string
+  buttons: string[]
+  axes: Record<string, number>
+  /**
+   * True when the device has an SDL controller-database mapping, so button
+   * and axis names reflect verified physical positions. False for raw HID
+   * joysticks: they still report, but names are assigned positionally in W3C
+   * standard-mapping order (button 0 is "south", ..., overflow "button17"...;
+   * axes 0-3 are "leftX"..."rightY", overflow "axis4"...), a d-pad hat folds
+   * into the "dpad*" names, and analog triggers, if any, appear wherever the
+   * device puts them (e.g. as *button* names "leftTrigger"/"rightTrigger" at
+   * indices 6/7) rather than as the trigger axes mapped pads have.
+   */
+  mapped: boolean
+}
+
+let gamepadsAccessor: (() => (GamepadState | null)[]) | undefined
+
+/**
+ * Connected gamepads as a reactive accessor. Slots are stable web-style: a
+ * pad keeps its index for its whole connection, disconnecting leaves a null
+ * hole, and the next connect fills the lowest free slot - so slot index works
+ * as a persistent player number. Read inside a tracked scope (JSX, memo,
+ * effect, onFrame) to re-run on pad activity.
+ */
+export function gamepads(): (GamepadState | null)[] {
+  if (!gamepadsAccessor) {
+    // ownedWrite: the sticky event replays synchronously inside on(), which
+    // may run within a tracked scope's first read (see environment.ts).
+    let [pads, setPads] = createSignal<(GamepadState | null)[]>([], { ownedWrite: true })
+    on("gamepads", (e: { pads?: (GamepadState | null)[] }) => setPads(e.pads ?? []))
+    gamepadsAccessor = pads
+  }
+  return gamepadsAccessor()
+}

package/src/gpu.ts

@@ -19,6 +19,12 @@ import * as gpu from "flux:gpu"
 // `<texture params={...}>` when a `<texture>` element is already in the tree.
 export { destroyTexture, setShaderParams, uploadTexture } from "flux:gpu"
 
+// Pipeline plumbing re-exported raw: setDrawCount re-renders a pipeline after
+// its buffer gained or lost dynamic geometry; destroyBuffer is the manual
+// cleanup path for buffers created outside a reactive scope.
+export { destroyBuffer, setDrawCount } from "flux:gpu"
+export type { Topology, VertexAttribute } from "flux:gpu"
+
 // captureSnapshot renders a node to a texture and readTexture reads any
 // texture's bytes back. Re-exported raw (no reactive auto-cleanup wrapper):
 // captureSnapshot resolves asynchronously, by which point the reactive owner is
@@ -79,4 +85,71 @@ export function createShader(
   let id = gpu.createShader(fragmentSrc, width, height, params, textures)
   if (getOwner()) onCleanup(() => gpu.destroyTexture(id))
   return id
+}
+
+// View any TypedArray or ArrayBuffer as a Uint8Array over the same memory,
+// without copying, so vertex data can be authored as Float32Array.
+function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
+  if (data instanceof Uint8Array) return data
+  if (data instanceof ArrayBuffer) return new Uint8Array(data)
+  return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+}
+
+/**
+ * Compiles a GLSL ES 3.00 vertex+fragment pipeline and renders it into a
+ * texture, returning the texture id (usable anywhere a normal texture id is,
+ * e.g. `<texture src>`). Unlike `createShader` the vertex stage is yours:
+ * declare `in` attributes matching `opts.attributes` (one interleaved vertex
+ * in `opts.buffer`, a {@link createBuffer} id) and your own varyings toward
+ * the fragment stage. Both sources may reference `iResolution`/`iTime` and any
+ * `uniform float` they declare; drive values with `<texture src={id}
+ * params={{...}} />` or `setShaderParams`, exactly like a fragment shader.
+ * `opts.depth` attaches a private depth buffer (cleared + tested per render);
+ * `opts.vertexCount` defaults to the whole buffer and can be changed later
+ * with `setDrawCount`. Frees the texture and GL program when the reactive
+ * owner is disposed; create outside any reactive scope for app-lifetime
+ * pipelines.
+ */
+export function createPipeline(
+  vertexSrc: string,
+  fragmentSrc: string,
+  width: number,
+  height: number,
+  opts?: {
+    params?: Record<string, number>
+    textures?: Record<string, number>
+    attributes?: gpu.VertexAttribute[]
+    buffer?: number
+    topology?: gpu.Topology
+    vertexCount?: number
+    depth?: boolean
+    clearColor?: [number, number, number, number]
+  },
+): number {
+  let id = gpu.createPipeline(vertexSrc, fragmentSrc, width, height, opts)
+  if (getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  return id
+}
+
+/**
+ * Creates a vertex buffer for pipeline attributes from raw data (typically a
+ * Float32Array laid out to match the pipeline's interleaved attribute list).
+ * Update it later with {@link writeBuffer}; the buffer's byte size is fixed at
+ * creation, so reserve room up front for dynamic geometry. Freed automatically
+ * when the reactive owner is disposed; created outside a reactive scope you
+ * must call `destroyBuffer` yourself. Destroy pipelines before their buffer.
+ */
+export function createBuffer(data: ArrayBuffer | ArrayBufferView): number {
+  let id = gpu.createBuffer(toUint8(data))
+  if (getOwner()) onCleanup(() => gpu.destroyBuffer(id))
+  return id
+}
+
+/**
+ * Overwrites part of a vertex buffer at `byteOffset` (default 0). Every
+ * pipeline drawing from the buffer re-renders with its last-applied params,
+ * so geometry-only changes reach the screen without a params update.
+ */
+export function writeBuffer(id: number, data: ArrayBuffer | ArrayBufferView, byteOffset?: number): void {
+  gpu.writeBuffer(id, toUint8(data), byteOffset)
 }

package/src/image.ts

@@ -3,7 +3,7 @@
 // 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 { createMemo, onCleanup } from "@solidjs/signals"
 import { createTexture, destroyTexture } from "./gpu"
 
 export type DecodedImage = {
@@ -24,6 +24,80 @@ export function decodeImage(bytes: Uint8Array): DecodedImage {
 
 export type ImageSource = string | Uint8Array
 
+// Shared loader for URL sources. Every mount of the same URL shares one
+// fetch/decode/texture (refcounted; the texture is destroyed when the last
+// mount releases it). Byte caching and fetch politeness live below, in the
+// runtime's fetch layer (disk cache + per-host limit); this map exists for
+// what a byte cache cannot provide, sharing the decoded GPU texture.
+// Uint8Array sources bypass all of this: no key, per-mount texture.
+type ImageEntry = {
+  refs: number
+  texture: number
+  promise: Promise<number>
+}
+
+let imageCache = new Map<string, ImageEntry>()
+
+async function loadImage(url: string): Promise<number> {
+  // Images are assets: cache to disk, no freshness. Use a versioned URL (or
+  // fetch + decodeImage manually) when a URL's content must be re-checked.
+  let res = await fetch(url, { cache: "force-cache" })
+  if (!res.ok) throw new Error(`Image fetch failed: HTTP ${res.status} for ${url}`)
+  let bytes = await res.bytes()
+  let decoded: DecodedImage
+  try {
+    decoded = decodeImage(bytes)
+  } catch (e) {
+    throw new Error(`Image decode failed for ${url} (first bytes: ${sniffBytes(bytes)}): ${e}`)
+  }
+  return createTexture(decoded.data, decoded.width, decoded.height)
+}
+
+function acquireImage(url: string): ImageEntry {
+  let entry = imageCache.get(url)
+  if (!entry) {
+    let e: ImageEntry = { refs: 0, texture: -1, promise: undefined as never }
+    e.promise = loadImage(url).then(
+      id => {
+        // Everyone released while the load was in flight: nothing owns the
+        // texture, so drop it here instead of recording it.
+        if (e.refs === 0) {
+          destroyTexture(id)
+          imageCache.delete(url)
+        } else {
+          e.texture = id
+        }
+        return id
+      },
+      err => {
+        // Concurrent mounts shared this rejection; dropping the entry lets a
+        // later remount retry (a transient failure recovers with the network).
+        imageCache.delete(url)
+        throw err
+      },
+    )
+    // Awaiters observe the rejection; this keeps a fully-released failed
+    // entry from surfacing as an unhandled rejection.
+    e.promise.catch(() => {})
+    imageCache.set(url, e)
+    entry = e
+  }
+  entry.refs++
+  return entry
+}
+
+function releaseImage(url: string): void {
+  let entry = imageCache.get(url)
+  if (!entry) return
+  entry.refs--
+  if (entry.refs > 0) return
+  if (entry.texture >= 0) {
+    destroyTexture(entry.texture)
+    imageCache.delete(url)
+  }
+  // Still pending: the settle handler above sees refs === 0 and cleans up.
+}
+
 /**
  * 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
@@ -35,6 +109,13 @@ export type ImageSource = string | Uint8Array
  * `<texture src={id()} />`; the texture carries its own pixel size, so no
  * width/height is needed unless you want to scale it.
  *
+ * URL loads are shared: mounts of the same URL reuse one fetch and one texture
+ * (freed when the last user is disposed). The bytes are fetched with
+ * `cache: "force-cache"` - images are assets, cached on disk with no
+ * freshness check - so use a versioned URL when the content behind a URL can
+ * change. A failed load rejects every mount sharing it; a later remount
+ * retries.
+ *
  * For bytes you already hold (a `with { type: "binary" }` import, or anything in
  * memory) this suspends needlessly: `decodeImage` + `createTexture` are both
  * synchronous, so reach for them directly and skip the `<Loading>` boundary.
@@ -43,29 +124,43 @@ export type ImageSource = string | Uint8Array
  */
 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.
+    if (typeof source === "string") {
+      // Acquire and register cleanup synchronously, before the await: an
+      // onCleanup added after an await is orphaned because the reactive owner
+      // is not restored across it.
+      let entry = acquireImage(source)
+      onCleanup(() => releaseImage(source))
+      return await entry.promise
+    }
+
+    // Byte sources decode and upload synchronously; this run owns the texture.
     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(source)
-
-    let { data, width, height } = decodeImage(bytes)
-    holder.id = createTexture(data, width, height)
+    let decoded: DecodedImage
+    try {
+      decoded = decodeImage(source)
+    } catch (e) {
+      throw new Error(`Image decode failed (first bytes: ${sniffBytes(source)}): ${e}`)
+    }
+    holder.id = createTexture(decoded.data, decoded.width, decoded.height)
     return holder.id
   })
+}
+
+// A payload that fails to decode is usually not an image at all (an HTML error
+// page, a JSON error body); showing its first bytes makes that recognizable in
+// the log without a debugger.
+function sniffBytes(bytes: Uint8Array): string {
+  let head = ""
+  for (let i = 0; i < Math.min(bytes.length, 24); i++) {
+    let b = bytes[i] ?? 0
+    head += b >= 32 && b < 127 ? String.fromCharCode(b) : "."
+  }
+  return JSON.stringify(head)
 }

package/src/index.ts

@@ -8,6 +8,8 @@ export { setPointerCapture, releasePointerCapture } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
 export { env } from "./environment"
 export type { InputDevices, SystemTheme, Orientation } from "./environment"
+export { gamepads } from "./gamepad"
+export type { GamepadState } from "./gamepad"
 export { capabilities } from "./capabilities"
 export type { Capabilities, WindowSizeClass } from "./capabilities"
 export { createTexture } from "./gpu"

package/src/renderer.ts

@@ -1,5 +1,6 @@
 import { createRoot, onCleanup } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
+import type { Element } from "solid-js"
 import * as tree from "flux:rendertree"
 import { attachWindow } from "./window"
 import { setEventHandler, cleanupNodeHandlers, getFocusedNodeId, setFocus } from "./core"
@@ -87,6 +88,25 @@ function removeNode(parent: ProxyNode, node: ProxyNode): void {
   }
 }
 
+// A property the native tree rejected must not take down the reactive system:
+// a typo'd or not-yet-implemented prop poisons only itself. Warn once per
+// element kind + property with a stack (the dev server remaps its frames to
+// the .tsx source), then ignore further writes of the same pair.
+let warnedUnknownProps = new Set<string>()
+
+function setTreeProperty(node: ProxyNode, name: string, value: unknown): void {
+  try {
+    tree.setProperty(node.id, name, value)
+  } catch (e) {
+    if (!String(e).includes("unknown property")) throw e
+    let key = node.elementType + "." + name
+    if (warnedUnknownProps.has(key)) return
+    warnedUnknownProps.add(key)
+    let stack = new Error().stack ?? ""
+    console.warn(`Ignoring unknown property '${name}' on <${node.elementType}>\n${stack}`)
+  }
+}
+
 // Applies a single prop to a node: routes events to the handler registry,
 // parses color strings/gradients, and forwards everything else to the tree.
 // Shared by the renderer's setProperty hook and by createElement, which since
@@ -103,16 +123,16 @@ function applyProp<T>(node: ProxyNode, name: string, value: T): void {
   }
 
   if (name === "color" && isGradient(value)) {
-    tree.setProperty(node.id, name, value)
+    setTreeProperty(node, name, value)
     return
   }
 
   if (name === "color" && typeof value === "string") {
-    tree.setProperty(node.id, name, parseColor(value))
+    setTreeProperty(node, name, parseColor(value))
     return
   }
 
-  tree.setProperty(node.id, name, value)
+  setTreeProperty(node, name, value)
 }
 
 export let {
@@ -245,12 +265,23 @@ export function render(code: () => any) {
  * 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.
+ *
+ * Returns null (nothing in place), so a component may return a portal directly.
+ *
+ * Portals cannot mount during the initial render: the default target is the
+ * window root, which exists only after the app's first build returns, so a
+ * portal created during that build throws. This is the contract, not a bug:
+ * portal content is overlay content, opened by a signal that starts false.
  */
-export function createPortal(node: ProxyNode, mount?: ProxyNode): void {
+export function createPortal(node: Element, mount?: ProxyNode): null {
   let target = mount ?? windowRoot
   if (!target) {
-    throw new Error("createPortal: no mount target (called before render()?)")
+    throw new Error("createPortal: no mount target (portals cannot mount during the initial render; open them after mount)")
+  }
+  if (node === null || typeof node !== "object" || Array.isArray(node)) {
+    throw new Error("createPortal: node must be a single built element")
   }
-  insertNode(target, node)
-  onCleanup(() => removeNode(target, node))
+  insertNode(target, node as ProxyNode)
+  onCleanup(() => removeNode(target, node as ProxyNode))
+  return null
 }

package/src/runtime-modules.d.ts

@@ -40,6 +40,15 @@ declare module "srt:dev" {
   export function connect(address: string): void
   export function discover(): void
   export function stop(): void
+  /**
+   * Register a named debug command, listable and callable from the dev server
+   * (the list_debug / call_debug MCP tools). `args` arrives JSON-parsed; the
+   * return value must be JSON-serializable and synchronous (promises are not
+   * awaited). Re-registering a name replaces it; registrations reset on hot
+   * reload, so register at module init. Callable in every build, but only dev
+   * clients ever invoke commands.
+   */
+  export function registerDebug(name: string, fn: (args?: any) => unknown): void
 }
 
 // Frame draw (lattice runner). renderFrame() synchronously renders the current

package/src/scroll.ts

@@ -49,6 +49,14 @@ export function createScroll(
 
   let [offset, setOffset] = createSignal<ScrollOffset>({ x: 0, y: 0 })
 
+  // A scroll viewport with no explicit main-axis size resolves to 0 in flex
+  // layout and its content silently vanishes - a classic trap (maxHeight alone
+  // does not size it either). Detect it at measure time and warn once, with a
+  // stack captured at creation so the warning points at the component that
+  // built the scroller (the dev server remaps the frames to .tsx).
+  let origin = new Error().stack ?? ""
+  let warnedCollapsed = false
+
   // Last measured overflow, refreshed each layout. scrollBy/scrollTo clamp
   // against these between layouts; onLayout re-clamps once new sizes are known.
   let maxX = 0
@@ -72,6 +80,18 @@ export function createScroll(
     let vb = getBoundingBox(vp)
     let cb = getBoundingBox(ct)
     if (!vb || !cb) return
+    if (!warnedCollapsed) {
+      let zeroY = canY && vb.height === 0 && cb.height > 0
+      let zeroX = canX && vb.width === 0 && cb.width > 0
+      if (zeroY || zeroX) {
+        warnedCollapsed = true
+        let axisName = zeroY ? "height" : "width"
+        console.warn(
+          `Scroll container resolved to ${axisName} 0, so its content is invisible. ` +
+            `Give it an explicit ${axisName} or flex; maxHeight/maxWidth alone does not size it.\n${origin}`,
+        )
+      }
+    }
     maxX = Math.max(0, cb.width - vb.width)
     maxY = Math.max(0, cb.height - vb.height)
     let cur = offset()

package/src/types.d.ts

@@ -308,6 +308,11 @@ export interface TextProps extends Position, PaintProps, PointerProps {
   h?: number
   fontFamily?: "sans" | "mono" | (string & {})
   fontSize?: number
+  /**
+   * Line height as a MULTIPLIER of fontSize, not pixels (the theme uses
+   * 1.3-1.6). A CSS-reflex pixel value like 22 makes each line box 22x the
+   * font size, rendering the text as blank space.
+   */
   lineHeight?: number
   fontStyle?: "normal" | "italic"
   fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900