feat: complete Web Component migration — Phases 1–7, CI, and v1.0.1 hardening

[fan-droide]

Summary

This PR brings the full webcomponent branch to main. It covers the complete migration from the original proof-of-concept to a published, hardened npm package — Phases 1 through 7 plus post-publication quality work.

---

Phase 1–3 — Component architecture

• Refactored TestLatencyMLS from static singleton to instance-based LatencyTestController
• Created <latency-test> Custom Element with Shadow DOM, start()/stop() methods, and six lifecycle events
• Implemented recording-mode="audioworklet" — dual-channel AudioWorklet processor capturing mic + reference PCM simultaneously, eliminating JS start-timing bias
• Added debug attribute for console.debug logging at internal checkpoints
• Added guard: recording-mode="mediarecorder-2ch" emits latency-error (Phase 3b placeholder)

Phase 4 — Demo and session model

• Rewrote demo as a tabbed multi-pattern showcase (Minimal, Multi-Run, Context Share, Mode Toggle, Lifecycle, Debug, Host Gain)
• Demo owns the audio session: getUserMedia + AudioContext created once behind a Connect Audio button; shared across all tabs
• Host Gain tab: ChannelSplitter → GainNode → MediaStreamDestination chain with bypass toggle
• Dev test pages moved to src/dev-test/; src/index.html becomes a navigation hub

Phase 5 — Build pipeline

• esbuild-based build script with plugin that inlines worker.js and recorder-processor.js as Blob URLs
• ESM (dist/latency-test.esm.js) + IIFE (dist/latency-test.iife.js) outputs with source maps
• cleanDist() fixed for fresh CI runners (was crashing with ENOENT on missing dist/)
• Pages CI updated to copy demo/ and dist/ into the VitePress output artifact

Phase 6 — Documentation

• Full VitePress docs site: API reference, install guide, six framework examples (Vanilla JS, React, Vue, Svelte, Angular, Next.js), host-gain example
• Unit tests: tests/mls.test.js + tests/worker.test.js using node:test, Node 18.12.1

Phase 7 — npm publication (@adasp/latency-test@1.0.0)

• Package scope: @hi-audio → @adasp across all files
• src/index.d.ts: full TypeScript declarations (LatencyTestElement, LatencyTestEventMap, all detail interfaces)
• package.json: types, exports.types, prepublishOnly, publishConfig, engines fields added
• All Draft/unpublished notices removed from docs and framework examples
• Published @adasp/latency-test@1.0.0 — live on npm, jsDelivr, unpkg

v1.0.1 — Truth and hardening patch

• Runtime: worker errors now routed via onError with !stopped guard; start() catch block resets state and cleans up stream/controller; public property class field defaults added
• Types: signalType narrowed to 'mls'; duplicate inputGain removed; JSDoc caveats on inputGain and mediarecorder-2ch; aborted?, bufferSize added
• Docs: "Multiple Signal Types" → "MLS-Based Measurement"; Mode Toggle latency-complete payload bug fixed; framework TypeScript sections use published import pattern

CI

• .github/workflows/ci.yml: runs npm test → build:component → docs:build → pack --dry-run on every push and PR targeting main; concurrency group cancels redundant runs
• agents/KNOWN_ISSUES.md: running log of deferred review findings (TypeScript CI check, branch protection, CDN pinning, framework verification, Firefox dev-test issue)

Test plan

• npm test passes
• npm run build:component passes
• npm pack --dry-run — 8 files including dist/index.d.ts
• @adasp/latency-test@1.0.0 and @1.0.1 confirmed live on npm
• jsDelivr and unpkg CDN URLs confirmed live
• CI workflow running on branch
• Browser verification matrix — Chrome / Firefox / Safari (gates Phase 3b, separate task)
• Framework examples end-to-end verification against published package (gates Phase 6 completion)

🤖 Generated with Claude Code