feat: update .gitignore and enhance documentation; add UI guidelines and fix service worker loader

Author: vchan-in

.gitignore

@@ -4,3 +4,6 @@ dist/
 *.zip
 *.vsix
 .memory/cleanup.log
+
+*storybook.log
+storybook-static

.memory/decisions.md

@@ -53,3 +53,5 @@
 - [markdown-rendering] Messages in the dashboard render markdown via react-markdown + remark-gfm + @tailwindcss/typography. MarkdownContent component lives in src/components/MarkdownContent.tsx. Overflow is hard-capped: pre=overflow-x-auto, img=max-w-full, table wrapped in overflow-x-auto div, links=break-all.
 
 - [message-copy-share] Per-message actions: Copy (MD/TXT toggle, shared copyMode state) + Share (Web Share API with clipboard fallback). Action bar is hover-revealed via Tailwind group/group-hover pattern. stripMarkdown utility lives in src/utils/stripMarkdown.ts (regex-only, no deps).
+
+- [dark-mode] Dark mode uses class-based toggling (.dark on root div). @custom-variant dark in global.css. Semantic tokens (background, grid, muted, faint) override via .dark CSS block. bg-white/gray/text-black use explicit dark: variants. Preference stored in localStorage("theme"). Moon/Sun toggle in sidebar header.

.memory/quirks.md

@@ -5,3 +5,9 @@
 - [project-quirks] Project-specific weirdness — the non-obvious stuff.
 
 - [claude-inject-fallback] Claude's `#chat-input-file-upload-onpage` is lazy-rendered — absent on existing chats until the composer is interacted with. Use MutationObserver to wait 2 s for it; fall back to ClipboardEvent paste into ProseMirror `div[contenteditable]` if still absent.
+
+- [storybook10-blocks-import] In Storybook 10, import Meta/ColorPalette/ColorItem from "@storybook/addon-docs/blocks", NOT "@storybook/blocks". The "@storybook/blocks" package is v8-only and breaks Storybook 10.
+
+- [storybook10-render-only-stories] In Storybook 10, render-only showcase stories must use `StoryObj` (no generic) not `StoryObj<typeof meta>`. Using the meta-typed Story for stories with a render function but no args causes TS2322 because Storybook 10 enforces required args.
+
+- [vitest-crx-conflict] vitest browser runner hangs (30s timeout) if crx plugin is included via `extends: true`. Keep vitest config in a separate vitest.config.ts that only includes react + tailwindcss plugins, never crx.

docs/ui-guidelines.md

@@ -0,0 +1,82 @@
+# UI Guidelines & Design System
+
+This document outlines the UI components, styling conventions, design tokens, and best practices for developing HackLM Migrate interfaces.
+
+## 1. Design Tokens and Theming
+
+We use **Tailwind CSS v4** for our styling foundation. Core tokens are stored as CSS variables in `src/styles/global.css`.
+
+### Colors
+- **Background (`bg-background`)**: `#fbfbfb` (Light) / `#111111` (Dark)
+- **Accent (`text-accent`, `bg-accent`)**: `#fb631b` (Primary brand color) / Hover: `#e85310`
+- **Grid / Borders (`border-grid`)**: `#e2e2e2` (Light) / `#2a2a2a` (Dark)
+- **Text (`text-muted`, `text-faint`)**: `#666666`, `#999999` (Light) / `#888888`, `#555555` (Dark)
+
+### Typography
+- **Sans-Serif (`font-sans`)**: `Inter`, default for all regular UI text.
+- **Monospace (`font-mono`)**: `JetBrains Mono`, used for code blocks, badges, and technical readouts.
+
+### Sizing and Spacing
+- **Border Radius (`rounded-sm`)**: Default small radius is `4px` (`--radius-sm`).
+- **Icons**: Handled by `lucide-react`. Standard sizes used are usually `16px` for inline actions and `24px` for larger UI elements.
+
+### Dark Mode
+Dark mode is class-based. It triggers when an ancestor has the `.dark` class (applied via `@custom-variant dark (&:where(.dark, .dark *));`).
+Semantic tokens (like `--color-background`) automatically flip when in dark mode, making it easy to support both modes without writing `dark:` utility classes everywhere.
+
+---
+
+## 2. Core Components
+
+### `HacklmIcon` & `HacklmLogo`
+- **Location**: `src/components/HacklmIcon.tsx`
+- **Usage**: Use this for displaying the brand logo. It dynamically selects the best resolution (`16`, `48`, `128`) based on the requested `size` prop and resolves the path for extension contexts using `chrome.runtime.getURL`.
+- **Example**: `<HacklmLogo size={24} />`
+
+### `MarkdownContent`
+- **Location**: `src/components/MarkdownContent.tsx`
+- **Usage**: Used to render extracted chat messages. Relies on `@tailwindcss/typography` (`prose`).
+- **Styling Details**:
+  - Overrides standard `code` and `pre` tags to utilize `.bg-gray-100` and `font-mono`.
+  - Enforces `break-all` on links to prevent layout overflows.
+  - Horizontal scrolling enabled on tables and code blocks to keep chat bubbles contained.
+
+### `FloatingDial`
+- **Location**: `src/content-scripts/FloatingDial.tsx`
+- **Usage**: The draggable primary Speed-Dial FAB injected into host pages.
+- **Styling Details**:
+  - Because content scripts run in host pages (which might have conflicting CSS), `FloatingDial` leans heavily on **inline styles** for layout positioning and animations to guarantee isolation.
+  - Features high `z-index` (`2147483646` / `2147483647`) to sit above all host content.
+
+---
+
+## 3. Styling Rules & Best Practices
+
+1. **Host Page Isolation (Content Scripts)**: 
+   When building UI injected directly into host pages (like `FloatingDial`), prefer robust inline styles or completely reset shadow-DOM constraints. Relying purely on global Tailwind classes might lead to styles being overridden or bleeding into the host site's CSS.
+2. **Extension Pages (Popup / Options)**:
+   For dedicated extension pages, use standard Tailwind utility classes enthusiastically.
+3. **Accessibility**:
+   Use `lucide-react` icons with appropriate `aria-label` or `title` hints. Ensure interactive elements show visual changes on `hover`, `focus`, and `active` states (e.g., dial buttons have hover background tweaks).
+4. **Animations**:
+   Keep micro-interactions fast and subtle. For example, the `FloatingDial` uses a `0.15s ease` transition for background changes and a staggered entrance animation for child actions.
+5. **No Placeholders**: 
+   Ensure content behaves well when empty. `FloatingDial`'s restore modal gracefully renders an "Empty Vault" state natively.
+
+---
+
+## 4. Component-Driven UI with Storybook
+
+We use [Storybook](https://storybook.js.org/) to develop and test components in isolation. This is especially useful for components like `HacklmIcon` and `MarkdownContent` which can be verified outside the browser extension environment.
+
+### Running Storybook
+To start the local Storybook server:
+
+```bash
+npm run storybook
+```
+
+This will spin up a local server (typically at `http://localhost:6006` or `http://localhost:6007`) where you can interact with the documented components, toggle dark mode, and verify Tailwind styling.
+
+### Writing Stories
+When creating new reusable UI components in `src/components`, consider adding a `.stories.tsx` file alongside them. See `src/components/HacklmIcon.stories.tsx` or `src/components/MarkdownContent.stories.tsx` for examples.

vite.config.ts

@@ -12,6 +12,7 @@ import path from "node:path";
  * This plugin rewrites the file after bundling to import the actual
  * built background chunk.
  */
+
 function fixServiceWorkerLoader(): Plugin {
   return {
     name: "fix-service-worker-loader",
@@ -21,49 +22,43 @@ function fixServiceWorkerLoader(): Plugin {
       const outDir = path.resolve(__dirname, "dist");
       const loaderPath = path.join(outDir, "service-worker-loader.js");
       const assetsDir = path.join(outDir, "assets");
-
       if (!fs.existsSync(loaderPath) || !fs.existsSync(assetsDir)) return;
 
       // CRXJS names the background bundle after its entry: index.ts-<hash>.js
-      const bgBundle = fs
-        .readdirSync(assetsDir)
-        .find((f) => /^index\.ts-.*\.js$/.test(f));
-
+      const bgBundle = fs.readdirSync(assetsDir).find(f => /^index\.ts-.*\.js$/.test(f));
       if (!bgBundle) {
         console.warn("[fix-service-worker-loader] background bundle not found");
         return;
       }
-
       fs.writeFileSync(loaderPath, `import './assets/${bgBundle}';\n`);
-      console.log(
-        `[fix-service-worker-loader] rewrote loader → assets/${bgBundle}`
-      );
-    },
+      console.log(`[fix-service-worker-loader] rewrote loader → assets/${bgBundle}`);
+    }
   };
 }
-
 export default defineConfig({
-  plugins: [react(), tailwindcss(), crx({ manifest }), fixServiceWorkerLoader()],
+  plugins: [react(), tailwindcss(), crx({
+    manifest
+  }), fixServiceWorkerLoader()],
   server: {
     /* Allow the Chrome extension's service worker (chrome-extension://<id>)
      * to fetch @vite/env, HMR scripts, and other dev-server resources.
      * Without this, service worker registration fails in dev mode with
      * "Status code: 3" and a CORS error. */
     cors: {
       origin: ["chrome-extension://*", /^chrome-extension:\/\//],
-      methods: ["GET", "HEAD"],
+      methods: ["GET", "HEAD"]
     },
     headers: {
-      "Access-Control-Allow-Origin": "*",
-    },
+      "Access-Control-Allow-Origin": "*"
+    }
   },
   build: {
     outDir: "dist",
     rollupOptions: {
       input: {
         options: "src/options/index.html",
-        popup: "src/popup/index.html",
-      },
-    },
-  },
-});
+        popup: "src/popup/index.html"
+      }
+    }
+  }
+});