docs: interactive mermaid diagrams (render by default + source toggle + copy)#49
docs: interactive mermaid diagrams (render by default + source toggle + copy)#49riethmayer wants to merge 1 commit into
Conversation
The docs embedded mermaid as an ES module, which Chrome blocks from file:// origins (CORS) — so diagrams showed as raw text when the files are opened locally. Switch to the classic UMD mermaid build plus a classic enhancer script that renders reliably from both file:// and http. Each diagram now renders by default and gains a Diagram/Source toggle and a Copy-source button. Also corrects the deployer SA storage role on the security page to project-level storage.admin (what builds submit actually needs).
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
📝 WalkthroughWalkthroughThis PR adds a client-side diagram enhancement system for documentation pages. A new ChangesMermaid Diagram Enhancement System
Cloud Deployer Role Permissions
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
docs/deployment/assets/docs.jsOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON docs/deployment/assets/styles.cssOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/deployment/assets/docs.js`:
- Around line 135-144: The fallback() function currently calls done()
unconditionally even if document.execCommand("copy") fails; change it to capture
the return value of document.execCommand("copy") (or detect thrown exceptions)
and only call done() when copy succeeded, ensuring catch blocks and failure
branches do not call done(); keep selection cleanup (sel.removeAllRanges()) in a
finally-like path so selection is cleared regardless of success but success
callback is gated on the actual copy result.
In `@docs/deployment/assets/styles.css`:
- Around line 169-196: The new diagram toolbar CSS uses bespoke styles that must
be migrated to Tailwind utilities: replace rules for .diagram .cap, .dgm-bar,
.dgm-seg, .dgm-tab (including .dgm-tab.is-active and :hover state), .dgm-copy
(including .dgm-copy.ok and :hover), .dgm-graph, .dgm-source (and its code), and
the .dgm-tab + .dgm-tab sibling border with equivalent Tailwind classes and
utility composition in the markup; keep only minimal custom CSS for things
Tailwind cannot express (e.g., complex keyframes or non-standard CSS
custom-property logic), preserve the [hidden] { display: none !important; }
rule, and remove the duplicated styling block from styles.css so styling lives
as Tailwind utility classes and small exception CSS (if absolutely required) for
.dgm-source max-height/overflow or the left border radius.
In `@docs/deployment/index.html`:
- Line 143: The Mermaid script tag currently uses a floating tag
"https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"; update that tag
to pin an exact release (e.g., mermaid@11.x.y) and add SRI and crossorigin
attributes by replacing the existing <script
src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
occurrences with a tag that includes integrity="sha384-..." and
crossorigin="anonymous" (use the correct integrity hash for the chosen exact
version); make the same change for the identical script occurrences in the other
docs pages.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 43a458f2-6c54-4570-a7a5-bf0a18f06596
📒 Files selected for processing (7)
docs/deployment/assets/docs.jsdocs/deployment/assets/mermaid-init.jsdocs/deployment/assets/styles.cssdocs/deployment/index.htmldocs/deployment/pipeline.htmldocs/deployment/security.htmldocs/deployment/tradeoffs.html
💤 Files with no reviewable changes (1)
- docs/deployment/assets/mermaid-init.js
| function fallback() { | ||
| var range = document.createRange(); | ||
| range.selectNodeContents(code); | ||
| var sel = window.getSelection(); | ||
| sel.removeAllRanges(); | ||
| sel.addRange(range); | ||
| try { document.execCommand("copy"); } catch (e) { /* ignore */ } | ||
| sel.removeAllRanges(); | ||
| done(); | ||
| } |
There was a problem hiding this comment.
Avoid showing “Copied” when fallback copy fails.
done() is called unconditionally in the fallback path, so users can see success even if copy did not happen (Line 141). Gate success on actual copy result.
Proposed fix
function fallback() {
var range = document.createRange();
range.selectNodeContents(code);
var sel = window.getSelection();
- sel.removeAllRanges();
- sel.addRange(range);
- try { document.execCommand("copy"); } catch (e) { /* ignore */ }
- sel.removeAllRanges();
- done();
+ if (!sel) return;
+ sel.removeAllRanges();
+ sel.addRange(range);
+ var copied = false;
+ try { copied = document.execCommand("copy"); } catch (e) { copied = false; }
+ sel.removeAllRanges();
+ if (copied) done();
}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/deployment/assets/docs.js` around lines 135 - 144, The fallback()
function currently calls done() unconditionally even if
document.execCommand("copy") fails; change it to capture the return value of
document.execCommand("copy") (or detect thrown exceptions) and only call done()
when copy succeeded, ensuring catch blocks and failure branches do not call
done(); keep selection cleanup (sel.removeAllRanges()) in a finally-like path so
selection is cleared regardless of success but success callback is gated on the
actual copy result.
| /* Diagram toolbar — Diagram/Source toggle + copy ------------------------- */ | ||
| .diagram .cap { flex-wrap: wrap; } | ||
| .dgm-bar { display: inline-flex; align-items: center; gap: 8px; margin-left: auto; } | ||
| .dgm-seg { display: inline-flex; border: 1px solid var(--line-2); border-radius: 8px; overflow: hidden; } | ||
| .dgm-tab { | ||
| font-family: var(--mono); font-size: 11px; letter-spacing: 0.04em; text-transform: none; | ||
| padding: 5px 11px; background: transparent; color: var(--muted); border: 0; cursor: pointer; | ||
| transition: background .15s, color .15s; | ||
| } | ||
| .dgm-tab + .dgm-tab { border-left: 1px solid var(--line-2); } | ||
| .dgm-tab:not(.is-active):hover { color: var(--text); background: var(--ink-3); } | ||
| .dgm-tab.is-active { background: var(--signal); color: var(--ink); font-weight: 600; } | ||
| .dgm-copy { | ||
| font-family: var(--mono); font-size: 11px; letter-spacing: 0.04em; | ||
| padding: 5px 11px; background: var(--ink-3); color: var(--text-soft); | ||
| border: 1px solid var(--line-2); border-radius: 8px; cursor: pointer; | ||
| transition: color .15s, border-color .15s; | ||
| } | ||
| .dgm-copy:hover { color: var(--text); border-color: var(--cyan); } | ||
| .dgm-copy.ok { color: var(--signal); border-color: var(--signal-dim); } | ||
| .dgm-graph { display: flex; justify-content: center; padding: 8px; } | ||
| .dgm-source { | ||
| margin: 6px 0 0; border: 0; border-left: 3px solid var(--violet); | ||
| background: var(--ink); border-radius: 0 10px 10px 0; max-height: 540px; overflow: auto; | ||
| } | ||
| .dgm-source code { color: var(--text-soft); background: none; border: 0; padding: 0; } | ||
| [hidden] { display: none !important; } | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift
Migrate new toolbar styling to Tailwind utilities.
This new block introduces custom component styling (states, colors, borders, spacing) beyond animation/layout primitives. Please move these styles to Tailwind classes (or utility composition) and keep custom CSS only for parts Tailwind cannot express.
As per coding guidelines, "**/*.{css,scss}: Use TailwindCSS for all styling; custom CSS only for animations and layout primitives that Tailwind cannot express (e.g., keyframe animations, CSS custom properties)".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/deployment/assets/styles.css` around lines 169 - 196, The new diagram
toolbar CSS uses bespoke styles that must be migrated to Tailwind utilities:
replace rules for .diagram .cap, .dgm-bar, .dgm-seg, .dgm-tab (including
.dgm-tab.is-active and :hover state), .dgm-copy (including .dgm-copy.ok and
:hover), .dgm-graph, .dgm-source (and its code), and the .dgm-tab + .dgm-tab
sibling border with equivalent Tailwind classes and utility composition in the
markup; keep only minimal custom CSS for things Tailwind cannot express (e.g.,
complex keyframes or non-standard CSS custom-property logic), preserve the
[hidden] { display: none !important; } rule, and remove the duplicated styling
block from styles.css so styling lives as Tailwind utility classes and small
exception CSS (if absolutely required) for .dgm-source max-height/overflow or
the left border radius.
| </footer> | ||
|
|
||
| <script type="module" src="assets/mermaid-init.js"></script> | ||
| <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify all deployment docs pages that load Mermaid from CDN and check for SRI/crossorigin.
rg -n 'cdn\.jsdelivr\.net/npm/mermaid@' docs/deployment/*.html
rg -n 'mermaid\.min\.js".*integrity=' docs/deployment/*.html
rg -n 'mermaid\.min\.js".*crossorigin=' docs/deployment/*.htmlRepository: riethmayer/eureka
Length of output: 539
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Mermaid jsDelivr inclusions =="
rg -n 'cdn\.jsdelivr\.net/npm/mermaid@' docs/deployment/*.html
echo
echo "== SRI matches (integrity=) on mermaid.min.js tags =="
rg -n 'mermaid\.min\.js".*integrity=' docs/deployment/*.html || true
echo
echo "== crossorigin matches on mermaid.min.js tags =="
rg -n 'mermaid\.min\.js".*crossorigin=' docs/deployment/*.html || true
echo
echo "== Context around mermaid@ occurrences (check integrity/crossorigin nearby) =="
rg -n -C 2 'cdn\.jsdelivr\.net/npm/mermaid@' docs/deployment/*.htmlRepository: riethmayer/eureka
Length of output: 2029
Pin Mermaid CDN and add SRI
docs/deployment/index.html loads Mermaid from jsDelivr as mermaid@11 without integrity/crossorigin, which allows silent upstream changes and weaker script integrity guarantees. The same pattern exists in docs/deployment/tradeoffs.html (line 107), docs/deployment/security.html (line 161), and docs/deployment/pipeline.html (line 149). Pin to an exact Mermaid version and add integrity + crossorigin="anonymous" to the <script> tag.
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/deployment/index.html` at line 143, The Mermaid script tag currently
uses a floating tag
"https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"; update that tag
to pin an exact release (e.g., mermaid@11.x.y) and add SRI and crossorigin
attributes by replacing the existing <script
src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
occurrences with a tag that includes integrity="sha384-..." and
crossorigin="anonymous" (use the correct integrity hash for the chosen exact
version); make the same change for the identical script occurrences in the other
docs pages.
1 participant
What
Makes the deployment docs' mermaid diagrams render by default and adds, per diagram, a Diagram ⇄ Source toggle and a Copy source button.
Why
The diagrams were showing as raw text when the docs are opened locally. Root cause: mermaid was loaded as an ES module, and Chrome blocks
<script type="module">fromfile://origins (CORS, originnull). Switched to the classic UMD mermaid build + a classic enhancer script (assets/docs.js) that renders reliably from bothfile://andhttp.Changes
assets/docs.js(new) — initialises mermaid (custom dark theme), renders each diagram, and builds the toggle + copy UI.assets/mermaid-init.js(the ES-module version).mermaid.min.js(UMD) +docs.js.styles.css— toolbar styling (segmented toggle, copy button, source view).security.html— corrected the deployer SA storage role to project-levelstorage.admin.Verified
Rendered over both
file://andhttp: flowcharts and the sequence diagram render; the Diagram/Source toggle flips views; Copy puts the mermaid source on the clipboard. No console errors.Docs-only — the Cloud Run deploy workflow ignores
docs/**, so merging won't trigger a deploy.Summary by CodeRabbit
New Features
Documentation