dsh-live-voice-debugger 0.6.1 → 0.7.0

package/ARCHITECTURE.md

@@ -2,10 +2,24 @@
 
 This public, optional client plugin builds separately from Live Voice. It contributes an optional Developer tab inside the existing Live Voice Settings and opens a separate browser window containing the React inspector only after explicit activation. Its runtime boundaries are the versioned read-only diagnostic source and the recording service published by the main plugin, not coordinator imports. The Recordings tab is primary; the live state inspector remains a secondary tab. A conditional Runtimes tab appears after a browser ASR model load is attempted and retains failed/released attempts for diagnosis. It reads the same versioned source, never imports the manager or controls inference. It shows pinned model/precision/provider metadata, worker/protocol versions, bounded 100-entry lifecycle events, load/inference timings, counters and scoped memory/storage accounting. Cached file sizes are not model RAM/VRAM; page JS heap is optional/non-standard and excludes full workers/WASM/GPU memory. No raw ONNX console, audio or transcript is retained in runtime events. It supports either plugin load order and source replacement/removal.
 
-The panel samples current state at a selectable 1, 2, 5, 10 or 20 Hz (default 10). State and event panes scroll independently. Event recording can be paused independently from live state sampling and the entire event history can be cleared. Resuming recording starts from the current baseline without replaying changes that occurred while paused. Changing the sampling rate preserves the history. While connected, coordinator notifications produce a bounded 200-entry state-difference history filterable by module. This is an initial inspector, not a complete semantic event logger: changes hidden inside an adapter can only be sampled, and native recognition internals remain unavailable. The generic diagnostic history retains no audio. Free-form diagnostic text is hidden by default and can be inspected explicitly in memory, never persisted by this inspector. The separate Recordings view reads opt-in archived sessions from the main recorder, including their transcript history, and exposes explicit playback, export, star protection and confirmed deletion actions. A starred recording is excluded from automatic cleanup and retention counts, but may still be deleted manually; the star is not browser persistence permission or backup protection. Opening/inspecting never deletes or exports. Session playback URLs and subscriptions are released on replacement, closing or page hiding. Closing the panel releases subscriptions and timers.
+The panel samples current state at a selectable 1, 2, 5, 10 or 20 Hz (default 10). State and event panes scroll independently. Event recording can be paused independently from live state sampling and the entire event history can be cleared. Resuming recording starts from the current baseline without replaying changes that occurred while paused. Changing the sampling rate preserves the history. While connected, coordinator notifications produce a bounded 200-entry state-difference history filterable by module. This is an initial inspector, not a complete semantic event logger: changes hidden inside an adapter can only be sampled, and native recognition internals remain unavailable. The generic diagnostic history retains no audio. Free-form diagnostic text is hidden by default and can be inspected explicitly in memory, never persisted by this inspector. The separate Recordings view reads opt-in archived sessions from the main recorder, including their transcript history, and exposes explicit playback, export, star protection, starred-session naming and confirmed deletion actions. Optional additive name support keeps older v1 recording services inspectable. A separate event table and timeline markers show persisted assistant playback and capture events, retaining actual time when multiple events share the final captured boundary. A starred recording is excluded from automatic cleanup and retention counts, but may still be deleted manually; the star is not browser persistence permission or backup protection. Opening/inspecting never deletes or exports. Session playback URLs and subscriptions are released on replacement, closing or page hiding. Closing the panel releases subscriptions and timers.
+
+EventTimeline uses five labeled semantic lanes (waiting, playback, capture/listening, voice command, interruptions/issues) and distinct action glyphs. Nearby events in the same category group into viewport-width buckets with a count; every original timestamp remains in the list. Immediate hover/focus tooltips use a manual top-layer popover, clamp to the owning viewport, ignore all pointer events, reposition on scroll and dismiss on Escape/resize/blur/page hide, and preview up to five originals. Activation highlights all group rows and focuses the first; no tooltip control intercepts neighboring markers. Recognized-command speech is an orange view annotation based on exact segment IDs, never a VAD pin or an inferred legacy classification.
+
+A separate event-marker track and accessible timestamped event table display assistant waiting, changing wait reasons, playback requests, input-stop request/completion/failure, confirmed engine playback, cancellations and errors. It never turns these into speech/silence pins or collapses events sharing the final capture boundary into one event. Typed numeric/reason details contain no transcript.
+
+Attempt details show measured HTTP WAV request bytes, input/output samples/rates, encoded versus expected duration, preparation time, language and response status. Missing legacy metadata is unavailable, never reconstructed as if measured. The UI explicitly distinguishes prepared browser-to-DSH bodies from server receipt/model consumption.
+
+Segment rows provide localized icon-only play, exact-range WAV download, and optional speech retranscription. Retranscription uses the currently selected `qwen-http`, `whisper-http`, browser-local `whisper-browser` / `qwen-browser`, or native Browser SpeechRecognition engine with boundary context (minimum 800 ms). Browser-local models must be downloaded in Settings first; retry never downloads models or falls back to HTTP. Native retry is available only when safe external-audio-track support is verified, processes existing saved segments under the selected local/remote-processing and language-pack requirements, and never falls back to microphone capture. Native Browser live capture still does not record original speech. Retranscription requires finished capture and adds audit attempts without editing the composer or executing commands; older v1 services simply omit it. Selecting speech or silence in the timeline loads that exact segment in the shared player without autoplay; zoom never changes the selected audio range.
+
+The recording timeline has a single sample-clock track with two accessible slider handles and a draggable selected band for a non-destructive zoom window. Pointer capture supports mouse/touch/pen; keyboard arrows, Page Up/Down and Home/End resize or pan with clamped bounds. The icon-only reset has a localized title and accessible name; rendered segments and pins are clipped/remapped without changing stored ranges or playback. The end follows live growth until narrowed. Switching sessions resets the window. Transcript search ranks normalized exact text/phrases, whole and partial words, then bounded typo matches; only successful nonempty transcripts appear while a query is active, and clearing restores chronological segments. A prominent storage card always summarizes the full unfiltered list, session count and encoded-audio size. Unknown/invalid legacy counts produce an explicit measured lower bound, not zero or a discarded total. Loading/failure is not a known empty archive. Confirmed bulk removal snapshots eligible IDs across all sources (including stars), rechecks each before the existing service remove call, preserves active/pending sessions and reports removed/skipped/failed counts without claiming transaction-wide atomicity. New sessions never join a confirmed batch; service replacement, unmount or page hide stop future calls, not an already-dispatched removal. Cancel receives initial focus, Escape cancels before execution, and the result receives focus after completion. Detail playback/retries are released while clearing; invalid source filters reset after removal. No DSH conversation, exported file or future-capture setting is deleted.
+
+Totals, per-session sizes and deletion previews share one decimal-SI formatter (1 KB = 1,000 bytes), automatically selecting B/KB/MB/GB/TB and capping units at TB. It shows at most one fractional digit, no thousands grouping, and uses the explicit DSH UI locale (Portuguese decimal comma), not browser or speech language. Values rounding to 1000 promote to the next unit where available. Encoded audio size is not origin quota, JS memory or WAV export size; older services without byte counts show unavailable rather than zero.
 
 For normal use, install the prebuilt npm package with `npx dsh plugin add --profile web dsh-live-voice-debugger`. Generated `lib/` directories are ignored and never committed. For local development, build before linking: build from the repository root with `pnpm build`, or build this package with `pnpm --filter dsh-live-voice-debugger build`. The generated client/server entries land in lib, not in the main client bundle. For local installation, add the packages/live-voice-debugger directory as a separate DSH plugin using the supported plugin manager; both the main plugin's diagnostic bridge and this plugin must be loaded. Then open Settings → Live Voice → Developer and open the separate inspector window (allow site popups if blocked). Publication is explicit through the npm workflow. Configure npm Trusted Publishing for this package with workflow publish.yml and environment npm. Select the debugger-only target when the aligned main version already exists. Publishing both packages is sequential, not atomic.
 
 The `src/i18n` boundary uses `@wads.dev/i18n-ts` contracts and the isolated `@wads.dev/i18n-react` provider/hook. Commons, recordings and runtimes each own an alphabetized typed contract and one locale file for en, es, fr, hi, pt-BR and zh. Root locale modules compose those namespaces; `catalogs.ts` exports `Langs` with typed loaders. The package-level `i18n.config.json` maps one structural module level directly to those directories. Only `registerDshLocales.ts` flattens keys for the real DSH namespace API, registering languages/dictionaries with disposable effects. Both the settings launcher and popup use a DSH-locale boundary; no separate preference or browser locale overrides UI language. Switching locale keeps mounted inspector/recording state.
 
 Tests deliver simulated activity, processing and final results through the real coordinator callback boundary; PCM chunks are supplied through the HTTP adapter's fake Web Audio input. They assert the same diagnostic projection that the panel reads. The panel itself never injects test events into live capture or playback.
+
+Recording source identity remains visible in session lists, selected headers, segment rows and playback accessible labels, independently of a custom recording title. Optional version-1 participant metadata identifies Attendee sources without parsing composite source IDs. Capture-start original name and alias are historical snapshots; participant UUID and bot/group ID stay available in expandable identity details for duplicate-name disambiguation. Older microphone/shared sessions without metadata use the existing source fallback. Named source channels do not imply acoustic speaker isolation.