iter-2 revision of Plan 04-08 (video-file MediaStream methodology reframe)
addressing the 2 BLOCKERs + 5 WARNINGs + 3 advisories from plan-checker
iter-1 (commit 051813e, .planning/phases/04-harden-clean-up-optional/04-08-CHECKER-iter-1.md).
BLOCKER 1 (Vite ?url asset emission for >=1 MB WebM): pre-decide the
bundling strategy. The 1.9 MB WebM is three orders of magnitude above
Vite's assetsInlineLimit (4096); it follows the extracted-asset path
(dist-test/assets/<hash>.webm), not the data-URI-inline path the
Plan 01-10 SVG precedent uses. The @crxjs/vite-plugin auto-WAR
behavior for extracted media assets in offscreen-document context is
empirically untested in this codebase. Resolution: add an explicit
web_accessible_resources entry for assets/*.webm in manifest.json
alongside the existing src/welcome/welcome.html entry. Production
dist/ has zero *.webm assets so the entry is inert; test dist-test/
has the hashed asset and the entry authorizes chrome-extension://<id>/
assets/<hash>.webm URL access from the offscreen document context.
No executor improvisation; the bundling strategy is locked-in BEFORE
Task 1 begins.
BLOCKER 2 (installFakeDisplayMedia async conversion breaks eager-install
contract): preserve the SYNCHRONOUS function signature. The existing
eager call at src/test-hooks/offscreen-hooks.ts:528-537 + the top-
level await at src/offscreen/recorder.ts:46-48 establish a contract
that navigator.mediaDevices.getDisplayMedia is monkey-patched BEFORE
recorder.bootstrap runs. Converting installFakeDisplayMedia() to
async would create a race window where recorder.startRecording calls
the REAL getDisplayMedia (Chrome screen-share picker hangs in
headless). Resolution: SYNC install (videoEl creation + DOM append +
monkey-patch assignment) + LAZY first-frame closure (await readyState
HAVE_FUTURE_DATA + .play() deferred INTO fakeGetDisplayMedia body).
First getDisplayMedia call may block ~50-500ms while video decodes;
subsequent calls observe the resolved readiness Promise + proceed
immediately. Bridge handler + eager-install try/catch remain sync.
WARNING 1 (autoplay reliability): explicit error class identifier
('autoplay-blocked or codec-unsupported in headless context') in the
.play() reject path; spike surface root cause instead of mysterious
0-frames.
WARNING 2 (patchDisplaySurface compatibility): new sub-gate in Task 1
verify that mints a stream + asserts track.getSettings().displaySurface
=== 'monitor'. Optional executor implementation as a --check-display-
surface-only mode on the spike script; spike re-run is the fallback
high-latency catch.
WARNING 3 (spike probe-value asserts): surfaced as explicit grep gates
in Task 2 verify block. POST-PRIME=0, PRE-KILL>=3, POST-KILL>=3 per
debug session-2 baseline.
WARNING 4 (ROADMAP.md edit): pre-specified exact pre-edit string +
replacement + grep gate (CLOSED via Plan 04-08 must appear; STATUS
2026-05-21: OPEN must disappear).
WARNING 5 (synthetic-display-source filename leak): new Tier-2 sub-
invariant in tests/background/no-test-hooks-in-prod-bundle.test.ts;
catches accidental test-hook inlining into production chunk. Tier-1
inventory at 12 entries unchanged.
advisory 1: commit message corrected to reference Task 1 + Task 2
only (not Task 3, which doesn't exist).
advisory 2: src/offscreen/recorder.ts:91 segments invariant added as
grep gate in Task 1 verify block.
advisory 3: dual-location fixture note added to Task 1 Step 1 (the
original tests/fixtures/last_30sec.webm remains in place; the new
tests/uat/fixtures/synthetic-display-source.webm is a SECOND copy
under the UAT subtree).
Plan validates via gsd-sdk frontmatter.validate --schema plan (valid:
true, no missing fields) AND gsd-sdk verify.plan-structure (valid:
true, 0 errors, 0 warnings, 2 tasks with full 4-element shapes).
files_modified updated to include tests/background/no-test-hooks-in-
prod-bundle.test.ts (Tier-2 gate location).
Iter-2 architectural thesis unchanged: HTMLVideoElement.captureStream
bypasses the canvas-throttling root cause per debug session-2 verdict.
The revision is methodology-tightening, not re-architecture.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
