WebMCP Surface Capture Registry — every green Human-approved surface becomes a permanent visual reference

[BryanHarrisScripts]

Why

Recent Human UAT found visual regressions on previously accepted PlotPickle surfaces even though architecture and live browser checks were green. The gap is that Human approval is not yet converted into a permanent visual reference set.

A surface should not be considered fully green if WebMCP/visual verification does not retain and re-check that approved presentation afterward.

Product rule

Every Human-approved green surface must be registered in the WebMCP / visual verification system and captured as durable reference evidence.

Green means:

1. implementation exists and is wired;
2. focused tests pass;
3. live Human UAT approves the surface;
4. WebMCP captures the approved surface/state;
5. future visual verification compares against or explicitly validates that approved reference contract.

Yellow surfaces remain active/testable but must not become canonical visual references until Human approval.

Registry requirements

Create one canonical registry/inventory for approved surfaces. Each entry should include at minimum:

• stable surface ID;
• Human-facing name;
• deterministic navigation path / activation sequence;
• selector proving the intended surface is open;
• expected approved state needed for capture;
• reference image/evidence location;
• approval issue/PR provenance;
• keyboard/back-path expectations where relevant;
• whether the surface is responsive/has more than one required viewport capture.

Do not encode transient profile names, private project content, local paths, credentials, timestamps or machine-specific values into the reference contract.

Capture behavior

• WebMCP should navigate to every registered green surface from the authenticated PlotPickle boundary.
• Capture named screenshots/evidence using stable filenames/IDs.
• Verify the correct destination is visible before capture.
• Fail clearly when a registered surface can no longer be reached, renders the wrong skin, loses required artwork, regresses typography/layout/state semantics, or returns through the wrong navigation path.
• Avoid fragile full-pixel equality where dynamic content exists; prefer stable visual/semantic contracts plus targeted screenshots for Human comparison.
• Keep current status truth live: connected/review/unwired colors must not be faked for screenshots.

Initial surface inventory

At minimum seed the registry from current accepted/reviewed Skin V1 surfaces:

• Dashboard
• Community
• Writer's Craft / Journey
• Story Library
• User Profile
• Settings directory
• Local Story Mode
• Cloud Story Mode
• Agents
• Advanced
• Issue Log
• Licensing
• Node Info

As #2029 repairs are Human-approved, add their exact approved states to this registry rather than relying on historic screenshots.

Workflow integration

When a Human promotes a surface from yellow to green:

1. update/add the surface registry entry;
2. capture the approved reference through WebMCP;
3. store/link the evidence in the repo artifact/reference convention;
4. add/enable the recurring visual check;
5. only then complete the green promotion issue.

A later visual redesign must deliberately replace the approved reference rather than silently drifting it.

Architecture / CI intent

This is not a new UI skin. It extends the existing Experience Skins / WebMCP visual readiness process so approved visual continuity becomes persistent product evidence.

Use the existing WebMCP surface readiness, visual director, visual audit and artifact pipeline where possible rather than adding a parallel screenshot system.

Acceptance

• canonical approved-surface registry exists;
• deterministic WebMCP navigation/capture supports every registered surface;
• approved evidence is named and discoverable;
• missing/unreachable/wrong-skin regressions fail the Experience gate;
• promotion guidance explicitly requires capture when yellow becomes green;
• Post-#2026 visual UAT regressions — restore dragon, simplify Writer's Craft return, profile status layout, and Skin V1 surface consistency #2029 repaired surfaces are added as the first expanded reference set after Human approval;
• exact-head seven-layer Architecture Verification passes.

[BryanHarrisScripts]

Evidence from local WebMCP run — 2026-09-13

Bryan ran the current WebMCP flow locally after #2029/#2031 merged.

Result:

• WebMCP Surface Visual UAT passed.
• UI conformance passed: 206 governed rendered elements across 8 surfaces, 0 violations.
• Visual Director compared 7 surfaces against Dashboard: 0 blockers, 0 advisories.
• 8 surface candidates were captured: Dashboard, Community, Settings, Cloud Story Mode, PlotPickle Agents, Profile, Local Story Mode, Node.
• 0 locked baselines were enforced.
• The runner already emits explicit Human-promotion commands such as node scripts/lock-skin-visual-baseline.mjs dashboard.
• Locking copies the approved candidate into tests/visual-baselines/skin-v1/<surface>.png and updates tests/visual-baselines/skin-v1/manifest.json.

This is important evidence for #2030: much of the capture/lock mechanism already exists. The remaining work should focus on making the Human approval -> lock -> commit -> recurring enforcement lifecycle canonical and discoverable, rather than building a second screenshot system.

Do not auto-lock all eight candidates. A candidate becomes a permanent baseline only after Bryan visually approves that exact surface. This preserves the rule that PlotPickle cannot bless its own regressions.

Recommended #2030 implementation focus:

1. treat the existing candidate capture + lock-skin-visual-baseline.mjs mechanism as the foundation;
2. add/confirm one canonical registry tying stable surface IDs to navigation/capture expectations and baseline state;
3. make Human green-light promotion require the matching lock command and committed PNG/manifest change;
4. have Experience/WebMCP gates enforce every locked baseline on future exact-head runs;
5. keep yellow/in-review surfaces captured but unlocked until explicit Human approval;
6. expand the registry as additional approved surfaces are reached, rather than auto-promoting candidates.

Current state after this run: capture infrastructure healthy; no baselines should be considered Human-approved merely because the run passed.

[BryanHarrisScripts]

Implementation scope update after #2046/#2049/#2050: #2030 will expand the current 8 historical WebMCP candidates to every currently reachable, Human-approved Skin V1 standard surface: Dashboard, Community, Writer's Craft, Identity/Profile, Manage/Settings, General, Local Story Mode, Cloud Story Mode, Node Info, Agents, Bug Report/Issue Log, and Notices/Licensing. Advanced is no longer a separate destination after the Settings consolidation; its retained content lives inside General. Library remains visibly present on Dashboard but is still marked unwired, so #2030 will not fake it as a reachable/approved Skin V1 capture target. The registry will preserve that live truth. Existing candidate→Human approval→lock→commit behavior remains; no screenshots will be auto-blessed.

[BryanHarrisScripts]

Infrastructure pass merged in #2052 at 7e2ca827bc439cf72c7463dc34089eb11f65da1c after all seven Architecture Verification layers passed, including live Layer 1 WebMCP. Local WebMCP testing now captures the 12 current standard Skin V1 candidates: Dashboard, Community, Writer's Craft, Identity, Manage, General, Local Story Mode, Cloud Story Mode, Node Info, Agents, Bug Report, and Notices. Library remains intentionally excluded while unwired; Advanced remains folded into General. No baseline was auto-locked. Final #2030 closeout remains the Human visual scan/approval + explicit lock/commit step.

[BryanHarrisScripts]

Human review of the 12-candidate catalogue identified one remaining visual-continuity issue: subordinate surfaces had inconsistent outer widths and return/header strips. #2053 fixed this as a CSS-only standard-shell pass and merged at 746bf75e0aa17bff6cf61053d8f6c5b8c047087c after all seven Architecture Verification layers passed, including live Layer 1 WebMCP. #2030 is intentionally reopened until Bryan reruns WebMCP locally, visually approves the refreshed 12 candidates, and explicitly locks/commits the approved baselines. Current registry still represents every connected Human-approved standard root surface: Dashboard, Community, Writer's Craft, Identity, Manage, General, Local Story Mode, Cloud Story Mode, Node Info, Agents, Bug Report, Notices. Unwired Dashboard destinations remain excluded; Log Off is an action; Advanced is folded into General; nested/transient sub-states are not separate canonical surfaces unless promoted later.

[BryanHarrisScripts]

Final closeout complete. Human-approved refreshed WebMCP catalogue is now locked as the official 12-surface Skin V1 baseline set via #2060. Canonical baseline PNGs are committed under tests/visual-baselines/skin-v1/, all 12 manifest entries are locked, temporary candidate copies were removed, and exact-head seven-layer Architecture Verification passed before merge. Merge commit: 8ec2ed23e766d9ac05350f2933b7bf5c927c464f.