Document extension architecture and refresh branding assets

Author: harley

docs/README.md

@@ -0,0 +1,37 @@
+# Documentation Hub
+
+CoderChart centralises product, technical, and process documentation inside `/docs`. Start here for high-level context and jump to deeper guides as needed.
+
+## Project Overview
+
+CoderChart is a Chrome extension that auto-renders Mermaid diagrams on supported AI chat surfaces. It detects Mermaid blocks, injects a themed inline preview with toolbar controls, and keeps settings in sync across browsers via `chrome.storage.sync`.
+
+## Quickstart
+
+```bash
+pnpm install
+pnpm dev
+# Load the dist/ directory as an unpacked extension in Chrome
+```
+
+Additional scripts live in `package.json`, including `pnpm build` for production bundles and `pnpm run zip` to package the extension.
+
+## Documentation Map
+
+- [Product Requirements](./prd.md)
+- [Architecture](./architecture.md)
+- [Extension Flow](./extension-flow.md)
+- [UI Guidelines](./ui-guidelines.md)
+- [Testing Guide](./testing.md)
+- [Changelog](./changelog.md)
+
+## Doc Conventions
+
+- Use Markdown with concise, action-oriented language.
+- Reference code with workspace-relative paths (e.g. `src/contentScript/index.ts`).
+- Call out defaults and limitations explicitly.
+- Prefer Mermaid diagrams for flows or sequences.
+
+## Ownership
+
+Primary owner: _TBD_. Contact: _TBD_. Update this section once a maintainer is assigned.

docs/architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+CoderChart follows the typical MV3 separation: a background service worker maintains defaults, the content script renders diagrams in-page, and the options UI manages configuration. Shared utilities in `src/shared` allow all surfaces to agree on settings and URL matching.
+
+## Runtime Components
+
+- **Background (`src/background/index.ts`)**
+  - Runs once on install/upgrade.
+  - Normalises settings saved in `chrome.storage.sync`, ensuring defaults exist (`autoRender: true`, ChatGPT host patterns).
+  - Acts as the central authority for schema migrations.
+- **Content Script (`src/contentScript/index.ts`)**
+  - Loads settings on startup and listens for `chrome.storage.onChanged` updates.
+  - Checks `window.location.href` against the whitelist via `doesUrlMatchPatterns`.
+  - Sets up DOM observers to detect new Mermaid blocks, renders via Mermaid, and injects inline toolbars plus themed containers.
+  - Handles export flows by converting SVG strings to downloadable SVG/PNG blobs.
+- **Options UI (`src/options/Options.tsx`)**
+  - Fetches settings on mount, exposes toggles and editable host patterns, and persists updates through `saveSettings`.
+  - Implements optimistic UI with save-status feedback and reset-to-defaults shortcut.
+  - Validates input lightly by ignoring empty/duplicate patterns.
+- **Shared Utilities (`src/shared`)**
+  - `settings.ts` centralises defaults, coercion, and persistence helpers.
+  - `url.ts` compiles user patterns into regular expressions for whitelist checks.
+
+## Data Flow Sequence
+
+```mermaid
+flowchart TD
+    A[Load content script] --> B[getSettings()]
+    B --> C{autoRender enabled?}
+    C -- No --> D[Stay idle]
+    C -- Yes --> E{URL matches whitelist?}
+    E -- No --> D
+    E -- Yes --> F[Configure Mermaid theme]
+    F --> G[Process existing DOM]
+    G --> H[Start MutationObserver]
+    H --> I[Render new Mermaid blocks]
+    I --> J[Update toolbar + downloads]
+    J --> K[Listen for storage changes]
+    K --> C
+```
+
+## Mermaid Rendering & Downloads
+
+- Mermaid is initialised with `startOnLoad: false` and theming keyed to system or page dark mode.
+- Each detected Mermaid block is rendered into a managed container that stores the last SVG string for reuse.
+- **SVG export:** cached SVG is wrapped in a Blob and downloaded via `URL.createObjectURL`.
+- **PNG export:** the SVG is rendered into an off-screen `<canvas>` using `drawImage`, respecting intrinsic dimensions before exporting to PNG via `canvas.toBlob`.
+- Toolbar buttons are disabled until render completes to avoid empty exports.
+
+## Settings Synchronisation
+
+- The background script seeds defaults, but the content script defensively normalises settings each time it loads.
+- Storage updates trigger a content-script listener that either re-activates, re-renders, or deactivates depending on `autoRender`/whitelist changes.
+- The options UI trims, deduplicates, and validates entries before writing, preventing malformed patterns from breaking runtime checks.
+
+## Known Constraints
+
+- Builds occasionally report Rollup chunk-size warnings; adjust splitting before release if bundle size grows.
+- Rendering currently assumes Mermaid syntax; invalid diagrams surface an inline error but do not retry automatically.

docs/changelog.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 2025-09-26 – Initial Mermaid Rendering Milestone
+
+- Content script renders Mermaid diagrams inline with themed containers and toolbar controls.
+- Toolbar enables show/hide, scroll-to-code, and SVG/PNG downloads.
+- Options page manages auto-render toggle and host whitelist synced via `chrome.storage.sync`.
+- Background script seeds default settings (auto-render true, ChatGPT host patterns) on install.
+- Known follow-up: monitor Vite build warnings about chunk sizes before publishing.
+
+_Use ISO dates and reverse chronological order for future entries._

docs/extension-flow.md

@@ -0,0 +1,47 @@
+# Extension Flow
+
+This guide walks through the end-to-end experience from installation to exporting rendered diagrams.
+
+## Narrative Flow
+
+1. **Install:** User loads the unpacked build or installs from the Chrome Web Store. The background script seeds default settings in `chrome.storage.sync`.
+2. **Grant permissions:** Chrome applies host permissions declared in `manifest.ts` (ChatGPT domains and localhost during development).
+3. **Open supported page:** When the user opens chatgpt.com or another whitelisted host, the content script loads, retrieves settings, and checks the URL against the whitelist.
+4. **Render diagrams:** Matching Mermaid code fences trigger the inline renderer. Mermaid initialises with theme selection, generates SVG, and injects a container with toolbar controls.
+5. **Adjust settings:** Users can visit `options.html` to disable auto-rendering, edit host patterns, or reset to defaults. Changes sync across devices.
+6. **Use toolbar:** Inline buttons allow collapsing/expanding the diagram, scrolling back to the source code block, and exporting as SVG or PNG.
+7. **Download pipeline:** SVG downloads reuse the cached render, while PNG downloads convert the SVG via an off-screen canvas before prompting a file save.
+8. **Keep updated:** A MutationObserver re-runs rendering when the chat adds new content, and storage listeners reconfigure the script when settings change.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Chrome
+    participant B as Background
+    participant CS as Content Script
+    participant Opt as Options UI
+
+    U->>C: Install extension
+    C->>B: fire onInstalled
+    B->>chrome.storage.sync: normalize defaults (autoRender true, ChatGPT hosts)
+    U->>C: Open chatgpt.com
+    C->>CS: Inject content script
+    CS->>chrome.storage.sync: getSettings()
+    chrome.storage.sync-->>CS: settings
+    CS->>CS: doesUrlMatchPatterns()
+    alt Matches whitelist
+        CS->>Mermaid: initialize(theme)
+        CS->>U: Render inline diagram and toolbar
+    else Not matched
+        CS->>CS: stay dormant
+    end
+    U->>Toolbar: Click download SVG/PNG
+    Toolbar->>CS: fetch cached SVG / convert to PNG
+    CS->>U: Trigger file download
+    U->>Opt: Open options page
+    Opt->>chrome.storage.sync: save updated settings
+    chrome.storage.sync-->>CS: onChanged event
+    CS->>CS: Apply settings (activate/deactivate/re-render)
+```

docs/prd.md

@@ -0,0 +1,51 @@
+# Product Requirements
+
+## Problem Statement
+
+AI chat platforms often expose Mermaid code blocks as raw text, forcing users to copy/paste into external renderers. CoderChart removes that friction by transforming recognised Mermaid snippets directly within the chat interface.
+
+## Goals
+
+- Auto-render Mermaid diagrams on trusted hosts without manual intervention.
+- Provide inline controls to manage visibility, navigation, and exports.
+- Keep configuration lightweight and synced across Chrome profiles.
+- Fail gracefully when diagrams cannot render and surface actionable feedback.
+
+## Target Users
+
+- Engineers and analysts who rely on ChatGPT or similar tools to sketch flows, ERDs, or diagrams.
+- Technical writers who review Mermaid output in AI-assisted drafts.
+- Product teams evaluating AI-generated diagrams during reviews.
+
+## Key Features
+
+- Default auto-rendering (`autoRender = true`) for fast feedback loops.
+- Host whitelist seeded with ChatGPT domains (`https://chatgpt.com/*`, `https://chat.openai.com/*`).
+- MutationObserver-driven detection to keep up with streaming chat updates.
+- Inline toolbar with show/hide, scroll-to-code, and SVG/PNG download actions.
+- Themed containers that respect host dark/light schemes.
+- Options page (`options.html`) for toggling auto-render, editing whitelists, and resetting defaults.
+
+## Success Metrics
+
+- 90%+ of Mermaid blocks render without manual refresh.
+- Diagram render latency under 500ms on typical chat conversations (after initial page load).
+- Less than 5% of renders trigger unhandled errors in production logs.
+- At least 50% of active users keep the default auto-render setting enabled.
+- Positive qualitative feedback on export quality (SVG/PNG) from beta users.
+
+## Non-goals
+
+- Supporting arbitrary third-party diagramming syntaxes beyond Mermaid.
+- Providing a pop-up or new-tab renderer. Focus is inline augmentation.
+- Offline mode or local backup of diagrams beyond user-triggered downloads.
+- Autosaving edited diagrams or providing a diagram editor.
+
+## Future Roadmap Ideas
+
+- Guided onboarding surfaced on install to highlight toolbar controls.
+- Additional host presets (e.g. internal Confluence, GitHub Issues) with user opt-in.
+- Granular theme controls for high-contrast or dyslexia-friendly modes.
+- Export presets (transparent backgrounds, custom dimensions) for presentation teams.
+- Automated integration tests to catch regressions in the download pipeline.
+- Resolve build-time chunk-size warnings by tuning Vite rollup settings.

docs/testing.md

@@ -0,0 +1,36 @@
+# Testing Guide
+
+## Manual Test Plan
+
+- **Local setup**
+  - Run `pnpm install` and `pnpm dev`.
+  - Load the generated `dist/` folder as an unpacked extension in Chrome (Developer Mode on).
+- **Settings sanity**
+  - Confirm defaults: auto-render enabled, whitelist contains ChatGPT domains.
+  - Toggle auto-render off in `options.html`; verify diagrams stop rendering until re-enabled.
+  - Add and remove a custom host pattern; ensure the input trims whitespace and disallows duplicates.
+- **Rendering lifecycle**
+  - On chatgpt.com, paste multiple Mermaid snippets (different diagram types) and verify each auto-renders below its code block.
+  - Trigger chat updates or regenerate responses to confirm the MutationObserver handles new content without duplicates.
+  - Switch the page between light and dark themes (or toggle system theme) and confirm container styling updates.
+- **Toolbar actions**
+  - Use "Hide diagram" / "Show diagram" toggles; ensure state persists while on the page.
+  - Click "Scroll to code" and verify smooth scrolling centers the source block.
+  - Download SVG and PNG; confirm filenames are unique per block and PNG output matches expected dimensions.
+  - Induce a Mermaid syntax error and check that the inline error pane displays message + hint.
+- **Extension lifecycle**
+  - Reload the extension in `chrome://extensions` to verify background script restores defaults without duplicates.
+  - Test on a non-whitelisted host to confirm the content script remains dormant.
+
+## Automated Testing Opportunities
+
+- Unit tests around `patternToRegExp` and `doesUrlMatchPatterns` to cover wildcard edge cases.
+- Jest/`@testing-library/react` tests for `Options` form interactions (validation, save states, reset behaviour).
+- Integration harness (e.g. Puppeteer) to open a static page with seeded Mermaid blocks and assert render/download flows.
+- Canvas conversion smoke tests ensuring `convertSvgToPng` returns blobs with expected dimensions.
+- CI check to detect Vite chunk-size warnings and fail builds when thresholds exceed targets.
+
+## Known Gaps
+
+- No automated coverage for the content script DOM manipulation; browser-based tests would increase confidence.
+- PNG export depends on browser canvas support; add fallbacks or better error messaging if conversion fails.

docs/ui-guidelines.md

@@ -0,0 +1,37 @@
+# UI Guidelines
+
+## Inline Diagram Container
+
+- Present diagrams directly beneath the source code block using a rounded container that mirrors host spacing.
+- Header displays "Mermaid diagram" with a compact toolbar aligned to the right.
+- Respect page theme changes: detect dark mode via root class or `prefers-color-scheme` and update backgrounds/borders accordingly.
+- Keep collapse/expand state intuitive; show "Hide diagram" when expanded and "Show diagram" when collapsed.
+
+## Toolbar Buttons
+
+- Order actions: `Hide diagram`, `Scroll to code`, `Download SVG`, `Download PNG`.
+- Disable download buttons until render succeeds to avoid empty files.
+- Provide hover feedback with subtle background changes; use consistent sizes and border radii.
+- Preserve the original label via `data-coderchart-label` so temporary text (e.g. "Preparing PNG…") can revert cleanly.
+
+## Options Page
+
+- Anchor primary controls (auto-render toggle) at the top of the form with descriptive copy.
+- Patterns list supports inline editing; include remove buttons with accessible labels.
+- Prevent duplicate or empty patterns; disable the "Add pattern" button until input is valid.
+- Show save status feedback (`Saving…`, `Settings saved`, error) near the form footer.
+- Include a "Reset to defaults" button for quick recovery.
+
+## Accessibility Considerations
+
+- Buttons and interactive elements use semantic `<button>`/`<input>` elements for screen-reader compatibility.
+- Contrast ratios aim to exceed WCAG AA by using muted backgrounds with solid borders and high-contrast text.
+- Scroll-to-code uses `scrollIntoView({ behavior: 'smooth', block: 'center' })` to avoid disorienting jumps.
+- Error notices provide text explanations and suggestions (`Check the Mermaid syntax and try again`).
+- Ensure focus outlines remain visible; do not disable browser outlines via CSS.
+
+## Future Enhancements
+
+- Add keyboard shortcuts for toggling diagrams or triggering exports.
+- Offer user-selectable themes or high-contrast mode overrides.
+- Surface toast confirmations after downloads to improve feedback.