fix: Mermaid diagram errors, dark theme compatibility, and mdhelp scroll reset

[Copilot]

Two distinct bugs: (1) Several Mermaid diagrams across /docs fail to parse or are near-invisible on dark backgrounds due to emoji in node labels, legacy graph TD syntax, back-edges into subgraphs, and near-white hardcoded fills. (2) Angular's Router resets scroll position to the top on every router.navigate() call in onSubmit(), including unchanged-URL navigations.

Changes

Frontend — scroll position reset (frontend/)

• app.config.ts: Added withInMemoryScrolling({ scrollPositionRestoration: 'enabled', anchorScrolling: 'enabled' }) to provideRouter() — enables Angular's built-in in-memory scroll restoration and anchor scrolling. The 72px scroll offset for the fixed header is applied via inject(ViewportScroller).setOffset([0, 72]) inside provideAppInitializer (the correct Angular 21 API — scrollOffset is not a valid option on InMemoryScrollingOptions or RouterConfigOptions).
• compiler.component.ts: Both router.navigate() calls in onSubmit() now guard on URL change and use replaceUrl: true to avoid pushing redundant history entries that trigger scroll resets. The URL comparison uses queryParamMap.get('url') instead of queryParams['url'] to correctly handle the string | string[] type and avoid false inequality when query params are repeated.

// Before: unconditional navigate on every submit
this.router.navigate([], { relativeTo: this.route, queryParams: { url: ... }, queryParamsHandling: 'merge' });

// After: only navigate when URL changes; replace instead of push
const currentUrl = this.route.snapshot.queryParamMap.get('url');
if (currentUrl !== urlEntries[0].source) {
    this.router.navigate([], {
        relativeTo: this.route,
        queryParams: { url: urlEntries[0].source },
        queryParamsHandling: 'merge',
        replaceUrl: true,
    });
}

Docs — Mermaid diagram fixes

• docs/architecture/SYSTEM_ARCHITECTURE.md: Stripped all emoji from quoted node labels; replaced near-white classDef fills (#F0C040, #E8A838, etc.) with medium-luminance palette (#1d6fbd, #b8860b, #2e7d32, …) with explicit color:#fff.
• docs/development/ARCHITECTURE.md: graph TD → flowchart TD (legacy parser); stripped emoji from node/subgraph labels; replaced all ~40 light classDef/style fills; replaced box rgb(...) in sequenceDiagram blocks with plain box for theme-aware rendering.
• docs/auth/auth-chain-reference.md: Fixed gantt axisFormat %b %Y → %Y-%m-%d (month-level ticks made 3–14 day bars invisible); replaced light inline style fills; removed emoji from node labels.
• docs/workflows/WORKFLOW_DIAGRAMS.md: Fixed BatchCompilationWorkflow illegal back-edge into subgraph (CHUNK2 -->|Yes| NEXT_CHUNK → C1_START collapsed to CHUNK2 -->|Yes| C1_START); replaced all ~60 light style fills.
• docs/cloudflare/CLOUDFLARE_WORKFLOWS.md: Added color:#fff to all three style Complete fill:#4caf50 overrides; replaced remaining light fills.

Testing

• Unit tests added/updated — N/A (docs + router config only)
• Manual testing performed — verified Mermaid syntax changes, TypeScript changes inspected in-editor
• CI passes

Zero Trust Architecture Checklist

Worker / Backend

• Every handler verifies auth before executing business logic — N/A
• CORS origin allowlist enforced (not *) on write/authenticated endpoints — N/A
• All secrets accessed via Worker Secret bindings (not [vars]) — N/A
• All external inputs Zod-validated before use — N/A
• All D1 queries use parameterized .prepare().bind() (no string interpolation) — N/A
• Security events emitted to Analytics Engine on auth failures — N/A

Frontend / Angular

• Protected routes have functional CanActivateFn auth guards — unchanged, no new routes
• Auth tokens managed via Clerk SDK (not localStorage) — N/A
• HTTP interceptor attaches ****** (no manual token passing) — N/A
• API responses validated with Zod schemas before consumption — N/A

API Shield / Vulnerability Scanner

• New/changed endpoints have a unique operationId in openapi.yaml — N/A
• Resource endpoints (those with /{id} path parameters) include a security: annotation — N/A
• Resource queries are scoped to the authenticated user (WHERE user_id = ?) — N/A
• Missing/unauthorized resources return 404 (not 403) to avoid leaking resource existence — N/A
• cloudflare-schema.yaml regenerated if openapi.yaml changed (deno task schema:cloudflare) — N/A

Original prompt

Overview

Two distinct problems need to be fixed:

1. Mermaid diagram errors across /docs — several charts fail to render or look broken on dark backgrounds.
2. mdhelp scroll position reset — every time a user clicks a section in the help panel, the viewport scrolls back to the top.

---

1 — Mermaid diagram fixes

Files to fix

docs/architecture/SYSTEM_ARCHITECTURE.md

• Both flowchart TD diagrams (Current Architecture and Target Architecture) use emoji inside quoted Mermaid node labels (e.g. ["🌐 Browser"], ["☁️ Cloudflare Access\n..."]). Emoji in node labels are not supported by all Mermaid renderers and cause parse/render failures. Replace all emoji in node labels with plain-text equivalents or remove them. Keep emoji only in subgraph titles if the renderer handles those separately, but plain text is safest everywhere.
• Both diagrams have hardcoded classDef fills that are near-white (fill:#F0C040, fill:#E8A838 with color:#fff, etc.) — legible on light backgrounds but extremely low contrast on dark themes. Replace with medium-luminance fills that work on both themes:
  • Use fills in the 35–65% lightness range with explicit color:#fff for dark fills and color:#1a1a1a for light fills.
  • Good palette to use: #1d6fbd (blue), #b05a10 (amber), #2e7d32 (green), #6a1fa0 (purple), #c62828 (red), #37474f (slate). These all pair with color:#fff.
  • For the corelib/jsrpkg yellow nodes use #b8860b (dark goldenrod) with color:#fff.

docs/development/ARCHITECTURE.md

• The System Context Diagram uses graph TD — change to flowchart TD for consistency and to avoid the graph legacy parser.
• The mindmap block for the module map: ensure all child nodes under root((src/)) use consistent 4-space indentation. Mixed 2-space and 4-space indentation breaks mindmap parsing.
• All classDef blocks use very light fills (e.g. fill:#eff6ff, fill:#fef9c3, fill:#f0fdf4, fill:#fdf4ff, fill:#fff7ed, fill:#fef2f2) with dark color:#1e293b text. These fills disappear on dark backgrounds. Replace them with the same medium-luminance palette described above:
  • external → fill:#37474f,color:#fff
  • client → fill:#1b5e20,color:#fff
  • system → fill:#b8860b,color:#fff
  • infra → fill:#1a237e,color:#fff
  • observability → fill:#b84000,color:#fff
  • auth → fill:#880e4f,color:#fff
  • core → fill:#b8860b,color:#fff
  • module → fill:#1b5e20,color:#fff
  • interface → fill:#1a237e,color:#fff
  • adapter → fill:#1b5e20,color:#fff
  • consumer → fill:#b8860b,color:#fff
  • step → fill:#1a237e,color:#fff
  • input → fill:#1b5e20,color:#fff
  • output → fill:#1a237e,color:#fff
  • entry → fill:#b8860b,color:#fff
  • router → fill:#1a237e,color:#fff
  • handler → fill:#1b5e20,color:#fff
  • middleware → fill:#6a1fa0,color:#fff
  • event → fill:#b8860b,color:#fff
  • hook → fill:#1b5e20,color:#fff
  • provider → fill:#1b5e20,color:#fff
  • message → fill:#b8860b,color:#fff
  • base → fill:#1a237e,color:#fff
  • error → fill:#c62828,color:#fff
  • client (deploy) → fill:#1b5e20,color:#fff
  • edge → fill:#b8860b,color:#fff
  • worker → fill:#1a237e,color:#fff
  • storage → fill:#6a1fa0,color:#fff
  • external → fill:#37474f,color:#fff
• The sequenceDiagram boxes (SSE Streaming and Async Queue) use box rgb(...) notation. These are valid in Mermaid v10+ but may render as solid-colour boxes that obscure text in dark mode. Replace each box rgb(...) with just box (no colour arg) which lets Mermaid use theme defaults, or remove the box wrapper and leave bare participants.

docs/auth/auth-chain-reference.md

• The gantt diagram uses axisFormat %b %Y (month-level axis) with step durations as short as 3d. Short bars at a monthly axis granularity often render as invisible zero-width bars. Change axisFormat to %Y-%m-%d so the axis ticks are at day level and all bars are visible.
• The flowchart TD auth chain uses inline style overrides with very light fills (fill:#e8f4f8, fill:#e8f5e9, fill:#fff3e0, fill:#f5f5f5, fill:#ffebee). These are near-invisible on dark backgrounds. Replace with the medium-luminance palette above:
  • REQ node: fill:#37474f,color:#fff
  • AUTH_OK, BA_OK nodes: fill:#1b5e20,color:#fff
  • CLERK_OK node: fill:#b84000,color:#fff
  • ANON node: fill:#37474f,color:#fff
  • REJECT, REJECT2, REJECT3, REJECT4 nodes: fill:#c62828,color:#fff

docs/workflows/WORKFLOW_DIAGRAMS.md

• BatchCompilationWorkflow flowchart: The edge CHUNK2 -->|Yes| NEXT_CHUNK[Process Next Chunk] followed by NEXT_CHUNK --> C1_START creates a backward edge into a subgraph (Chunk Processing). This is illegal in strict Mermaid flowchart TD and causes a render error. Fix: move NEXT_CHUNK outside the subgraph OR restructure the loop so that CHUNK2 -->|Yes| C1_START dir...

This pull request was created from Copilot chat.

[Copilot]

Copilot wasn't able to review any files in this pull request.

[jaypatrick]

@copilot CI is broken

[Copilot]

@copilot CI is broken

Fixed in 76b1975. The build was failing with TS2353: 'scrollPositionRestoration' does not exist in type 'RouterConfigOptions' — I had incorrectly placed scroll options inside withRouterConfig(). Those properties belong in withInMemoryScrolling() (Angular's InMemoryScrollingOptions). Replaced withRouterConfig with withInMemoryScrolling({ scrollPositionRestoration: 'enabled', anchorScrolling: 'enabled' }).

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

[jaypatrick]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied all three review items in b8d9fa5:

1. app.config.ts — Added scrollOffset: [0, 72] to withInMemoryScrolling so the comment matches the actual behaviour.
2. compiler.component.ts (both navigate guards) — Replaced this.route.snapshot.queryParams['url'] (type string | string[]) with this.route.snapshot.queryParamMap.get('url') (always string | null) at both call sites, making the URL-change guard reliable when query params are repeated.

[jaypatrick]

@copilot fix CI

[Copilot]

@copilot fix CI

Fixed in d20d0e4. The build was failing with TS2353: 'scrollOffset' does not exist in type 'InMemoryScrollingOptions' — scrollOffset is a RouterConfigOptions property, not InMemoryScrollingOptions. Moved it to a separate withRouterConfig({ scrollOffset: [0, 72] }) feature alongside withInMemoryScrolling().

[jaypatrick]

@copilot fix CI

[Copilot]

@copilot fix CI

Fixed in 7c18973. scrollOffset is not a valid option on either InMemoryScrollingOptions or RouterConfigOptions in Angular 21. The correct API is ViewportScroller.setOffset([0, 72]) — now called inside provideAppInitializer before any await (so the injection context is still active). Removed withRouterConfig entirely and updated the comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.