@solidrt/core 0.0.23 → 0.0.25

package/jsx-runtime.d.ts

@@ -7,7 +7,6 @@ import type {
   ViewProps,
   TextProps,
   TextureProps,
-  AudioProps,
   LayoutProps,
   Element as CoreElement,
   ElementChildrenAttribute as CoreElementChildrenAttribute
@@ -40,7 +39,6 @@ export namespace JSX {
     path: PathProps & LayoutProps & ElementRef
     svg: SvgProps & LayoutProps & ElementRef
     texture: TextureProps & LayoutProps & ElementRef
-    audio: AudioProps & ElementRef
     "d-view": ViewProps & ElementRef
     "d-rect": RectProps & ElementRef
     "d-oval": OvalProps & ElementRef

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -11,6 +11,7 @@
     "./gpu": "./src/gpu.ts",
     "./image": "./src/image.ts",
     "./microphone": "./src/microphone.ts",
+    "./sound": "./src/sound.ts",
     "./speech-recognition": "./src/speech-recognition.ts",
     "./text-input": "./src/text-input.ts",
     "./jsx-runtime": "./jsx-runtime.d.ts",
@@ -26,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.23"
+    "@solidrt/flux-types": "0.0.25"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.15",

package/src/color.ts

@@ -43,6 +43,11 @@ type Stop = { offset: number; color: number }
 // element's box), so one gradient can be reused on elements of any size. Branded
 // so the renderer can tell it from a solid color string. The object crosses to
 // the runtime as-is and is decoded by key (see properties/paint.rs).
+//
+// These 0..1 coords are deliberately their own normalized space, NOT the pixel/
+// `pct()` length vocabulary used by layout and transformOrigin: a gradient's
+// position is naturally a fraction (like a stop offset), so 0..1 reads cleaner
+// than pct(0)..pct(100). Do not "unify" them onto pct().
 export type Gradient =
   | { readonly __gradient: "linear"; x0: number; y0: number; x1: number; y1: number; stops: Stop[] }
   | { readonly __gradient: "radial"; cx: number; cy: number; r: number; circle: boolean; stops: Stop[] }

package/src/environment.ts

@@ -10,6 +10,14 @@ import { windowSize, safeArea, displayScale, windowFocused, keyboardHeight } fro
 // been seen this session. Seen-flags only ever go from false to true, so a
 // 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.
 
 /** Connected input device classes, as reported by the runtime. */
 export interface InputDevices {
@@ -26,7 +34,7 @@ let devicesAccessor: (() => InputDevices | undefined) | undefined
 
 function ensureDevicesState() {
   if (devicesAccessor) return
-  let [devices, setDevices] = createSignal<InputDevices | undefined>(undefined)
+  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) => {
@@ -39,7 +47,7 @@ let systemThemeAccessor: (() => SystemTheme) | undefined
 
 function ensureSystemThemeState() {
   if (systemThemeAccessor) return
-  let [theme, setTheme] = createSignal<SystemTheme>("unknown")
+  let [theme, setTheme] = createSignal<SystemTheme>("unknown", { ownedWrite: true })
   on("systemTheme", (e: { theme?: SystemTheme }) => setTheme(e.theme ?? "unknown"))
   systemThemeAccessor = theme
 }
@@ -48,7 +56,7 @@ let orientationAccessor: (() => Orientation) | undefined
 
 function ensureOrientationState() {
   if (orientationAccessor) return
-  let [orientation, setOrientation] = createSignal<Orientation>("unknown")
+  let [orientation, setOrientation] = createSignal<Orientation>("unknown", { ownedWrite: true })
   on("displayOrientation", (e: { orientation?: Orientation }) => {
     setOrientation(e.orientation ?? "unknown")
   })
@@ -59,7 +67,7 @@ let textScaleAccessor: (() => number) | undefined
 
 function ensureTextScaleState() {
   if (textScaleAccessor) return
-  let [scale, setScale] = createSignal(1)
+  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 }) => {

package/src/gpu.ts

@@ -19,6 +19,13 @@ import * as gpu from "flux:gpu"
 // `<texture params={...}>` when a `<texture>` element is already in the tree.
 export { destroyTexture, setShaderParams, uploadTexture } 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
+// no longer current, so the caller owns the returned id and frees it with
+// destroyTexture (as with any texture created after an await).
+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`

package/src/index.ts

@@ -32,11 +32,16 @@ export type {
   PathProps,
   TextProps,
   TextureProps,
-  AudioProps,
   Color,
+  Pct,
 } from "./types"
 export type { MeasureTextOptions } from "flux:rendertree"
 
+// A percentage value for dimensional props (e.g. transformOrigin): `pct(50)` is
+// half the element box. Keeps percentages a first-class branded value rather
+// than a string that has to be parsed - a bare number stays pixels.
+export let pct = (v: number): import("./types").Pct => ({ __unit: "pct", v })
+
 // --- 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

package/src/sound.ts

@@ -0,0 +1,119 @@
+// Sound playback, reactive (SolidJS) layer. `createSound` decodes an encoded
+// clip (Ogg/Vorbis or WAV) once and owns its lifecycle: the decoded clip is
+// released, and any playing voices stopped, when the reactive owner is disposed.
+// Each play() is cheap (no re-decode). `createSoundStream` is the same but reads
+// 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.
+
+import { createSignal, onCleanup } from "@solidjs/signals"
+import { load, stream } from "flux:audio"
+import { file } from "flux:fs"
+
+type FluxFile = ReturnType<typeof file>
+
+type LoadedSound = ReturnType<typeof load>
+
+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
+  /**
+   * Let play() stack overlapping voices instead of restarting. Defaults to
+   * true: rapid triggers overlap. Set false for a single-voice sound where each
+   * play() cuts off the previous one.
+   */
+  overlap?: boolean
+}
+
+/** Options for a streamed sound. Streams are always single-voice. */
+export type SoundStreamOptions = {
+  /** Repeat the track until stopped. Defaults to false. */
+  loop?: boolean
+  /** Volume scale, 1.0 leaves the track unchanged. Defaults to 1.0. */
+  gain?: number
+}
+
+/** A decoded sound with reactive lifecycle. */
+export type Sound = {
+  /** Start the clip. Overlaps or restarts per the `overlap` option. */
+  play(): void
+  /** Stop every voice started from this sound. */
+  stop(): 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
+// disposes both on cleanup. `loader` runs once (may throw -> error signal).
+function reactiveSound(
+  loader: () => LoadedSound,
+  overlap: boolean,
+  playOptions: { loop?: boolean; gain?: 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 }[] = []
+  try {
+    handle = loader()
+  } catch (e) {
+    setError(e instanceof Error ? e : new Error(String(e)))
+  }
+
+  let stopAll = () => {
+    for (let v of voices) v.stop()
+    voices = []
+    setPlaying(false)
+  }
+
+  onCleanup(() => {
+    stopAll()
+    if (handle) {
+      handle.unload()
+      handle = undefined
+    }
+  })
+
+  return {
+    play() {
+      if (!handle) return
+      if (!overlap) stopAll()
+      voices.push(handle.play(playOptions))
+      setPlaying(true)
+    },
+    stop: stopAll,
+    playing,
+    error,
+  }
+}
+
+/**
+ * Decodes a sound once and owns its lifecycle: releases the clip and stops its
+ * voices when the reactive owner is disposed. play() replays without decoding.
+ * For imperative use, call load()/play() from "flux:audio".
+ */
+export function createSound(source: Uint8Array, options: SoundOptions = {}): Sound {
+  return reactiveSound(() => load(source), options.overlap ?? true, {
+    loop: options.loop,
+    gain: options.gain,
+  })
+}
+
+/**
+ * Streams a large track, decoding on demand instead of loading it into memory.
+ * Single-voice: each play() restarts it. Pass a path (resolved like flux:fs,
+ * relative to the process cwd) or a `file()` from flux:fs; a path is wrapped in
+ * `file()` for you, so a dev-server-proxied file streams over the proxy. Owns
+ * the stream's lifecycle: stopped and released when the reactive owner is
+ * disposed. For imperative use, call stream()/play() from "flux:audio".
+ */
+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 })
+}

package/src/types.d.ts

@@ -44,9 +44,9 @@ type Children = Element
 // alone (e.g. shorthand-vs-longhand precedence, a subsetted value range).
 
 interface FlexboxProps {
-  gap?: number
-  rowGap?: number
-  columnGap?: number
+  gap?: LengthPercentage
+  rowGap?: LengthPercentage
+  columnGap?: LengthPercentage
   /** Shorthand; overridden by flexGrow/flexShrink/flexBasis when they're also set. */
   flex?: number | "none" | "auto" | (string & {})
   flexGrow?: number
@@ -74,8 +74,14 @@ interface GridProps {
   gridTemplateRows?: string
 }
 
-/** A layout length: a bare number is pixels, plus "auto" and percent strings. */
-type Dimension = number | "auto" | `${number}%`
+/**
+ * A layout length: a bare number is pixels, `pct(n)` is a percentage of the
+ * containing block, plus "auto" and the `"50%"` string form (kept for paste).
+ */
+type Dimension = number | Pct | "auto" | `${number}%`
+
+/** Like {@link Dimension} without "auto" (e.g. gap, which has no auto value). */
+type LengthPercentage = number | Pct | `${number}%`
 
 export interface LayoutProps extends FlexboxProps, GridProps {
   display?: "block" | "flex" | "grid" | "none"
@@ -131,6 +137,16 @@ export interface PaintProps {
   strokeWidth?: number
 }
 
+/** A percentage value, from `pct(50)`. Resolves against the element box. */
+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.
+type OriginX = number | Pct | "left" | "center" | "right"
+type OriginY = number | Pct | "top" | "center" | "bottom"
+
 export interface TransformProps {
   rotate?: number
   scale?: number
@@ -149,8 +165,8 @@ export interface TransformProps {
   perspective?: number
   x?: number
   y?: number
-  cx?: number
-  cy?: number
+  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.
   opacity?: number
@@ -212,7 +228,7 @@ interface Position {
 
 // Primitives
 
-export interface WindowProps extends LayoutProps {
+export interface WindowProps extends LayoutProps, PointerProps {
   children?: Children
   title?: string
   fullscreen?: boolean
@@ -242,16 +258,6 @@ export interface ViewProps extends LayoutProps, TransformProps, PointerProps {
   repaintBoundary?: boolean | "snapshot"
 }
 
-/**
- * Not implemented: there is no native `audio` element kind yet, so using
- * `<audio>` panics ("unknown node kind: audio"). Typed ahead of the backing
- * work; treat this interface as a plan, not a working API.
- */
-export interface AudioProps {
-  src?: Uint8Array
-  play?: number
-}
-
 // draw primitives
 
 export interface RectProps extends Position, PaintProps, PointerProps {
@@ -309,7 +315,7 @@ export interface TextProps extends Position, PaintProps, PointerProps {
   maxLines?: number
 }
 
-export interface TextureProps extends Position {
+export interface TextureProps extends Position, PointerProps {
   src?: number
   w?: number
   h?: number

package/src/window.ts

@@ -93,7 +93,9 @@ export function onResize(fn: (data: ResizeEvent) => void) {
 // Singleton accessors over the same events as onResize / onWindowFocus. There
 // is one window, so these are bare accessors rather than a createX instance.
 // Lazily subscribed on first read (resize is sticky, so the first read sees the
-// current value); app-lifetime, so no onCleanup.
+// current value); app-lifetime, so no onCleanup. `ownedWrite: true` on the
+// signals below is the sticky-replay-into-a-tracked-scope case explained on
+// the ensure* functions in environment.ts.
 
 let sizeAccessor: (() => { width: number; height: number }) | undefined
 let safeAreaAccessor: (() => SafeArea) | undefined
@@ -101,9 +103,9 @@ let displayScaleAccessor: (() => number) | undefined
 
 function ensureResizeState() {
   if (sizeAccessor) return
-  let [size, setSize] = createSignal({ width: 0, height: 0 })
-  let [safe, setSafe] = createSignal<SafeArea>({ top: 0, left: 0, right: 0, bottom: 0 })
-  let [scale, setScale] = createSignal(1)
+  let [size, setSize] = createSignal({ width: 0, height: 0 }, { ownedWrite: true })
+  let [safe, setSafe] = createSignal<SafeArea>({ top: 0, left: 0, right: 0, bottom: 0 }, { ownedWrite: true })
+  let [scale, setScale] = createSignal(1, { ownedWrite: true })
   on("resize", (e: ResizeEvent) => {
     setSize({ width: e.width, height: e.height })
     setSafe(e.safeArea)