From 495bc41ba693728be693e4b01c4e7ce3bc358e3a Mon Sep 17 00:00:00 2001 From: Harley Trung Date: Sat, 27 Sep 2025 12:01:13 +0700 Subject: [PATCH] docs: consolidate --- README.md | 4 ++++ docs/README.md | 3 ++- docs/architecture.md | 9 ++++++--- docs/changelog.md | 11 ----------- docs/extension-flow.md | 27 ++++++++++++++------------- 5 files changed, 26 insertions(+), 28 deletions(-) delete mode 100644 docs/changelog.md diff --git a/README.md b/README.md index 6f370aa..feec841 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,10 @@ pnpm run build The production bundle lands in `dist/`. Package it manually or use `pnpm run zip` for a distributable archive. +## Releases + +Release Please manages versioning and release notes. Check the autogenerated root `CHANGELOG.md` or the GitHub Releases tab for the latest history. + --- Bootstrapped with [create-chrome-ext](https://github.com/guocaoyi/create-chrome-ext) diff --git a/docs/README.md b/docs/README.md index c2258d5..c4f718b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,7 +23,8 @@ Additional scripts live in `package.json`, including `pnpm build` for production - [Extension Flow](./extension-flow.md) - [UI Guidelines](./ui-guidelines.md) - [Testing Guide](./testing.md) -- [Changelog](./changelog.md) + +Release notes are generated automatically via release-please and published with GitHub Releases; there is no manual changelog in this folder. ## Doc Conventions diff --git a/docs/architecture.md b/docs/architecture.md index 3cb43b4..858a2a5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,6 +2,8 @@ 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. +For a user-centric walkthrough of the lifecycle, see [`extension-flow.md`](./extension-flow.md). + ## Runtime Components - **Background (`src/background/index.ts`)** @@ -25,7 +27,7 @@ CoderChart follows the typical MV3 separation: a background service worker maint ```mermaid flowchart TD - A[Load content script] --> B[getSettings()] + A[Load content script] --> B[Fetch settings] B --> C{autoRender enabled?} C -- No --> D[Stay idle] C -- Yes --> E{URL matches whitelist?} @@ -55,5 +57,6 @@ flowchart TD ## 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. +- Clearing all host patterns in options is not persisted: `normalizeSettings` restores the default ChatGPT domains, so disable `autoRender` to pause rendering globally. +- PNG export relies on drawing the generated SVG into a canvas; diagrams that pull in external assets or exceed canvas limits can fail to export and log a warning. +- Mermaid parse failures surface inline with a copyable fix prompt, but there is still no automatic retry or self-healing. diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index 46fe6cd..0000000 --- a/docs/changelog.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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._ diff --git a/docs/extension-flow.md b/docs/extension-flow.md index e02adc8..ddd5417 100644 --- a/docs/extension-flow.md +++ b/docs/extension-flow.md @@ -1,17 +1,17 @@ # Extension Flow -This guide walks through the end-to-end experience from installation to exporting rendered diagrams. +This guide outlines the user-visible lifecycle. For component responsibilities and deeper mechanics, see [`architecture.md`](./architecture.md). -## Narrative Flow +## Lifecycle Overview -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. +| Step | Trigger | Primary owner | Notes | +| --- | --- | --- | --- | +| Install or upgrade | Extension installed from source or Web Store | Background service worker | Seeds defaults and handles migrations (`architecture.md` → Runtime Components). | +| Host access granted | Chrome applies `manifest.ts` host permissions | Chrome / MV3 platform | Controls where the content script can run (`architecture.md` → Runtime Components). | +| Page activation | User opens a whitelisted URL | Content script | Fetches settings, checks URL against patterns, and, if allowed, initialises Mermaid (`architecture.md` → Data Flow Sequence). | +| Inline rendering | Mermaid blocks detected | Content script + Mermaid runtime | Injects managed containers, themes Mermaid, and caches SVG output (`architecture.md` → Mermaid Rendering & Downloads). | +| Settings changes | Options UI edits or resets settings | Options UI + shared settings utils | Saves updates through `saveSettings`; listeners reconcile state across surfaces (`architecture.md` → Settings Synchronisation). | +| Continuous updates | Chat adds new content or settings sync changes arrive | Content script | MutationObserver re-runs detection; storage listeners reapply activation rules (`architecture.md` → Settings Synchronisation). | ## Sequence Diagram @@ -21,7 +21,8 @@ sequenceDiagram participant C as Chrome participant B as Background participant CS as Content Script - participant Opt as Options UI + participant Options as Options UI + participant Toolbar as Download Toolbar U->>C: Install extension C->>B: fire onInstalled @@ -40,8 +41,8 @@ sequenceDiagram 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 + U->>Options: Open options page + Options->>chrome.storage.sync: save updated settings chrome.storage.sync-->>CS: onChanged event CS->>CS: Apply settings (activate/deactivate/re-render) ```