Add Captain's Bridge — novel doc reading experience

[nomadicmehul]

Summary

Introduces Captain's Bridge — a purpose-built doc reading layout that replaces Docusaurus's stock three-column row with a CSS-Grid canvas tailored for learning content. Ships as the default reading mode for all doc pages, with a one-click toggle back to the classic Docusaurus layout remembered per-browser.

Four commits, each reviewable independently:

#	Commit	What it does
1	45d4fc6	v1 — layered overlay (telemetry strip, right rail, bottom console, keyboard shortcuts, focus mode, localStorage read state, help modal).
2	9baf119	v2 — full DocItem/Layout replacement via eject-swizzle. Pure CSS Grid. Adds chapter cards (per-H2 progress bubble + ETA + auto-difficulty), reading gutter (left ribbon), resume banner, mark-section-complete buttons.
3	0aa4d98	Polish — completion toast with particle burst, cross-page sidebar progress dots (SidebarSpine), download-all-commands-as-.sh, tuned chapter card density.
4	0dfc2ba	Trim — drop the under-performing "Concepts" tab; rail now has just Contents + Commands.

What users see

• Sticky telemetry strip — ⚓ BRIDGE | progress 47% | section 04/12 | eta 6 min plus focus / rail / ? / classic buttons.
• Left reading gutter — thin 2px ribbon fills green→cyan as you scroll; H2 markers appear as dots (click to jump, green when read).
• Centered article (max 860px) with chapter cards before every H2 and a "✓ Mark section complete" button at the end of each section.
• Right rail with two tabs:
  • Contents — headings with per-section read checkmarks (localStorage per URL).
  • Commands — CLI lines auto-extracted from code blocks with one-click copy, plus ⬇ .sh download (generates a runnable #!/usr/bin/env bash script with header, set -euo pipefail, and each command labelled by detected language) and ⎘ all copy-all.
• Bottom console — vim-style shortcuts (j k gg G f t m n p / ? Esc), read counter (N/M read), prev/next doc, help.
• Resume banner — appears when partial progress exists; "Jump to §X" link with visual progress bar.
• Focus mode (f) — dims all paragraphs except the one at viewport center; scroll-tracked via requestAnimationFrame. Respects prefers-reduced-motion.
• Sidebar spine — every doc link in the left nav gets a progress dot (◐ partial, ● complete) based on localStorage state. Live-updates across tabs via storage event + in-tab via a cc-bridge-read-change CustomEvent.
• Completion toast — 🎉 <section> complete — 4/12 gradient pill with 5-particle CSS burst. 🏁 Page complete on the final section.
• Classic toggle — one click falls back to stock Docusaurus; a ⚓ FAB re-enables. Preference persists.
• Keyboard help (?) — modal listing every shortcut.

Architecture

Swizzle-ejected theme/DocItem/Layout. The layout picks between:

• BridgeLayout (default) — CSS Grid with five regions: header / gutter / main / rail / footer-console. Consumes unswizzled sub-components (DocItemContent, DocItemFooter, DocItemPaginator, DocBreadcrumbs, DocVersionBanner, ContentVisibility) so markdown, MDX, admonitions, mermaid, and every content plugin continue to work unchanged.
• ClassicLayout (fallback) — verbatim stock Docusaurus layout. SSR also renders this to avoid hydration flash and to give search engines stable markup; BrowserOnly swaps to Bridge client-side.

Key hooks

• useScrollProgress — computes active heading + progress % + ETA, rAF-throttled.
• useExtractors — scans code blocks for CLI commands by language + keyword heuristics (kubectl, docker, terraform, helm, git, aws, az, gcloud, etc.).
• useReadProgress — localStorage-backed {readSections, totalSections, lastUpdated} per pathname. Emits a window-scoped cc-bridge-read-change CustomEvent on every write so SidebarSpine updates without a tab switch. Exports getAllReadEntries() for cross-page aggregation.

Chapter enhancements

ChapterEnhancements.tsx traverses the post-rendered DOM and injects invisible host <div>s before each H2 + after the last block of each H2 section. React portals then render the chapter card and mark-complete button into those hosts — the markdown itself is never mutated, so hot-reload and MDX compilation are unaffected.

Difficulty heuristic

Per-section auto-classified from code-block density + inline-code count + word length:

score = codeBlocks × 2 + inlineCodes × 0.15 + words / 400
score < 4  → beginner ●○○
score < 10 → intermediate ●●○
else       → advanced ●●●

Tune weights in ChapterEnhancements.tsx.

Persistence keys

Key	What
cloudcaptain.bridge.enabled	Bridge on/off (global)
cloudcaptain.bridge.focus	Focus mode
cloudcaptain.bridge.rail	Rail open
cloudcaptain.bridge.railTab	Active tab (contents or commands)
cloudcaptain.bridge.read.{pathname}	{readSections, totalSections, lastUpdated}

Trade-offs

• Ejected swizzle — DocItem/Layout upstream changes won't auto-merge into the custom branch; ClassicLayout.tsx remains a verbatim copy for diffing on major Docusaurus bumps. DocItem/Layout changes roughly twice a year in upstream.
• Desktop-first — rail hides under 996px, gutter hides under 768px. Mobile reading is prose-only + console; full feature surface is tuned for ≥1100px.
• No new dependencies — pure React + CSS. No zustand, no framer, no hotkeys lib.
• Dark aesthetic even in light mode — intentional "mission control" feel that signals Bridge is a distinct mode. Classic fallback respects light/dark normally.

Test plan

• Open a long doc (e.g. /docs/tools/docker/fundamentals) — telemetry strip renders at top, gutter fills as you scroll, chapter cards appear above every H2, rail populates Contents + Commands.
• Click "✓ Mark section complete" — chapter bubble fills, rail entry gets checkmark, gutter dot turns green, console counter ticks up, toast fires.
• Refresh page — read state persists, Resume banner appears with "Jump to §X" link.
• Complete all sections — final toast shows "🏁 Page complete".
• Navigate between docs via sidebar — partial/complete dots appear next to previously-read pages.
• Open site in second tab, complete a section there — first tab's sidebar updates automatically.
• Keyboard: j / k / gg / G scrolling, f focus, t rail toggle, m mark read, n / p prev/next doc, / search focus, ? help.
• Commands tab: ⬇ .sh downloads a runnable script; ⎘ all copies to clipboard.
• Click classic in telemetry — layout falls back to stock Docusaurus; ⚓ FAB re-enables Bridge.
• Resize to 900px wide — rail hides, gutter stays, console compresses; below 768px, gutter hides too.
• prefers-reduced-motion — focus mode + toast burst degrade to linear fade.
• npm run build in website/ — passes with no new warnings introduced by this branch.

Files

website/src/theme/DocItem/Layout/
  index.tsx                        (ejected; delegates to BridgeLayout / ClassicLayout)
  styles.module.css                (stock Docusaurus styles, used by ClassicLayout)

website/src/components/CaptainsBridge/
  BridgeLayout.tsx                 (grid orchestrator, state, keyboard)
  ClassicLayout.tsx                (verbatim Docusaurus fallback)
  BridgeTelemetry.tsx              (sticky top strip)
  BridgeRail.tsx                   (right rail: Contents + Commands + .sh download)
  BridgeConsole.tsx                (bottom keyboard bar)
  BridgeHelp.tsx                   (shortcuts modal)
  BridgeGutter.tsx                 (left reading ribbon)
  ResumeBanner.tsx                 (top banner for partial progress)
  ChapterEnhancements.tsx          (per-H2 cards + mark-complete buttons via portals)
  CompletionToast.tsx              (celebratory pill + particle burst)
  SidebarSpine.tsx                 (cross-page progress dots on sidebar links)
  useScrollProgress.ts             (scroll → progress/section/ETA)
  useExtractors.ts                 (DOM → CLI commands)
  useReadProgress.ts               (localStorage read state + cross-tab sync)
  styles.module.css                (all Bridge styling)

website/src/css/custom.css         (focus-mode paragraph dimming only)

Not in this PR

• Lab pane / live sandbox integration → see stacked branch feature/learn-lab-split.
• Cross-learning-path /progress page.
• WebVM / Pyodide in-page labs (Phase 3).

[github-actions]

🚀 Preview Deployment

Your changes have been deployed to a preview URL:

https://cloudcaptain-pr-41.surge.sh

This preview will be updated on every push to this PR.

---

Deployed by GitHub Actions