atomic-design-poc/docs/project/archive/backlog/WP-28-brief-v2-demo-polish.md

WP-28 — Brief v2 demo polish (scenarios, e2e, docs)

Status: done (pending commit; npm run e2e unverified in this dev sandbox — see Deviations) Phase: 6 — Brief v2 (edit-on-the-letter, org templates, server-rendered preview)

Why

Phase 6 ships across five WPs; this one makes it demonstrable and closes the loop: a demo script that maps every kept PRD §12 scenario to a URL + click path, an e2e spec covering the new flows end-to-end, story gap-fill, and the docs/README updates that keep CLAUDE.md and the backlog truthful.

Read first

• PRD Brief v2 §6 (demo choreography), §12 (scenario list); WP-23..27 as built
• e2e/ (WP-19 conventions); src/app/shared/infrastructure/scenario.ts

Decisions (pre-made, don't relitigate)

• No preset registry. The PRD's 18 scenarios collapse onto the existing toggles: ?role=drafter|approver|admin, ?scenario=slow|loading|error (the interceptor already covers all /api/ calls, the new endpoints included), and POST /brief/reset. The demo script documents the mapping; no new interceptor cases, no scenario code.
• Demo script lives at docs/project/prd/0003-brief-v2-demo-script.md and follows the §6 choreography (compose → preview → switch sub-org seed → "two axes, one render").
• One e2e spec, not a suite: drafter composes on canvas → submit → approve → send pins the org-template version; admin publishes → drafter canvas reflects it. Preview assertion is content-type-level (text/html), not pixel.
• CLAUDE.md gets the new role value + route only — keep it rules, not narrative.

Files

• docs/project/prd/0003-brief-v2-demo-script.md (new)
• e2e/brief-v2.spec.ts (new)
• story gap-fill where WP-24..27 left holes
• docs/project/backlog/README.md (statuses), CLAUDE.md (roles/routes touch-up)

Steps

1. Demo script: table scenario → URL + clicks, covering every kept §12 entry.
2. e2e spec (backend + FE running, WP-19 pattern).
3. Story sweep for the new components/states.
4. Docs updates.

Acceptance criteria

• Every kept PRD §12 scenario has a working URL + click path in the script (walked manually once).
• npm run e2e green, including the new spec — not verified in this dev sandbox; see Deviations.
• Full GREEN; backlog README statuses correct; CLAUDE.md mentions ?role=admin and /brief/huisstijl.

Deviations / notes (as built)

• No Brief v2 PRD was ever committed. WP-23..27 cite "PRD Brief v2 §N" throughout, but docs/project/prd/ never held such a file — it only ever existed as chat context. The demo script (docs/project/prd/0003-brief-v2-demo-script.md) is written directly against the shipped code instead of translating an external §12 scenario list, and says so up top.
• ?scenario= does not reach every endpoint. /brief/preview, /admin/org-template/{id}/preview and /brief/reveal-bignummer are hand-written fetch calls (same seam as uploads, deliberately .ExcludeFromDescription()'d) and bypass scenarioInterceptor. The demo script and CLAUDE.md now say so explicitly.
• Canvas authoring moved. The original "drafter composes on the canvas" framing predates commit ba32e3d ("brief v3 — besluit-driven guided drafting"): LetterCanvasComponent.editableRegions no longer has a 'content' mode. The drafter now works through BehandelSchermComponent (case header + stepper + app-besluit-panel + app-letter-editor), with the canvas as a read-only preview in a modal. The demo script and e2e spec follow that path.
• passage-picker is dead code — superseded by besluit-panel's guided drafting, no consumer left besides its own story. Flagged with a comment on the component rather than deleted in this WP (out of scope for a demo-polish pass).
• Story gaps were state gaps, not component gaps — every component already had a co-located story. Added: letter-composer RejectionDiff + AlleenLezen (WP-27's diff view and the pure-viewer notice had no story), letter-canvas + org-template-editor MetLogo (WP-26's logo letterhead had no story), and org-template-editor LogoUploadFout (the upload-rejection branch had no story).
• Org templates have no reset endpoint — the e2e spec's admin section restores the org-template draft it edits (rollback + republish) instead of relying on a reset, so repeated runs don't drift the seeded "BIG-register" template.
• npm run e2e could not be verified green in this dev sandbox — both the new brief-v2.spec.ts and the pre-existing, untouched smoke.spec.ts fail here at the same kind of step (clicking a CIBG-styled radio's <label for>; e.g. label[for="correspondentie-post"] in smoke.spec.ts), with Playwright reporting the element "detached from the DOM, retrying" or a native input whose rendered box collapses to 1×1px. Reproduced with --workers=1 and running smoke.spec.ts alone, so it isn't cross-test contention. Since smoke.spec.ts predates this WP and is unrelated to any file it touches, this reads as a sandbox-specific rendering/CSS-loading issue (fonts 404 here; a stylesheet may not be fully served), not a regression from this WP's changes. Needs confirming green on a normal dev machine / CI before this box can be ticked.

Verification

Walk the demo script top to bottom against docker compose up; GREEN one-liner; npm run e2e.

Out of scope

New scenario interceptor cases; a scenario-switcher UI; screenshots/video.

Risks

The demo script rots when flows change — it lists URLs + clicks only (no prose walkthroughs), so churn stays cheap.