feat(wavesurfer): promote peaks + duration to first-class props

Surface `peaks` (pre-computed waveform, untyped) and `duration` (Number) as
construction-time props so the render-without-decoding path (SSR / offline /
deterministic tests) is discoverable instead of buried in the `options` bag.
They override `options` ONLY when actually provided (conditional assignment),
so existing options.peaks callers — incl. the VR cell — keep working.

Surface now 27 props; compile ×6 / typecheck ×6 / build ×6 / surface 14/14 /
props-table validated / VR 6/6 re-validated on Linux.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lxeam8c3XSttraCZPxufKM

Author: serpentblade

docs/components/wavesurfer.md

@@ -219,6 +219,8 @@ There are two **two-way** model props — `currentTime` and `regions` (bind eith
 | Name | Type | Default | Two-way (model) | Runtime-updatable? | Description |
 | --- | --- | --- | :---: | :---: | --- |
 | `src` | `String` | `null` | | ✓ | The audio URL the waveform loads. Changing it calls `load(url)`. |
+| `peaks` | `unknown` | `undefined` | | | Pre-computed waveform peaks (array of channel sample arrays, or a single `number[]`) — render without downloading/decoding audio; pair with `duration`. **Construction-only.** |
+| `duration` | `Number` | `null` | | | Audio duration in seconds — required alongside `peaks` when there's no decodable `src`. **Construction-only.** |
 | `height` | `Number` | `128` | | ✓ | The waveform height in pixels. Reconciled via `setOptions`. |
 | `waveColor` | `String` | `"#8a2be2"` | | ✓ | Color of the unplayed portion of the waveform. Reconciled via `setOptions`. |
 | `progressColor` | `String` | `"#5a189a"` | | ✓ | Color of the played (progress) portion. Reconciled via `setOptions`. |
@@ -308,8 +310,8 @@ When you drive `regions` as a controlled list, include a stable `id` on each des
 
 ### Offline / deterministic rendering
 
-To render a waveform without decoding audio (CI, tests, SSR-adjacent), pass a pre-computed peaks array and a duration through `options`:
+To render a waveform without decoding audio (CI, tests, SSR-adjacent), pass a pre-computed peaks array and a duration — no `src` needed:
 
 ```ts
-<Waveform :options="{ peaks: [/* -1..1 samples */], duration: 8 }" src="/audio.mp3" />
+<Waveform :peaks="[/* -1..1 samples */]" :duration="8" />
 ```

packages/ui/wavesurfer/packages/angular/README.md

@@ -41,6 +41,8 @@ export class DemoComponent {
 | Name | Type | Default | Two-way (model) | Required |
 | --- | --- | --- | :---: | :---: |
 | `src` | `String` | `null` |  |  |
+| `peaks` | `unknown` | `undefined` |  |  |
+| `duration` | `Number` | `null` |  |  |
 | `height` | `Number` | `128` |  |  |
 | `waveColor` | `String` | `"#8a2be2"` |  |  |
 | `progressColor` | `String` | `"#5a189a"` |  |  |

packages/ui/wavesurfer/packages/angular/src/Waveform.ts

@@ -35,6 +35,14 @@ export class Waveform {
    * <Waveform :src="audioUrl" r-model:currentTime="time" />
    */
   src = input<(string) | null>(null);
+  /**
+   * Pre-computed waveform peaks (an array of channel sample arrays, or a single `number[]`). Renders the waveform without downloading or decoding audio — pair with `duration`. Construction-only.
+   */
+  peaks = input<unknown>(undefined);
+  /**
+   * The audio duration in seconds. Required alongside `peaks` when rendering without a decodable `src` (the timeline/ruler and region positions are derived from it). Construction-only.
+   */
+  duration = input<(number) | null>(null);
   /**
    * The waveform height in pixels. Reconciled at runtime via `setOptions`.
    */
@@ -124,7 +132,7 @@ export class Waveform {
    */
   regionColor = input<(string) | null>(null);
   /**
-   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`peaks`, `duration`, `sampleRate`, `mediaControls`, `splitChannels`, …).
+   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`sampleRate`, `mediaControls`, `splitChannels`, `barHeight`, …).
    */
   options = input<Record<string, any>>((() => ({}))());
   /**
@@ -315,6 +323,8 @@ export class Waveform {
     if (addedWithoutId) this.writeBackRegions();
   };
   buildWaveSurfer = () => {
+    const __peaks = this.peaks();
+    const __duration = this.duration();
     let plugins = [];
     plugins = [];
     if (this.timeline()) plugins.push(TimelinePlugin.create());
@@ -348,6 +358,10 @@ export class Waveform {
       dragToSeek: !this.disableDragToSeek(),
       plugins: plugins
     };
+    // peaks/duration override the `options` bag ONLY when actually provided —
+    // assigning `undefined` unconditionally would clobber a caller's options.peaks.
+    if (__peaks != null) cfg.peaks = __peaks;
+    if (__duration != null) cfg.duration = __duration;
     this.ws = WaveSurfer.create(cfg);
 
     // ── engine events → emits + the two-way currentTime writeback ──────────────

packages/ui/wavesurfer/packages/lit/README.md

@@ -29,6 +29,8 @@ el.addEventListener('ready', (e) => console.log('duration', e.detail));
 | Name | Type | Default | Two-way (model) | Required |
 | --- | --- | --- | :---: | :---: |
 | `src` | `String` | `null` |  |  |
+| `peaks` | `unknown` | `undefined` |  |  |
+| `duration` | `Number` | `null` |  |  |
 | `height` | `Number` | `128` |  |  |
 | `waveColor` | `String` | `"#8a2be2"` |  |  |
 | `progressColor` | `String` | `"#5a189a"` |  |  |

packages/ui/wavesurfer/packages/lit/src/Waveform.ts

@@ -30,6 +30,14 @@ export default class Waveform extends SignalWatcher(LitElement) {
    * <Waveform :src="audioUrl" r-model:currentTime="time" />
    */
   @property({ type: String, reflect: true }) src: string | null = null;
+  /**
+   * Pre-computed waveform peaks (an array of channel sample arrays, or a single `number[]`). Renders the waveform without downloading or decoding audio — pair with `duration`. Construction-only.
+   */
+  @property({ type: Object }) peaks: unknown = undefined;
+  /**
+   * The audio duration in seconds. Required alongside `peaks` when rendering without a decodable `src` (the timeline/ruler and region positions are derived from it). Construction-only.
+   */
+  @property({ type: Number, reflect: true }) duration: number | null = null;
   /**
    * The waveform height in pixels. Reconciled at runtime via `setOptions`.
    */
@@ -120,7 +128,7 @@ export default class Waveform extends SignalWatcher(LitElement) {
    */
   @property({ type: String, reflect: true }) regionColor: string | null = null;
   /**
-   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`peaks`, `duration`, `sampleRate`, `mediaControls`, `splitChannels`, …).
+   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`sampleRate`, `mediaControls`, `splitChannels`, `barHeight`, …).
    */
   @property({ type: Object }) options: any = {};
   /**
@@ -355,6 +363,10 @@ private __rozieFirstUpdateDone = false;
     dragToSeek: !this.disableDragToSeek,
     plugins: plugins
   };
+  // peaks/duration override the `options` bag ONLY when actually provided —
+  // assigning `undefined` unconditionally would clobber a caller's options.peaks.
+  if (this.peaks != null) cfg.peaks = this.peaks;
+  if (this.duration != null) cfg.duration = this.duration;
   this.ws = WaveSurfer.create(cfg);
 
   // ── engine events → emits + the two-way currentTime writeback ──────────────
@@ -569,7 +581,7 @@ private __rozieFirstUpdateDone = false;
    * (explicit `attribute:`) AND lowercased property name (Lit's default).
    */
   private get $attrs(): Record<string, string> {
-    const __skip = new Set<string>(['src', 'height', 'wave-color', 'wavecolor', 'progress-color', 'progresscolor', 'cursor-color', 'cursorcolor', 'cursor-width', 'cursorwidth', 'bar-width', 'barwidth', 'bar-gap', 'bargap', 'bar-radius', 'barradius', 'min-px-per-sec', 'minpxpersec', 'volume', 'playback-rate', 'playbackrate', 'autoplay', 'normalize-amplitude', 'normalizeamplitude', 'hide-scrollbar', 'hidescrollbar', 'disable-interaction', 'disableinteraction', 'disable-drag-to-seek', 'disabledragtoseek', 'timeline', 'hover', 'hover-color', 'hovercolor', 'regions', 'drag-to-create-regions', 'dragtocreateregions', 'region-color', 'regioncolor', 'options', 'current-time', 'currenttime']);
+    const __skip = new Set<string>(['src', 'peaks', 'duration', 'height', 'wave-color', 'wavecolor', 'progress-color', 'progresscolor', 'cursor-color', 'cursorcolor', 'cursor-width', 'cursorwidth', 'bar-width', 'barwidth', 'bar-gap', 'bargap', 'bar-radius', 'barradius', 'min-px-per-sec', 'minpxpersec', 'volume', 'playback-rate', 'playbackrate', 'autoplay', 'normalize-amplitude', 'normalizeamplitude', 'hide-scrollbar', 'hidescrollbar', 'disable-interaction', 'disableinteraction', 'disable-drag-to-seek', 'disabledragtoseek', 'timeline', 'hover', 'hover-color', 'hovercolor', 'regions', 'drag-to-create-regions', 'dragtocreateregions', 'region-color', 'regioncolor', 'options', 'current-time', 'currenttime']);
     const out: Record<string, string> = {};
     for (const a of Array.from(this.attributes)) {
       if (__skip.has(a.name)) continue;

packages/ui/wavesurfer/packages/react/README.md

@@ -36,6 +36,8 @@ export function Demo() {
 | Name | Type | Default | Two-way (model) | Required |
 | --- | --- | --- | :---: | :---: |
 | `src` | `String` | `null` |  |  |
+| `peaks` | `unknown` | `undefined` |  |  |
+| `duration` | `Number` | `null` |  |  |
 | `height` | `Number` | `128` |  |  |
 | `waveColor` | `String` | `"#8a2be2"` |  |  |
 | `progressColor` | `String` | `"#5a189a"` |  |  |

packages/ui/wavesurfer/packages/react/src/Waveform.d.ts

@@ -9,6 +9,14 @@ export interface WaveformProps {
    * <Waveform :src="audioUrl" r-model:currentTime="time" />
    */
   src?: (string) | null;
+  /**
+   * Pre-computed waveform peaks (an array of channel sample arrays, or a single `number[]`). Renders the waveform without downloading or decoding audio — pair with `duration`. Construction-only.
+   */
+  peaks?: unknown;
+  /**
+   * The audio duration in seconds. Required alongside `peaks` when rendering without a decodable `src` (the timeline/ruler and region positions are derived from it). Construction-only.
+   */
+  duration?: (number) | null;
   /**
    * The waveform height in pixels. Reconciled at runtime via `setOptions`.
    */
@@ -100,7 +108,7 @@ export interface WaveformProps {
    */
   regionColor?: (string) | null;
   /**
-   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`peaks`, `duration`, `sampleRate`, `mediaControls`, `splitChannels`, …).
+   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`sampleRate`, `mediaControls`, `splitChannels`, `barHeight`, …).
    */
   options?: Record<string, unknown>;
   /**

packages/ui/wavesurfer/packages/react/src/Waveform.tsx

@@ -22,6 +22,14 @@ interface WaveformProps {
    * <Waveform :src="audioUrl" r-model:currentTime="time" />
    */
   src?: (string) | null;
+  /**
+   * Pre-computed waveform peaks (an array of channel sample arrays, or a single `number[]`). Renders the waveform without downloading or decoding audio — pair with `duration`. Construction-only.
+   */
+  peaks?: unknown;
+  /**
+   * The audio duration in seconds. Required alongside `peaks` when rendering without a decodable `src` (the timeline/ruler and region positions are derived from it). Construction-only.
+   */
+  duration?: (number) | null;
   /**
    * The waveform height in pixels. Reconciled at runtime via `setOptions`.
    */
@@ -113,7 +121,7 @@ interface WaveformProps {
    */
   regionColor?: (string) | null;
   /**
-   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`peaks`, `duration`, `sampleRate`, `mediaControls`, `splitChannels`, …).
+   * Raw wavesurfer `WaveSurferOptions` passthrough — spread into `WaveSurfer.create()` before the curated keys (explicit props win). Use it for any v7 option not surfaced as a first-class prop (`sampleRate`, `mediaControls`, `splitChannels`, `barHeight`, …).
    */
   options?: Record<string, any>;
   /**
@@ -161,9 +169,11 @@ export interface WaveformHandle {
 
 const Waveform = forwardRef<WaveformHandle, WaveformProps>(function Waveform(_props: WaveformProps, ref): JSX.Element {
   const __defaultOptions = useState(() => (() => ({}))())[0];
-  const props: Omit<WaveformProps, 'src' | 'height' | 'waveColor' | 'progressColor' | 'cursorColor' | 'cursorWidth' | 'barWidth' | 'barGap' | 'barRadius' | 'minPxPerSec' | 'volume' | 'playbackRate' | 'autoplay' | 'normalizeAmplitude' | 'hideScrollbar' | 'disableInteraction' | 'disableDragToSeek' | 'timeline' | 'hover' | 'hoverColor' | 'dragToCreateRegions' | 'regionColor' | 'options'> & { src: (string) | null; height: number; waveColor: string; progressColor: string; cursorColor: string; cursorWidth: number; barWidth: (unknown) | null; barGap: (unknown) | null; barRadius: (unknown) | null; minPxPerSec: number; volume: number; playbackRate: number; autoplay: boolean; normalizeAmplitude: boolean; hideScrollbar: boolean; disableInteraction: boolean; disableDragToSeek: boolean; timeline: boolean; hover: boolean; hoverColor: (string) | null; dragToCreateRegions: boolean; regionColor: (string) | null; options: Record<string, any> } = {
+  const props: Omit<WaveformProps, 'src' | 'peaks' | 'duration' | 'height' | 'waveColor' | 'progressColor' | 'cursorColor' | 'cursorWidth' | 'barWidth' | 'barGap' | 'barRadius' | 'minPxPerSec' | 'volume' | 'playbackRate' | 'autoplay' | 'normalizeAmplitude' | 'hideScrollbar' | 'disableInteraction' | 'disableDragToSeek' | 'timeline' | 'hover' | 'hoverColor' | 'dragToCreateRegions' | 'regionColor' | 'options'> & { src: (string) | null; peaks: unknown; duration: (number) | null; height: number; waveColor: string; progressColor: string; cursorColor: string; cursorWidth: number; barWidth: (unknown) | null; barGap: (unknown) | null; barRadius: (unknown) | null; minPxPerSec: number; volume: number; playbackRate: number; autoplay: boolean; normalizeAmplitude: boolean; hideScrollbar: boolean; disableInteraction: boolean; disableDragToSeek: boolean; timeline: boolean; hover: boolean; hoverColor: (string) | null; dragToCreateRegions: boolean; regionColor: (string) | null; options: Record<string, any> } = {
     ..._props,
     src: _props.src ?? null,
+    peaks: _props.peaks ?? undefined,
+    duration: _props.duration ?? null,
     height: _props.height ?? 128,
     waveColor: _props.waveColor ?? '#8a2be2',
     progressColor: _props.progressColor ?? '#5a189a',
@@ -188,8 +198,8 @@ const Waveform = forwardRef<WaveformHandle, WaveformProps>(function Waveform(_pr
     options: _props.options ?? __defaultOptions,
   };
   const attrs: Record<string, unknown> = (() => {
-    const { src, height, waveColor, progressColor, cursorColor, cursorWidth, barWidth, barGap, barRadius, minPxPerSec, volume, playbackRate, autoplay, normalizeAmplitude, hideScrollbar, disableInteraction, disableDragToSeek, timeline, hover, hoverColor, regions, dragToCreateRegions, regionColor, options, currentTime, defaultValue, onRegionsChange, defaultRegions, onCurrentTimeChange, defaultCurrentTime, ...rest } = _props as WaveformProps & Record<string, unknown>;
-    void src; void height; void waveColor; void progressColor; void cursorColor; void cursorWidth; void barWidth; void barGap; void barRadius; void minPxPerSec; void volume; void playbackRate; void autoplay; void normalizeAmplitude; void hideScrollbar; void disableInteraction; void disableDragToSeek; void timeline; void hover; void hoverColor; void regions; void dragToCreateRegions; void regionColor; void options; void currentTime; void defaultValue; void onRegionsChange; void defaultRegions; void onCurrentTimeChange; void defaultCurrentTime;
+    const { src, peaks, duration, height, waveColor, progressColor, cursorColor, cursorWidth, barWidth, barGap, barRadius, minPxPerSec, volume, playbackRate, autoplay, normalizeAmplitude, hideScrollbar, disableInteraction, disableDragToSeek, timeline, hover, hoverColor, regions, dragToCreateRegions, regionColor, options, currentTime, defaultValue, onRegionsChange, defaultRegions, onCurrentTimeChange, defaultCurrentTime, ...rest } = _props as WaveformProps & Record<string, unknown>;
+    void src; void peaks; void duration; void height; void waveColor; void progressColor; void cursorColor; void cursorWidth; void barWidth; void barGap; void barRadius; void minPxPerSec; void volume; void playbackRate; void autoplay; void normalizeAmplitude; void hideScrollbar; void disableInteraction; void disableDragToSeek; void timeline; void hover; void hoverColor; void regions; void dragToCreateRegions; void regionColor; void options; void currentTime; void defaultValue; void onRegionsChange; void defaultRegions; void onCurrentTimeChange; void defaultCurrentTime;
     return rest;
   })();
   const regionsPlugin = useRef<any>(null);
@@ -324,6 +334,10 @@ const Waveform = forwardRef<WaveformHandle, WaveformProps>(function Waveform(_pr
       dragToSeek: !props.disableDragToSeek,
       plugins: plugins
     };
+    // peaks/duration override the `options` bag ONLY when actually provided —
+    // assigning `undefined` unconditionally would clobber a caller's options.peaks.
+    if (props.peaks != null) cfg.peaks = props.peaks;
+    if (props.duration != null) cfg.duration = props.duration;
     ws.current = WaveSurfer.create(cfg);
 
     // ── engine events → emits + the two-way currentTime writeback ──────────────
@@ -390,7 +404,7 @@ const Waveform = forwardRef<WaveformHandle, WaveformProps>(function Waveform(_pr
         _rozieProp_onRegionOut && _rozieProp_onRegionOut(serializeRegion(region));
       });
     }
-  }, [_rozieProp_onError, _rozieProp_onFinished, _rozieProp_onInteraction, _rozieProp_onLoading, _rozieProp_onPaused, _rozieProp_onPlaying, _rozieProp_onReady, _rozieProp_onRegionClicked, _rozieProp_onRegionCreated, _rozieProp_onRegionIn, _rozieProp_onRegionOut, _rozieProp_onRegionRemoved, _rozieProp_onRegionUpdated, _rozieProp_onSeeking, _rozieProp_onTimeupdate, props.autoplay, props.barGap, props.barRadius, props.barWidth, props.cursorColor, props.cursorWidth, props.disableDragToSeek, props.disableInteraction, props.dragToCreateRegions, props.height, props.hideScrollbar, props.hover, props.hoverColor, props.minPxPerSec, props.normalizeAmplitude, props.options, props.progressColor, props.regionColor, props.src, props.timeline, props.waveColor, reconcileRegions, regions, serializeRegion, setCurrentTime, writeBackRegions]);
+  }, [_rozieProp_onError, _rozieProp_onFinished, _rozieProp_onInteraction, _rozieProp_onLoading, _rozieProp_onPaused, _rozieProp_onPlaying, _rozieProp_onReady, _rozieProp_onRegionClicked, _rozieProp_onRegionCreated, _rozieProp_onRegionIn, _rozieProp_onRegionOut, _rozieProp_onRegionRemoved, _rozieProp_onRegionUpdated, _rozieProp_onSeeking, _rozieProp_onTimeupdate, props.autoplay, props.barGap, props.barRadius, props.barWidth, props.cursorColor, props.cursorWidth, props.disableDragToSeek, props.disableInteraction, props.dragToCreateRegions, props.duration, props.height, props.hideScrollbar, props.hover, props.hoverColor, props.minPxPerSec, props.normalizeAmplitude, props.options, props.peaks, props.progressColor, props.regionColor, props.src, props.timeline, props.waveColor, reconcileRegions, regions, serializeRegion, setCurrentTime, writeBackRegions]);
   // ─── imperative handle (Phase 21 $expose) ────────────────────────────────────
   // Collision-clear across all six targets: canonical media verbs play/pause/
   // playPause kept (the emits were renamed playing/paused/finished to dodge ROZ121);

packages/ui/wavesurfer/packages/solid/README.md

@@ -36,6 +36,8 @@ export function Demo() {
 | Name | Type | Default | Two-way (model) | Required |
 | --- | --- | --- | :---: | :---: |
 | `src` | `String` | `null` |  |  |
+| `peaks` | `unknown` | `undefined` |  |  |
+| `duration` | `Number` | `null` |  |  |
 | `height` | `Number` | `128` |  |  |
 | `waveColor` | `String` | `"#8a2be2"` |  |  |
 | `progressColor` | `String` | `"#5a189a"` |  |  |