@solidrt/core 0.0.10 → 0.0.13

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 } 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"
 
@@ -47,8 +49,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 +58,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 +79,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,8 +111,8 @@ 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)
     }
   },
 
@@ -121,7 +128,7 @@ export let {
     }
     node.parent = undefined
 
-    ffi.deleteNode(parent.id, node.id)
+    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.
@@ -145,6 +152,12 @@ export let {
   },
 })
 
+/**
+ * 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()

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 }
+}

package/src/text-input.ts

@@ -0,0 +1,207 @@
+// Headless text-input mechanism. These primitives own the objective parts of
+// an editable single-line field -- the value buffer (text + caret/selection)
+// and the scroll-to-caret geometry -- and nothing with a UI opinion. Caret
+// blink, keybindings, placeholder and styling are policy and belong to the
+// component (the "skin") that composes these.
+
+import { createSignal, flush } from "@solidjs/signals"
+import { getBoundingBox, measureText } from "./core"
+import { onLayout } from "./window"
+
+/**
+ * A text selection as anchor/focus character offsets, following the same model
+ * as the platform editors (Flutter's TextSelection, the DOM Selection): the
+ * anchor is where the selection started, the focus is the moving end where the
+ * caret sits. A collapsed selection (anchor === focus) is a plain caret.
+ */
+export type Selection = { anchor: number; focus: number }
+
+export type MoveDirection = "left" | "right" | "start" | "end"
+
+export type TextBufferOptions = {
+  /**
+   * Controlled value accessor. When it returns a string, the buffer mirrors it
+   * and edits flow out only through onInput (the internal text is bypassed).
+   * The selection is always buffer-owned editing state regardless.
+   */
+  value?: () => string | undefined
+  /** Initial value when uncontrolled. */
+  defaultValue?: string
+  /** Called with the new text after every edit, already clamped to maxLength. */
+  onInput?: (value: string) => void
+  /** Max length; inserts past it are clamped. */
+  maxLength?: () => number | undefined
+}
+
+export type TextBuffer = {
+  /** Current text: the controlled value if provided, else internal state. */
+  value(): string
+  /** Current selection, clamped to the text length. Collapsed = a caret. */
+  selection(): Selection
+  /** The focus offset (where the caret sits). */
+  caret(): number
+  /** Replace the current selection with text, then collapse the caret after it. */
+  insertText(text: string): void
+  /** Delete the selection if any, else the character before the caret. */
+  deleteBackward(): void
+  /** Delete the selection if any, else the character after the caret. */
+  deleteForward(): void
+  /** Move the caret. `extend` keeps the anchor to grow a selection (else collapses). */
+  move(direction: MoveDirection, options?: { extend?: boolean }): void
+  /** Set the selection directly (offsets are clamped to the text length). */
+  setSelection(anchor: number, focus: number): void
+  /** Replace the whole value, caret to the end. */
+  setValue(next: string): void
+  /** Clear to empty. */
+  clear(): void
+}
+
+/**
+ * An editable text buffer that bridges controlled/uncontrolled use and owns the
+ * caret/selection. With a `value` accessor the buffer is controlled: edits do
+ * not mutate internal text, they only call `onInput` so the owner can update its
+ * source. Without one it holds the text itself. The selection is always
+ * buffer-owned state and is clamped to the current text length on read, so an
+ * external truncation of a controlled value cannot leave the caret dangling.
+ * Every edit is clamped to `maxLength`.
+ */
+export function createTextBuffer(options: TextBufferOptions = {}): TextBuffer {
+  let initial = options.defaultValue ?? ""
+  let [internalValue, setInternalValue] = createSignal(initial)
+  let [selectionState, setSelectionState] = createSignal<Selection>({
+    anchor: initial.length,
+    focus: initial.length,
+  })
+
+  let value = () => options.value?.() ?? internalValue()
+
+  let selection = (): Selection => {
+    let len = value().length
+    let s = selectionState()
+    return { anchor: Math.min(s.anchor, len), focus: Math.min(s.focus, len) }
+  }
+
+  // Ordered selection bounds [start, end).
+  let range = () => {
+    let { anchor, focus } = selection()
+    return anchor <= focus ? [anchor, focus] : [focus, anchor]
+  }
+
+  let setCaret = (offset: number) => setSelectionState({ anchor: offset, focus: offset })
+
+  // Apply a text edit and place the caret, clamping to maxLength.
+  let apply = (next: string, caret: number) => {
+    let max = options.maxLength?.()
+    if (max != null && next.length > max) next = next.slice(0, max)
+    caret = Math.min(caret, next.length)
+    if (options.value?.() == null) setInternalValue(next)
+    setCaret(caret)
+    options.onInput?.(next)
+  }
+
+  return {
+    value,
+    selection,
+    caret: () => selection().focus,
+
+    insertText: (text) => {
+      let v = value()
+      let [start, end] = range()
+      apply(v.slice(0, start) + text + v.slice(end), start + text.length)
+    },
+
+    deleteBackward: () => {
+      let v = value()
+      let [start, end] = range()
+      if (start !== end) apply(v.slice(0, start) + v.slice(end), start)
+      else if (start > 0) apply(v.slice(0, start - 1) + v.slice(start), start - 1)
+    },
+
+    deleteForward: () => {
+      let v = value()
+      let [start, end] = range()
+      if (start !== end) apply(v.slice(0, start) + v.slice(end), start)
+      else if (end < v.length) apply(v.slice(0, end) + v.slice(end + 1), end)
+    },
+
+    move: (direction, opts) => {
+      let extend = opts?.extend ?? false
+      let { anchor, focus } = selection()
+      let len = value().length
+      // A non-extending left/right on a range collapses to the near edge.
+      if (!extend && anchor !== focus && (direction === "left" || direction === "right")) {
+        setCaret(direction === "left" ? Math.min(anchor, focus) : Math.max(anchor, focus))
+        return
+      }
+      let next = focus
+      if (direction === "left") next = Math.max(0, focus - 1)
+      else if (direction === "right") next = Math.min(len, focus + 1)
+      else if (direction === "start") next = 0
+      else if (direction === "end") next = len
+      setSelectionState({ anchor: extend ? anchor : next, focus: next })
+    },
+
+    setSelection: (anchor, focus) => {
+      let len = value().length
+      setSelectionState({ anchor: Math.min(anchor, len), focus: Math.min(focus, len) })
+    },
+
+    setValue: (next) => apply(next, next.length),
+    clear: () => apply("", 0),
+  }
+}
+
+export type CaretScrollInput = {
+  text: string
+  fontSize: number
+  /** Caret offset into `text`. Defaults to the text end. */
+  caret?: number
+  /** Px reserved so the caret stays visible at the viewport edge. Default 0. */
+  caretWidth?: number
+}
+
+/**
+ * Returns the horizontal scroll offset that keeps the caret within the viewport
+ * node. The offset is retained between frames and only adjusted when the caret
+ * would fall outside the visible range (scrolled left when the caret runs past
+ * the right edge, right when it moves before the left edge), so stationary text
+ * does not jump. The viewport width and offset are computed in onLayout and the
+ * synchronous flush drains the update before paint, so the scroll tracks a caret
+ * or width change in the same frame. Pure geometry: no caret rendering and no
+ * placeholder/visual policy.
+ */
+export function createCaretScroll(
+  viewport: () => { id: number } | undefined,
+  input: () => CaretScrollInput,
+): () => number {
+  let [scrollX, setScrollX] = createSignal(0)
+
+  onLayout(() => {
+    let node = viewport()
+    if (!node) return
+    let vw = getBoundingBox(node)?.width ?? 0
+    let { text, fontSize, caret, caretWidth = 0 } = input()
+    let len = text.length
+    let c = caret == null ? len : Math.max(0, Math.min(caret, len))
+
+    let totalWidth = measureText(text, { fontSize }).width
+    let caretX = c >= len ? totalWidth : measureText(text.slice(0, c), { fontSize }).width
+    let maxScroll = Math.max(0, totalWidth + caretWidth - vw)
+
+    let cur = scrollX()
+    let next = cur
+    if (vw <= 0) {
+      next = 0
+    } else if (caretX < cur) {
+      next = caretX
+    } else if (caretX + caretWidth > cur + vw) {
+      next = caretX + caretWidth - vw
+    }
+    next = Math.max(0, Math.min(next, maxScroll))
+
+    if (next !== cur) setScrollX(next)
+    flush()
+  })
+
+  return scrollX
+}

package/src/types.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="@solidrt/flux-types" />
 
 import type { JSX as SolidJSX } from "@solidjs/signals"
+import type { Gradient } from "./color"
 
 // UI event bus (lattice), provided by the runtime as a builtin module.
 // on/once return an unsubscribe function.
@@ -20,51 +21,26 @@ declare module "srt:dev" {
   export function stop(): void
 }
 
-declare global {
-  function requestAnimationFrame(callback: (time: number) => void): number
-  function cancelAnimationFrame(id: number): void
-
-  let ffi: {
-    createRoot(id: number): void
-    createNode(id: number, kind: string): void
-    insertNode(parentId: number, nodeId: number, anchorId?: number): void
-    deleteNode(parentId: number, nodeId: number): void
-    setProperty(nodeId: number, name: string, value: unknown): void
-    setTextInputActive(active: boolean): void
-    requestFrame(): void
-    measureText(text: string, options?: MeasureTextOptions): { width: number, height: number }
-    getBoundingBox(id: number): { x: number, y: number, width: number, height: number } | null
-  }
+// Frame draw (lattice runner). renderFrame() synchronously renders the current
+// frame: layout, the postLayout hook, paint and hover refresh, then builds and
+// submits the display list. To schedule a future frame instead, use
+// requestFrame() from "flux:rendertree". The tree-building surface itself is
+// "flux:rendertree" (from @solidrt/flux-types).
+declare module "srt:render" {
+  export function renderFrame(): void
+}
 
-  let gpu: {
-    createTexture(data: Uint8Array, width: number, height: number): number
-    createMutableTexture(data: Uint8Array, width: number, height: number): number
-    uploadTexture(textureId: number, offset?: number): void
+declare global {
+  let image: {
     decodeImage(bytes: Uint8Array): { data: Uint8Array, width: number, height: number }
   }
 
-  let camera: {
-    listCameras(): { id: number, name: string, facing: "front" | "back" | "unknown" }[]
-    open(options: { camera?: number, facing?: "front" | "back", width?: number, height?: number, scan?: string[] }):
-      Promise<{ handle: number, texture: number, width: number, height: number }>
-    setBarcodeCallback(handle: number, callback: (result: { data: string, format: "qr" }) => void): void
-    scanImage(data: Uint8Array, width: number, height: number): { data: string, format: "qr" }[]
-    close(handle: number): void
-  }
-
-  let microphone: {
-    listMicrophones(): { id: number, name: string }[]
-    open(options: { microphone?: number, sampleRate?: number }): { handle: number, sampleRate: number }
-    read(handle: number): Float32Array
-    close(handle: number): void
-  }
-
   let speech: {
     start(options: {
-      model: Uint8Array, vadModel: Uint8Array, language?: string, microphone?: number,
-      singleUtterance?: boolean, interimResults?: boolean, wakeWord?: Uint8Array | string | string[], wakeThreshold?: number,
+      model: Uint8Array, vadModel: Uint8Array, lang?: string, microphone?: number,
+      continuous?: boolean, interimResults?: boolean, wakeWord?: Uint8Array | string | string[], wakeThreshold?: number,
     }): Promise<{ handle: number }>
-    setResultCallback(handle: number, callback: (result: { text: string, final: boolean }) => void): void
+    setResultCallback(handle: number, callback: (result: { transcript: string, isFinal: boolean }) => void): void
     setSpeechStartCallback(handle: number, callback: () => void): void
     setSpeechEndCallback(handle: number, callback: () => void): void
     setWakeCallback(handle: number, callback: () => void): void
@@ -72,14 +48,6 @@ declare global {
   }
 }
 
-export interface MeasureTextOptions {
-  fontFamily?: "sans" | "mono" | (string & {})
-  fontSize?: number
-  fontStyle?: "normal" | "italic"
-  fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
-  maxLines?: number
-}
-
 type Children = SolidJSX.Element
 
 interface FlexboxProps {
@@ -128,6 +96,7 @@ export interface LayoutProps extends FlexboxProps, GridProps {
   minHeight?: Dimension
   maxWidth?: Dimension
   maxHeight?: Dimension
+  aspectRatio?: number | (string & {})
 
   padding?: Dimension
   paddingTop?: Dimension
@@ -146,11 +115,12 @@ export interface LayoutProps extends FlexboxProps, GridProps {
   overflowY?: "visible" | "clip" | "hidden" | "scroll"
 }
 
-// Colors are CSS color strings, parsed to a packed u32 by parseColorToU32.
+/** Colors are CSS color strings, parsed to a packed u32 by `parseColor`. */
 export type Color = string
 
 export interface PaintProps {
-  color?: Color
+  // A solid color, or a gradient from createLinearGradient/createRadialGradient.
+  color?: Color | Gradient
   blendMode?: "clear" | "source" | "destination" | "source-over" | "destination-over" | "source-in" | "destination-in" | "source-out" | "destination-out" | "source-atop" | "destination-atop" | "xor" | "plus" | "modulate" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "multiply" | "hue" | "saturation" | "color" | "luminosity"
   drawStyle?: "fill" | "stroke" | "stroke-and-fill"
   strokeCap?: "butt" | "round" | "square"
@@ -288,7 +258,15 @@ export interface LineProps extends PaintProps, PointerProps {
 
 export interface PathProps extends Position, PaintProps, PointerProps {
   d?: string
-  fillRule?: "nonZero" | "evenOdd"
+  fillRule?: "nonzero" | "evenodd"
+}
+
+export interface SvgProps extends Position, PointerProps {
+  // A whole SVG document as a string (an imported asset, a fetched string, or a
+  // template literal). Parsed and rendered as one unit; takes no JSX children.
+  src?: string
+  // Drives currentColor in the document. Explicit fills/strokes still win.
+  color?: Color
 }
 
 export interface TextProps extends PaintProps, PointerProps {