iter-3 polish pass on Plan 04-08 per checker iter-2 verdict PASSED
(commit 9c334b7). Five cosmetic-level fixes; no thesis/scope changes;
BLOCKER fixes from iter-2 + WARNING fixes from iter-2 preserved verbatim.
Remediations:
- WARNING 1 (low-severity; displaySurface sub-gate scope ambiguity):
HIGH-LATENCY catch path locked in; the under-specified
`--check-display-surface-only` spike-script mode is dropped (would have
required 5-10 LOC of executor improvisation for no meaningful latency
win over the canonical spike re-run's assertA2 fast-fail at <30s).
- Advisory 1 (symbol-name mismatch): Tier-2 snippet's `collectDistFiles`
replaced with the actual helper `listAllFilesRecursive(DIST_DIR)` from
tests/background/no-test-hooks-in-prod-bundle.test.ts:152; also uses
the existing `countOccurrencesInFile` for binary-extension-aware grep.
- Advisory 2 (SUMMARY-write practice for WARNING 1): explicit note added
that 04-08-SUMMARY.md documents the WARNING 1 closure path (no Plan B
fallback; explicit error-class identifier; observable via offscreen
console capture).
- Advisory 3 (vitest math): 183 -> 184 clarified consistently across
must_haves truth + Step 5 body + acceptance_criteria + verification +
success_criteria (+1 from the new Tier-2 `test(...)` block).
- Advisory 4 (duration-N/A rationale): moved out of the PLAN body into
the SUMMARY content list (Step 6); PLAN keeps only the load-bearing
size gate + loop-attr behavioral assertion + spike-re-run empirical
catch; 1.9 MB / ~400 kbps / ~38s decoded-timeline reasoning lands at
SUMMARY-time.
Frontmatter:
- Added iter-2 entry to revision_history (iter-3 polish closure).
- Tag flipped planner-iter-2-revision -> planner-iter-3-revision.
Plan validates via gsd-sdk frontmatter.validate + verify.plan-structure:
- valid: true; 0 errors; 0 warnings; 2 tasks; all 4 task elements present.
Diff: +51/-22 lines (5640 chars net). Branch ready for plan-checker
iter-3 (cosmetic-only polish review expected to PASS without further
findings).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
