@solidrt/core 0.0.55 → 0.0.56

package/src/environment.ts

@@ -1,4 +1,4 @@
-import { createRoot, createSignal } from "@solidjs/signals"
+import { createSignal, runWithOwner } from "@solidjs/signals"
 import { on } from "srt:events"
 import { onPointerMove } from "./core"
 import { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } from "./window"
@@ -12,13 +12,17 @@ import { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } fro
 // capability derived from them can appear mid-session (e.g. the first mouse
 // move) but never flickers away.
 //
-// `ownedWrite: true` on the signals below: each is lazily created the first
-// time its ensure* function runs, which can happen inside a tracked scope
-// (e.g. a memo's first read of env.inputDevices). Sticky events replay their
-// cached value synchronously on subscribe (srt:events' on()), so that same
-// call can immediately write the signal it just created. That's a legitimate
-// internal-state write, not a stray write escaping a computation, so it opts
-// out of the write-in-owned-scope guard.
+// Every fact below is lazily created the first time its ensure* function
+// runs, which is usually inside a component or a computation (a memo's first
+// read of env.inputDevices, a HUD effect's first read of pointerLocked()).
+// Created there, the fact would belong to that reader: sticky events replay
+// their cached value synchronously on subscribe (srt:events' on()), so the
+// on() call writes the signal it just created inside the reader's owned
+// scope - a render-time write, which the guard rejects - and a root or a
+// subscription created there is disposed with the reader. The facts are
+// app-lifetime, so each ensure* creates under no owner (runWithOwner(null)):
+// the replay lands unowned, nothing is filed under the reader, and no
+// `ownedWrite` opt-out is needed.
 
 /** Connected input device classes, as reported by the runtime. */
 export interface InputDevices {
@@ -39,58 +43,68 @@ let devicesAccessor: (() => InputDevices | undefined) | undefined
 
 function ensureDevicesState() {
   if (devicesAccessor) return
-  let [devices, setDevices] = createSignal<InputDevices | undefined>(undefined, { ownedWrite: true })
-  // Sticky: the current state replays on subscribe, so the first read already
-  // sees it on runtimes that report devices.
-  on("inputDevices", (d: InputDevices) => {
-    setDevices({ keyboard: !!d.keyboard, mouse: !!d.mouse, touch: !!d.touch, screenKeyboard: !!d.screenKeyboard })
+  runWithOwner(null, () => {
+    let [devices, setDevices] = createSignal<InputDevices | undefined>(undefined)
+    // Sticky: the current state replays on subscribe, so the first read already
+    // sees it on runtimes that report devices.
+    on("inputDevices", (d: InputDevices) => {
+      setDevices({ keyboard: !!d.keyboard, mouse: !!d.mouse, touch: !!d.touch, screenKeyboard: !!d.screenKeyboard })
+    })
+    devicesAccessor = devices
   })
-  devicesAccessor = devices
 }
 
 let systemThemeAccessor: (() => SystemTheme) | undefined
 
 function ensureSystemThemeState() {
   if (systemThemeAccessor) return
-  let [theme, setTheme] = createSignal<SystemTheme>("unknown", { ownedWrite: true })
-  on("systemTheme", (e: { theme?: SystemTheme }) => setTheme(e.theme ?? "unknown"))
-  systemThemeAccessor = theme
+  runWithOwner(null, () => {
+    let [theme, setTheme] = createSignal<SystemTheme>("unknown")
+    on("systemTheme", (e: { theme?: SystemTheme }) => setTheme(e.theme ?? "unknown"))
+    systemThemeAccessor = theme
+  })
 }
 
 let visibilityAccessor: (() => Visibility) | undefined
 
 function ensureVisibilityState() {
   if (visibilityAccessor) return
-  let [visibility, setVisibility] = createSignal<Visibility>("visible", { ownedWrite: true })
-  // Sticky. The runtime may report the same state through several platform
-  // paths; the signal's equality check turns repeats into no-ops for
-  // reactive consumers.
-  on("visibility", (e: { state?: Visibility }) => setVisibility(e.state === "hidden" ? "hidden" : "visible"))
-  visibilityAccessor = visibility
+  runWithOwner(null, () => {
+    let [visibility, setVisibility] = createSignal<Visibility>("visible")
+    // Sticky. The runtime may report the same state through several platform
+    // paths; the signal's equality check turns repeats into no-ops for
+    // reactive consumers.
+    on("visibility", (e: { state?: Visibility }) => setVisibility(e.state === "hidden" ? "hidden" : "visible"))
+    visibilityAccessor = visibility
+  })
 }
 
 let orientationAccessor: (() => Orientation) | undefined
 
 function ensureOrientationState() {
   if (orientationAccessor) return
-  let [orientation, setOrientation] = createSignal<Orientation>("unknown", { ownedWrite: true })
-  on("displayOrientation", (e: { orientation?: Orientation }) => {
-    setOrientation(e.orientation ?? "unknown")
+  runWithOwner(null, () => {
+    let [orientation, setOrientation] = createSignal<Orientation>("unknown")
+    on("displayOrientation", (e: { orientation?: Orientation }) => {
+      setOrientation(e.orientation ?? "unknown")
+    })
+    orientationAccessor = orientation
   })
-  orientationAccessor = orientation
 }
 
 let textScaleAccessor: (() => number) | undefined
 
 function ensureTextScaleState() {
   if (textScaleAccessor) return
-  let [scale, setScale] = createSignal(1, { ownedWrite: true })
-  // Sticky, like systemTheme. Guard nonsense values: a runtime bug reporting
-  // 0 or a negative would otherwise collapse all text.
-  on("textScale", (e: { scale?: number }) => {
-    setScale(typeof e.scale === "number" && e.scale > 0 ? e.scale : 1)
+  runWithOwner(null, () => {
+    let [scale, setScale] = createSignal(1)
+    // Sticky, like systemTheme. Guard nonsense values: a runtime bug reporting
+    // 0 or a negative would otherwise collapse all text.
+    on("textScale", (e: { scale?: number }) => {
+      setScale(typeof e.scale === "number" && e.scale > 0 ? e.scale : 1)
+    })
+    textScaleAccessor = scale
   })
-  textScaleAccessor = scale
 }
 
 let mouseSeenAccessor: (() => boolean) | undefined
@@ -98,50 +112,54 @@ let touchSeenAccessor: (() => boolean) | undefined
 
 function ensurePointerState() {
   if (mouseSeenAccessor) return
-  let [mouse, setMouse] = createSignal(false)
-  let [touch, setTouch] = createSignal(false)
-  let sawMouse = false
-  let sawTouch = false
-  let unsubs: (() => void)[] = []
-  let unsubMove: () => void = null!
-  let note = (e: { pointerType?: string }) => {
-    if (e.pointerType === "mouse" && !sawMouse) {
-      sawMouse = true
-      setMouse(true)
-      // Moves have nothing left to teach: touch is learned from downs (a
-      // touch never moves without one), so drop the move subscription and
-      // with it the ambient interest bit that forces move deliveries.
-      unsubMove()
-    } else if (e.pointerType === "touch" && !sawTouch) {
-      sawTouch = true
-      setTouch(true)
+  runWithOwner(null, () => {
+    let [mouse, setMouse] = createSignal(false)
+    let [touch, setTouch] = createSignal(false)
+    let sawMouse = false
+    let sawTouch = false
+    let unsubs: (() => void)[] = []
+    let unsubMove: () => void = null!
+    let note = (e: { pointerType?: string }) => {
+      if (e.pointerType === "mouse" && !sawMouse) {
+        sawMouse = true
+        setMouse(true)
+        // Moves have nothing left to teach: touch is learned from downs (a
+        // touch never moves without one), so drop the move subscription and
+        // with it the ambient interest bit that forces move deliveries.
+        unsubMove()
+      } else if (e.pointerType === "touch" && !sawTouch) {
+        sawTouch = true
+        setTouch(true)
+      }
+      // Both types observed: nothing left to learn, stop listening.
+      if (sawMouse && sawTouch) for (let u of unsubs) u()
     }
-    // Both types observed: nothing left to learn, stop listening.
-    if (sawMouse && sawTouch) for (let u of unsubs) u()
-  }
-  // Downs always deliver, so the raw bus tap suffices; moves are gated when
-  // nobody listens, so they go through onPointerMove, whose subscription
-  // keeps them flowing. The probe is app-lifetime: createRoot detaches its
-  // scope cleanup from whatever computation first read the accessor.
-  unsubMove = createRoot(() => onPointerMove(note))
-  unsubs.push(unsubMove, on("pointerDown", note))
-  mouseSeenAccessor = mouse
-  touchSeenAccessor = touch
+    // Downs always deliver, so the raw bus tap suffices; moves are gated when
+    // nobody listens, so they go through onPointerMove, whose subscription
+    // keeps them flowing. Unowned here, so it registers no cleanup: the
+    // returned unsubscribe is the probe's only handle, as intended.
+    unsubMove = onPointerMove(note)
+    unsubs.push(unsubMove, on("pointerDown", note))
+    mouseSeenAccessor = mouse
+    touchSeenAccessor = touch
+  })
 }
 
 let keyboardSeenAccessor: (() => boolean) | undefined
 
 function ensureKeyboardState() {
   if (keyboardSeenAccessor) return
-  let [keyboard, setKeyboard] = createSignal(false)
-  // Soft keyboards also deliver some keydowns (Backspace, Return), so this can
-  // read true on a touch-only device once the user types in a field. Only a
-  // fallback: capabilities prefer runtime-reported device presence.
-  let unsub = on("keydown", () => {
-    setKeyboard(true)
-    unsub()
+  runWithOwner(null, () => {
+    let [keyboard, setKeyboard] = createSignal(false)
+    // Soft keyboards also deliver some keydowns (Backspace, Return), so this can
+    // read true on a touch-only device once the user types in a field. Only a
+    // fallback: capabilities prefer runtime-reported device presence.
+    let unsub = on("keydown", () => {
+      setKeyboard(true)
+      unsub()
+    })
+    keyboardSeenAccessor = keyboard
   })
-  keyboardSeenAccessor = keyboard
 }
 
 /**

package/src/gamepad.ts

@@ -1,4 +1,4 @@
-import { createSignal } from "@solidjs/signals"
+import { createSignal, runWithOwner } from "@solidjs/signals"
 import { on } from "srt:events"
 
 // Gamepad State: a reactive mirror of the runtime's sticky "gamepads" event.
@@ -18,7 +18,7 @@ import { on } from "srt:events"
  *
  * The snapshot is a faithful report. Note that pressing "back" (select) on a
  * mapped pad ALSO emits the `back` event (see onBack) - it is the pad-side
- * sibling of Android's system back, the runtime's exit-to-launcher gesture.
+ * sibling of Android's system back, the runtime's exit-to-player gesture.
  * Apps that bind "back" for their own controls should preventDefault that
  * event.
  */
@@ -52,11 +52,13 @@ let gamepadsAccessor: (() => (GamepadState | null)[]) | undefined
  */
 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
+    // Under no owner: the sticky event replays synchronously inside on(),
+    // and the first read is usually a tracked scope (see environment.ts).
+    runWithOwner(null, () => {
+      let [pads, setPads] = createSignal<(GamepadState | null)[]>([])
+      on("gamepads", (e: { pads?: (GamepadState | null)[] }) => setPads(e.pads ?? []))
+      gamepadsAccessor = pads
+    })
   }
-  return gamepadsAccessor()
+  return gamepadsAccessor!()
 }

package/src/gpu.ts

@@ -51,7 +51,11 @@
 //   and target holds 8-bit RGBA UNORM exactly as written; nothing converts to
 //   or from linear light. `filter: "linear"` averages and the `blend` modes
 //   accumulate non-linear values - the usual approximation, stated so
-//   shaders written today stay correct if a format vocabulary arrives.
+//   shaders written today stay correct. The one exception is opt-in: an
+//   "rgba8-srgb" texture decodes to linear light when a shader samples it
+//   (and "rgba16f" holds linear HDR values), which is how a linear-space
+//   renderer such as `@solidrt/3d` reads its inputs before encoding its
+//   output back into this contract.
 
 import { createEffect, createSignal, getOwner, onCleanup, untrack } from "@solidjs/signals"
 import * as gpu from "flux:gpu"
@@ -73,9 +77,16 @@ export type SamplerOptions = { filter?: gpu.FilterMode; wrap?: gpu.WrapMode; mip
 export type { FilterMode, WrapMode, TextureBinding, TextureBindings } from "flux:gpu"
 
 // Pixel format option for the pixel-upload creates (createTexture,
-// createMutableTexture), fixed for the id's lifetime like the sampler state.
-// "rgba8" (default) or "r8" - see TextureFormat in flux:gpu for the r8
-// contract (1 byte/pixel, sampled as `(v, 0, 0, 1)`, any width).
+// createCubeTexture, createMutableTexture), fixed for the id's lifetime like
+// the sampler state. "rgba8" (default), "rgba8-srgb" (decodes to linear
+// light on sample), "r8", the float data-texture formats "r32f"/"rgba32f"
+// (Float32Array payload, nearest/texelFetch sampling only, no readback) and
+// the HDR image format "rgba16f" (Float32Array payload packed to half float,
+// filterable) - see TextureFormat in flux:gpu for each format's contract.
+// Draw targets (createDrawTarget, createCubeDrawTarget) take the renderable
+// subset: "rgba8", "rgba8-srgb", "rgba16f".
+// "etc2-rgba8" (compressed) is a reserved future value of the same
+// vocabulary.
 export type TextureFormatOptions = { format?: gpu.TextureFormat }
 export type { TextureFormat } from "flux:gpu"
 
@@ -136,7 +147,7 @@ export {
 // GPU-side (exact, same size): seed a loadOp "load" accumulator, snapshot a
 // ping-pong buffer, reset state to a known image.
 export { copyTexture, destroyBuffer, renderTarget, setDraw } from "flux:gpu"
-export type { BlendMode, BufferUpdate, CullMode, DrawRange, IndexBinding, IndexFormat, IndexRange, InstanceAttribute, ShaderParams, Topology, VertexAttribute } from "flux:gpu"
+export type { BlendMode, BufferUpdate, CullMode, DrawRange, IndexBinding, IndexFormat, IndexRange, InstanceAttribute, InstanceOrder, OrderUpdate, ShaderParams, Topology, VertexAttribute } from "flux:gpu"
 
 // The draw-list verbs, re-exported raw: entries live and die with their draw
 // target (see createDrawTarget below), so there is no per-entry lifetime to
@@ -150,7 +161,10 @@ export type { BlendMode, BufferUpdate, CullMode, DrawRange, IndexBinding, IndexF
 // params every entry reads. setDrawOrder replaces the whole
 // list order with a full permutation of the live ids - the sorting verb
 // (opaque front-to-back, transparent back-to-front, re-issued when the
-// camera moves).
+// camera moves). That orders ENTRIES; ordering the instance RECORDS within
+// one entry is the instanceOrder creation option (see InstanceOrder), whose
+// projected-key direction updates ride setDraw/setDrawRange as
+// orderDirection.
 export { addDraw, removeDraw, setDrawBuffers, setDrawOrder, setDrawParams, setDrawRange, setDrawTextures } from "flux:gpu"
 
 // The device ceilings (max texture/target size, sampler inputs per pass,
@@ -217,8 +231,9 @@ export { captureSnapshot, readTexture } from "flux:gpu"
 /**
  * Uploads raw pixels to an immutable GPU texture and returns its id (use it
  * as `<texture src={id} />`). `data` must be exactly `width * height` pixels
- * at the declared format's size (`* 4` bytes for the default "rgba8", `* 1`
- * for "r8"); a mismatch throws. RGBA data is uploaded verbatim and composited
+ * at the declared format's size, in the view type matching the format
+ * (Uint8Array for "rgba8"/"rgba8-srgb"/"r8", Float32Array for "r32f"/
+ * "rgba32f"/"rgba16f"); a mismatch throws. RGBA data is uploaded verbatim and composited
  * as premultiplied alpha, like every texture: `decodeImage` and the readback
  * calls already deliver that, and hand-built pixels must too (`rgb * a`). For pixels you intend to mutate and
  * re-upload, use `createMutableTexture` instead. When called inside a
@@ -230,7 +245,7 @@ export { captureSnapshot, readTexture } from "flux:gpu"
  * scope.
  */
 export function createTexture(
-  data: Uint8Array,
+  data: Uint8Array | Float32Array,
   width: number,
   height: number,
   opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
@@ -240,18 +255,52 @@ export function createTexture(
   return id
 }
 
+/**
+ * Uploads a cube map: six square faces of `size * size` pixels in GL order
+ * (+X, -X, +Y, -Y, +Z, -Z), each in the view type matching the declared
+ * format like `createTexture`, and returns its id. A cube map is sampled by
+ * DIRECTION from a `uniform samplerCube` in a shader (`texture(uEnv, dir)`;
+ * `textureLod` for an explicit mip level, `mipmap: true` builds the chain
+ * from the faces) - the skybox, reflection and environment-lighting
+ * primitive. `faces` may instead be an explicit mip chain - an array of
+ * six-face arrays, level 0 first, halving down to the 1x1 level (the full
+ * chain) - uploaded as given: prefiltered environment levels, with no
+ * generated chain and so no renderability requirement on the format (an
+ * "rgba16f" chain works on every device). Explicit levels imply `mipmap:
+ * true`. Sampler-only: the id binds through `textures` like any other,
+ * but `<texture src>` cannot display it and `readTexture`, `copyTexture`,
+ * `uploadTexture` and `resizeTexture` throw (it is create-once). `wrap` has
+ * no effect - cube filtering is seamless across faces. Binding a cube map
+ * to a `sampler2D`, or a 2D texture to a `samplerCube`, throws at the bind.
+ * Note GL's cube convention: each face is what a lookup in that direction
+ * returns, the cube as seen from OUTSIDE, so a face set authored the Three
+ * way (each face as seen from inside) reads mirrored on x unless each
+ * image is mirrored at load. Freed like `createTexture` (auto-free under a
+ * reactive owner, `{ autoFree: false }` or `destroyTexture` otherwise).
+ */
+export function createCubeTexture(
+  faces: (Uint8Array | Float32Array)[] | (Uint8Array | Float32Array)[][],
+  size: number,
+  opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
+): gpu.TextureId {
+  let id = gpu.createCubeTexture(faces, size, opts)
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  return id
+}
+
 /**
  * Creates a GPU texture you intend to update over time: seed it with `data`,
  * then call `uploadTexture(id, data)` (from flux:gpu) to push new pixels.
  * `data` must hold at least `width * height` pixels at the declared format's
- * size (`* 4` bytes for the default "rgba8", `* 1` for "r8"; it may hold
- * several frames). Like `createTexture`, the texture is freed automatically
+ * size, in the view type matching the format (Uint8Array for "rgba8"/
+ * "rgba8-srgb"/"r8", Float32Array for "r32f"/"rgba32f"/"rgba16f"); it may
+ * hold several frames. Like `createTexture`, the texture is freed automatically
  * when the reactive owner is disposed (opt out with `{ autoFree: false }`);
  * created outside a reactive scope you must call `destroyTexture` (from
  * flux:gpu) yourself.
  */
 export function createMutableTexture(
-  data: Uint8Array,
+  data: Uint8Array | Float32Array,
   width: number,
   height: number,
   opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
@@ -360,6 +409,8 @@ export function createShaderTarget(
     /** One buffer per instance slot of the pipeline (index = the
      * attributes' `slot`); pass this OR `instanceBuffer`, not both. */
     instanceBuffers?: gpu.BufferId[]
+    /** Draw the instance records in key order (see InstanceOrder). */
+    instanceOrder?: gpu.InstanceOrder
     clearColor?: [number, number, number, number]
     render?: "auto" | "manual"
     loadOp?: "clear" | "load"
@@ -400,6 +451,13 @@ export function createShaderTarget(
  * driven later with `setTargetTextures`, same precedence and coverage
  * rules.
  *
+ * `format` is the color storage: "rgba8" (default), "rgba8-srgb" (encodes
+ * what a pass writes, decodes on sample) or "rgba16f" (half float, keeps
+ * the range - an HDR view or bake; where `limits.halfFloatRenderable`,
+ * else it throws). A target of either non-default format is SAMPLER-ONLY:
+ * a pass source, never displayed by a `<texture>` leaf, read back or
+ * copied (render it through a pass into an rgba8 target for those).
+ *
  * `into` makes a sub-target: a draw target rendering into the rectangle at
  * `x`/`y` (top-left origin) of draw target `into`'s storage, so N views or
  * N shadow maps share one texture and ONE pass; the id is a draw target to
@@ -421,6 +479,7 @@ export function createDrawTarget(
   params?: gpu.ShaderParams | null,
   opts?: {
     depth?: boolean | "texture"
+    format?: "rgba8" | "rgba8-srgb" | "rgba16f"
     textures?: gpu.TextureBindings
     clearColor?: [number, number, number, number]
     render?: "auto" | "manual"
@@ -437,6 +496,41 @@ export function createDrawTarget(
   return id
 }
 
+/**
+ * Creates a cube draw target: a draw target whose output is a `size` x
+ * `size` cube map, rendered one face at a time with `renderTarget(id,
+ * face)` (0 +X, 1 -X, 2 +Y, 3 -Y, 4 +Z, 5 -Z) - the reflection-probe
+ * primitive (`@solidrt/3d`'s `scene.createReflectionProbe` drives it).
+ * Manual by contract, one depth renderbuffer for the six faces (`depth:
+ * true`), no samples or tiles; `format` rgba8, rgba8-srgb (encodes on
+ * write, decodes on sample) or rgba16f (half float, the HDR probe format,
+ * where `limits.halfFloatRenderable`); `mipmap: true` allocates the chain and
+ * `renderTarget(id, face, level)` renders one level of it (a face render
+ * without a level regenerates the chain instead) - the prefiltered
+ * environment path. The id binds to a `samplerCube`
+ * and cannot be displayed, read back, copied or resized. Each face pass
+ * inverts the front-face rule (a GL cube face is the x mirror of a 2D
+ * target's image), so render the faces through an x-mirrored projection;
+ * see flux:gpu's createCubeDrawTarget. Freed like every target.
+ */
+export function createCubeDrawTarget(
+  size: number,
+  params?: gpu.ShaderParams | null,
+  opts?: {
+    depth?: boolean
+    format?: "rgba8" | "rgba8-srgb" | "rgba16f"
+    textures?: gpu.TextureBindings
+    clearColor?: [number, number, number, number]
+    render?: "manual"
+    loadOp?: "clear" | "load"
+  } & CreateOptions &
+    SamplerOptions,
+): gpu.TextureId {
+  let id = gpu.createCubeDrawTarget(size, params, opts)
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => gpu.destroyTexture(id))
+  return id
+}
+
 /** The reactive shader description `createShaderTextureMemo` builds from.
  * Sampling (`filter`/`wrap`/`mipmap`) is creation-time state, so changing it rebuilds
  * at a fresh id, like a fragment-source or sampler-binding change. */
@@ -449,14 +543,22 @@ export type ShaderSpec = {
 } & SamplerOptions
 
 // Shallow name->value equality for params/textures records; treats undefined
-// as the empty record. A param value may be a number or a flat number array
-// (typed uniforms), so arrays compare elementwise; a texture binding may be
-// an `{ id, filter?, wrap? }` override, compared field by field.
-type RecordValue = number | number[] | gpu.TextureBinding
+// as the empty record. A param value may be a number or a flat number list
+// (typed uniforms: a number[] or a Float32Array/Float64Array), so lists
+// compare elementwise; a texture binding may be an `{ id, filter?, wrap? }`
+// override, compared field by field.
+type RecordValue = number | number[] | Float32Array | Float64Array | gpu.TextureBinding
+function isNumberList(v: RecordValue | undefined): v is number[] | Float32Array | Float64Array {
+  return Array.isArray(v) || v instanceof Float32Array || v instanceof Float64Array
+}
 function sameValue(a: RecordValue | undefined, b: RecordValue | undefined): boolean {
   if (a === b) return true
-  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => v === b[i])
-  if (typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+  if (isNumberList(a) && isNumberList(b)) {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
+    return true
+  }
+  if (typeof a === "object" && typeof b === "object" && !isNumberList(a) && !isNumberList(b)) {
     return a.id === b.id && a.filter === b.filter && a.wrap === b.wrap
   }
   return false
@@ -606,6 +708,8 @@ export function createPipelineTexture(
     /** One buffer per instance slot (index = the attributes' `slot`);
      * pass this OR `instanceBuffer`, not both. */
     instanceBuffers?: gpu.BufferId[]
+    /** Draw the instance records in key order (see InstanceOrder). */
+    instanceOrder?: gpu.InstanceOrder
     topology?: gpu.Topology
     depth?: boolean
     depthWrite?: boolean

package/src/index.ts

@@ -1,5 +1,5 @@
 export * from "./renderer"
-export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, layoutNextLine, unitInk, getBoundingBox, getBoundingBoxViewport, snapshotTexture, onPointerMove } from "./core"
+export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, layoutNextLine, unitInk, getBoundingBox, getBoundingBoxViewport, getLayoutBox, snapshotTexture, onPointerMove } from "./core"
 export type { BoundingBox, GlobalPointerEvent, TextLine } from "./core"
 export { parseColor, mixColors, withAlpha, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
@@ -12,7 +12,7 @@ export { gamepads } from "./gamepad"
 export type { GamepadState } from "./gamepad"
 export { capabilities } from "./capabilities"
 export type { Capabilities, WindowSizeClass } from "./capabilities"
-export { createTexture } from "./gpu"
+export { createCubeTexture, createTexture } from "./gpu"
 export type { TextureId } from "./gpu"
 export { createImage, decodeImage, encodeImage } from "./image"
 export type { DecodedImage, ImageSource } from "./image"

package/src/pan.ts

@@ -18,7 +18,13 @@ export interface PanOptions {
    */
   axis?: PanAxis
   onPanStart?: () => void
-  /** Pointer movement since the previous event; positive dx is rightward, positive dy downward. */
+  /**
+   * Pointer movement since the previous event, in the handler node's PARENT
+   * frame (the frame its own x/y live in: window pixels under no scaling
+   * ancestor, design pixels under a designSize fit), so it applies 1:1
+   * whether the consumer moves the node itself or content inside it.
+   * Positive dx is rightward, positive dy downward.
+   */
   onPanMove?: (dx: number, dy: number) => void
   onPanEnd?: () => void
 }
@@ -35,8 +41,17 @@ export interface PanOptions {
 // cancel() is the external-cancel hook; it ends an active pan without
 // onPanEnd. Options are read at event time. Single-pointer by design; for
 // multi-pointer pinch/rotate compose createTransform instead.
+//
+// Frames: the slop is finger travel, so it is measured in window pixels
+// (clientX/clientY); the deltas are measured in the node's parent frame
+// (parentX/parentY), the frame the node's own coordinates live in, so a
+// scaled ancestor (a designSize fit) is accounted for and both the drag
+// idiom (move the node) and the content idiom (scroll what is inside it)
+// apply the delta unchanged. The event carries both frames exactly, on
+// and off the node.
 export function createPan(options: PanOptions) {
-  // Down position while armed; last delivered position while active.
+  // Down position (window pixels) while armed; last delivered position
+  // (parent frame) while active.
   let origin: { x: number; y: number } | null = null
   let active: number | null = null
   let armed: number | null = null
@@ -78,7 +93,7 @@ export function createPan(options: PanOptions) {
         if (arena.steal(e.pointerId, owner)) {
           active = e.pointerId
           armed = null
-          origin = { x: e.clientX, y: e.clientY }
+          origin = { x: e.parentX, y: e.parentY }
           options.onPanStart?.()
         } else {
           // The arena is resolved against us; the drag belongs elsewhere.
@@ -87,8 +102,8 @@ export function createPan(options: PanOptions) {
         return
       }
       if (active === e.pointerId && origin) {
-        options.onPanMove?.(e.clientX - origin.x, e.clientY - origin.y)
-        origin = { x: e.clientX, y: e.clientY }
+        options.onPanMove?.(e.parentX - origin.x, e.parentY - origin.y)
+        origin = { x: e.parentX, y: e.parentY }
       }
     },
     onPointerUp: (e: PointerEvent) => {

package/src/runtime-modules.d.ts

@@ -66,8 +66,8 @@ declare module "srt:events" {
 // The running application's own surface (lattice), present in every build.
 declare module "srt:app" {
   /**
-   * Leave the current app, unconditionally: back to the launcher in a dev
-   * client, quit when standalone or at the launcher root (on Android the
+   * Leave the current app, unconditionally: back to the player in a dev
+   * client, quit when standalone or at the player root (on Android the
    * client backgrounds instead of dying). The default action of an
    * unprevented `back` event; prefer the @solidrt/core re-export.
    */
@@ -81,7 +81,7 @@ declare module "srt:dev" {
   export const canDiscover: boolean
   export const recents: string[]
   /**
-   * The dev-server address the client was launched with (so the launcher can
+   * The dev-server address the client was launched with (so the player can
    * auto-connect without on-device interaction), or null when launched without
    * one.
    */
@@ -101,7 +101,7 @@ declare module "srt:dev" {
   export function registerDebug(name: string, fn: (args?: any) => unknown): void
 }
 
-// Installed-app management (lattice), the launcher's surface over the client's
+// Installed-app management (lattice), the player's surface over the client's
 // version store. Present only in go/dev client builds; elsewhere `available`
 // is false, `list` returns [], and launch/remove are no-ops.
 declare module "srt:apps" {
@@ -166,7 +166,7 @@ declare module "srt:apps" {
   export function info(id: string): AppInfo
   /**
    * Boot the app's installed current version, replacing the running app (the
-   * launcher). Throws when the app is not installed. Custom fonts of the
+   * player). Throws when the app is not installed. Custom fonts of the
    * launched app register at client startup only, not mid-session.
    */
   export function launch(id: string): void
@@ -182,8 +182,8 @@ declare module "srt:apps" {
    */
   export function clearCache(id: string): void
   /**
-   * Build identity of this runtime, for the launcher's settings screen. Not
-   * app-specific, but surfaced here since the launcher already imports this
+   * Build identity of this runtime, for the player's settings screen. Not
+   * app-specific, but surfaced here since the player already imports this
    * module. `version` is the release version (git describe; "0.0.0-dev" in a
    * plain build), `profile` is "debug" or "release", `platform` is the OS
    * (std::env::consts::OS, e.g. "linux", "android", "windows", "macos").