@solidrt/core 0.0.11 → 0.0.14

package/src/microphone.ts

@@ -1,40 +1,58 @@
-// Microphone capture. A session delivers raw mono float32 samples at the
-// requested sample rate (the device format is converted by SDL); read()
-// drains whatever was captured since the last call. Captured audio buffers
-// until read, so poll read() regularly (e.g. once per frame) while open.
+// Microphone capture, reactive (SolidJS) layer. A session delivers raw mono
+// float32 samples at the requested sample rate (the device format is converted
+// by SDL); read() drains whatever was captured since the last call. Captured
+// audio buffers until read, so poll read() regularly (e.g. once per frame) while
+// open.
+//
+// The imperative primitive lives in the `flux:microphone` module; import
+// { open, listMicrophones } from "flux:microphone" for non-reactive use.
 
-export type MicrophoneInfo = {
-  id: number
-  name: string
-}
+import { createSignal, onCleanup } from "@solidjs/signals"
+import { open } from "flux:microphone"
 
 export type MicrophoneOptions = {
-  /** Explicit device id from listMicrophones(); default is the system default recording device. */
+  /** Explicit device id from flux:microphone listMicrophones(); default is the system default. */
   microphone?: number
   /** Sample rate of the delivered samples (the device rate is converted). Default 16000. */
   sampleRate?: number
 }
 
-export type Microphone = {
-  /** Sample rate of read() samples. */
-  sampleRate: number
-  /** Drain the mono float32 samples captured since the last read. */
+/** A live microphone with reactive lifecycle. */
+export type MicrophoneStream = {
+  /** Sample rate of read() samples (0 if opening failed). */
+  sampleRate(): number
+  /** Drain the mono float32 samples captured since the last read (empty if not open). */
   read(): Float32Array
-  /** Release the device. */
-  close(): void
+  /** Set if opening failed. */
+  error(): Error | undefined
 }
 
-export function listMicrophones(): MicrophoneInfo[] {
-  return microphone.listMicrophones()
-}
+/**
+ * Opens a microphone and owns its lifecycle: closes when the reactive owner is
+ * disposed. Capture stays pull-based, so read() drains samples on demand (e.g.
+ * once per frame). For imperative use, call open() from "flux:microphone".
+ */
+export function createMicrophone(options: MicrophoneOptions = {}): MicrophoneStream {
+  let [error, setError] = createSignal<Error | undefined>(undefined)
+  let session: ReturnType<typeof open> | undefined
+  let rate = 0
+  try {
+    session = open(options)
+    rate = session.sampleRate
+  } catch (e) {
+    setError(e instanceof Error ? e : new Error(String(e)))
+  }
+
+  onCleanup(() => {
+    if (session) {
+      session.close()
+      session = undefined
+    }
+  })
 
-// Async to leave room for an OS permission prompt on platforms that need one
-// (the desktop backends open synchronously).
-export async function openMicrophone(options: MicrophoneOptions = {}): Promise<Microphone> {
-  let opened = microphone.open(options)
   return {
-    sampleRate: opened.sampleRate,
-    read: () => microphone.read(opened.handle),
-    close: () => microphone.close(opened.handle),
+    sampleRate: () => rate,
+    read: () => (session ? session.read() : new Float32Array(0)),
+    error,
   }
 }

package/src/renderer.ts

@@ -1,7 +1,9 @@
-import { createRoot, createEffect } from "@solidjs/signals"
+import { createRoot, onCleanup } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
+import * as tree from "flux:rendertree"
 import { attachWindow } from "./window"
-import { parseColorToU32, setEventHandler, cleanupNodeHandlers, getFocusedNodeId, setFocus } from "./core"
+import { setEventHandler, cleanupNodeHandlers, getFocusedNodeId, setFocus } from "./core"
+import { parseColor, isGradient } from "./color"
 
 export { getEventHandler } from "./core"
 
@@ -28,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,
@@ -47,8 +77,8 @@ export let {
 
     // console.debug("[srt] createElement", proxy.id, elementType)
 
-    if (elementType === "window") ffi.createRoot(proxy.id)
-    else ffi.createNode(proxy.id, elementType)
+    if (elementType === "window") tree.createRoot(proxy.id)
+    else tree.createNode(proxy.id, elementType)
 
     return proxy
   },
@@ -56,14 +86,14 @@ export let {
   createTextNode: (value: string): ProxyNode => {
     let proxy = createProxyNode("d-span")
     // console.debug("[srt] createTextNode", proxy.id, value)
-    ffi.createNode(proxy.id, "d-span")
-    ffi.setProperty(proxy.id, "text", "" + value)
+    tree.createNode(proxy.id, "d-span")
+    tree.setProperty(proxy.id, "text", "" + value)
     return proxy
   },
 
   replaceText: (node: ProxyNode, value: string): void => {
     // console.debug("[srt] replaceText", node.id, value)
-    ffi.setProperty(node.id, "text", "" + value)
+    tree.setProperty(node.id, "text", "" + value)
   },
 
   isTextNode: (node: ProxyNode): boolean => node?.elementType === "d-span",
@@ -77,12 +107,17 @@ export let {
       return
     }
 
+    if (name === "color" && isGradient(value)) {
+      tree.setProperty(node.id, name, value)
+      return
+    }
+
     if (name === "color" && typeof value === "string") {
-      ffi.setProperty(node.id, name, parseColorToU32(value))
+      tree.setProperty(node.id, name, parseColor(value))
       return
     }
 
-    ffi.setProperty(node.id, name, value)
+    tree.setProperty(node.id, name, value)
   },
 
   insertNode: (parent: ProxyNode, node: ProxyNode, anchor?: ProxyNode): void => {
@@ -104,35 +139,12 @@ export let {
 
       // console.debug("[srt] insertNode", parent.id, node.id, anchor?.id ?? "")
 
-      if (anchor) ffi.insertNode(parent.id, node.id, anchor.id)
-      else ffi.insertNode(parent.id, node.id)
+      if (anchor) tree.insertNode(parent.id, node.id, anchor.id)
+      else tree.insertNode(parent.id, node.id)
     }
   },
 
-  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
-
-    ffi.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],
@@ -145,13 +157,48 @@ 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
+ * window and root of the render tree); anything else throws. Runs inside a
+ * reactive root, so the whole tree is disposed together on engine reload.
+ */
 export function render(code: () => any) {
   createRoot(() => {
     let root = code()
     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/speech-recognition.ts

@@ -0,0 +1,149 @@
+// Speech recognition. A session captures the microphone, segments utterances
+// by silence (Silero VAD) and transcribes each one with Whisper, delivering
+// final transcripts through onResult. With wakeWord the session starts
+// asleep behind an efficient wake word detector (livekit-wakeword) and only
+// transcribes after the wake word. startRecognition resolves once the models
+// are loaded and listening has begun; it rejects when loading fails.
+// Models are passed as bytes so any source composes: flux:fs file(), fetch
+// (incl. the dev-server file proxy), or a download cache layered on top.
+// Requires a runtime built with speech support.
+
+import { createSignal, onCleanup } from "@solidjs/signals"
+
+export type SpeechOptions = {
+  /** A ggml Whisper model (file contents, e.g. ggml-tiny.en.bin). */
+  model: Uint8Array
+  /** A ggml Silero VAD model (file contents). */
+  vadModel: Uint8Array
+  /** Whisper language code; "auto" detects (multilingual models only). Default "en". */
+  lang?: string
+  /** Explicit microphone device id from listMicrophones(). */
+  microphone?: number
+  /**
+   * Keep transcribing utterance after utterance. Default true. Set false to
+   * stop after the first final result (with wakeWord: re-arm instead, one
+   * result per wake). Inverse of the Web Speech API default (false there).
+   */
+  continuous?: boolean
+  /** Also deliver snapshot transcripts (final: false) while an utterance is still being spoken. */
+  interimResults?: boolean
+  /**
+   * Wake word: start asleep, fire onWake when it is heard, then transcribe
+   * the speech that follows. How the wake word is specified depends on the
+   * engine. The current engine detects with a trained classifier and takes
+   * the model's bytes (livekit-wakeword ONNX, e.g. the pretrained "hey
+   * livekit"; custom phrases are trained offline with its toolkit). Phrase
+   * strings are reserved for engines that match text; passing them to this
+   * engine rejects with an error.
+   */
+  wakeWord?: Uint8Array | string | string[]
+  /** Detector confidence (0..1) that counts as a wake. Default 0.5. */
+  wakeThreshold?: number
+}
+
+export type SpeechResult = {
+  /** Transcript of the utterance (a snapshot of it when isFinal is false). */
+  transcript: string
+  /** True for the completed utterance, false for interim snapshots. */
+  isFinal: boolean
+}
+
+export type SpeechSession = {
+  /** Receive transcripts (replaces any previous callback). */
+  onResult(callback: (result: SpeechResult) => void): void
+  /** The user started speaking (replaces any previous callback). */
+  onSpeechStart(callback: () => void): void
+  /** The utterance ended; its final result follows once transcribed. */
+  onSpeechEnd(callback: () => void): void
+  /** The wake word was heard (wakeWordModel sessions only). */
+  onWake(callback: () => void): void
+  /** Release the microphone and discard any utterance in progress. */
+  stop(): void
+}
+
+export async function startRecognition(options: SpeechOptions): Promise<SpeechSession> {
+  let started = await speech.start(options)
+  return {
+    onResult: (callback: (result: SpeechResult) => void) => speech.setResultCallback(started.handle, callback),
+    onSpeechStart: (callback: () => void) => speech.setSpeechStartCallback(started.handle, callback),
+    onSpeechEnd: (callback: () => void) => speech.setSpeechEndCallback(started.handle, callback),
+    onWake: (callback: () => void) => speech.setWakeCallback(started.handle, callback),
+    stop: () => speech.stop(started.handle),
+  }
+}
+
+/** A live recognition session as reactive accessors. */
+export type SpeechStream = {
+  /** True once the models are loaded and listening has begun. */
+  ready(): boolean
+  /** Latest transcript, "" until the first result (a snapshot while isFinal is false). */
+  transcript(): string
+  /** Whether transcript() is the completed utterance rather than an interim snapshot. */
+  isFinal(): boolean
+  /** True while the user is mid-utterance (between speech start and end). */
+  speaking(): boolean
+  /** True from when an utterance ends until its transcript arrives. */
+  transcribing(): boolean
+  /**
+   * wakeWord sessions only: true from when the wake word is heard until the
+   * following command is transcribed (the next final result), then false.
+   * Always false without a wakeWord.
+   */
+  awake(): boolean
+  /** Set if loading or starting failed. */
+  error(): Error | undefined
+}
+
+/**
+ * Starts speech recognition and exposes it as reactive signals: read
+ * transcript()/isFinal() for results, speaking() and awake() for session
+ * state. Stops when the reactive owner is disposed. The lower-level
+ * startRecognition() is the imperative alternative.
+ */
+export function createSpeechRecognition(options: SpeechOptions): SpeechStream {
+  let [ready, setReady] = createSignal(false)
+  let [transcript, setTranscript] = createSignal("")
+  let [isFinal, setIsFinal] = createSignal(false)
+  let [speaking, setSpeaking] = createSignal(false)
+  let [transcribing, setTranscribing] = createSignal(false)
+  let [awake, setAwake] = createSignal(false)
+  let [error, setError] = createSignal<Error | undefined>(undefined)
+  let handle: number | undefined
+  let disposed = false
+
+  speech
+    .start(options)
+    .then((started) => {
+      if (disposed) {
+        speech.stop(started.handle)
+        return
+      }
+      handle = started.handle
+      speech.setResultCallback(started.handle, (result) => {
+        setTranscript(result.transcript)
+        setIsFinal(result.isFinal)
+        if (result.isFinal) {
+          setTranscribing(false)
+          setAwake(false)
+        }
+      })
+      speech.setSpeechStartCallback(started.handle, () => setSpeaking(true))
+      speech.setSpeechEndCallback(started.handle, () => {
+        setSpeaking(false)
+        setTranscribing(true)
+      })
+      speech.setWakeCallback(started.handle, () => setAwake(true))
+      setReady(true)
+    })
+    .catch((e) => setError(e instanceof Error ? e : new Error(String(e))))
+
+  onCleanup(() => {
+    disposed = true
+    if (handle !== undefined) {
+      speech.stop(handle)
+      handle = undefined
+    }
+  })
+
+  return { ready, transcript, isFinal, speaking, transcribing, awake, error }
+}