@solidrt/core 0.0.42 → 0.0.43

package/AGENTS.md

@@ -24,6 +24,15 @@ hardcode desktop pixels.
   (<600), `medium` (600-840), `expanded` (>=840). Drive column counts / layout
   switches off it (see the responsive-grid example).
 
+Exception - fixed-aspect content. For content with fixed internal geometry
+(diagrams, slides, dashboards, games, emulators), do not branch on window size
+at all: author everything in one design space and let `viewBox` fit it.
+`<view flex={1} viewBox={[1280, 800]}>` uniformly scales and centers the
+children (letterboxed), pointer events on them arrive in design coordinates,
+and the same code runs unchanged from a desktop window to a phone. Reach for
+`windowSizeClass` branching only when the layout genuinely reflows across form
+factors.
+
 `env` and `capabilities` (both exported from `@solidrt/core`) are the two
 objects that expose this. They are plain objects with REACTIVE GETTERS, not
 functions - read them as `capabilities.windowSizeClass`, `env.displayScale`
@@ -104,10 +113,11 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   Outlines: `drawStyle="stroke"` (or "stroke-and-fill") plus `strokeWidth`.
   Corner radius on draw primitives: `radius` (number or [tl, tr, br, bl]).
 
-- Registered JSX intrinsics: `window`, `view`, `text`, `rect`, `oval`, `path`,
-  `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`, `d-oval`,
-  `d-path`, `d-texture`, `d-text`. NOTE: `<line>` has a LineProps type but is
-  NOT a registered intrinsic - it will not typecheck.
+- Registered JSX intrinsics: `window`, `view`, `text`, `rect`, `oval`, `line`,
+  `path`, `texture`, `audio`, plus the `d-` variants `d-view`, `d-rect`,
+  `d-oval`, `d-line`, `d-path`, `d-texture`, `d-text`. Line endpoints
+  (`x1`/`y1`/`x2`/`y2`) exist only on `d-line`; a laid-out `<line>` has no
+  endpoint props and spans its layout box corner to corner.
 
 - Plain vs `d-` variant (the `d-` prefix means "detached" - detached from the
   layout engine, Taffy): a plain element (e.g. `rect`) is `RectProps &
@@ -119,6 +129,13 @@ 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.
 
+- Transform origin on a `d-view`: with `originX`/`originY` unset, scale/rotate
+  pivot at the view's local (0,0) - the origin its children's coordinates are
+  authored against - not at a box center (a laid-out view pivots at its own
+  box center; a d-view has no box). To scale a detached group around its
+  content's center, set the origin explicitly in pixels, e.g.
+  `originX={100} originY={50}` for content drawn in a 200x100 local space.
+
 - 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
@@ -137,6 +154,11 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   `position:absolute` at `left:0,top:0`, or just let normal flow place it) and
   then translate it with `x`/`y`.
 
+- JSX text children collapse whitespace (ordinary JSX semantics): runs of
+  spaces become one, so space-padding a mono label collapses silently. An
+  expression container preserves it - `<d-text>{"one    two"}</d-text>` - and
+  `\n` inside one produces a hard line break.
+
 - 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.42",
+  "version": "0.0.43",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.42"
+    "@solidrt/flux-types": "0.0.43"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.26",

package/src/gpu.ts

@@ -60,6 +60,13 @@ export type CreateOptions = { manual?: boolean; label?: string }
 export type SamplerOptions = { filter?: gpu.FilterMode; wrap?: gpu.WrapMode }
 export type { FilterMode, WrapMode } 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).
+export type TextureFormatOptions = { format?: gpu.TextureFormat }
+export type { TextureFormat } from "flux:gpu"
+
 // The branded id types, one per id space (see flux:gpu): plain numbers at
 // runtime, distinct types to the checker, so a cross-space slip like
 // destroyBuffer(textureId) fails to compile. Exported so apps can annotate
@@ -166,21 +173,22 @@ export let glsl = String.raw
 export { captureSnapshot, readTexture } 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`
- * bytes; a mismatch throws. For pixels you intend to mutate and re-upload, use
- * `createMutableTexture` instead. When called inside a reactive scope the
- * texture is freed automatically once that owner is disposed; when called
- * outside one (e.g. after an `await`, where the owner is no longer current)
- * nothing is registered and you must call `destroyTexture` (from flux:gpu)
- * yourself. Pass `{ manual: true }` to skip the auto-free and own the
- * disposal yourself even inside a reactive scope.
+ * 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. For pixels you intend to mutate and
+ * re-upload, use `createMutableTexture` instead. When called inside a
+ * reactive scope the texture is freed automatically once that owner is
+ * disposed; when called outside one (e.g. after an `await`, where the owner
+ * is no longer current) nothing is registered and you must call
+ * `destroyTexture` (from flux:gpu) yourself. Pass `{ manual: true }` to skip
+ * the auto-free and own the disposal yourself even inside a reactive scope.
  */
 export function createTexture(
   data: Uint8Array,
   width: number,
   height: number,
-  opts?: CreateOptions & SamplerOptions,
+  opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
 ): gpu.TextureId {
   let id = gpu.createTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
@@ -189,18 +197,19 @@ export function createTexture(
 
 /**
  * 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`
- * is RGBA8 and must hold at least `width * height * 4` bytes (it may hold several
- * frames). Like `createTexture`, the texture is freed automatically when the
- * reactive owner is disposed (opt out with `{ manual: true }`); created
- * outside a reactive scope you must call `destroyTexture` (from flux:gpu)
- * yourself.
+ * 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
+ * when the reactive owner is disposed (opt out with `{ manual: true }`);
+ * created outside a reactive scope you must call `destroyTexture` (from
+ * flux:gpu) yourself.
  */
 export function createMutableTexture(
   data: Uint8Array,
   width: number,
   height: number,
-  opts?: CreateOptions & SamplerOptions,
+  opts?: CreateOptions & SamplerOptions & TextureFormatOptions,
 ): gpu.TextureId {
   let id = gpu.createMutableTexture(data, width, height, opts)
   if (!opts?.manual && getOwner()) onCleanup(() => gpu.destroyTexture(id))
@@ -237,7 +246,9 @@ export function createMutableTexture(
  * as written, so a shader carrying its own uniform names - one ported from
  * elsewhere - runs unchanged here without dropping to compileShader /
  * linkProgram. The built-in vertex stage still supplies `vUV`; declare
- * `in vec2 vUV;` yourself to read it.
+ * `in vec2 vUV;` yourself to read it. One naming trap: GLSL ES reserves
+ * `packed` as a keyword, so `vec4 packed = texture(...)` fails with a syntax
+ * error that does not name the identifier - pick another name.
  */
 export function createShaderTexture(
   fragmentSrc: string,

package/src/sound.ts

@@ -5,7 +5,7 @@
 // a large track from a file path on demand instead of decoding it into memory.
 //
 // The imperative primitive lives in the `flux:audio` module; import
-// { play, load, stream } from "flux:audio" for non-reactive use.
+// { play, load, loadPcm, stream } from "flux:audio" for non-reactive use.
 
 import { createSignal, onCleanup } from "@solidjs/signals"
 import { load, stream } from "flux:audio"
@@ -13,13 +13,19 @@ import { file } from "flux:fs"
 
 type FluxFile = ReturnType<typeof file>
 
-type LoadedSound = ReturnType<typeof load>
+type Clip = ReturnType<typeof load>
+type Playback = ReturnType<Clip["play"]>
 
 export type SoundOptions = {
   /** Repeat the clip until stopped. Defaults to false. */
   loop?: boolean
   /** Volume scale, 1.0 leaves the clip unchanged. Defaults to 1.0. */
   gain?: number
+  /**
+   * Stereo position in [-1, 1], -1 = left, 0 = center, 1 = right (equal-power).
+   * Omitted means unspatialized.
+   */
+  pan?: number
   /**
    * Let play() stack overlapping voices instead of restarting. Defaults to
    * true: rapid triggers overlap. Set false for a single-voice sound where each
@@ -34,6 +40,8 @@ export type SoundStreamOptions = {
   loop?: boolean
   /** Volume scale, 1.0 leaves the track unchanged. Defaults to 1.0. */
   gain?: number
+  /** Stereo position in [-1, 1] (see {@link SoundOptions.pan}). */
+  pan?: number
 }
 
 /** A decoded sound with reactive lifecycle. */
@@ -42,30 +50,45 @@ export type Sound = {
   play(): void
   /** Stop every voice started from this sound. */
   stop(): void
+  /** Set the volume of every live voice, and of voices started later. */
+  setGain(gain: number): void
+  /** Set the stereo position of every live voice, and of voices started later. */
+  setPan(pan: number): void
   /** True after play() until stop() (does not track natural completion). */
   playing(): boolean
   /** Set if loading failed. */
   error(): Error | undefined
 }
 
-// Shared reactive wrapper: owns the loaded handle, tracks live voices, and
+// Shared reactive wrapper: owns the loaded clip, tracks live voices, and
 // disposes both on cleanup. `loader` runs once (may throw -> error signal).
+// Gain and pan are remembered so later voices start where setGain/setPan left
+// the sound, not back at the initial options.
 function reactiveSound(
-  loader: () => LoadedSound,
+  loader: () => Clip,
   overlap: boolean,
-  playOptions: { loop?: boolean; gain?: number },
+  initial: { loop?: boolean; gain?: number; pan?: number },
 ): Sound {
   let [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true })
   let [playing, setPlaying] = createSignal(false, { ownedWrite: true })
 
-  let handle: LoadedSound | undefined
-  let voices: { stop(): void }[] = []
+  let clip: Clip | undefined
+  let voices: Playback[] = []
+  let loop = initial.loop
+  let gain = initial.gain
+  let pan = initial.pan
   try {
-    handle = loader()
+    clip = loader()
   } catch (e) {
     setError(e instanceof Error ? e : new Error(String(e)))
   }
 
+  // Voices that finished on their own keep a dead handle in `voices` until the
+  // next call here; ended() lets each touch point clear them out.
+  let prune = () => {
+    voices = voices.filter((v) => !v.ended())
+  }
+
   let stopAll = () => {
     for (let v of voices) v.stop()
     voices = []
@@ -74,20 +97,31 @@ function reactiveSound(
 
   onCleanup(() => {
     stopAll()
-    if (handle) {
-      handle.unload()
-      handle = undefined
+    if (clip) {
+      clip.unload()
+      clip = undefined
     }
   })
 
   return {
     play() {
-      if (!handle) return
-      if (!overlap) stopAll()
-      voices.push(handle.play(playOptions))
+      if (!clip) return
+      if (overlap) prune()
+      else stopAll()
+      voices.push(clip.play({ loop, gain, pan }))
       setPlaying(true)
     },
     stop: stopAll,
+    setGain(value) {
+      gain = value
+      prune()
+      for (let v of voices) v.setGain(value)
+    },
+    setPan(value) {
+      pan = value
+      prune()
+      for (let v of voices) v.setPan(value)
+    },
     playing,
     error,
   }
@@ -102,6 +136,7 @@ export function createSound(source: Uint8Array, options: SoundOptions = {}): Sou
   return reactiveSound(() => load(source), options.overlap ?? true, {
     loop: options.loop,
     gain: options.gain,
+    pan: options.pan,
   })
 }
 
@@ -115,5 +150,5 @@ export function createSound(source: Uint8Array, options: SoundOptions = {}): Sou
  */
 export function createSoundStream(source: string | FluxFile, options: SoundStreamOptions = {}): Sound {
   let src = typeof source === "string" ? file(source) : source
-  return reactiveSound(() => stream(src), false, { loop: options.loop, gain: options.gain })
+  return reactiveSound(() => stream(src), false, { loop: options.loop, gain: options.gain, pan: options.pan })
 }

package/src/types.d.ts

@@ -157,7 +157,12 @@ export type Pct = { readonly __unit: "pct"; v: number }
 // One axis of the transform origin (the point rotate/scale/3D pivot around),
 // split per axis to match the engine's x/y prop convention. A bare number is
 // pixels; `pct(50)` is a fraction of the box, so a percentage origin tracks the
-// layout size with no reactive wiring. Unset defaults to the axis center.
+// layout size with no reactive wiring. Unset defaults to the axis center on a
+// laid-out view; on a d-view (no box of its own) it defaults to the view's
+// local (0,0) - the origin its children's coordinates are authored against, so
+// the pivot never depends on the inherited box. To pivot a d-view around its
+// content's center, set the origin explicitly in pixels; pct()/keywords on a
+// d-view resolve against the inherited box, which is rarely what you want.
 type OriginX = number | Pct | "left" | "center" | "right"
 type OriginY = number | Pct | "top" | "center" | "bottom"
 
@@ -185,7 +190,11 @@ export interface TransformProps {
   originX?: OriginX
   originY?: OriginY
   // Group opacity in 0..1: children are composited together, then faded as a
-  // whole (CSS `opacity`). Does not affect hit testing.
+  // whole (CSS `opacity`). Does not affect hit testing. Costs a compositing
+  // layer (save_layer around the subtree) while below 1, except on a
+  // repaintBoundary view, where it is hoisted to composite time for free. To
+  // fade a single primitive, put the alpha in its `color` (rgba) instead -
+  // paint alpha costs nothing.
   opacity?: number
   scrollX?: number
   scrollY?: number
@@ -458,6 +467,13 @@ export interface RectProps extends PaintProps, PointerProps {
 // Strokes paint inside the box, same as `RectProps`.
 export interface OvalProps extends PaintProps, PointerProps {}
 
+// A line's geometry is numbers, not a path string: the segment primitive to
+// reach for when endpoints move (each endpoint is one property write; a path
+// animates by rebuilding its `d` string). Endpoints (x1/y1/x2/y2) exist on
+// the detached `d-line` only. A laid-out `<line>` is practically a rule -
+// give it a thin box (length x strokeWidth); in general it draws its layout
+// box's top-left-to-bottom-right diagonal. For arbitrary angles and
+// connectors use `d-line`; for polylines and curves, a path.
 export interface LineProps extends PaintProps, PointerProps {
   /** Dash pattern in local units: the drawn segment length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
   onLength?: number