Run the Mermaid browser pass and security probes #529

Part of #521. Depends on #528. Read the tracker first: its §Shared contract binds this issue. Work on main.

Summary

Prove the feature in real browsers, in all seven themes and on both phone engines. Then run nine hostile inputs against the webapp and the bare package. A code change happens only to fix a failed row.

Rulings: 2, 4, 10, 14 (#521 §Maintainer rulings).

Files and interfaces

Files (gitignored, under REPO/Notes/local-docs/)

• Create: <run date>-mermaid-ship-check.md with the sections ## Measure and release gates, ## Browser matrix, ## Security probes, ## Type sweep, ## Quality pass, ## Doc audit, ## check:ci verdict and ## Owed to the maintainer. Each row is check | PASS/FAIL | evidence.
• Create: mermaid-ship-check/browser.ts (the Playwright row runner), mermaid-ship-check/mermaid-qa.html (the pad fixture), mermaid-ship-check/types.json (one source per diagram type), and its screenshots.

Implementation steps

• Step 1: Start clean.

  • bun run build in PKG. Remove REPO/apps/webapp/.next/cache. Run make dev-local in the background. Store the webapp port from its Local: http://localhost:<port> line as APP_URL. curl -s -o /dev/null -w '%{http_code}' "$APP_URL/" prints 200.
  • In the test tab, unregister every service worker (navigator.serviceWorker.getRegistrations()), then hard-refresh.
  • Note: dev uses Turbopack's chunk loader. The production webpack loader is checked by offline-prod (Step 5).

• Step 2: Fill ## Measure and release gates by citing four results. They are the D10 verdict and the starter row p95 (the Measure Pele render time on a phone and set the default diagram limits #522 comment), the CJS verdict and the pack list (Register extension-mermaid as the sixth family package #527), and the D6 proof (Draw Mermaid diagrams in the pad, history and /editor #528). Run the Mermaid quality pass and ship gates #530 adds the make build-prod-ci row.

• Step 3: Write and load the fixture. mermaid-qa.html holds an <h1>, 40 filler paragraphs of about 60 words each (so no diagram is near the first screen), then one <h2> per block, each followed by <pre><code class="language-…">: Flowchart (nested subgraphs), Pie (8 slices), Gantt (fixed dates, one crit task), Sequence, Broken (flowchart TD / A --), Accessible (accTitle and accDescr), Wide (flowchart LR with six nodes), and Plain (language-js).

  • Open $APP_URL/mermaid-qa. Check that .ProseMirror[contenteditable="true"] exists while signed out. If not, every typing row runs signed in: browser.ts uses applyActorSession, and Chrome uses the maintainer's existing session.
  • Load the fixture with Meta+a and a synthetic ClipboardEvent('paste') carrying it as text/html. Expect 7 .mermaid-diagram and 1 plain pre. Read the editor as document.querySelector('.ProseMirror').editor.

• Step 4: Run the desktop matrix in Claude in Chrome at 1280×800, theme docsplus. Before judging a row, check document.visibilityState === 'visible'.

  Check	Pass criterion
  Ready	Scroll each block into view. Each valid block reaches ready with one svg.pele; Broken reaches error; Plain has no wrapper.
  Name	Flowchart's SVG has aria-label="flowchart diagram". Accessible keeps aria-labelledby, aria-describedby, <title> and <desc>, and has no aria-label.
  Sanitize keeps attrs	The root svg.pele keeps role, aria-roledescription, class and style (D8).
  No live regions	.ProseMirror holds no [aria-live], [role=status], [role=alert] or output.
  Undo after load	Reload, scroll each block into view, wait until all 7 are ready or error, and save the JSON. Mod-z leaves the JSON unchanged (no dispatch).
  Empty	Deleting a block's text gives empty, an empty diagram host, and the hint "Write a Mermaid diagram" inside the pre box (screenshot).
  Slash	/diagram and /mermaid each list one "Diagram" item. Enter inserts the starter, and a typed x lands at the end of the source. Inside Plain, typing / opens no menu (the slash menu never opens in code).
  Code select state	In Flowchart, only "Diagram" is checked and the trigger shows the diagram icon. In Plain, only "Code block" is checked.
  Code select actions	"Code block" on Flowchart gives a code block with language: null and the same text; undo restores the diagram. "Diagram" in Plain changes nothing.
  Fold	Folding Flowchart hides its frame. Unfolding shows ready, with no error line.
  TOC rail clone	With the rail committed (sash below 240px), hover the Flowchart tick. The clone holds no .pele-zoom and no error line; svg.pele has tabindex="-1"; no id remains under .mermaid-diagram; the arrowheads draw.
  /editor	A pasted mermaid fence reaches ready (D2).
  Chat	A mermaid fence in a chat message stays a plain code block.
  Pop-in	Scroll to a diagram far down the pad. Record whether it pops in or the content shifts. Record only; this row does not gate.
  Full-doc copy and paste	Meta+a. Dispatch a ClipboardEvent('copy') with a fresh DataTransfer, then a ClipboardEvent('paste') with that same DataTransfer (AGENTS.md:112 asks for a full-document paste check). Still 7 diagrams; no .ProseMirror p holds a default-view string; text/html holds no <svg.
  Source fold	At rest only the mermaid label shows. Hover swaps it in place for Syntax, Copy and Hide source. Copy puts the source on the clipboard and shows a check for 2.2 s. Hide source folds it smoothly; reload keeps it folded. ArrowDown into the folded block opens it. Syntax opens the Mermaid guide in a new tab. On #history and for a signed-out visitor of a read-only pad, blocks start folded. With reduced motion on, nothing animates.
  Exit and entry keys	ArrowDown at the end and Mod-Enter leave the block. ArrowUp from the paragraph below lands in the last source line, and a typed x changes the source.
  Themes	Switch with data-theme on <html> through docsplus, docsplus-dark, docsplus-dark-hc, docsplus-graphite, docsplus-graphite-dark, docsplus-paper and docsplus-paper-dark. For each, screenshot Flowchart, Pie and Broken. The frame border shows, the SVG ink reads on its background, the error line reads, and Pie keeps Pele's default colours (D4).

• Step 5: Write and run browser.ts.

  • Imports: chromium, webkit and devices from REPO/packages/document-swarm/node_modules/playwright/index.mjs; applyActorSession from REPO/packages/document-swarm/src/actors/sessionInject.ts; readActorsFile from REPO/packages/document-swarm/src/actors/loadActors.ts, called with REPO/packages/document-swarm/actors.json. A null result means "provision first": run bun run --filter @docs.plus/document-swarm provision --count 20 once.
  • It reads APP_URL (exit 1 when unset), runs each named row (all rows when none), gives each row a fresh context, and prints ROW <name> PASS|FAIL <detail>. Timing rows measure inside the page. A pageerror event fails the row, and the row detail prints its message, so an app error can be told apart from a diagram failure. Any row that renders a Gantt calls page.clock.setFixedTime(Date.UTC(2026, 9, 1)) before loading.
  • Run: cd REPO && APP_URL=<APP_URL> bun --env-file=.env.local Notes/local-docs/mermaid-ship-check/browser.ts.

  Row	Setup	Pass criterion
  type-race	chromium, desktop, cold context	First record the class-diagram chunk URL in a throwaway context. Hold that request with page.route (do not continue it yet). Replace Flowchart's text with `classDiagram\n A <
  mobile	run twice: webkit with devices['iPhone 13'], chromium with devices['Pixel 7']	html.m_mobile exists; (pointer: coarse) matches; no .pele-zoom; the page scrolls over a diagram; Wide's viewBox is taller than wide (D9); /diagram, Enter and x give a ready block with x at the end. Screenshots under docsplus and docsplus-dark pass the Themes rule.
  offline	chromium, cold context	First, in a separate throwaway context, load once online and record the Pele chunk URL pattern. Load at the top: no request matches the pattern yet, no .mermaid-diagram intersects the viewport, and 7 loading views. Go offline and scroll to Flowchart: "Could not load the diagram renderer." and "Try again"; one framenavigated only; one [observability] mermaid:load-error console line (requires an empty NEXT_PUBLIC_GLITCHTIP_DSN). Dev runs Turbopack, which caches a failed chunk for the life of the page, so Try again recovery is not checked here: offline-prod checks it.
  print	Scroll Flowchart and Broken into view and wait for ready and error first. Then emulateMedia({ media: 'print' })	Flowchart shows its diagram unclipped, with the pre hidden. Broken shows its pre, with the view hidden. Every .pele-zoom is hidden.
  collab	two chromium contexts, A and B	Simultaneous typing in Flowchart keeps both texts in both tabs. When B stops on a broken edit, A shows no error at +900 ms and shows it by +1500 ms, wherever A's caret is (A1).
  history-restore	signed in	Setup: type the Broken source into a block, wait 15 s idle, and confirm that #history lists a new version. Then #history shows ready diagrams (D2), and restoring that version leaves the pad editable within 2 s.
  history-visitor	signed out	#history renders the diagrams, and no Restore control exists (restore is signed-in only).
  types	chromium, $APP_URL/mermaid-types	Each of the 33 types from pele/dist/detect.d.ts (pele.run examples, or the Mermaid docs where pele.run has none) reaches ready, or error with its message printed. Save one full-page screenshot.

  • Production loader rows (offline-prod). Dev uses Turbopack; production uses webpack, which retries a failed chunk. Stop make dev-local, and start make dev-backend in the background, so REST and the collaboration socket stay up for the pad.
    • Build with the Draw Mermaid diagrams in the pad, history and /editor #528 build:ci command. Then, from REPO/apps/webapp, run cp -r .next/static .next/standalone/apps/webapp/.next/static && cp -r public .next/standalone/apps/webapp/public, and start PORT=3100 bun run start in the background.
    • From REPO: APP_URL=http://localhost:3100 bun --env-file=.env.local Notes/local-docs/mermaid-ship-check/browser.ts offline-prod. browser.ts creates this row's context with serviceWorkers: 'block', so the service worker cannot serve chunks. The row opens $APP_URL/mermaid-qa.
    • offline-prod passes when: offline shows "Could not load the diagram renderer."; going online and clicking Try again reaches ready. Then, with Flowchart drawn, go offline and change it to classDiagram\n A <|-- B (a type absent from the fixture): load-error and one framenavigated only; online and Try again draws the class diagram.
    • Under Add the extension-mermaid playground and clean-room Cypress suite #525 Result B or C, prove S5 here (and S4 under Result C) with the sabotage form across calls: back up the file, apply the change, rebuild PKG, repeat the build, copy and start lines, and run offline-prod. S5 must fail at Try again. S4 must fail the row, by a page reload or a page error. Restore the file, check cmp, then rebuild both.
    • Afterwards stop the 3100 server and make dev-backend, and run rm -rf REPO/apps/webapp/.next and rm -f REPO/apps/webapp/public/sw.js REPO/apps/webapp/public/workbox-*.js REPO/apps/webapp/public/worker-*.js. Then rerun Step 1.
  • Harness limits, recorded as limits and added to Owed: WebKit not installed (skip the iOS run; install nothing); a mobile row where (pointer: coarse) does not match.

• Step 6: Run the security probes as two more browser.ts rows: probes on $APP_URL/mermaid-qa (with sanitizeDiagramSvg), and probes-playground on http://127.0.0.1:5178 (package default sanitize: null; start the playground first and stop it after). Each row sets every source as a mermaid fence and logs any request to beacon.invalid.

  Probe	Source
  H1 classDef url	flowchart LR\n A --> B\n classDef evil fill:url(https://beacon.invalid/h1),stroke:#f00\n class A evil
  H2 style url and filter	flowchart LR\n A --> B\n style A fill:url(https://beacon.invalid/h2),filter:url(https://beacon.invalid/h2f)
  H3 @import	flowchart LR\n A --> B\n classDef evil fill:#fff;@import url(https://beacon.invalid/h3)\n class A evil
  H4 init fontFamily	%%{init: {"fontFamily": "x;}</style><script>window.__pwned=4</script><style>"}}%%\nflowchart LR\n A --> B
  H5 init themeCSS	%%{init: {"themeCSS": "@import url(https://beacon.invalid/h5); .node{fill:url(https://beacon.invalid/h5b)}"}}%%\nflowchart LR\n A --> B
  H6 frontmatter config	---\nconfig:\n themeCSS: "@import url(https://beacon.invalid/h6);"\n fontFamily: "x</style><script>window.__pwned=6</script>"\n---\nflowchart LR\n A --> B
  H7 script text in labels	flowchart LR\n A["<script>window.__pwned=7</script>"] --> B["<img src=x onerror=window.__pwned=7>"]
  H8 script text in a message	sequenceDiagram\n A->>B: <script>window.__pwned=8</script>
  H9 link	flowchart LR\n A --> B\n click A "javascript:window.__pwned=9"

  • Check through the DOM, never by regex on serialized markup.
  • Pass needs: 0 requests to beacon.invalid; window.__pwned === undefined 500 ms after the last probe; no .ProseMirror script and no [onerror]; no a[href^="javascript:"] in a diagram host; no style attribute or <style> text in a diagram host matching /url\(\s*['"]?(?!#)/ or /@import/i; the editor and the toolbar still visible.
  • Record H6's effect beside the docs/security.md frontmatter claim.
  • Any probes FAIL blocks the ship: record it and stop. The fix (stripping url() in sanitizeDiagramSvg) waits for the maintainer.
  • A probes-playground FAIL that docs/security.md already names as a default risk is not a blocker. Otherwise it is a doc defect for Run the Mermaid quality pass and ship gates #530.

• Step 7: Fix failed rows. Fix each FAIL in the file that owns the behaviour, with the smallest change. Then rebuild (Step 1), rerun that row plus type-race, and run bun run test in PKG. A fix that needs a new option, token or a change to [Tracking] Mermaid diagrams in docs.plus through a headless Pele extension #521 §Design is a design change: record it and stop.

• Step 8: Review checkpoint. Report the matrix, the browser.ts rows, both probe rows and the type sweep.

Decisions

• R5. Should we keep the aria-label fallback? Recommended: yes, unless VoiceOver and NVDA both read the type twice (aria-roledescription plus aria-label). The maintainer checks. Dropping it reopens Add the Mermaid renderer, default view, styles and node view #524 and Add the extension-mermaid playground and clean-room Cypress suite #525 case 1.

Acceptance criteria

• Every Step 4 row and every browser.ts row passes, or is a recorded harness limit.
• probes has no FAIL. Any probes FAIL blocks the ship.