diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b8481791a..39ccbd32e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -655,14 +655,28 @@ Launch with `mode: "plan"` to produce a PRD before writing code. Plan Mode restr
 
 ## Tests
 
-Tests live next to the code they cover under `electron/`:
+Tests live next to the code they cover, under both `electron/` (store/lib/MCP logic) and `src/` (store slices, pure libs, and React components):
 
 ```bash
 npm test                  # run all tests
 npm run test:watch        # watch mode — great for TDD
 npm run test:coverage     # coverage report
+npm run test:unit         # node project only (store/lib/electron logic)
+npm run test:component    # component project only (React + jsdom)
 ```
 
+vitest runs **two projects** (see `vitest.config.ts`):
+
+- **`node`** — the default fast suite for store slices, pure libs, and the
+  electron/MCP layer. Runs in the `node` environment with the native SQLite
+  shim. Matches `electron/**/*.test.ts`, `src/**/*.test.ts`, and
+  `src/**/*.test.tsx`, excluding component tests (`src/**/*.component.test.tsx`).
+- **`component`** — React component tests rendered in **jsdom** via
+  `@testing-library/react`. Matches `src/**/*.component.test.tsx` and loads
+  `vitest.setup.components.ts` (jest-dom matchers + auto-cleanup). Use these for
+  presentational behavior (disabled states, ARIA attributes, click handlers).
+  Store-connected components can mock `@/store` with `vi.mock`.
+
 | Test file | What it covers |
 |-----------|---------------|
 | `electron/db/queries.test.ts` | SQLite query helpers — CRUD, search, soft-delete |
diff --git a/changelogs/v2.3.3.md b/changelogs/v2.3.3.md
new file mode 100644
index 000000000..f95ec378b
--- /dev/null
+++ b/changelogs/v2.3.3.md
@@ -0,0 +1,26 @@
+## What's new
+
+A quality release that hardens the test suite around the v2.3.2 features and adds a React component-testing harness, plus two Markdown bug fixes.
+
+### Bug fixes
+
+- **Clickable checkboxes inside tables**: Task-list checkboxes (`[ ]` / `[x]`) placed inside a Markdown table cell now render as real, clickable checkboxes and toggle the underlying source — previously they stayed as plain text. (GFM doesn't emit checkboxes inside table cells, so the preview now recovers them via custom `td`/`th` rendering, with toggling mapped back to source in document order across both list-item and table-cell checkboxes.)
+- **Ordered-list numbering in the editor**: The note editor now auto-continues and renumbers ordered/bulleted lists on Enter, exits the list cleanly from an empty item, and renumbers correctly on Backspace. Previously breaking the numbering left the list out of order.
+
+### Changes
+
+- **Shared "What's New" gate**: Extracted the duplicated "unseen latest features" logic (previously copy-pasted in `NewFeatureModal` and the boot path in `page.tsx`) into a single pure `getUnseenLatestFeatures(registry, seenFeatures, forceOpen?)`. Both call sites now share one implementation, eliminating drift between the modal and the tour-deferral gate. No behavior change.
+
+### Tests
+
+- **Component test harness**: Added a second vitest project (`component`) running **jsdom + Testing Library** alongside the existing `node` project, plus `npm run test:unit` / `npm run test:component` scripts and a jest-dom setup file. Component tests live in `*.component.test.tsx`.
+- **Onboarding component tests**: `StepCreateProject` — submit gating on empty/whitespace names, icon picker selection and `aria-pressed` state, accessible labels on icon-only buttons, and all controls (back, skip, icon picker) disabled while a create is in flight.
+- **What's New modal component tests**: boot gating (unseen shows, seen hidden), "Done" marks the feature seen and closes, and — via the `forceOpen` (Settings) path — pagination dots, Next navigation, and "Skip All" marking every displayed feature seen.
+- **Feature-gate unit tests**: full coverage of `getUnseenLatestFeatures` (forceOpen, empty registry, latest-version-only filtering, seen filtering, order-derived latest version).
+- **Store & pure-logic unit tests**:
+  - `createProject` — icon persistence (the v2.3.2 onboarding fix), icon omitted when absent, the 5 optimistic columns with correct types/orders, and append-not-replace semantics.
+  - UI slice tour/seen-feature actions — `markFeatureAsSeen` (append/idempotent), `setTutorialActive` (with its step-index reset), `setTutorialStepIndex`.
+  - Board slice — `moveCard` (same/cross-column reindex, index clamping, untouched columns) and `getReadyCards` (blocker resolution, done/archived handling, orphan blockers, project scoping).
+  - `buildFolderTree` — folder-path normalization edge cases (undefined vs empty, leading/trailing/double slashes, deep nesting, alphabetical sort).
+  - `searchAll` — empty-query, title/content/description matching, snippet length, archived skipping, 50-result cap.
+  - Date helpers — `formatRelative` thresholds and `getDueDateStatus` (timezone-robust day comparison).
\ No newline at end of file
diff --git a/electron/ipc/registry.test.ts b/electron/ipc/registry.test.ts
new file mode 100644
index 000000000..9df9a5ad9
--- /dev/null
+++ b/electron/ipc/registry.test.ts
@@ -0,0 +1,86 @@
+/**
+ * Unit tests for the registry's read/write channel classification.
+ *
+ * `isWriteChannel` decides whether a completed `db:*` channel auto-broadcasts
+ * `db:changed` (a full snapshot re-hydration in every window + mobile client).
+ * Misclassifying a read as a write causes a silent re-hydration storm, so this
+ * guards the convention: reads (by action verb or the small irregular-name set)
+ * must never broadcast; everything else `db:*` does.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+
+// registry.ts imports `electron` at module load; stub the bits it touches so the
+// pure classifier can be imported in the node test environment.
+vi.mock("electron", () => ({
+  ipcMain: { handle: vi.fn(), on: vi.fn() },
+  BrowserWindow: { getAllWindows: () => [] },
+}));
+
+import { __isWriteChannel as isWriteChannel } from "./registry";
+
+describe("isWriteChannel", () => {
+  it("treats non-db channels as non-writes (they never broadcast db:changed)", () => {
+    for (const c of ["app:setTheme", "git:status", "chat:stream", "updater:install"]) {
+      expect(isWriteChannel(c)).toBe(false);
+    }
+  });
+
+  it("classifies write actions as writes", () => {
+    const writes = [
+      "db:note:create",
+      "db:note:update",
+      "db:note:delete",
+      "db:note:moveToFolder",
+      "db:card:addBlocker",
+      "db:card:removeBlocker",
+      "db:cards:archive-done",
+      "db:chat:addMessage",
+      "db:chat:upsertThread",
+      "db:chat:deleteThread",
+      "db:chat:clearThreadMessages",
+      "db:project:updateSettings",
+      "db:piSession:saveMessages",
+      "db:graph:recompute",
+      "db:embeddings:reindex",
+      "db:embeddings:recomputeProjections",
+      "db:flow:node:update",
+      "db:flow:node:delete",
+      "db:flow:edge:delete",
+    ];
+    for (const c of writes) expect(isWriteChannel(c)).toBe(true);
+  });
+
+  it("classifies read actions as reads (no broadcast)", () => {
+    const reads = [
+      "db:workspace:list",
+      "db:project:list",
+      "db:note:list",
+      "db:column:list",
+      "db:card:list",
+      "db:card:ready",
+      "db:flow:get",
+      "db:graph:get",
+      "db:graph:neighbors",
+      "db:tag:list",
+      "db:chat:threads",
+      "db:chat:messages",
+      "db:piSession:list",
+      "db:piSession:messages",
+      "db:embeddings:search",
+    ];
+    for (const c of reads) expect(isWriteChannel(c)).toBe(false);
+  });
+
+  it("classifies irregularly-named read channels as reads", () => {
+    for (const c of ["db:snapshot", "db:hasData", "db:mcpQuery"]) {
+      expect(isWriteChannel(c)).toBe(false);
+    }
+  });
+
+  it("does not broadcast for db:flow:url:fetch — a pure URL-metadata read (regression)", () => {
+    // Previously misclassified as a write because it wasn't in the denylist,
+    // causing a db:changed re-hydration on every URL preview.
+    expect(isWriteChannel("db:flow:url:fetch")).toBe(false);
+  });
+});
diff --git a/electron/ipc/registry.ts b/electron/ipc/registry.ts
index 214e64b0c..9048f6f62 100644
--- a/electron/ipc/registry.ts
+++ b/electron/ipc/registry.ts
@@ -29,33 +29,50 @@ const listeners = new Map<string, IpcHandler>();
 
 let mobileBroadcastCallback: ((channel: string, payload: unknown) => void) | null = null;
 
-function isWriteChannel(channel: string): boolean {
-  if (!channel.startsWith("db:")) return false;
+/**
+ * Decide whether a completed `db:*` channel should auto-broadcast `db:changed`
+ * (which triggers a full snapshot re-hydration in every window + mobile client).
+ *
+ * Write channels broadcast; read channels must NOT. The previous implementation
+ * was a pure denylist of read channels, defaulting any *unlisted* `db:*` channel
+ * to "write" — so a forgotten read channel would silently fire `db:changed` on
+ * every call (a re-hydration storm that never errors, just wastes work).
+ *
+ * The codebase follows a strict `db:<entity>:<action>` naming convention, so we
+ * primarily classify by the trailing action verb: reads are the well-known
+ * read verbs below. A small denylist of irregularly-named read channels
+ * (e.g. `db:chat:threads`, `db:snapshot`) covers the cases that don't end in a
+ * read verb. Anything else is treated as a write.
+ */
+const READ_ACTIONS = new Set([
+  "list",
+  "get",
+  "search",
+  "neighbors",
+  "ready",
+  "messages",
+  "threads",
+  "fetch", // db:flow:url:fetch — fetches URL metadata, no DB write
+]);
 
-  const readChannels = [
-    "db:snapshot",
-    "db:hasData",
-    "db:workspace:list",
-    "db:project:list",
-    "db:note:list",
-    "db:column:list",
-    "db:card:list",
-    "db:card:ready",
-    "db:flow:get",
-    "db:tag:list",
-    "db:chat:threads",
-    "db:chat:messages",
-    "db:piSession:list",
-    "db:piSession:messages",
-    "db:graph:get",
-    "db:graph:neighbors",
-    "db:embeddings:search",
-    "db:mcpQuery"
-  ];
+// Read channels whose names don't end in a recognised read verb.
+const READ_CHANNELS = new Set([
+  "db:snapshot",
+  "db:hasData",
+  "db:mcpQuery",
+]);
 
-  return !readChannels.includes(channel);
+function isWriteChannel(channel: string): boolean {
+  if (!channel.startsWith("db:")) return false;
+  if (READ_CHANNELS.has(channel)) return false;
+  const action = channel.slice(channel.lastIndexOf(":") + 1);
+  if (READ_ACTIONS.has(action)) return false;
+  return true;
 }
 
+/** Exported for unit testing the read/write classification. */
+export const __isWriteChannel = isWriteChannel;
+
 /**
  * Register a handler that maps to ipcMain.handle.
  */
diff --git a/electron/splash/bootsplash.ts b/electron/splash/bootsplash.ts
index 748836a9c..0a8f6c085 100644
--- a/electron/splash/bootsplash.ts
+++ b/electron/splash/bootsplash.ts
@@ -79,8 +79,14 @@ function getAppVersion(): string {
   }
 }
 
-function buildSplashHtml(iconDataUrl: string | null): string {
+function buildSplashHtml(iconDataUrl: string | null, colors: Record<string, string>): string {
   const version = getAppVersion();
+  // Bake the resolved theme palette into the initial CSS so the splash paints
+  // with the correct (light or dark) colors on first frame — no dark flash
+  // before the post-load `splash:theme` IPC override arrives.
+  const initialVars = Object.keys(colors)
+    .map((key) => `    --splash-${key}: ${colors[key]};`)
+    .join("\n");
   const logoHtml = iconDataUrl
     ? `<img src="${iconDataUrl}" width="64" height="64" alt="Cairn" />`
     : `<div style="width:64px;height:64px;border-radius:12px;background:var(--splash-accent);display:flex;align-items:center;justify-content:center;font-size:1.5rem;font-weight:700;color:var(--splash-background);">C</div>`;
@@ -93,6 +99,9 @@ function buildSplashHtml(iconDataUrl: string | null): string {
 <title>Cairn</title>
 <style>
   * { margin: 0; padding: 0; box-sizing: border-box; }
+  :root {
+${initialVars}
+  }
   html, body {
     height: 100%; width: 100%;
     overflow: hidden;
@@ -103,13 +112,7 @@ function buildSplashHtml(iconDataUrl: string | null): string {
     display: flex; flex-direction: column;
     align-items: center; justify-content: center;
     padding: 48px 32px;
-    --splash-text: #e8e8e8;
-    --splash-text-dim: #666;
-    --splash-accent: #8b7bd8;
-    --splash-progress-bg: #222;
-    --splash-success: #22c55e;
-    --splash-error: #ef4444;
-    --splash-background: #0d0d0d;
+    background: var(--splash-background);
   }
   .logo {
     width: 64px; height: 64px;
@@ -310,34 +313,36 @@ function buildSplashHtml(iconDataUrl: string | null): string {
 }
 
 function getThemeColors(): Record<string, string> {
+  // Mirrors the app's real design tokens in src/app/globals.css so the splash
+  // matches the window that follows it (light branch = [data-theme="light"]).
+  const light: Record<string, string> = {
+    text: "#1a1917",          // --text-primary (light)
+    "text-dim": "#9e9a94",    // --text-tertiary (light)
+    accent: "#6457e8",        // --accent (light)
+    "progress-bg": "#f0eeeb", // --surface-2 (light)
+    success: "#1a9e68",       // --success (light)
+    error: "#dc2626",         // --danger (light)
+    background: "#f5f4f1",    // --background (light)
+  };
+  const dark: Record<string, string> = {
+    text: "#e8e4dc",          // --text-primary (dark)
+    "text-dim": "#66635f",    // --text-tertiary (dark)
+    accent: "#7c6af7",        // --accent (dark)
+    "progress-bg": "#1a1a1a", // --surface-2 (dark)
+    success: "#3ecf8e",       // --success (dark)
+    error: "#ef4444",         // --danger (dark)
+    background: "#0d0d0d",    // --background (dark)
+  };
   try {
     const themeFile = path.join(app.getPath("userData"), "theme.json");
     if (fs.existsSync(themeFile)) {
       const t = JSON.parse(fs.readFileSync(themeFile, "utf8")).theme;
-      if (t === "light") {
-        return {
-          text: "#1a1a1a",
-          "text-dim": "#888",
-          accent: "#6366f1",
-          "progress-bg": "#e0e0e0",
-          success: "#22c55e",
-          error: "#ef4444",
-          background: "#f5f4f1",
-        };
-      }
+      if (t === "light") return light;
     }
   } catch {
     // ignore — use dark defaults
   }
-  return {
-    text: "#e8e8e8",
-    "text-dim": "#666",
-    accent: "#8b7bd8",
-    "progress-bg": "#222",
-    success: "#22c55e",
-    error: "#ef4444",
-    background: "#0d0d0d",
-  };
+  return dark;
 }
 
 export class BootSplash {
@@ -364,7 +369,7 @@ export class BootSplash {
 
     this.win.loadURL(
       "data:text/html;charset=utf-8," +
-        encodeURIComponent(buildSplashHtml(getIconDataUrl())),
+        encodeURIComponent(buildSplashHtml(getIconDataUrl(), colors)),
     );
 
     this.win.webContents.on("did-finish-load", () => {
diff --git a/package-lock.json b/package-lock.json
index 0ddbf5849..c9e57f396 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -59,12 +59,17 @@
         "@radix-ui/react-select": "^2.2.6",
         "@radix-ui/react-tooltip": "^1.2.8",
         "@tailwindcss/postcss": "^4",
+        "@testing-library/dom": "^10.4.1",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
         "@types/better-sqlite3": "^7.6.13",
         "@types/d3-sankey": "^0.12.5",
         "@types/node": "^22.20.0",
         "@types/qrcode": "^1.5.6",
         "@types/react": "^19",
         "@types/react-dom": "^19",
+        "@vitejs/plugin-react": "^6.0.3",
         "@vitest/coverage-v8": "^4.1.5",
         "@yao-pkg/pkg": "^6.19.0",
         "ai": "^7.0.4",
@@ -82,6 +87,7 @@
         "eslint-config-next": "16.2.9",
         "gpt-tokenizer": "^3.4.0",
         "gray-matter": "^4.0.3",
+        "jsdom": "^29.1.1",
         "lowlight": "^3.3.0",
         "lucide-react": "^1.11.0",
         "nanoid": "^5.1.9",
@@ -100,6 +106,13 @@
         "zustand": "^5.0.12"
       }
     },
+    "node_modules/@adobe/css-tools": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/@adobe/css-tools/-/css-tools-4.5.0.tgz",
+      "integrity": "sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@ai-sdk/gateway": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/@ai-sdk/gateway/-/gateway-4.0.4.tgz",
@@ -176,6 +189,57 @@
         "url": "https://github.com/sponsors/antfu"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "5.1.11",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz",
+      "integrity": "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@csstools/css-calc": "^3.2.0",
+        "@csstools/css-color-parser": "^4.1.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.1.1.tgz",
+      "integrity": "sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@asamuzakjp/nwsapi": "^2.3.9",
+        "bidi-js": "^1.0.3",
+        "css-tree": "^3.2.1",
+        "is-potential-custom-element-name": "^1.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/generational-cache": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz",
+      "integrity": "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/nwsapi": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
+      "integrity": "sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.29.7",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz",
@@ -388,6 +452,16 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz",
+      "integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/template": {
       "version": "7.29.7",
       "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.29.7.tgz",
@@ -452,6 +526,19 @@
       "integrity": "sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA==",
       "license": "MIT"
     },
+    "node_modules/@bramus/specificity": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
+      "integrity": "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.0.0"
+      },
+      "bin": {
+        "specificity": "bin/cli.js"
+      }
+    },
     "node_modules/@chevrotain/types": {
       "version": "11.1.2",
       "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz",
@@ -886,6 +973,146 @@
         "w3c-keyname": "^2.2.4"
       }
     },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.1.0.tgz",
+      "integrity": "sha512-064IFJdjTfUqnjpCVpMOdbr8FLQBhinbZj6yRv2An2E41O/pLEXqfFRWqGq/SxlE5PEUYTlvWsG2r8MswAVvkg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.1.tgz",
+      "integrity": "sha512-DtdHlgXh5ZkA43cwBcAm+huzgJiwx3ZTWVjBs94kwz2xKqSimDA3lBgCjphYgwgVUMWatSM0pDd8TILB1yrVVg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.9.tgz",
+      "integrity": "sha512-paQcIaOO53Rk5+YrBaBjm/SgrV4INImjo2BT1DtQRYr+XeTRbeAYlS+jxXp9drqvKmtFnWRJKIalDLhZZDu42A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.1.0",
+        "@csstools/css-calc": "^3.2.1"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.5.tgz",
+      "integrity": "sha512-oNjBvzLq2GPZtJphCjLqXow/cHySHSgtxvKZb7OqSZ/xHgw6NWNhfad+6AB9cLeVm6eA9d/qMll3JdEHjy6M+A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "peerDependencies": {
+        "css-tree": "^3.2.1"
+      },
+      "peerDependenciesMeta": {
+        "css-tree": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.0.tgz",
+      "integrity": "sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
     "node_modules/@dagrejs/dagre": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/@dagrejs/dagre/-/dagre-3.0.0.tgz",
@@ -1868,6 +2095,24 @@
         "node": "^20.19.0 || ^22.13.0 || >=24"
       }
     },
+    "node_modules/@exodus/bytes": {
+      "version": "1.15.1",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.1.tgz",
+      "integrity": "sha512-S6mL0yNB/Abt9Ei4tq8gDhcczc4S3+vQ4ra7vxnAf+YHC02srtqxKKZghx2Dq6p0e66THKwR6r8N6P95wEty7Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@floating-ui/core": {
       "version": "1.7.5",
       "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.5.tgz",
@@ -4219,6 +4464,105 @@
         "tailwindcss": "4.3.1"
       }
     },
+    "node_modules/@testing-library/dom": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
+      "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.10.4",
+        "@babel/runtime": "^7.12.5",
+        "@types/aria-query": "^5.0.1",
+        "aria-query": "5.3.0",
+        "dom-accessibility-api": "^0.5.9",
+        "lz-string": "^1.5.0",
+        "picocolors": "1.1.1",
+        "pretty-format": "^27.0.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@testing-library/dom/node_modules/aria-query": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "dequal": "^2.0.3"
+      }
+    },
+    "node_modules/@testing-library/jest-dom": {
+      "version": "6.9.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/jest-dom/-/jest-dom-6.9.1.tgz",
+      "integrity": "sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@adobe/css-tools": "^4.4.0",
+        "aria-query": "^5.0.0",
+        "css.escape": "^1.5.1",
+        "dom-accessibility-api": "^0.6.3",
+        "picocolors": "^1.1.1",
+        "redent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=14",
+        "npm": ">=6",
+        "yarn": ">=1"
+      }
+    },
+    "node_modules/@testing-library/jest-dom/node_modules/dom-accessibility-api": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.6.3.tgz",
+      "integrity": "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@testing-library/react": {
+      "version": "16.3.2",
+      "resolved": "https://registry.npmjs.org/@testing-library/react/-/react-16.3.2.tgz",
+      "integrity": "sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.12.5"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": "^10.0.0",
+        "@types/react": "^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^18.0.0 || ^19.0.0",
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@testing-library/user-event": {
+      "version": "14.6.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.1.tgz",
+      "integrity": "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12",
+        "npm": ">=6"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": ">=7.21.4"
+      }
+    },
     "node_modules/@tweenjs/tween.js": {
       "version": "25.0.0",
       "resolved": "https://registry.npmjs.org/@tweenjs/tween.js/-/tween.js-25.0.0.tgz",
@@ -4236,6 +4580,13 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@types/aria-query": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
+      "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/better-sqlite3": {
       "version": "7.6.13",
       "resolved": "https://registry.npmjs.org/@types/better-sqlite3/-/better-sqlite3-7.6.13.tgz",
@@ -5312,6 +5663,32 @@
         "node": ">= 20"
       }
     },
+    "node_modules/@vitejs/plugin-react": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-6.0.3.tgz",
+      "integrity": "sha512-vmFvco5/QuC2f9Oj+wTk0+9XeDFkHxSamwZKYc7MxYwKICfvUvlMhqKI0VuICPltGqh1neqBKDvO4kes1ya8vg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rolldown/pluginutils": "^1.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "@rolldown/plugin-babel": "^0.1.7 || ^0.2.0",
+        "babel-plugin-react-compiler": "^1.0.0",
+        "vite": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@rolldown/plugin-babel": {
+          "optional": true
+        },
+        "babel-plugin-react-compiler": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@vitest/coverage-v8": {
       "version": "4.1.9",
       "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.9.tgz",
@@ -6972,6 +7349,16 @@
         "url": "https://github.com/Pomax/bezierjs/blob/master/FUNDING.md"
       }
     },
+    "node_modules/bidi-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
+      "integrity": "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
     "node_modules/bindings": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
@@ -7934,6 +8321,27 @@
         "node": ">= 8"
       }
     },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/css.escape": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/css.escape/-/css.escape-1.5.1.tgz",
+      "integrity": "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/csstype": {
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
@@ -8475,6 +8883,58 @@
       "dev": true,
       "license": "BSD-2-Clause"
     },
+    "node_modules/data-urls": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
+      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/data-urls/node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/data-urls/node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/data-urls/node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/data-view-buffer": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/data-view-buffer/-/data-view-buffer-1.0.2.tgz",
@@ -8571,6 +9031,13 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/decode-named-character-reference": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz",
@@ -8807,6 +9274,13 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/dom-accessibility-api": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/dompurify": {
       "version": "3.4.11",
       "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.11.tgz",
@@ -11436,6 +11910,19 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
+      "integrity": "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.6.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/html-escaper": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
@@ -11610,6 +12097,16 @@
         "node": ">=0.8.19"
       }
     },
+    "node_modules/indent-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
+      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/index-array-by": {
       "version": "1.4.2",
       "resolved": "https://registry.npmjs.org/index-array-by/-/index-array-by-1.4.2.tgz",
@@ -12065,6 +12562,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/is-promise": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
@@ -12409,6 +12913,121 @@
         "js-yaml": "bin/js-yaml.js"
       }
     },
+    "node_modules/jsdom": {
+      "version": "29.1.1",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-29.1.1.tgz",
+      "integrity": "sha512-ECi4Fi2f7BdJtUKTflYRTiaMxIB0O6zfR1fX0GXpUrf6flp8QIYn1UT20YQqdSOfk2dfkCwS8LAFoJDEppNK5Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^5.1.11",
+        "@asamuzakjp/dom-selector": "^7.1.1",
+        "@bramus/specificity": "^2.4.2",
+        "@csstools/css-syntax-patches-for-csstree": "^1.1.3",
+        "@exodus/bytes": "^1.15.0",
+        "css-tree": "^3.2.1",
+        "data-urls": "^7.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^6.0.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.3.5",
+        "parse5": "^8.0.1",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^6.0.1",
+        "undici": "^7.25.0",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^8.0.1",
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.1",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.0.0"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/jsdom/node_modules/entities": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-8.0.0.tgz",
+      "integrity": "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/jsdom/node_modules/lru-cache": {
+      "version": "11.5.1",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.1.tgz",
+      "integrity": "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/jsdom/node_modules/parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^8.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/jsdom/node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/jsdom/node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/jsdom/node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/jsesc": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@@ -13007,6 +13626,16 @@
         "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/lz-string": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
+      "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "lz-string": "bin/bin.js"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -13417,6 +14046,13 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "dev": true,
+      "license": "CC0-1.0"
+    },
     "node_modules/media-typer": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
@@ -14197,6 +14833,16 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/min-indent": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz",
+      "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/minimatch": {
       "version": "10.2.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
@@ -15483,6 +16129,41 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/pretty-format": {
+      "version": "27.5.1",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+      "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^17.0.1"
+      },
+      "engines": {
+        "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0"
+      }
+    },
+    "node_modules/pretty-format/node_modules/ansi-styles": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/pretty-format/node_modules/react-is": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
+      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/proc-log": {
       "version": "6.1.0",
       "resolved": "https://registry.npmjs.org/proc-log/-/proc-log-6.1.0.tgz",
@@ -16119,6 +16800,20 @@
         "url": "https://paulmillr.com/funding/"
       }
     },
+    "node_modules/redent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz",
+      "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "indent-string": "^4.0.0",
+        "strip-indent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/reflect.getprototypeof": {
       "version": "1.0.10",
       "resolved": "https://registry.npmjs.org/reflect.getprototypeof/-/reflect.getprototypeof-1.0.10.tgz",
@@ -16694,6 +17389,19 @@
         "node": ">=11.0.0"
       }
     },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
     "node_modules/scheduler": {
       "version": "0.27.0",
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
@@ -17404,6 +18112,19 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/strip-indent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
+      "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "min-indent": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/style-mod": {
       "version": "4.1.3",
       "resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.3.tgz",
@@ -17499,6 +18220,13 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tailwind-merge": {
       "version": "3.6.0",
       "resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.6.0.tgz",
@@ -17708,6 +18436,26 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/tldts": {
+      "version": "7.4.4",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.4.4.tgz",
+      "integrity": "sha512-kFXFK7O4WPextIUAOk8qtnw9dxR9UIXP9CjuH1cTBVBZMDeQcUPgr/IazGiw1B0Yiw5L75gHLWeW4iD793r90g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.4.4"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.4.4",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.4.4.tgz",
+      "integrity": "sha512-vwVLJVvvpslm7vqAH7+XNj/neA/Ynq7DT2EEcMuwc5YzN5XaMyRAqxwU+uX3azZ1FQtB2gvrvnLnAEkvYlVdfg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tmp": {
       "version": "0.2.7",
       "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.7.tgz",
@@ -17751,6 +18499,19 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/tough-cookie": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.1.tgz",
+      "integrity": "sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
     "node_modules/tr46": {
       "version": "0.0.3",
       "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
@@ -18075,7 +18836,6 @@
       "integrity": "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==",
       "dev": true,
       "license": "MIT",
-      "optional": true,
       "engines": {
         "node": ">=20.18.1"
       }
@@ -18649,6 +19409,19 @@
       "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
       "license": "MIT"
     },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/wait-on": {
       "version": "9.0.10",
       "resolved": "https://registry.npmjs.org/wait-on/-/wait-on-9.0.10.tgz",
@@ -18700,6 +19473,16 @@
       "dev": true,
       "license": "BSD-2-Clause"
     },
+    "node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/whatwg-url": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
@@ -18873,6 +19656,16 @@
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "license": "ISC"
     },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/xmlbuilder": {
       "version": "15.1.1",
       "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
@@ -18883,6 +19676,13 @@
         "node": ">=8.0"
       }
     },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
diff --git a/package.json b/package.json
index 820fe9f09..6f4a27a64 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,8 @@
   "scripts": {
     "test": "npm run compile && vitest run",
     "test:fast": "vitest run",
+    "test:unit": "vitest run --project node",
+    "test:component": "vitest run --project component",
     "test:watch": "vitest",
     "test:coverage": "npm run compile && vitest run --coverage",
     "dev": "node scripts/generate-licenses.js && concurrently -n next,esbuild,electron -c cyan,magenta,yellow \"next dev\" \"npm run compile:watch\" \"wait-on http://localhost:3000 dist-electron/main.js && node scripts/electron-dev.js\"",
@@ -89,12 +91,17 @@
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@tailwindcss/postcss": "^4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/d3-sankey": "^0.12.5",
     "@types/node": "^22.20.0",
     "@types/qrcode": "^1.5.6",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.5",
     "@yao-pkg/pkg": "^6.19.0",
     "ai": "^7.0.4",
@@ -112,6 +119,7 @@
     "eslint-config-next": "16.2.9",
     "gpt-tokenizer": "^3.4.0",
     "gray-matter": "^4.0.3",
+    "jsdom": "^29.1.1",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.11.0",
     "nanoid": "^5.1.9",
diff --git a/src/app/globals.css b/src/app/globals.css
index 705f82a39..bce035637 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -18,6 +18,10 @@
   --accent: #7c6af7;
   --accent-hover: #9281ff;
   --accent-dim: rgba(124, 106, 247, 0.15);
+  /* Dark accent (#7c6af7) is too light for white text at small sizes (only
+     3.99:1, fails AA). A near-black foreground reaches 4.75:1. Light theme
+     keeps #ffffff (5.16:1 on its darker accent). */
+  --accent-fg: #16082e;
   --muted: #666360;
   --muted-fg: #a09c96;
   --text-primary: #e8e4dc;
@@ -42,6 +46,7 @@
   --accent: #6457e8;
   --accent-hover: #7c6af7;
   --accent-dim: rgba(100, 87, 232, 0.12);
+  --accent-fg: #ffffff;
   --muted: #a09c96;
   --muted-fg: #66635f;
   --text-primary: #1a1917;
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 0ea0657c5..b59287438 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useState, useRef } from "react";
+import React, { useEffect, useState, useRef } from "react";
 import { useCairnStore } from "@/store";
 import { useShallow } from "zustand/react/shallow";
 import { CairnEvents } from "@/lib/events";
@@ -26,6 +26,7 @@ import { NewFeatureModal } from "@/components/layout/NewFeatureModal";
 import { AppTutorial } from "@/components/tutorial/AppTutorial";
 import { cn } from "@/lib/utils";
 import { NEW_FEATURES_REGISTRY } from "@/lib/new-features-registry";
+import { completeOnboarding } from "@/lib/complete-onboarding";
 
 export default function Home() {
   const [pendingTutorial, setPendingTutorial] = useState(false);
@@ -329,25 +330,14 @@ export default function Home() {
           <Onboarding
             initialStep={initialStep}
             onComplete={(startTour) => {
-              hydrateFromElectron().then(() => {
-                setOnboardingState(false);
-                if (startTour) {
-                  const state = useCairnStore.getState();
-                  // Match NewFeatureModal's gating: only unseen features from the latest
-                  // registry version defer the tour. Older unseen entries are ignored.
-                  const latestVersion = NEW_FEATURES_REGISTRY.length > 0
-                    ? NEW_FEATURES_REGISTRY[NEW_FEATURES_REGISTRY.length - 1].version
-                    : null;
-                  const hasUnseenLatest = latestVersion !== null
-                    && NEW_FEATURES_REGISTRY.some(
-                      (f) => f.version === latestVersion && !state.seenFeatures.includes(f.id)
-                    );
-                  if (hasUnseenLatest) {
-                    setPendingTutorial(true);
-                  } else {
-                    state.setTutorialActive(true);
-                  }
-                }
+              const state = useCairnStore.getState();
+              completeOnboarding(startTour, {
+                hydrateFromElectron,
+                setOnboardingState,
+                setPendingTutorial,
+                setTutorialActive: state.setTutorialActive,
+                getSeenFeatures: () => useCairnStore.getState().seenFeatures,
+                registry: NEW_FEATURES_REGISTRY,
               });
             }}
           />
@@ -357,8 +347,20 @@ export default function Home() {
   }
 
   // Main app
+  // Top offset for fixed-position chrome (the chat panel): the title bar
+  // occupies 41px (40px + 1px bottom border, both font-scale-independent), plus
+  // the update banner when visible. The banner is `h-9` (2.25rem) in
+  // app-chrome.tsx, so we add the SAME rem-based height here — a hard-coded px
+  // value would drift from the banner's real size under applyFontScale() /
+  // --font-scale root sizing. The chat panel anchors to this so it never
+  // overlaps the banner's download button and aligns with the Topbar.
+  const updateBannerVisible = !!(updateVersion || updateDownloaded);
+  const chromeTop = updateBannerVisible ? "calc(41px + 2.25rem)" : "41px";
   return (
-    <main className="flex flex-col h-dvh w-screen overflow-hidden bg-[var(--background)]">
+    <main
+      className="flex flex-col h-dvh w-screen overflow-hidden bg-[var(--background)]"
+      style={{ "--chrome-top": chromeTop } as React.CSSProperties}
+    >
       {/* Electron title bar — draggable, clears macOS traffic lights */}
       <TitleBar />
 
diff --git a/src/components/agent/AgentMessageBubble.tsx b/src/components/agent/AgentMessageBubble.tsx
index 5b9d50f95..4469289ec 100644
--- a/src/components/agent/AgentMessageBubble.tsx
+++ b/src/components/agent/AgentMessageBubble.tsx
@@ -253,8 +253,8 @@ export const AgentMessageBubble = React.memo(function AgentMessageBubble({ messa
     return (
       <div className="flex gap-2 items-start justify-end">
         <div className="flex-1 min-w-0 flex flex-col items-end gap-1">
-          <div className="px-3 py-2 rounded-xl rounded-tr-sm text-xs leading-relaxed bg-[var(--accent)] text-white max-w-[85%]">
-            <MarkdownContent content={message.content} />
+          <div className="px-3 py-2 rounded-xl rounded-tr-sm text-xs leading-relaxed bg-[var(--accent)] text-[var(--accent-fg)] max-w-[85%]">
+            <MarkdownContent content={message.content} isUser />
           </div>
         </div>
         <MessageAvatar role="user" size="md" />
diff --git a/src/components/chat/UnifiedChatPanel.tsx b/src/components/chat/UnifiedChatPanel.tsx
index d6f17bfc6..25316a2eb 100644
--- a/src/components/chat/UnifiedChatPanel.tsx
+++ b/src/components/chat/UnifiedChatPanel.tsx
@@ -125,7 +125,7 @@ export function UnifiedChatPanel({ prefill, onPrefillConsumed }: UnifiedChatPane
     <aside
       ref={panelRef}
       className={cn(
-        "fixed top-[40px] bottom-0 z-30 flex overflow-hidden",
+        "fixed top-[var(--chrome-top,41px)] bottom-0 z-30 flex overflow-hidden",
         !chatPanelResizing && "transition-all duration-300 ease-in-out",
         positioningClasses
       )}
diff --git a/src/components/chat/chat-panel/MarkdownContent.tsx b/src/components/chat/chat-panel/MarkdownContent.tsx
index c6bb5f3df..fc7c1e9b7 100644
--- a/src/components/chat/chat-panel/MarkdownContent.tsx
+++ b/src/components/chat/chat-panel/MarkdownContent.tsx
@@ -97,6 +97,30 @@ export function MarkdownContent({ content, isUser }: { content: string; isUser?:
     return preprocessMarkdown(content, notes, cards, cwd);
   }, [content, notes, cards, cwd]);
 
+  // The user bubble has an accent (purple) background with --accent-fg text.
+  // Block elements below must read against the accent there (token-based, with
+  // alpha via color-mix) instead of the dark surface tokens (which are only
+  // legible on the assistant/surface bubble).
+  const strongColor = isUser ? "text-[var(--accent-fg)]" : "text-[var(--text-primary)]";
+  const headingColor = isUser ? "text-[var(--accent-fg)]" : "text-[var(--text-primary)]";
+  const listColor = isUser ? "text-[var(--accent-fg)]" : "text-[var(--text-secondary)]";
+  const codeClass = isUser
+    ? "bg-[color-mix(in_srgb,var(--accent-fg)_20%,transparent)] text-[var(--accent-fg)]"
+    : "bg-[var(--surface-3)] text-[var(--text-primary)]";
+  const quoteClass = isUser
+    ? "border-[color-mix(in_srgb,var(--accent-fg)_40%,transparent)] text-[color-mix(in_srgb,var(--accent-fg)_80%,transparent)]"
+    : "border-[var(--accent)] text-[var(--text-tertiary)]";
+  // Table / rule chrome — re-themed against the accent bubble for the user path.
+  const ruleBorder = isUser
+    ? "border-[color-mix(in_srgb,var(--accent-fg)_40%,transparent)]"
+    : "border-[var(--border)]";
+  const thClass = isUser
+    ? "text-[var(--accent-fg)] bg-[color-mix(in_srgb,var(--accent-fg)_15%,transparent)] border-[color-mix(in_srgb,var(--accent-fg)_40%,transparent)]"
+    : "text-[var(--text-primary)] bg-[var(--surface-2)] border-[var(--border)]";
+  const tdClass = isUser
+    ? "text-[var(--accent-fg)] border-[color-mix(in_srgb,var(--accent-fg)_40%,transparent)]"
+    : "text-[var(--text-secondary)] border-[var(--border)]";
+
   return (
     <ReactMarkdown
       remarkPlugins={[remarkGfm, remarkBreaks]}
@@ -104,14 +128,14 @@ export function MarkdownContent({ content, isUser }: { content: string; isUser?:
       urlTransform={(url) => url.startsWith("cairn://") ? url : defaultUrlTransform(url)}
       components={{
         p: ({ children }) => <p className="mb-1.5 last:mb-0 leading-relaxed break-words">{children}</p>,
-        strong: ({ children }) => <strong className="font-semibold text-[var(--text-primary)]">{children}</strong>,
+        strong: ({ children }) => <strong className={`font-semibold ${strongColor}`}>{children}</strong>,
         em: ({ children }) => <em className="italic opacity-80">{children}</em>,
-        ul: ({ children }) => <ul className="my-1.5 pl-4 list-disc space-y-0.5 text-[var(--text-secondary)]">{children}</ul>,
-        ol: ({ children }) => <ol className="my-1.5 pl-4 list-decimal space-y-0.5 text-[var(--text-secondary)]">{children}</ol>,
+        ul: ({ children }) => <ul className={`my-1.5 pl-4 list-disc space-y-0.5 ${listColor}`}>{children}</ul>,
+        ol: ({ children }) => <ol className={`my-1.5 pl-4 list-decimal space-y-0.5 ${listColor}`}>{children}</ol>,
         li: ({ children }) => <li className="leading-relaxed break-words">{children}</li>,
-        h1: ({ children }) => <h1 className="font-semibold text-[var(--text-primary)] text-sm mt-2 mb-1">{children}</h1>,
-        h2: ({ children }) => <h2 className="font-semibold text-[var(--text-primary)] text-sm mt-2 mb-1">{children}</h2>,
-        h3: ({ children }) => <h3 className="font-medium text-[var(--text-primary)] mt-1.5 mb-0.5">{children}</h3>,
+        h1: ({ children }) => <h1 className={`font-semibold ${headingColor} text-sm mt-2 mb-1`}>{children}</h1>,
+        h2: ({ children }) => <h2 className={`font-semibold ${headingColor} text-sm mt-2 mb-1`}>{children}</h2>,
+        h3: ({ children }) => <h3 className={`font-medium ${headingColor} mt-1.5 mb-0.5`}>{children}</h3>,
         pre: ({ children }) => {
           const child = Array.isArray(children) ? children[0] : children;
           const code = child as React.ReactElement<{ className?: string; children?: React.ReactNode }>;
@@ -125,22 +149,22 @@ export function MarkdownContent({ content, isUser }: { content: string; isUser?:
           // Fenced blocks handled by `pre` above — this only runs for inline code
           if (className?.startsWith("language-")) return <>{children}</>;
           return (
-            <code className="px-1 py-0.5 rounded bg-[var(--surface-3)] font-mono text-[0.786rem] text-[var(--text-primary)] break-all">
+            <code className={`px-1 py-0.5 rounded font-mono text-[0.786rem] break-all ${codeClass}`}>
               {children}
             </code>
           );
         },
         blockquote: ({ children }) => (
-          <blockquote className="border-l-2 border-[var(--accent)] pl-2.5 my-1.5 text-[var(--text-tertiary)] italic">
+          <blockquote className={`border-l-2 pl-2.5 my-1.5 italic ${quoteClass}`}>
             {children}
           </blockquote>
         ),
         a: ({ href, children }) => {
           const linkClass = isUser
-            ? "inline-flex items-center text-white hover:text-white/80 underline font-medium cursor-pointer"
+            ? "inline-flex items-center text-[var(--accent-fg)] hover:text-[color-mix(in_srgb,var(--accent-fg)_80%,transparent)] underline font-medium cursor-pointer"
             : "inline-flex items-center text-[var(--accent)] hover:underline font-medium cursor-pointer";
           const fallbackClass = isUser
-            ? "text-white hover:text-white/80 underline"
+            ? "text-[var(--accent-fg)] hover:text-[color-mix(in_srgb,var(--accent-fg)_80%,transparent)] underline"
             : "text-[var(--accent)] hover:underline";
 
           if (href?.startsWith("cairn://note/")) {
@@ -203,7 +227,7 @@ export function MarkdownContent({ content, isUser }: { content: string; isUser?:
             </a>
           );
         },
-        hr: () => <hr className="my-2 border-[var(--border)]" />,
+        hr: () => <hr className={`my-2 ${ruleBorder}`} />,
         table: ({ children }) => (
           <div className="my-2 overflow-x-auto">
             <table className="w-full border-collapse text-xs">{children}</table>
@@ -211,14 +235,14 @@ export function MarkdownContent({ content, isUser }: { content: string; isUser?:
         ),
         thead: ({ children }) => <thead>{children}</thead>,
         tbody: ({ children }) => <tbody>{children}</tbody>,
-        tr: ({ children }) => <tr className="border-b border-[var(--border)]">{children}</tr>,
+        tr: ({ children }) => <tr className={`border-b ${ruleBorder}`}>{children}</tr>,
         th: ({ children }) => (
-          <th className="px-2.5 py-1.5 text-left font-semibold text-[var(--text-primary)] bg-[var(--surface-2)] border border-[var(--border)]">
+          <th className={`px-2.5 py-1.5 text-left font-semibold border ${thClass}`}>
             {children}
           </th>
         ),
         td: ({ children }) => (
-          <td className="px-2.5 py-1.5 text-[var(--text-secondary)] border border-[var(--border)]">
+          <td className={`px-2.5 py-1.5 border ${tdClass}`}>
             {children}
           </td>
         ),
diff --git a/src/components/flow/flow-utils.test.ts b/src/components/flow/flow-utils.test.ts
new file mode 100644
index 000000000..e64efe70a
--- /dev/null
+++ b/src/components/flow/flow-utils.test.ts
@@ -0,0 +1,112 @@
+/**
+ * Unit tests for computeGroupAssignments — the Idea Flow geometric containment
+ * logic that decides which group (if any) a node belongs to after a drag.
+ *
+ * This is the trickiest pure logic in the flow feature: absolute-position
+ * accumulation through parent chains, smallest-enclosing-group selection by the
+ * node's CENTER point, and coordinate conversion (parent-relative on entry,
+ * absolute on exit). It only emits CHANGES, never no-op reassignments.
+ */
+
+import { describe, it, expect } from "vitest";
+import type { Node } from "@xyflow/react";
+import { computeGroupAssignments } from "./flow-utils";
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+function node(
+  id: string,
+  x: number,
+  y: number,
+  opts: Partial<{ type: string; parentId: string; w: number; h: number; gw: number; gh: number }> = {},
+): Node {
+  const n: Node = {
+    id,
+    position: { x, y },
+    data: {},
+    type: opts.type,
+    parentId: opts.parentId,
+  } as Node;
+  if (opts.w != null || opts.h != null) {
+    n.measured = { width: opts.w ?? 220, height: opts.h ?? 80 };
+  }
+  if (opts.gw != null || opts.gh != null) {
+    n.style = { width: opts.gw ?? 320, height: opts.gh ?? 200 };
+  }
+  return n;
+}
+
+const group = (id: string, x: number, y: number, gw: number, gh: number, parentId?: string): Node =>
+  node(id, x, y, { type: "group", gw, gh, parentId });
+
+describe("computeGroupAssignments", () => {
+  it("returns no changes when there are no groups", () => {
+    const nodes = [node("a", 10, 10, { w: 100, h: 100 })];
+    expect(computeGroupAssignments(nodes)).toEqual([]);
+  });
+
+  it("assigns an unparented node whose center falls inside a group (relative coords)", () => {
+    // Group at (0,0) 320x200. Node at (100,50), 100x100 → center (150,100) inside.
+    const nodes = [group("g1", 0, 0, 320, 200), node("a", 100, 50, { w: 100, h: 100 })];
+    const changes = computeGroupAssignments(nodes);
+    expect(changes).toEqual([
+      // entry coords are parent-relative: abs(100,50) - groupAbs(0,0)
+      { nodeId: "a", parentId: "g1", x: 100, y: 50 },
+    ]);
+  });
+
+  it("does not reassign a node already correctly parented (no-op suppressed)", () => {
+    // Node already a child of g1 and still inside it → no change emitted.
+    const nodes = [
+      group("g1", 0, 0, 320, 200),
+      node("a", 100, 50, { w: 100, h: 100, parentId: "g1" }),
+    ];
+    expect(computeGroupAssignments(nodes)).toEqual([]);
+  });
+
+  it("removes a node from its group when its center leaves (absolute coords)", () => {
+    // Child positioned (relative) far outside the 320x200 group → exits to root.
+    const nodes = [
+      group("g1", 0, 0, 320, 200),
+      node("a", 500, 500, { w: 100, h: 100, parentId: "g1" }),
+    ];
+    const changes = computeGroupAssignments(nodes);
+    // Exit coords are absolute: groupAbs(0,0) + rel(500,500) = (500,500).
+    expect(changes).toEqual([{ nodeId: "a", parentId: null, x: 500, y: 500 }]);
+  });
+
+  it("picks the SMALLEST-area group when nested groups both contain the center", () => {
+    // Big group 400x400 at (0,0); small group 100x100 at (50,50). Node center
+    // (100,100) is inside both → smaller wins.
+    const nodes = [
+      group("big", 0, 0, 400, 400),
+      group("small", 50, 50, 100, 100),
+      node("a", 80, 80, { w: 40, h: 40 }), // center (100,100)
+    ];
+    const changes = computeGroupAssignments(nodes);
+    const a = changes.find((c) => c.nodeId === "a");
+    expect(a?.parentId).toBe("small");
+  });
+
+  it("uses default node dimensions (220x80) when measured is absent", () => {
+    // Group 320x200 at (0,0). Node at (0,0) with default 220x80 → center (110,40) inside.
+    const nodes = [group("g1", 0, 0, 320, 200), node("a", 0, 0)];
+    const changes = computeGroupAssignments(nodes);
+    expect(changes).toEqual([{ nodeId: "a", parentId: "g1", x: 0, y: 0 }]);
+  });
+
+  it("ignores group nodes themselves as assignment candidates", () => {
+    const nodes = [group("g1", 0, 0, 320, 200), group("g2", 10, 10, 50, 50)];
+    // No non-group nodes → nothing to assign.
+    expect(computeGroupAssignments(nodes)).toEqual([]);
+  });
+
+  it("accumulates absolute position through a parent chain", () => {
+    // g1 at (100,100); child node parented to g1 at relative (10,10) → abs (110,110),
+    // center with default 220x80 = (220,150). g1 is 320x200 → inside, already parented.
+    const nodes = [
+      group("g1", 100, 100, 320, 200),
+      node("a", 10, 10, { parentId: "g1" }),
+    ];
+    expect(computeGroupAssignments(nodes)).toEqual([]);
+  });
+});
diff --git a/src/components/kanban/board-dnd.test.ts b/src/components/kanban/board-dnd.test.ts
new file mode 100644
index 000000000..be7d91708
--- /dev/null
+++ b/src/components/kanban/board-dnd.test.ts
@@ -0,0 +1,129 @@
+/**
+ * Unit tests for the Kanban board's pure drag-and-drop logic.
+ *
+ * Guards two regression-prone behaviors extracted from board.tsx:
+ *  - getZoneHit: destructive archive/delete drop-zone hit-testing.
+ *  - resolveCardDrop: the column/card move + reorder index math, including the
+ *    same-column off-by-one (excluding the dragged card) and no-op detection.
+ */
+
+import { describe, it, expect } from "vitest";
+import { getZoneHit, resolveCardDrop } from "./board-dnd";
+import type { TaskCard, BoardColumn } from "@/types";
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+const col = (id: string): BoardColumn =>
+  ({ id, projectId: "p", workspaceId: "w", name: id, type: "todo", order: 0,
+     createdAt: "", updatedAt: "" }) as BoardColumn;
+
+const card = (id: string, columnId: string): TaskCard =>
+  ({ id, columnId, projectId: "p", workspaceId: "w", title: id, tagIds: [],
+     priority: "medium", linkedNoteIds: [], blockedByIds: [], order: 0,
+     createdAt: "", updatedAt: "", version: 1 }) as TaskCard;
+
+const rect = (left: number, right: number, top = 0, bottom = 50): DOMRect =>
+  ({ left, right, top, bottom, x: left, y: top, width: right - left, height: bottom - top,
+     toJSON: () => ({}) }) as DOMRect;
+
+// ── getZoneHit ────────────────────────────────────────────────────────────────
+describe("getZoneHit", () => {
+  const bar = rect(0, 200, 100, 150);
+  const archive = rect(0, 100, 100, 150);
+  const del = rect(100, 200, 100, 150);
+
+  it("returns null when there is no bar rect", () => {
+    expect(getZoneHit(50, 120, null, archive, del)).toBeNull();
+  });
+
+  it("returns null when the pointer is above or below the bar", () => {
+    expect(getZoneHit(50, 90, bar, archive, del)).toBeNull();
+    expect(getZoneHit(50, 160, bar, archive, del)).toBeNull();
+  });
+
+  it("returns 'archive' when over the archive zone", () => {
+    expect(getZoneHit(50, 120, bar, archive, del)).toBe("archive");
+  });
+
+  it("returns 'delete' when over the delete zone", () => {
+    expect(getZoneHit(150, 120, bar, archive, del)).toBe("delete");
+  });
+
+  it("returns null when within the bar vertically but between/outside zones", () => {
+    expect(getZoneHit(250, 120, bar, archive, del)).toBeNull();
+  });
+
+  it("prefers archive when zones overlap at a boundary", () => {
+    const a = rect(0, 100, 100, 150);
+    const d = rect(100, 200, 100, 150);
+    // x=100 is the shared edge → archive (checked first) wins.
+    expect(getZoneHit(100, 120, bar, a, d)).toBe("archive");
+  });
+
+  it("ignores zones that are null", () => {
+    expect(getZoneHit(150, 120, bar, null, del)).toBe("delete");
+    expect(getZoneHit(50, 120, bar, archive, null)).toBe("archive");
+  });
+});
+
+// ── resolveCardDrop ─────────────────────────────────────────────────────────
+describe("resolveCardDrop", () => {
+  // Board: todo = [a, b, c], done = [d]
+  const columns = [col("todo"), col("done")];
+  const byCol: Record<string, TaskCard[]> = {
+    todo: [card("a", "todo"), card("b", "todo"), card("c", "todo")],
+    done: [card("d", "done")],
+  };
+  const getColumnCards = (id: string) => byCol[id] ?? [];
+
+  it("appends to the end when dropped on a column", () => {
+    const drop = resolveCardDrop(columns, getColumnCards, card("d", "done"), "todo");
+    expect(drop).toEqual({ targetColumnId: "todo", targetIndex: 3 });
+  });
+
+  it("inserts at the target card's index when moving across columns", () => {
+    // Move d (done) onto b (index 1 in todo).
+    const drop = resolveCardDrop(columns, getColumnCards, card("d", "done"), "b");
+    expect(drop).toEqual({ targetColumnId: "todo", targetIndex: 1 });
+  });
+
+  it("excludes the dragged card so same-column reorder isn't off by one", () => {
+    // Move a (todo[0]) onto c (todo[2]). After excluding a, list is [b, c]; c is index 1.
+    const drop = resolveCardDrop(columns, getColumnCards, card("a", "todo"), "c");
+    expect(drop).toEqual({ targetColumnId: "todo", targetIndex: 1 });
+  });
+
+  it("returns null for an unknown over-id", () => {
+    expect(resolveCardDrop(columns, getColumnCards, card("a", "todo"), "ghost")).toBeNull();
+  });
+
+  it("returns null for a no-op drop onto the card's current column slot", () => {
+    // done = [d]. Dragging d onto d: exclude d → [], index falls back to 0, and
+    // the slot at index 0 is still d → recognised as a no-op (no move fired).
+    const cols = [col("done")];
+    const get = (id: string) => (id === "done" ? [card("d", "done")] : []);
+    expect(resolveCardDrop(cols, get, card("d", "done"), "d")).toBeNull();
+  });
+
+  it("returns null when the last card is dropped on its own column body", () => {
+    // todo = [a, b, c]. Dropping c (already last) onto the todo COLUMN appends
+    // to the end — i.e. exactly where it already is. The card-target guard
+    // can't see this (targetIndex == length, lookup is undefined), so the
+    // column-body guard must catch it to avoid a no-op move/timestamp bump.
+    expect(resolveCardDrop(columns, getColumnCards, card("c", "todo"), "todo")).toBeNull();
+  });
+
+  it("still moves a non-last card dropped on its own column body to the end", () => {
+    // Dropping a (todo[0], not last) onto the todo column appends to the end.
+    // The column-body branch uses the full column length (3), so this is a real
+    // move, not a no-op.
+    const drop = resolveCardDrop(columns, getColumnCards, card("a", "todo"), "todo");
+    expect(drop).toEqual({ targetColumnId: "todo", targetIndex: 3 });
+  });
+
+  it("appends to an empty target column", () => {
+    const cols = [col("todo"), col("empty")];
+    const get = (id: string) => (id === "todo" ? [card("a", "todo")] : []);
+    const drop = resolveCardDrop(cols, get, card("a", "todo"), "empty");
+    expect(drop).toEqual({ targetColumnId: "empty", targetIndex: 0 });
+  });
+});
diff --git a/src/components/kanban/board-dnd.ts b/src/components/kanban/board-dnd.ts
new file mode 100644
index 000000000..379cc8b5d
--- /dev/null
+++ b/src/components/kanban/board-dnd.ts
@@ -0,0 +1,87 @@
+import type { TaskCard, BoardColumn } from "@/types";
+
+/**
+ * Pure drag-and-drop interaction logic for the Kanban board, extracted from
+ * board.tsx so the reorder/move math and destructive-zone hit-testing can be
+ * unit-tested without React-DnD or the store.
+ */
+
+/**
+ * Hit-test a pointer against the archive / delete drop zones in the action bar.
+ * Returns the zone the pointer is over, or null if outside the bar entirely.
+ *
+ * The pointer must be vertically within the bar; then archive takes precedence
+ * over delete (matching their left-to-right layout).
+ */
+export function getZoneHit(
+  clientX: number,
+  clientY: number,
+  barRect: DOMRect | null,
+  archiveRect: DOMRect | null,
+  deleteRect: DOMRect | null,
+): "archive" | "delete" | null {
+  if (!barRect) return null;
+  if (clientY < barRect.top || clientY > barRect.bottom) return null;
+  if (archiveRect && clientX >= archiveRect.left && clientX <= archiveRect.right) return "archive";
+  if (deleteRect && clientX >= deleteRect.left && clientX <= deleteRect.right) return "delete";
+  return null;
+}
+
+/**
+ * Resolve where a dragged card should land given the drop target id (`overId`).
+ *
+ * Two cases:
+ *  - Dropping onto a column → append to the end of that column.
+ *  - Dropping onto a card → insert at that card's index within its column
+ *    (the dragged card is excluded first so the index isn't skewed by its own
+ *    presence — the classic same-column reorder off-by-one).
+ *
+ * Returns `null` for invalid targets or no-op moves (dropping a card back onto
+ * its own current slot), so callers can short-circuit without mutating state.
+ */
+export function resolveCardDrop(
+  columns: BoardColumn[],
+  getColumnCards: (columnId: string) => TaskCard[],
+  draggedCard: TaskCard,
+  overId: string,
+): { targetColumnId: string; targetIndex: number } | null {
+  let targetColumnId: string;
+  let targetIndex: number;
+
+  const isOverColumn = columns.some((c) => c.id === overId);
+  if (isOverColumn) {
+    targetColumnId = overId;
+    targetIndex = getColumnCards(overId).length;
+  } else {
+    const overCard = columns
+      .flatMap((c) => getColumnCards(c.id).map((card) => ({ id: card.id, colId: c.id })))
+      .find((c) => c.id === overId);
+    if (!overCard) return null;
+    targetColumnId = overCard.colId;
+    const colCards = getColumnCards(targetColumnId).filter((c) => c.id !== draggedCard.id);
+    const overIdx = colCards.findIndex((c) => c.id === overId);
+    targetIndex = overIdx >= 0 ? overIdx : colCards.length;
+  }
+
+  // No-op: the card is already occupying the resolved slot.
+  //  - Card-target drop: the resolved index already holds the dragged card.
+  //  - Column-body drop (append to end): the dragged card is already the last
+  //    card of the same column, so appending wouldn't move it. The card-target
+  //    guard below can't catch this because targetIndex == length (one past the
+  //    end), where the lookup is always undefined.
+  const sameColumn = draggedCard.columnId === targetColumnId;
+  if (sameColumn && isOverColumn) {
+    const colCards = getColumnCards(targetColumnId);
+    if (colCards[colCards.length - 1]?.id === draggedCard.id) {
+      return null;
+    }
+  }
+  if (
+    sameColumn &&
+    getColumnCards(targetColumnId)[targetIndex]?.id === draggedCard.id
+  ) {
+    return null;
+  }
+
+  return { targetColumnId, targetIndex };
+}
diff --git a/src/components/kanban/board.tsx b/src/components/kanban/board.tsx
index c71a87e06..a17392625 100644
--- a/src/components/kanban/board.tsx
+++ b/src/components/kanban/board.tsx
@@ -31,14 +31,7 @@ import { KanbanColumn } from "./column";
 import { KanbanCard } from "./card";
 import { CardDetailModal } from "./card-detail";
 import type { TaskCard, BoardColumn } from "@/types";
-
-function getZoneHit(clientX: number, clientY: number, barRect: DOMRect | null, archiveRect: DOMRect | null, deleteRect: DOMRect | null): "archive" | "delete" | null {
-  if (!barRect) return null;
-  if (clientY < barRect.top || clientY > barRect.bottom) return null;
-  if (archiveRect && clientX >= archiveRect.left && clientX <= archiveRect.right) return "archive";
-  if (deleteRect && clientX >= deleteRect.left && clientX <= deleteRect.right) return "delete";
-  return null;
-}
+import { getZoneHit, resolveCardDrop } from "./board-dnd";
 
 export function KanbanBoard() {
   const {
@@ -236,32 +229,9 @@ export function KanbanBoard() {
 
     // ── Card move / reorder ───────────────────────────────────────────────
     if (!draggedCard) return;
-    const overIdStr = over.id as string;
-    let targetColumnId: string;
-    let targetIndex: number;
-
-    const isOverColumn = columns.some((c) => c.id === overIdStr);
-    if (isOverColumn) {
-      targetColumnId = overIdStr;
-      targetIndex = getColumnCards(overIdStr).length;
-    } else {
-      const allCards = columns.flatMap((c) =>
-        getColumnCards(c.id).map((card) => ({ ...card, _colId: c.id }))
-      );
-      const overCard = allCards.find((c) => c.id === overIdStr);
-      if (!overCard) return;
-      targetColumnId = overCard._colId;
-      const colCards = getColumnCards(targetColumnId).filter((c) => c.id !== draggedCard.id);
-      const overIdx  = colCards.findIndex((c) => c.id === overIdStr);
-      targetIndex = overIdx >= 0 ? overIdx : colCards.length;
-    }
-
-    if (
-      draggedCard.columnId === targetColumnId &&
-      getColumnCards(targetColumnId)[targetIndex]?.id === draggedCard.id
-    ) return;
-
-    moveCard(draggedCard.id, targetColumnId, targetIndex);
+    const cardDrop = resolveCardDrop(columns, getColumnCards, draggedCard, over.id as string);
+    if (!cardDrop) return;
+    moveCard(draggedCard.id, cardDrop.targetColumnId, cardDrop.targetIndex);
   }
 
   // Deep-link: open card detail
diff --git a/src/components/kanban/card-detail-utils.test.ts b/src/components/kanban/card-detail-utils.test.ts
new file mode 100644
index 000000000..de3761f5c
--- /dev/null
+++ b/src/components/kanban/card-detail-utils.test.ts
@@ -0,0 +1,74 @@
+/**
+ * Unit tests for card-detail blocker logic (card-detail-utils.ts).
+ *
+ * computeCandidateBlockers applies a 5-clause exclusion filter; dropping any
+ * one clause silently lets an invalid card be offered as a blocker (self-block,
+ * cross-project, archived, done, or already-a-blocker). These tests pin each
+ * clause independently.
+ */
+
+import { describe, it, expect } from "vitest";
+import { computeDoneColumnIds, computeCandidateBlockers } from "./card-detail-utils";
+import type { TaskCard, BoardColumn } from "@/types";
+
+const col = (id: string, type: string, projectId = "p1"): BoardColumn =>
+  ({ id, projectId, workspaceId: "w", name: id, type, order: 0,
+     createdAt: "", updatedAt: "" }) as BoardColumn;
+
+const card = (id: string, over: Partial<TaskCard> = {}): TaskCard =>
+  ({ id, columnId: "todo", projectId: "p1", workspaceId: "w", title: id, tagIds: [],
+     priority: "medium", linkedNoteIds: [], blockedByIds: [], order: 0,
+     createdAt: "", updatedAt: "", version: 1, ...over }) as TaskCard;
+
+describe("computeDoneColumnIds", () => {
+  it("collects only done-type columns for the given project", () => {
+    const cols = [
+      col("todo", "todo"),
+      col("done1", "done"),
+      col("done2", "done", "p2"), // other project — excluded
+    ];
+    const ids = computeDoneColumnIds(cols, "p1");
+    expect([...ids]).toEqual(["done1"]);
+  });
+});
+
+describe("computeCandidateBlockers", () => {
+  const subject = card("self", { projectId: "p1", blockedByIds: ["already"] });
+  const done = new Set(["done"]);
+
+  it("includes a valid same-project, non-archived, non-done, unrelated card", () => {
+    const cards = [subject, card("ok", { columnId: "todo" })];
+    expect(computeCandidateBlockers(cards, subject, done).map((c) => c.id)).toEqual(["ok"]);
+  });
+
+  it("excludes the card itself (no self-block)", () => {
+    const cards = [subject];
+    expect(computeCandidateBlockers(cards, subject, done)).toEqual([]);
+  });
+
+  it("excludes cards from other projects", () => {
+    const cards = [subject, card("other", { projectId: "p2" })];
+    expect(computeCandidateBlockers(cards, subject, done)).toEqual([]);
+  });
+
+  it("excludes archived cards", () => {
+    const cards = [subject, card("arch", { archivedAt: "2026-01-01" })];
+    expect(computeCandidateBlockers(cards, subject, done)).toEqual([]);
+  });
+
+  it("excludes cards already in a done column", () => {
+    const cards = [subject, card("finished", { columnId: "done" })];
+    expect(computeCandidateBlockers(cards, subject, done)).toEqual([]);
+  });
+
+  it("excludes cards already listed as blockers", () => {
+    const cards = [subject, card("already", { columnId: "todo" })];
+    expect(computeCandidateBlockers(cards, subject, done)).toEqual([]);
+  });
+
+  it("treats a missing blockedByIds as no existing blockers", () => {
+    const noBlockers = card("self2", { blockedByIds: undefined as unknown as string[] });
+    const cards = [noBlockers, card("ok")];
+    expect(computeCandidateBlockers(cards, noBlockers, done).map((c) => c.id)).toEqual(["ok"]);
+  });
+});
diff --git a/src/components/kanban/card-detail-utils.ts b/src/components/kanban/card-detail-utils.ts
new file mode 100644
index 000000000..f3c1db736
--- /dev/null
+++ b/src/components/kanban/card-detail-utils.ts
@@ -0,0 +1,38 @@
+import type { TaskCard, BoardColumn } from "@/types";
+
+/**
+ * Pure blocker-candidate logic for the card-detail modal, extracted from
+ * card-detail.tsx so the multi-clause exclusion filter is tested in isolation
+ * (a silently-dropped clause here would let invalid blockers be selected).
+ */
+
+/** The set of column ids that are "done" columns within a given project. */
+export function computeDoneColumnIds(columns: BoardColumn[], projectId: string): Set<string> {
+  return new Set(
+    columns.filter((c) => c.projectId === projectId && c.type === "done").map((c) => c.id),
+  );
+}
+
+/**
+ * Cards eligible to be added as blockers of `card`. Excludes, in order:
+ *  - cards in a different project
+ *  - the card itself (no self-block)
+ *  - archived cards
+ *  - cards already in a done column (a done task can't block)
+ *  - cards already listed as blockers
+ */
+export function computeCandidateBlockers(
+  cards: TaskCard[],
+  card: Pick<TaskCard, "id" | "projectId" | "blockedByIds">,
+  doneColumnIds: Set<string>,
+): TaskCard[] {
+  const existingBlockers = card.blockedByIds ?? [];
+  return cards.filter(
+    (c) =>
+      c.projectId === card.projectId &&
+      c.id !== card.id &&
+      !c.archivedAt &&
+      !doneColumnIds.has(c.columnId) &&
+      !existingBlockers.includes(c.id),
+  );
+}
diff --git a/src/components/kanban/card-detail.tsx b/src/components/kanban/card-detail.tsx
index 7954f7b56..b1aacdfd9 100644
--- a/src/components/kanban/card-detail.tsx
+++ b/src/components/kanban/card-detail.tsx
@@ -17,6 +17,7 @@ import { CairnEvents } from "@/lib/events";
 import { SpawnAgentModal } from "@/components/agent/SpawnAgentModal";
 import { NoteMarkdownPreview } from "@/components/notes/NoteMarkdownPreview";
 import { CardDetailSidebar } from "./card-detail-sidebar";
+import { computeDoneColumnIds, computeCandidateBlockers } from "./card-detail-utils";
 
 interface CardDetailModalProps {
   cardId: string;
@@ -56,12 +57,9 @@ export function CardDetailModal({ cardId, onClose }: CardDetailModalProps) {
 
   if (!card) return null;
 
-  const doneColumnIds = new Set(columns.filter((c) => c.projectId === card.projectId && c.type === "done").map((c) => c.id));
+  const doneColumnIds = computeDoneColumnIds(columns, card.projectId);
   const blockerCards = (card.blockedByIds ?? []).map((id) => cards.find((c) => c.id === id)).filter(Boolean) as typeof cards;
-  const candidateBlockers = cards.filter(
-    (c) => c.projectId === card.projectId && c.id !== cardId && !c.archivedAt
-      && !doneColumnIds.has(c.columnId) && !(card.blockedByIds ?? []).includes(c.id)
-  );
+  const candidateBlockers = computeCandidateBlockers(cards, card, doneColumnIds);
 
   return (
     <>
diff --git a/src/components/kanban/column-utils.test.ts b/src/components/kanban/column-utils.test.ts
new file mode 100644
index 000000000..318f3af06
--- /dev/null
+++ b/src/components/kanban/column-utils.test.ts
@@ -0,0 +1,61 @@
+/**
+ * Unit tests for Kanban column WIP-limit logic (column-utils.ts).
+ *
+ * parseWipLimit was previously duplicated across two dialog call sites; these
+ * tests pin the blank/invalid/positive behavior in one place. isAtWipLimit
+ * gates the add-card button and over-limit banner — its null/0 and >= boundary
+ * are the kind of thing that breaks subtly on edits.
+ */
+
+import { describe, it, expect } from "vitest";
+import { parseWipLimit, isAtWipLimit } from "./column-utils";
+
+describe("parseWipLimit", () => {
+  it("returns null for blank or whitespace input", () => {
+    expect(parseWipLimit("")).toBeNull();
+    expect(parseWipLimit("   ")).toBeNull();
+  });
+
+  it("returns null for non-numeric input", () => {
+    expect(parseWipLimit("abc")).toBeNull();
+  });
+
+  it("returns null for zero and negative numbers", () => {
+    expect(parseWipLimit("0")).toBeNull();
+    expect(parseWipLimit("-3")).toBeNull();
+  });
+
+  it("parses a positive integer", () => {
+    expect(parseWipLimit("5")).toBe(5);
+    expect(parseWipLimit(" 12 ")).toBe(12);
+  });
+
+  it("rejects trailing-garbage / non-integer strings (must not truncate like parseInt)", () => {
+    // parseInt would silently accept these and save a value the user never
+    // typed; parseWipLimit must reject anything that isn't a whole integer.
+    expect(parseWipLimit("3 cards")).toBeNull();
+    expect(parseWipLimit("3.5")).toBeNull();
+    expect(parseWipLimit("1e3")).toBeNull();
+    expect(parseWipLimit("0x10")).toBeNull();
+  });
+});
+
+describe("isAtWipLimit", () => {
+  it("is false when there is no limit (null/undefined/0)", () => {
+    expect(isAtWipLimit(null, 99)).toBe(false);
+    expect(isAtWipLimit(undefined, 99)).toBe(false);
+    expect(isAtWipLimit(0, 99)).toBe(false);
+  });
+
+  it("is false below the limit", () => {
+    expect(isAtWipLimit(3, 2)).toBe(false);
+  });
+
+  it("is true at exactly the limit (>=)", () => {
+    expect(isAtWipLimit(3, 3)).toBe(true);
+  });
+
+  it("is true over the limit", () => {
+    expect(isAtWipLimit(3, 5)).toBe(true);
+  });
+});
diff --git a/src/components/kanban/column-utils.ts b/src/components/kanban/column-utils.ts
new file mode 100644
index 000000000..9f7e545d1
--- /dev/null
+++ b/src/components/kanban/column-utils.ts
@@ -0,0 +1,32 @@
+/**
+ * Pure WIP-limit logic for Kanban columns, extracted from column.tsx so the
+ * parse and "at limit" boundary checks are tested once and can't diverge
+ * between the two dialog call sites that previously duplicated the parse.
+ */
+
+/**
+ * Parse a raw WIP-limit input string into a positive integer, or null to clear.
+ *
+ * - Blank/whitespace → null (no limit).
+ * - Non-numeric or < 1 → null (invalid limits are treated as "no limit").
+ * - Otherwise the parsed integer.
+ */
+export function parseWipLimit(raw: string): number | null {
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+  // Only accept a whole positive integer string in its entirety — parseInt
+  // would silently truncate "3.5" → 3 or "1e3" → 1, saving a value the user
+  // never typed.
+  if (!/^\d+$/.test(trimmed)) return null;
+  const n = Number(trimmed);
+  if (n < 1) return null;
+  return n;
+}
+
+/**
+ * Whether a column is at or over its WIP limit (gates the add-card button and
+ * the over-limit banner). A limit of null or <= 0 means "no limit".
+ */
+export function isAtWipLimit(cardLimit: number | null | undefined, cardCount: number): boolean {
+  return cardLimit != null && cardLimit > 0 && cardCount >= cardLimit;
+}
diff --git a/src/components/kanban/column.tsx b/src/components/kanban/column.tsx
index 80650b84d..48ce66d92 100644
--- a/src/components/kanban/column.tsx
+++ b/src/components/kanban/column.tsx
@@ -19,6 +19,7 @@ import {
 import { KanbanCard } from "./card";
 import type { BoardColumn, TaskCard } from "@/types";
 import { COLUMN_COLORS } from "@/lib/constants";
+import { parseWipLimit, isAtWipLimit } from "./column-utils";
 
 interface NewCardData {
   title: string;
@@ -68,7 +69,7 @@ export function KanbanColumn({
   } = useSortable({ id: column.id, data: { column } });
 
   const accent = COLUMN_COLORS[column.type] ?? COLUMN_COLORS.custom;
-  const atLimit = column.cardLimit != null && column.cardLimit > 0 && cards.length >= column.cardLimit;
+  const atLimit = isAtWipLimit(column.cardLimit, cards.length);
 
   const style = {
     transform: CSS.Transform.toString(transform),
@@ -161,8 +162,7 @@ export function KanbanColumn({
               onChange={(e) => setLimitValue(e.target.value)}
               onKeyDown={(e) => {
                 if (e.key === "Enter") {
-                  const n = parseInt(limitValue, 10);
-                  onSetLimit(limitValue.trim() === "" ? null : (isNaN(n) || n < 1 ? null : n));
+                  onSetLimit(parseWipLimit(limitValue));
                   setLimitDialogOpen(false);
                 }
                 if (e.key === "Escape") setLimitDialogOpen(false);
@@ -187,8 +187,7 @@ export function KanbanColumn({
                 <Button
                   variant="accent" size="sm"
                   onClick={() => {
-                    const n = parseInt(limitValue, 10);
-                    onSetLimit(limitValue.trim() === "" ? null : (isNaN(n) || n < 1 ? null : n));
+                    onSetLimit(parseWipLimit(limitValue));
                     setLimitDialogOpen(false);
                   }}
                 >
diff --git a/src/components/layout/NewFeatureModal.component.test.tsx b/src/components/layout/NewFeatureModal.component.test.tsx
new file mode 100644
index 000000000..2bcb0bf65
--- /dev/null
+++ b/src/components/layout/NewFeatureModal.component.test.tsx
@@ -0,0 +1,152 @@
+/**
+ * Component tests for NewFeatureModal — the "What's New" highlights modal.
+ *
+ * Demonstrates the component harness with a store-connected component: the
+ * @/store module is mocked so seenFeatures and markFeatureAsSeen are fully
+ * controllable. Radix Dialog content is portaled to document.body; Testing
+ * Library queries it from there.
+ *
+ * Runs in the "component" vitest project (jsdom + Testing Library).
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { NewFeature } from "@/lib/new-features-registry";
+
+// ── Mock the store ────────────────────────────────────────────────────────────
+const markFeatureAsSeen = vi.fn();
+let seenFeatures: string[] = [];
+
+vi.mock("@/store", () => ({
+  useCairnStore: (selector: (s: unknown) => unknown) =>
+    selector({ seenFeatures, markFeatureAsSeen }),
+}));
+
+// ── Mock the registry ─────────────────────────────────────────────────────────
+// Decouple the modal-behavior assertions from the live registry: a stable local
+// fixture means these tests don't break when real release notes are added/changed.
+// Two versions, with the latest (v9.1) holding a single feature so the boot gate
+// surfaces exactly one item — mirroring the real single-latest-feature contract.
+// Built via vi.hoisted so it's available to the hoisted vi.mock factory below.
+const { FIXTURE_REGISTRY } = vi.hoisted(() => {
+  const FEATURE = (id: string, version: string, title: string): NewFeature => ({
+    id,
+    version,
+    title,
+    category: "Test",
+    description: `${title} description`,
+    highlights: [`${title} highlight`],
+  });
+  return {
+    FIXTURE_REGISTRY: [
+      FEATURE("v9.0-alpha", "v9.0", "Alpha Feature"),
+      FEATURE("v9.0-beta", "v9.0", "Beta Feature"),
+      FEATURE("v9.0-gamma", "v9.0", "Gamma Feature"),
+      FEATURE("v9.0-delta", "v9.0", "Delta Feature"),
+      FEATURE("v9.1-latest", "v9.1", "Latest Feature"),
+    ] as NewFeature[],
+  };
+});
+
+vi.mock("@/lib/new-features-registry", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@/lib/new-features-registry")>();
+  return { ...actual, NEW_FEATURES_REGISTRY: FIXTURE_REGISTRY };
+});
+
+import { NewFeatureModal } from "./NewFeatureModal";
+
+const LATEST = FIXTURE_REGISTRY[FIXTURE_REGISTRY.length - 1];
+
+beforeEach(() => {
+  markFeatureAsSeen.mockClear();
+  seenFeatures = [];
+});
+
+describe("NewFeatureModal", () => {
+  it("renders the latest unseen feature on mount", () => {
+    render(<NewFeatureModal />);
+    expect(screen.getByRole("heading", { name: /What's New in Cairn/i })).toBeInTheDocument();
+    expect(screen.getByText(LATEST.title)).toBeInTheDocument();
+  });
+
+  it("does not render when the latest feature is already seen", () => {
+    seenFeatures = [LATEST.id];
+    render(<NewFeatureModal />);
+    expect(screen.queryByRole("heading", { name: /What's New in Cairn/i })).not.toBeInTheDocument();
+  });
+
+  it("shows a single-feature footer with a 'Done' action (no pagination)", () => {
+    render(<NewFeatureModal />);
+    // The latest registry version has exactly one feature → Done, no dots/Skip All.
+    expect(screen.getByRole("button", { name: "Done" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /Skip All/i })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /Go to feature/i })).not.toBeInTheDocument();
+  });
+
+  it("marks the displayed feature seen and calls onClose when Done is clicked", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(<NewFeatureModal onClose={onClose} />);
+
+    await user.click(screen.getByRole("button", { name: "Done" }));
+
+    expect(markFeatureAsSeen).toHaveBeenCalledWith(LATEST.id);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  describe("forceOpen (Settings entrypoint)", () => {
+    it("renders even when everything has been seen", () => {
+      seenFeatures = FIXTURE_REGISTRY.map((f) => f.id);
+      render(<NewFeatureModal forceOpen />);
+      expect(screen.getByRole("heading", { name: /What's New in Cairn/i })).toBeInTheDocument();
+    });
+
+    it("shows pagination + Skip All when the full registry has multiple features", () => {
+      render(<NewFeatureModal forceOpen />);
+      // The full registry has many features → dots, Skip All, and Next.
+      expect(screen.getByRole("button", { name: "Go to feature 1" })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: /Skip All/i })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: /Next Feature/i })).toBeInTheDocument();
+    });
+
+    it("advances to the next feature and disables Prev only on the first slide", async () => {
+      const user = userEvent.setup();
+      render(<NewFeatureModal forceOpen />);
+
+      const first = FIXTURE_REGISTRY[0];
+      const second = FIXTURE_REGISTRY[1];
+
+      // First slide: showing feature[0], Prev is disabled.
+      expect(screen.getByText(first.title)).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Previous feature" })).toBeDisabled();
+
+      await user.click(screen.getByRole("button", { name: /Next Feature/i }));
+
+      // Second slide: showing feature[1], Prev is now enabled.
+      expect(screen.getByText(second.title)).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Previous feature" })).toBeEnabled();
+    });
+
+    it("jumps to a feature via its pagination dot", async () => {
+      const user = userEvent.setup();
+      render(<NewFeatureModal forceOpen />);
+
+      // Dot index 3 → 4th registry feature.
+      await user.click(screen.getByRole("button", { name: "Go to feature 4" }));
+      expect(screen.getByText(FIXTURE_REGISTRY[3].title)).toBeInTheDocument();
+    });
+
+    it("marks every displayed feature seen when Skip All is clicked", async () => {
+      const user = userEvent.setup();
+      const onClose = vi.fn();
+      render(<NewFeatureModal forceOpen onClose={onClose} />);
+
+      await user.click(screen.getByRole("button", { name: /Skip All/i }));
+
+      // forceOpen shows the whole registry → all ids marked seen.
+      expect(markFeatureAsSeen).toHaveBeenCalledTimes(FIXTURE_REGISTRY.length);
+      expect(onClose).toHaveBeenCalledTimes(1);
+    });
+  });
+});
diff --git a/src/components/layout/NewFeatureModal.tsx b/src/components/layout/NewFeatureModal.tsx
index ed4ee2a85..e11aac662 100644
--- a/src/components/layout/NewFeatureModal.tsx
+++ b/src/components/layout/NewFeatureModal.tsx
@@ -3,7 +3,7 @@
 import React, { useState } from "react";
 import { Sparkles, ChevronLeft, ChevronRight, Check } from "lucide-react";
 import { ModalShell } from "@/components/ui/modal-shell";
-import { NEW_FEATURES_REGISTRY } from "@/lib/new-features-registry";
+import { NEW_FEATURES_REGISTRY, getUnseenLatestFeatures } from "@/lib/new-features-registry";
 import { useCairnStore } from "@/store";
 import { useShallow } from "zustand/react/shallow";
 
@@ -23,14 +23,10 @@ export function NewFeatureModal({ forceOpen = false, onClose }: Props) {
   // Determine which features to highlight.
   // If forceOpen (e.g. from Settings), show all features in the registry.
   // Otherwise, show only unseen features belonging to the latest version.
-  const featuresToShow = React.useMemo(() => {
-    if (forceOpen) {
-      return NEW_FEATURES_REGISTRY;
-    }
-    if (NEW_FEATURES_REGISTRY.length === 0) return [];
-    const latestVersion = NEW_FEATURES_REGISTRY[NEW_FEATURES_REGISTRY.length - 1].version;
-    return NEW_FEATURES_REGISTRY.filter((f) => f.version === latestVersion && !seenFeatures.includes(f.id));
-  }, [forceOpen, seenFeatures]);
+  const featuresToShow = React.useMemo(
+    () => getUnseenLatestFeatures(NEW_FEATURES_REGISTRY, seenFeatures, forceOpen),
+    [forceOpen, seenFeatures],
+  );
 
   const [activeIdx, setActiveIdx] = useState(0);
   const [prevFeaturesLength, setPrevFeaturesLength] = useState(featuresToShow.length);
@@ -130,6 +126,7 @@ export function NewFeatureModal({ forceOpen = false, onClose }: Props) {
               <button
                 onClick={handlePrev}
                 disabled={activeIdx === 0}
+                aria-label="Previous feature"
                 className="p-2 rounded-lg border border-[var(--border)] bg-[var(--surface-2)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:bg-[var(--surface-3)] transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
               >
                 <ChevronLeft size={14} />
diff --git a/src/components/layout/app-chrome.tsx b/src/components/layout/app-chrome.tsx
index 8a454b9e7..4b717c36a 100644
--- a/src/components/layout/app-chrome.tsx
+++ b/src/components/layout/app-chrome.tsx
@@ -20,7 +20,7 @@ export function UpdateBanner({
 }) {
   if (!version && !downloaded) return null;
   return (
-    <div className="flex items-center gap-3 px-4 py-2 bg-[var(--accent-dim)] border-b border-[color-mix(in_srgb,var(--accent)_30%,transparent)] flex-shrink-0">
+    <div className="flex items-center gap-3 px-4 h-9 bg-[var(--accent-dim)] border-b border-[color-mix(in_srgb,var(--accent)_30%,transparent)] flex-shrink-0">
       <Download size={13} className="text-[var(--accent)] shrink-0" />
       <span className="text-xs text-[var(--text-secondary)] flex-1">
         {downloaded
diff --git a/src/components/layout/sidebar-utils.test.ts b/src/components/layout/sidebar-utils.test.ts
new file mode 100644
index 000000000..bc6be4a97
--- /dev/null
+++ b/src/components/layout/sidebar-utils.test.ts
@@ -0,0 +1,130 @@
+/**
+ * Unit tests for sidebar pure helpers (sidebar-utils.ts).
+ *
+ *  - buildShortcutMap: the ⌘3…⌘9 assignment with the >9 drop boundary — an
+ *    off-by-one here breaks the whole shortcut row.
+ *  - countOpenCardsByProject: single-pass aggregation excluding archived cards.
+ *  - dueDateSeverity: overdue/soon/none bucketing (a fixed `now` is passed so
+ *    the test is deterministic regardless of clock/timezone).
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  buildShortcutMap,
+  countOpenCardsByProject,
+  dueDateSeverity,
+  dueDateDiffDays,
+} from "./sidebar-utils";
+
+describe("buildShortcutMap", () => {
+  const items = (n: number) => Array.from({ length: n }, (_, i) => ({ view: `v${i}` }));
+
+  it("assigns ⌘3, ⌘4, … starting at the default base", () => {
+    const map = buildShortcutMap(items(3), 3, true);
+    expect(map.get("v0")).toBe("⌘3");
+    expect(map.get("v1")).toBe("⌘4");
+    expect(map.get("v2")).toBe("⌘5");
+  });
+
+  it("drops shortcuts past ⌘9 (empty string)", () => {
+    // base 3 + 7 items → ⌘3..⌘9, then the 8th would be ⌘10 → "".
+    const map = buildShortcutMap(items(8), 3, true);
+    expect(map.get("v6")).toBe("⌘9"); // index 6 → 9
+    expect(map.get("v7")).toBe("");   // index 7 → 10 → dropped
+  });
+
+  it("respects a custom base", () => {
+    const map = buildShortcutMap(items(2), 1, true);
+    expect(map.get("v0")).toBe("⌘1");
+    expect(map.get("v1")).toBe("⌘2");
+  });
+
+  it("uses Ctrl on non-macOS platforms", () => {
+    const map = buildShortcutMap(items(2), 3, false);
+    expect(map.get("v0")).toBe("Ctrl+3");
+    expect(map.get("v1")).toBe("Ctrl+4");
+  });
+
+  it("returns an empty map for no items", () => {
+    expect(buildShortcutMap([], 3, true).size).toBe(0);
+  });
+});
+
+describe("countOpenCardsByProject", () => {
+  it("counts non-archived cards per project", () => {
+    const counts = countOpenCardsByProject([
+      { projectId: "p1" },
+      { projectId: "p1" },
+      { projectId: "p2" },
+    ]);
+    expect(counts.get("p1")).toBe(2);
+    expect(counts.get("p2")).toBe(1);
+  });
+
+  it("excludes archived cards", () => {
+    const counts = countOpenCardsByProject([
+      { projectId: "p1" },
+      { projectId: "p1", archivedAt: "2026-01-01" },
+    ]);
+    expect(counts.get("p1")).toBe(1);
+  });
+
+  it("omits projects with only archived cards entirely", () => {
+    const counts = countOpenCardsByProject([
+      { projectId: "p1", archivedAt: "2026-01-01" },
+    ]);
+    expect(counts.has("p1")).toBe(false);
+  });
+
+  it("returns an empty map for no cards", () => {
+    expect(countOpenCardsByProject([]).size).toBe(0);
+  });
+});
+
+describe("dueDateSeverity", () => {
+  const NOW = new Date("2026-06-15T12:00:00Z").getTime();
+  const daysFromNow = (d: number) =>
+    new Date(NOW + d * 24 * 60 * 60 * 1000).toISOString();
+
+  it("returns 'danger' for a past due date", () => {
+    expect(dueDateSeverity(daysFromNow(-1), NOW)).toBe("danger");
+    expect(dueDateSeverity(daysFromNow(-30), NOW)).toBe("danger");
+  });
+
+  it("returns 'danger' for a due date earlier today (overdue, not warning)", () => {
+    // A small negative diff used to round to -0 via Math.ceil and slip into the
+    // 7-day "warning" branch — overdue items must always be "danger".
+    expect(dueDateSeverity(daysFromNow(-0.1), NOW)).toBe("danger");
+  });
+
+  it("returns 'warning' for due today and within 7 days", () => {
+    expect(dueDateSeverity(daysFromNow(0.1), NOW)).toBe("warning"); // later today
+    expect(dueDateSeverity(daysFromNow(3), NOW)).toBe("warning");
+    expect(dueDateSeverity(daysFromNow(7), NOW)).toBe("warning");
+  });
+
+  it("returns null for due dates more than 7 days away", () => {
+    expect(dueDateSeverity(daysFromNow(8), NOW)).toBeNull();
+    expect(dueDateSeverity(daysFromNow(60), NOW)).toBeNull();
+  });
+});
+
+describe("dueDateDiffDays", () => {
+  it("returns 0 for a deadline later the same calendar day (Due today)", () => {
+    // Build `now` at local noon so a few hours later is still the same day in
+    // the local timezone (the helper compares local calendar dates).
+    const now = new Date(2026, 5, 15, 12, 0, 0).getTime();
+    const laterToday = new Date(2026, 5, 15, 18, 30, 0).toISOString();
+    // Math.ceil of the ~6.5h fraction would round up to 1 ("Due in 1 day");
+    // same-calendar-day detection must yield 0 → "Due today".
+    expect(dueDateDiffDays(laterToday, now)).toBe(0);
+  });
+
+  it("returns whole days for future deadlines on later calendar days", () => {
+    const now = new Date(2026, 5, 15, 12, 0, 0).getTime();
+    const tomorrow = new Date(2026, 5, 16, 12, 0, 0).toISOString();
+    const inThree = new Date(2026, 5, 18, 12, 0, 0).toISOString();
+    expect(dueDateDiffDays(tomorrow, now)).toBe(1);
+    expect(dueDateDiffDays(inThree, now)).toBe(3);
+  });
+});
diff --git a/src/components/layout/sidebar-utils.ts b/src/components/layout/sidebar-utils.ts
new file mode 100644
index 000000000..2b670679a
--- /dev/null
+++ b/src/components/layout/sidebar-utils.ts
@@ -0,0 +1,82 @@
+/**
+ * Pure helpers for the sidebar, extracted from sidebar.tsx so the
+ * keyboard-shortcut mapping, per-project open-card aggregation, and due-date
+ * severity bucketing can be unit-tested without rendering the sidebar.
+ */
+
+/**
+ * Map each visible nav view to its keyboard shortcut label (⌘3, ⌘4, …).
+ *
+ * Overview is ⌘1 and Notes is ⌘2, so views start at `base` (3). Shortcuts past
+ * ⌘9 are dropped (empty string) since there's no single-digit key for them.
+ *
+ * The modifier symbol matches the platform: ⌘ on macOS, Ctrl elsewhere — the
+ * page.tsx shortcut handler accepts both `metaKey` and `ctrlKey`, so the label
+ * must reflect whichever the user actually presses.
+ */
+export function buildShortcutMap(
+  visibleNavItems: Array<{ view: string }>,
+  base = 3,
+  isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform),
+): Map<string, string> {
+  const map = new Map<string, string>();
+  const prefix = isMac ? "\u2318" : "Ctrl+";
+  visibleNavItems.forEach((item, idx) => {
+    const num = idx + base;
+    map.set(item.view, num <= 9 ? `${prefix}${num}` : "");
+  });
+  return map;
+}
+
+/**
+ * Count non-archived ("open") cards per project in a single pass — O(cards)
+ * rather than O(projects × cards).
+ */
+export function countOpenCardsByProject(
+  cards: Array<{ projectId: string; archivedAt?: string }>,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const c of cards) {
+    if (c.archivedAt) continue;
+    counts.set(c.projectId, (counts.get(c.projectId) ?? 0) + 1);
+  }
+  return counts;
+}
+
+export type DueDateSeverity = "danger" | "warning" | null;
+
+/**
+ * Bucket a due date relative to `now` into a severity:
+ *  - "danger"  → overdue (in the past)
+ *  - "warning" → due within the next 7 days (inclusive, including today)
+ *  - null      → more than 7 days away
+ *
+ * Uses whole-day ceiling so "later today" still counts as 0 days (due today).
+ */
+export function dueDateSeverity(dueDate: string, now: number = Date.now()): DueDateSeverity {
+  const due = new Date(dueDate).getTime();
+  // Any timestamp strictly before now is overdue. Checking this first avoids
+  // Math.ceil rounding a small negative diff (e.g. earlier today) up to -0,
+  // which would otherwise slip through to the 7-day "warning" branch.
+  if (due < now) return "danger";
+  const diffDays = Math.ceil((due - now) / (1000 * 60 * 60 * 24));
+  if (diffDays <= 7) return "warning";
+  return null;
+}
+
+/**
+ * Whole-day countdown from `now` to a due date, used for the "Due in N days"
+ * label. A deadline later *today* is 0 days away, but `Math.ceil` of a small
+ * positive fraction rounds up to 1 ("Due in 1 day"); detect the same calendar
+ * day first and return 0 before falling back to the ceiling calculation.
+ */
+export function dueDateDiffDays(dueDate: string, now: number = Date.now()): number {
+  const due = new Date(dueDate);
+  const nowDate = new Date(now);
+  const sameCalendarDay =
+    due.getFullYear() === nowDate.getFullYear() &&
+    due.getMonth() === nowDate.getMonth() &&
+    due.getDate() === nowDate.getDate();
+  if (sameCalendarDay) return 0;
+  return Math.ceil((due.getTime() - now) / (1000 * 60 * 60 * 24));
+}
diff --git a/src/components/layout/sidebar.tsx b/src/components/layout/sidebar.tsx
index 30d685b1a..c1cd2147c 100644
--- a/src/components/layout/sidebar.tsx
+++ b/src/components/layout/sidebar.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import React, { useState, useRef, useEffect, useCallback, useMemo } from "react";
+import React, { useState, useRef, useEffect, useCallback } from "react";
 import {
   FileText, Kanban, Settings, Search, MessageSquare,
   ChevronDown, ChevronRight, Plus, MoreHorizontal,
@@ -19,6 +19,7 @@ import {
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogClose } from "@/components/ui/dialog";
 import { WorkspaceSwitcher } from "./sidebar/WorkspaceSwitcher";
 import { ProjectCreateForm } from "./sidebar/ProjectCreateForm";
+import { buildShortcutMap, countOpenCardsByProject, dueDateSeverity, dueDateDiffDays } from "./sidebar-utils";
 import type { Project } from "@/types";
 
 // ── View nav config ───────────────────────────────────────────────────────────
@@ -78,15 +79,10 @@ export function Sidebar() {
     [hiddenViews],
   );
   // ⌘1 = overview, ⌘2 = notes, then visible views in order
-  const shortcutBase = 3; // first view after overview+notes
-  const shortcutMap = React.useMemo(() => {
-    const map = new Map<string, string>();
-    visibleNavItems.forEach((item, idx) => {
-      const num = idx + shortcutBase;
-      map.set(item.view, num <= 9 ? `⌘${num}` : "");
-    });
-    return map;
-  }, [visibleNavItems]);
+  const shortcutMap = React.useMemo(
+    () => buildShortcutMap(visibleNavItems),
+    [visibleNavItems],
+  );
   function shortcutLabel(item: ViewNavItem): string {
     return shortcutMap.get(item.view) ?? "";
   }
@@ -240,11 +236,7 @@ export function Sidebar() {
             <div className="space-y-0.5 px-1">
               {(() => {
                 // Pre-compute card counts per project to avoid O(projects × cards) in the map
-                const openCardCountByProject = new Map<string, number>();
-                for (const c of cards) {
-                  if (c.archivedAt) continue;
-                  openCardCountByProject.set(c.projectId, (openCardCountByProject.get(c.projectId) ?? 0) + 1);
-                }
+                const openCardCountByProject = countOpenCardsByProject(cards);
                 return projects.map((project) => (
                   <ProjectItem
                     key={project.id}
@@ -424,20 +416,22 @@ function ProjectItem({ project, isActive, isExpanded, onToggleExpand, onSelectPr
 }
 
 function DueDateDot({ dueDate }: { dueDate: string }) {
-  const { diffDays, dueDateLabel } = useMemo(() => {
-    const due = new Date(dueDate);
-    return {
-      // eslint-disable-next-line react-hooks/purity
-      diffDays: Math.ceil((due.getTime() - Date.now()) / (1000 * 60 * 60 * 24)),
-      dueDateLabel: due.toLocaleDateString(),
-    };
-  }, [dueDate]);
-  if (diffDays < 0) return (
+  // Computed on every render rather than memoised on `dueDate` alone: a memo
+  // keyed only by dueDate would freeze Date.now() at first render, so the
+  // severity/diffDays/label would go stale as wall-clock time advances while
+  // the app stays open (e.g. a "due in 1 day" item never ticking to overdue).
+  const due = new Date(dueDate);
+  // eslint-disable-next-line react-hooks/purity
+  const now = Date.now();
+  const severity = dueDateSeverity(dueDate, now);
+  const diffDays = dueDateDiffDays(dueDate, now);
+  const dueDateLabel = due.toLocaleDateString();
+  if (severity === "danger") return (
     <Tooltip content={`Overdue — due ${dueDateLabel}`} side="right">
       <span className="w-1.5 h-1.5 rounded-full bg-[var(--danger)] flex-shrink-0" />
     </Tooltip>
   );
-  if (diffDays <= 7) return (
+  if (severity === "warning") return (
     <Tooltip content={diffDays === 0 ? "Due today" : `Due in ${diffDays} day${diffDays !== 1 ? "s" : ""}`} side="right">
       <span className="w-1.5 h-1.5 rounded-full bg-[var(--warning)] flex-shrink-0" />
     </Tooltip>
diff --git a/src/components/notes/ai-text-toolbar.component.test.tsx b/src/components/notes/ai-text-toolbar.component.test.tsx
new file mode 100644
index 000000000..3685e10b4
--- /dev/null
+++ b/src/components/notes/ai-text-toolbar.component.test.tsx
@@ -0,0 +1,126 @@
+/**
+ * Tests for the note editor's text-formatting + AI-prompt logic
+ * (ai-text-toolbar.tsx).
+ *
+ *  - buildAIActionPrompt: pure prompt builder; guards prompt drift and the
+ *    custom-action branch.
+ *  - applyFormat: the wrap/unwrap + line-prefix toggle logic, driven through a
+ *    real headless CodeMirror EditorView. This has a huge branch surface and
+ *    "toggle on then off" idempotency is exactly where edits regress.
+ *
+ * Runs in the "component" project (jsdom) because EditorView needs a DOM and
+ * the module imports React UI.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { EditorState } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import { buildAIActionPrompt, applyFormat, type FormatAction } from "./ai-text-toolbar";
+
+// ── buildAIActionPrompt ───────────────────────────────────────────────────────
+describe("buildAIActionPrompt", () => {
+  it("embeds the selected text and an action-specific instruction", () => {
+    const p = buildAIActionPrompt("summarize", "Hello world");
+    expect(p).toContain('"Hello world"');
+    expect(p).toContain("Summarize this text concisely");
+    expect(p).toContain("Return only the summary");
+  });
+
+  it("uses the custom prompt for the custom action", () => {
+    const p = buildAIActionPrompt("custom", "selected", "Translate to French");
+    expect(p).toContain("Translate to French");
+    expect(p).toContain("Return only the resulting text");
+  });
+
+  it("produces a distinct instruction per action", () => {
+    const actions = ["rephrase", "summarize", "expand", "fix_grammar", "change_tone"] as const;
+    const tails = actions.map((a) => buildAIActionPrompt(a, "x").split("highlighted text")[0]);
+    // Each prompt should differ (no two actions collapse to the same text).
+    expect(new Set(tails).size).toBe(actions.length);
+  });
+});
+
+// ── applyFormat ───────────────────────────────────────────────────────────────
+describe("applyFormat", () => {
+  let view: EditorView | null = null;
+
+  afterEach(() => {
+    view?.destroy();
+    view = null;
+  });
+
+  /** Build a headless EditorView with the given doc and selection range. */
+  function mk(doc: string, from: number, to: number): EditorView {
+    const state = EditorState.create({ doc, selection: { anchor: from, head: to } });
+    view = new EditorView({ state, parent: document.body });
+    return view;
+  }
+
+  const docText = (v: EditorView) => v.state.doc.toString();
+
+  it("wraps a selection in bold markers", () => {
+    const v = mk("hello", 0, 5);
+    applyFormat(v, "bold");
+    expect(docText(v)).toBe("**hello**");
+  });
+
+  it("unwraps an already-bold selection (toggle off)", () => {
+    const v = mk("**hello**", 0, 9);
+    applyFormat(v, "bold");
+    expect(docText(v)).toBe("hello");
+  });
+
+  it("is idempotent: wrap then unwrap restores the original", () => {
+    const v = mk("text", 0, 4);
+    const first = applyFormat(v, "italic");
+    // Re-select the wrapped range and toggle again.
+    v.dispatch({ selection: { anchor: first!.from, head: first!.to } });
+    applyFormat(v, "italic");
+    expect(docText(v)).toBe("text");
+  });
+
+  it("inserts a placeholder when wrapping an empty selection", () => {
+    const v = mk("", 0, 0);
+    applyFormat(v, "bold");
+    expect(docText(v)).toBe("**bold text**");
+  });
+
+  it("wraps a selection as a link with a url placeholder", () => {
+    const v = mk("Cairn", 0, 5);
+    applyFormat(v, "link");
+    expect(docText(v)).toBe("[Cairn](url)");
+  });
+
+  it("unwraps an existing markdown link back to its text", () => {
+    const v = mk("[Cairn](https://x.com)", 0, 22);
+    applyFormat(v, "link");
+    expect(docText(v)).toBe("Cairn");
+  });
+
+  it("toggles a bullet-list line prefix", () => {
+    const v = mk("item", 0, 4);
+    applyFormat(v, "bullet");
+    expect(docText(v)).toBe("- item");
+    // toggle off
+    v.dispatch({ selection: { anchor: 0, head: v.state.doc.length } });
+    applyFormat(v, "bullet");
+    expect(docText(v)).toBe("item");
+  });
+
+  it("toggles a heading prefix", () => {
+    const v = mk("Title", 0, 5);
+    applyFormat(v, "h2");
+    expect(docText(v)).toBe("## Title");
+  });
+
+  it("returns a range for inline formatting (used to re-select)", () => {
+    const v = mk("x", 0, 1);
+    const r = applyFormat(v, "bold");
+    expect(r).not.toBeNull();
+    expect(r!.to).toBeGreaterThan(r!.from);
+  });
+});
+
+// keep the FormatAction type referenced so an unused-import lint never trips
+const _action: FormatAction = "bold";
+void _action;
diff --git a/src/components/notes/markdown-editor.component.test.tsx b/src/components/notes/markdown-editor.component.test.tsx
new file mode 100644
index 000000000..9065c9422
--- /dev/null
+++ b/src/components/notes/markdown-editor.component.test.tsx
@@ -0,0 +1,134 @@
+/**
+ * Tests for markdown list continuation + renumbering in the CodeMirror editor.
+ *
+ * The editor's Enter/Backspace bindings (markdown-editor.tsx) delegate to
+ * @codemirror/lang-markdown's `insertNewlineContinueMarkup` /
+ * `deleteMarkupBackward` so that ordered lists auto-continue and renumber.
+ * This builds the same keymap + markdown extension against a real headless
+ * EditorView and drives the commands directly — guarding the wiring that, if
+ * dropped, silently reverts to a plain newline (the original bug).
+ *
+ * Runs in the "component" project (jsdom) because EditorView needs a DOM.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { EditorState } from "@codemirror/state";
+import { EditorView, keymap } from "@codemirror/view";
+import { defaultKeymap } from "@codemirror/commands";
+import {
+  markdown,
+  markdownLanguage,
+  insertNewlineContinueMarkup,
+  deleteMarkupBackward,
+} from "@codemirror/lang-markdown";
+
+let view: EditorView | null = null;
+afterEach(() => {
+  view?.destroy();
+  view = null;
+});
+
+function makeView(doc: string, cursor: number): EditorView {
+  const state = EditorState.create({
+    doc,
+    selection: { anchor: cursor },
+    extensions: [
+      // Mirror markdown-editor.tsx ordering: markdown bindings precede defaults.
+      keymap.of([
+        { key: "Enter", run: insertNewlineContinueMarkup },
+        { key: "Backspace", run: deleteMarkupBackward },
+        ...defaultKeymap,
+      ]),
+      markdown({ base: markdownLanguage }),
+    ],
+  });
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  return new EditorView({ state, parent: el });
+}
+
+/**
+ * Dispatch a real keydown against the editor's content DOM so the event flows
+ * through CodeMirror's installed keymap handler — exercising the actual binding
+ * order (markdown commands before defaultKeymap) rather than calling the
+ * commands directly. Returns whether the keymap handled (preventDefault'd) it.
+ */
+function dispatchKey(v: EditorView, key: string): boolean {
+  v.focus();
+  const event = new KeyboardEvent("keydown", {
+    key,
+    code: key,
+    bubbles: true,
+    cancelable: true,
+  });
+  v.contentDOM.dispatchEvent(event);
+  return event.defaultPrevented;
+}
+
+/** Simulate the Enter binding firing at the current selection via the keymap. */
+function pressEnter(v: EditorView): boolean {
+  return dispatchKey(v, "Enter");
+}
+function pressBackspace(v: EditorView): boolean {
+  return dispatchKey(v, "Backspace");
+}
+
+describe("ordered-list continuation", () => {
+  it("continues numbering on Enter at end of an ordered item", () => {
+    const doc = "1. first";
+    view = makeView(doc, doc.length);
+    expect(pressEnter(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe("1. first\n2. ");
+  });
+
+  it("continues bullet markers on Enter", () => {
+    const doc = "- item";
+    view = makeView(doc, doc.length);
+    expect(pressEnter(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe("- item\n- ");
+  });
+
+  it("renumbers following items when a new item is inserted mid-list", () => {
+    // Cursor at end of "1. a"; inserting a new item should bump 2→3, 3→... etc.
+    const doc = "1. a\n2. b\n3. c";
+    view = makeView(doc, 4); // end of "1. a"
+    expect(pressEnter(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe("1. a\n2. \n3. b\n4. c");
+  });
+});
+
+describe("breaking the list (the reported bug)", () => {
+  it("breaks out of the list on Enter from an empty continued item", () => {
+    // "1. a\n2. " with cursor after "2. " — pressing Enter terminates the list
+    // by inserting a blank line rather than emitting "3. ". The first item's
+    // numbering is left intact.
+    const doc = "1. a\n2. ";
+    view = makeView(doc, doc.length);
+    expect(pressEnter(view)).toBe(true);
+    const out = view.state.doc.toString();
+    // First item untouched, and no "3." was auto-generated.
+    expect(out.startsWith("1. a")).toBe(true);
+    expect(out).not.toContain("3. ");
+  });
+
+  it("removes the marker and renumbers when Backspace deletes an item's number", () => {
+    // Deleting the auto-number of item 2 should not leave a stale "2." that
+    // breaks ordering — deleteMarkupBackward strips the markup cleanly.
+    const doc = "1. a\n2. ";
+    view = makeView(doc, doc.length);
+    expect(pressBackspace(view)).toBe(true);
+    // Marker removed; remaining content has no dangling "2." prefix line.
+    expect(view.state.doc.toString().endsWith("2. ")).toBe(false);
+  });
+});
+
+describe("non-list context falls through", () => {
+  it("inserts a plain newline outside list markup (defaultKeymap fallthrough)", () => {
+    const doc = "plain paragraph";
+    view = makeView(doc, doc.length);
+    // Outside a list the markdown command declines, so the Enter keybinding
+    // falls through to defaultKeymap, which inserts a newline.
+    expect(pressEnter(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe("plain paragraph\n");
+  });
+});
diff --git a/src/components/notes/markdown-editor.tsx b/src/components/notes/markdown-editor.tsx
index addc92f72..07c89c472 100644
--- a/src/components/notes/markdown-editor.tsx
+++ b/src/components/notes/markdown-editor.tsx
@@ -10,7 +10,12 @@
 import React, { useEffect, useRef, useImperativeHandle, forwardRef } from "react";
 import { EditorView, ViewUpdate, keymap, placeholder as cmPlaceholder } from "@codemirror/view";
 import { EditorState, Compartment } from "@codemirror/state";
-import { markdown, markdownLanguage } from "@codemirror/lang-markdown";
+import {
+  markdown,
+  markdownLanguage,
+  insertNewlineContinueMarkup,
+  deleteMarkupBackward,
+} from "@codemirror/lang-markdown";
 import { languages } from "@codemirror/language-data";
 import { defaultKeymap, indentWithTab, history, historyKeymap } from "@codemirror/commands";
 import { search, searchKeymap } from "@codemirror/search";
@@ -243,7 +248,18 @@ const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorProps>(
         doc: initialValue,
         extensions: [
           history(),
-          keymap.of([...defaultKeymap, ...historyKeymap, indentWithTab, ...searchKeymap]),
+          keymap.of([
+            // Markdown-aware list continuation + renumbering. Must precede
+            // defaultKeymap so its Enter/Backspace bindings take priority;
+            // both commands return false outside markdown markup and fall
+            // through to the default newline/delete behaviour.
+            { key: "Enter", run: insertNewlineContinueMarkup },
+            { key: "Backspace", run: deleteMarkupBackward },
+            ...defaultKeymap,
+            ...historyKeymap,
+            indentWithTab,
+            ...searchKeymap,
+          ]),
           markdown({
             base: markdownLanguage,
             codeLanguages: languages,
diff --git a/src/components/notes/markdown-pipeline.bench.test.ts b/src/components/notes/markdown-pipeline.bench.test.ts
index 63d2a1b73..87f62edac 100644
--- a/src/components/notes/markdown-pipeline.bench.test.ts
+++ b/src/components/notes/markdown-pipeline.bench.test.ts
@@ -51,6 +51,13 @@ type FixtureName = keyof typeof fixtures;
 // ── Pipeline stages (exact mirrors of note-editor.tsx) ────────────────────────
 
 // ── Benchmark harness ─────────────────────────────────────────────────────────
+//
+// Each `it` runs the stage under test for many iterations, so its *total* wall
+// time (not just per-iteration p95) can exceed vitest's default 5s timeout on
+// slow/contended CI runners — the failure mode seen on GitHub shared runners.
+// We give the whole suite a generous explicit timeout below (BENCH_TIMEOUT_MS)
+// and keep iteration counts modest so a stable p95 is reached quickly.
+const BENCH_TIMEOUT_MS = 30_000;
 
 interface BenchResult {
   mean: number;
@@ -61,7 +68,7 @@ interface BenchResult {
   iterations: number;
 }
 
-function bench(fn: () => void, iterations = 100): BenchResult {
+function bench(fn: () => void, iterations = 60): BenchResult {
   for (let i = 0; i < Math.min(10, iterations); i++) fn(); // warmup
   const times: number[] = [];
   for (let i = 0; i < iterations; i++) {
@@ -116,13 +123,12 @@ describe("Markdown pipeline benchmarks", () => {
     const md = fixtures[fixtureName];
 
     describe(`fixture: ${fixtureName} (${md.length} chars)`, () => {
-
       // ── Stage 1: remark-parse only ───────────────────────────────────────
       it("remark-parse: string → mdast", () => {
         const r = bench(() => unified().use(remarkParse).parse(md));
         console.log(`  [${fixtureName}] remark-parse          ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["remark-parse"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 2: remark-gfm + remark-math ───────────────────────────────
       // Note: .parse() only runs the parser; transforms run during .runSync().
@@ -131,7 +137,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => remarkProcessor.runSync(remarkProcessor.parse(md)));
         console.log(`  [${fixtureName}] remark-gfm+math       ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["remark-gfm+math"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 3: remarkCallout transformer ───────────────────────────────
       // Input: mdast after remark-gfm+math. Clone once, run N times.
@@ -141,7 +147,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => transformer(structuredClone(mdast)));
         console.log(`  [${fixtureName}] remark-callout        ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["remark-callout"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 4: remarkPromoteDisplayMath transformer ────────────────────
       it("remarkPromoteDisplayMath plugin", () => {
@@ -150,7 +156,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => transformer(structuredClone(mdast)));
         console.log(`  [${fixtureName}] remark-promoteDisplay ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["remark-promoteDisplay"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 5: remark-rehype (mdast → hast) ───────────────────────────
       // Input: fully transformed mdast (callout + promoteDisplay applied).
@@ -160,7 +166,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => toHast.runSync(structuredClone(mdast) as any));
         console.log(`  [${fixtureName}] remark→hast           ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["remark→hast"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 6: rehypeCaptureLatex ──────────────────────────────────────
       // Input: hast after remark-rehype (before rehype-katex).
@@ -172,7 +178,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => transformer(structuredClone(preKatexHast)));
         console.log(`  [${fixtureName}] rehype-captureLatex   ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["rehype-captureLatex"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 7: rehype-katex ────────────────────────────────────────────
       // Input: hast after captureLatex (so latexBlocks is populated),
@@ -190,7 +196,7 @@ describe("Markdown pipeline benchmarks", () => {
         }, 50);
         console.log(`  [${fixtureName}] rehype-katex          ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["rehype-katex"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Stage 8: rehypeMergedPass (tagLatex + ==highlights==) ───────────
       // Input: hast after rehype-katex (katex-display spans present).
@@ -204,7 +210,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => transformer(structuredClone(postKatexHast)));
         console.log(`  [${fixtureName}] rehype-mergedPass     ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["rehype-mergedPass"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
 
       // ── Full pipeline ────────────────────────────────────────────────────
       // Times the complete string → final hast path as ReactMarkdown runs it.
@@ -224,7 +230,7 @@ describe("Markdown pipeline benchmarks", () => {
         const r = bench(() => processor.runSync(processor.parse(md)), 50);
         console.log(`  [${fixtureName}] FULL PIPELINE         ${fmt(r)}`);
         expect(r.p95).toBeLessThan(CEILINGS["full-pipeline"][fixtureName]);
-      });
+      }, BENCH_TIMEOUT_MS);
     });
   }
 });
diff --git a/src/components/notes/note-editor-utils.test.ts b/src/components/notes/note-editor-utils.test.ts
new file mode 100644
index 000000000..0bbabea64
--- /dev/null
+++ b/src/components/notes/note-editor-utils.test.ts
@@ -0,0 +1,126 @@
+import { describe, it, expect } from "vitest";
+import { toggleCheckboxInSource } from "./note-editor-utils";
+
+describe("toggleCheckboxInSource — list-item checkboxes", () => {
+  it("toggles an unchecked list item to checked", () => {
+    expect(toggleCheckboxInSource("- [ ] task", 0)).toBe("- [x] task");
+  });
+
+  it("toggles a checked list item back to unchecked", () => {
+    expect(toggleCheckboxInSource("- [x] task", 0)).toBe("- [ ] task");
+  });
+
+  it("treats uppercase [X] as checked → unchecks it", () => {
+    expect(toggleCheckboxInSource("- [X] task", 0)).toBe("- [ ] task");
+  });
+
+  it("toggles the correct item by document-order index", () => {
+    const src = "- [ ] a\n- [ ] b\n- [ ] c";
+    expect(toggleCheckboxInSource(src, 1)).toBe("- [ ] a\n- [x] b\n- [ ] c");
+  });
+
+  it("supports *, + and ordered list markers", () => {
+    expect(toggleCheckboxInSource("* [ ] a", 0)).toBe("* [x] a");
+    expect(toggleCheckboxInSource("+ [ ] a", 0)).toBe("+ [x] a");
+    expect(toggleCheckboxInSource("1. [ ] a", 0)).toBe("1. [x] a");
+    expect(toggleCheckboxInSource("2) [ ] a", 0)).toBe("2) [x] a");
+  });
+
+  it("preserves indentation of nested items", () => {
+    const src = "- [ ] parent\n  - [ ] child";
+    expect(toggleCheckboxInSource(src, 1)).toBe("- [ ] parent\n  - [x] child");
+  });
+
+  it("toggles only the marker checkbox, not literal [x] text later on the line", () => {
+    // The marker box must flip; the literal "[x]" inside the item text must not.
+    const src = "- [ ] see the [x] in this text";
+    expect(toggleCheckboxInSource(src, 0)).toBe("- [x] see the [x] in this text");
+  });
+});
+
+describe("toggleCheckboxInSource — table-cell checkboxes", () => {
+  const table = [
+    "| Task | Done |",
+    "| --- | --- |",
+    "| Write tests | [ ] |",
+    "| Ship it | [x] |",
+  ].join("\n");
+
+  it("toggles a checkbox inside a table body cell", () => {
+    const out = toggleCheckboxInSource(table, 0);
+    expect(out.split("\n")[2]).toBe("| Write tests | [x] |");
+  });
+
+  it("toggles the second table checkbox by index", () => {
+    const out = toggleCheckboxInSource(table, 1);
+    expect(out.split("\n")[3]).toBe("| Ship it | [ ] |");
+  });
+
+  it("handles multiple checkboxes in a single row in order", () => {
+    const row = "| [ ] | [ ] | [ ] |";
+    expect(toggleCheckboxInSource(row, 0)).toBe("| [x] | [ ] | [ ] |");
+    expect(toggleCheckboxInSource(row, 2)).toBe("| [ ] | [ ] | [x] |");
+  });
+
+  it("does not treat the delimiter row as a checkbox", () => {
+    const out = toggleCheckboxInSource(table, 0);
+    expect(out.split("\n")[1]).toBe("| --- | --- |");
+  });
+
+  it("ignores non-cell-leading checkbox text when indexing cells", () => {
+    // Only the cell-leading `[ ]` renders as a checkbox (mirrors
+    // renderCellWithCheckboxes); the mid-cell literal "[ ]" must not consume an
+    // index or be toggled.
+    const row = "| [ ] | note [ ] here | [ ] |";
+    // index 0 → first cell-leading box; index 1 → the THIRD cell's leading box
+    // (the literal mid-text box in cell 2 is skipped entirely).
+    expect(toggleCheckboxInSource(row, 0)).toBe("| [x] | note [ ] here | [ ] |");
+    expect(toggleCheckboxInSource(row, 1)).toBe("| [ ] | note [ ] here | [x] |");
+  });
+});
+
+describe("toggleCheckboxInSource — mixed lists and tables (document order)", () => {
+  const mixed = [
+    "- [ ] before-table",      // index 0
+    "",
+    "| x | y |",
+    "| - | - |",
+    "| [ ] | a |",             // index 1
+    "",
+    "- [ ] after-table",       // index 2
+  ].join("\n");
+
+  it("indexes a list item that precedes a table", () => {
+    expect(toggleCheckboxInSource(mixed, 0).split("\n")[0]).toBe("- [x] before-table");
+  });
+
+  it("indexes a table checkbox between list items", () => {
+    expect(toggleCheckboxInSource(mixed, 1).split("\n")[4]).toBe("| [x] | a |");
+  });
+
+  it("indexes a list item that follows a table", () => {
+    expect(toggleCheckboxInSource(mixed, 2).split("\n")[6]).toBe("- [x] after-table");
+  });
+});
+
+describe("toggleCheckboxInSource — boundaries", () => {
+  it("returns source unchanged for out-of-range index", () => {
+    const src = "- [ ] only";
+    expect(toggleCheckboxInSource(src, 5)).toBe(src);
+  });
+
+  it("returns source unchanged for negative index", () => {
+    const src = "- [ ] only";
+    expect(toggleCheckboxInSource(src, -1)).toBe(src);
+  });
+
+  it("returns source unchanged when there are no checkboxes", () => {
+    const src = "# heading\n\nplain text";
+    expect(toggleCheckboxInSource(src, 0)).toBe(src);
+  });
+
+  it("only mutates the targeted checkbox, leaving others untouched", () => {
+    const src = "- [x] a\n- [ ] b";
+    expect(toggleCheckboxInSource(src, 0)).toBe("- [ ] a\n- [ ] b");
+  });
+});
diff --git a/src/components/notes/note-editor-utils.ts b/src/components/notes/note-editor-utils.ts
index f28413f81..030ea0b71 100644
--- a/src/components/notes/note-editor-utils.ts
+++ b/src/components/notes/note-editor-utils.ts
@@ -14,6 +14,84 @@ export function countWords(md: string): number {
   return text.split(/\s+/).filter(Boolean).length;
 }
 
+/**
+ * Toggle the Nth task-list checkbox in raw markdown source.
+ *
+ * Handles both contexts that render a clickable checkbox in the preview:
+ *   1. List-marker task items — `- [ ]` / `* [x]` / `1. [ ]` at line start.
+ *   2. Checkboxes embedded inside GFM table cells — `| [x] | … |`.
+ *      (remark-gfm does not natively turn these into checkbox nodes, so the
+ *       preview injects them via a custom td/th renderer; this keeps the
+ *       source-toggle mapping in sync.)
+ *
+ * Checkboxes are matched in document order so the index lines up with the
+ * top-to-bottom DOM order react-markdown produces. Returns the source
+ * unchanged if `index` is out of range.
+ */
+export function toggleCheckboxInSource(source: string, index: number): string {
+  if (index < 0) return source;
+
+  // Matches a `[ ]`, `[x]` or `[X]` checkbox. We scan line-by-line so that we
+  // can distinguish list-marker checkboxes (one per line, at the start) from
+  // table-cell checkboxes (potentially several per line, inside `| … |`).
+  const listLineRe = /^\s*(?:[-*+]|\d+[.)])\s+\[([ xX])\]/;
+  const tableRowRe = /^\s*\|.*\|/;
+  // A cell renders a checkbox only when the task token leads the cell (mirrors
+  // renderCellWithCheckboxes in note-editor.tsx: `first.match(/^\s*\[…\]\s?/)`).
+  const cellLeadingRe = /^(\s*)\[([ xX])\]/;
+
+  let seen = 0;
+  let changed = false;
+
+  const lines = source.split("\n").map((line) => {
+    if (changed) return line;
+
+    if (listLineRe.test(line)) {
+      // Exactly one task checkbox at the marker position.
+      if (seen === index) {
+        changed = true;
+        // Toggle ONLY the marker checkbox, not any literal `[x]` text later on
+        // the line. listLineRe is non-global, so it matches just the leading
+        // marker + box; the inner non-global replace flips that single box.
+        return line.replace(listLineRe, (full) =>
+          full.replace(/\[([ xX])\]/, (_m, state: string) =>
+            state === " " ? "[x]" : "[ ]"
+          )
+        );
+      }
+      seen += 1;
+      return line;
+    }
+
+    if (tableRowRe.test(line)) {
+      // A table row may contain several cells; only cell-leading task tokens
+      // render as checkboxes, so only those count toward the index. Splitting
+      // on `|` preserves the cell boundaries we rejoin with afterwards.
+      const cells = line.split("|");
+      let lineChanged = false;
+      const newCells = cells.map((cell) => {
+        if (changed) return cell;
+        const cm = cell.match(cellLeadingRe);
+        if (!cm) return cell;
+        if (seen === index) {
+          seen += 1;
+          changed = true;
+          lineChanged = true;
+          const next = cm[2] === " " ? "[x]" : "[ ]";
+          return cell.replace(cellLeadingRe, `${cm[1]}${next}`);
+        }
+        seen += 1;
+        return cell;
+      });
+      return lineChanged ? newCells.join("|") : line;
+    }
+
+    return line;
+  });
+
+  return changed ? lines.join("\n") : source;
+}
+
 export function stripMarkdown(md: string): string {
   return md
     .replace(/^#{1,6}\s+/gm, "")
diff --git a/src/components/notes/note-editor.tsx b/src/components/notes/note-editor.tsx
index 1c64fa93a..d2d916337 100644
--- a/src/components/notes/note-editor.tsx
+++ b/src/components/notes/note-editor.tsx
@@ -27,7 +27,7 @@ import { MarkdownEditor, type MarkdownEditorHandle } from "./markdown-editor";
 import { remarkCallout, remarkObsidianEmbeds, remarkWikilinks, remarkPromoteDisplayMath, makeLatexPlugins, InlineCode } from "@/lib/markdown/pipeline";
 import { BacklinksPanel, NoteTagBar } from "./BacklinksPanel";
 import { MDPreviewPanel } from "./MDPreviewPanel";
-import { countWords, stripMarkdown } from "./note-editor-utils";
+import { countWords, stripMarkdown, toggleCheckboxInSource } from "./note-editor-utils";
 
 interface NoteEditorProps {
   note: Note;
@@ -36,6 +36,45 @@ interface NoteEditorProps {
 
 type EditorMode = "write" | "read";
 
+/**
+ * Render a table cell's children, converting any leading `[ ]` / `[x]` token
+ * into a clickable checkbox. GFM table cells only parse inline content, so
+ * remark-gfm never emits checkbox nodes inside `<td>`/`<th>` — we recover them
+ * here so table task-lists are interactive like list task-items.
+ *
+ * Only the first text child is inspected (the token must lead the cell, mirroring
+ * GFM task-list semantics: `| [x] done | …`). Toggle wiring maps the rendered
+ * checkbox back to source order via toggleCheckboxInSource().
+ */
+function renderCellWithCheckboxes(
+  children: React.ReactNode,
+  onToggle: (el: HTMLInputElement) => void
+): React.ReactNode {
+  const arr = React.Children.toArray(children);
+  if (arr.length === 0) return children;
+
+  const first = arr[0];
+  if (typeof first !== "string") return children;
+
+  const m = first.match(/^\s*\[([ xX])\]\s?/);
+  if (!m) return children;
+
+  const checked = m[1] !== " ";
+  const rest = first.slice(m[0].length);
+  return (
+    <>
+      <input
+        type="checkbox"
+        defaultChecked={checked}
+        className="cursor-pointer accent-[var(--accent)] w-3.5 h-3.5 relative top-[1px] mr-1"
+        onChange={(e) => onToggle(e.currentTarget)}
+      />
+      {rest}
+      {arr.slice(1)}
+    </>
+  );
+}
+
 export function NoteEditor({ note, onBack }: NoteEditorProps) {
   const { updateNote, aiConfig, activeProjectId, getProjectColumns, tags, createTag, getTagById, activeWorkspaceId, setView, notes, projects } = useCairnStore(useShallow((s) => ({
     updateNote:        s.updateNote,
@@ -380,6 +419,26 @@ export function NoteEditor({ note, onBack }: NoteEditorProps) {
   }, [note.id, activeProjectId, getProjectColumns, aiConfig]);
 
   // ── Stable ReactMarkdown component overrides ──────────────────────────────
+  // Toggle the Nth checkbox (document order) in the raw markdown source.
+  // Shared by both list-item checkboxes and table-cell checkboxes so their
+  // indices map to a single source-order scan. `el` is the clicked input;
+  // its index among all `.prose-cairn` checkboxes equals the source index.
+  const toggleCheckbox = useCallback((el: HTMLInputElement) => {
+    const root = el.closest(".prose-cairn");
+    if (!root) return;
+    const checkboxes = Array.from(
+      root.querySelectorAll<HTMLInputElement>("input[type='checkbox']")
+    );
+    const idx = checkboxes.indexOf(el);
+    if (idx === -1) return;
+    const next = toggleCheckboxInSource(note.content ?? "", idx);
+    if (next !== (note.content ?? "")) {
+      // Keep contentText in sync with content (matching the save flow above) so
+      // derived plain-text state doesn't go stale after a preview toggle.
+      updateNote(note.id, { content: next, contentText: stripMarkdown(next) });
+    }
+  }, [note.id, note.content, updateNote]);
+
   // Extracted from JSX so ReactMarkdown receives a stable object reference
   // across renders. Only recreated when the note or updateNote changes.
   // previewScrollRef is a stable ref so it doesn't need to be in deps.
@@ -454,24 +513,7 @@ export function NoteEditor({ note, onBack }: NoteEditorProps) {
           type="checkbox"
           defaultChecked={checked}
           className="cursor-pointer accent-[var(--accent)] w-3.5 h-3.5 relative top-[1px]"
-          onChange={(e) => {
-            const checkboxes = Array.from(
-              e.currentTarget.closest(".prose-cairn")!
-                .querySelectorAll<HTMLInputElement>("input[type='checkbox']")
-            );
-            const idx = checkboxes.indexOf(e.currentTarget);
-            if (idx === -1) return;
-            const lines = (note.content ?? "").split("\n");
-            let found = 0;
-            const next = lines.map((line) => {
-              if (/^(\s*[-*+]\s+)\[([ xX])\]/.test(line)) {
-                if (found === idx) { found++; return line.replace(/\[([ xX])\]/, e.currentTarget.checked ? "[x]" : "[ ]"); }
-                found++;
-              }
-              return line;
-            }).join("\n");
-            updateNote(note.id, { content: next });
-          }}
+          onChange={(e) => toggleCheckbox(e.currentTarget)}
         />
       );
     },
@@ -629,9 +671,16 @@ export function NoteEditor({ note, onBack }: NoteEditorProps) {
         </div>
       );
     },
+    td({ children, style }: { children?: React.ReactNode; style?: React.CSSProperties }) {
+      return <td style={style}>{renderCellWithCheckboxes(children, toggleCheckbox)}</td>;
+    },
+    th({ children, style }: { children?: React.ReactNode; style?: React.CSSProperties }) {
+      return <th style={style}>{renderCellWithCheckboxes(children, toggleCheckbox)}</th>;
+    },
   // previewScrollRef is a stable React ref — no need to list it as a dep
-  // notes is needed for wikilink resolution
-  }), [note.id, note.content, updateNote, notes]) as import("react-markdown").Components;
+  // notes is needed for wikilink resolution; toggleCheckbox carries the
+  // note id/content/updateNote closure for checkbox source-toggling.
+  }), [notes, toggleCheckbox]) as import("react-markdown").Components;
 
   const handleToggleTag = useCallback((tagId: string) => {
     const has = note.tagIds.includes(tagId);
diff --git a/src/components/notes/notes-view/buildFolderTree.test.ts b/src/components/notes/notes-view/buildFolderTree.test.ts
new file mode 100644
index 000000000..5957645e3
--- /dev/null
+++ b/src/components/notes/notes-view/buildFolderTree.test.ts
@@ -0,0 +1,108 @@
+/**
+ * Unit tests for buildFolderTree — the two-pass folder tree builder that powers
+ * the Notes sidebar. Focus on folder-path normalization edge cases.
+ */
+
+import { describe, expect, it } from "vitest";
+import { buildFolderTree, type FolderNode } from "./buildFolderTree";
+import type { Note } from "@/types";
+
+// Minimal note factory — only id + folder matter for the tree shape.
+const note = (id: string, folder?: string): Note =>
+  ({ id, folder, title: id, content: "", contentText: "" } as unknown as Note);
+
+// Find a folder node by path in the (possibly nested) tree.
+function findFolder(folders: FolderNode[], path: string): FolderNode | undefined {
+  for (const f of folders) {
+    if (f.path === path) return f;
+    const nested = findFolder(f.children, path);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+describe("buildFolderTree", () => {
+  it("places notes with no folder at the root", () => {
+    const { rootNotes, folders } = buildFolderTree([
+      note("a"),
+      note("b", ""),
+    ]);
+    expect(rootNotes.map((n) => n.id)).toEqual(["a", "b"]);
+    expect(folders).toEqual([]);
+  });
+
+  it("treats undefined and empty-string folder identically (root)", () => {
+    const { rootNotes } = buildFolderTree([note("a"), note("b", "")]);
+    expect(rootNotes).toHaveLength(2);
+  });
+
+  it("creates a top-level folder and nests its notes", () => {
+    const { rootNotes, folders } = buildFolderTree([note("a", "Work")]);
+    expect(rootNotes).toEqual([]);
+    expect(folders).toHaveLength(1);
+    expect(folders[0].name).toBe("Work");
+    expect(folders[0].path).toBe("Work");
+    expect(folders[0].notes.map((n) => n.id)).toEqual(["a"]);
+  });
+
+  it("builds nested folders from a slash path", () => {
+    const { folders } = buildFolderTree([note("a", "Work/Projects")]);
+    expect(folders).toHaveLength(1);
+    const work = folders[0];
+    expect(work.path).toBe("Work");
+    expect(work.children).toHaveLength(1);
+    expect(work.children[0].path).toBe("Work/Projects");
+    expect(work.children[0].notes.map((n) => n.id)).toEqual(["a"]);
+    // The note lives only in the leaf, not the intermediate folder.
+    expect(work.notes).toEqual([]);
+  });
+
+  it("normalizes leading/trailing/double slashes", () => {
+    const { folders } = buildFolderTree([note("a", "/Work//Projects/")]);
+    const leaf = findFolder(folders, "Work/Projects");
+    expect(leaf).toBeDefined();
+    expect(leaf!.notes.map((n) => n.id)).toEqual(["a"]);
+    // No empty-segment folders were created.
+    expect(findFolder(folders, "")).toBeUndefined();
+  });
+
+  it("groups multiple notes sharing a folder", () => {
+    const { folders } = buildFolderTree([
+      note("a", "Work"),
+      note("b", "Work"),
+    ]);
+    expect(folders).toHaveLength(1);
+    expect(folders[0].notes.map((n) => n.id).sort()).toEqual(["a", "b"]);
+  });
+
+  it("sorts top-level folders alphabetically (case-insensitive locale)", () => {
+    const { folders } = buildFolderTree([
+      note("z", "Zebra"),
+      note("a", "apple"),
+      note("m", "Mango"),
+    ]);
+    expect(folders.map((f) => f.name)).toEqual(["apple", "Mango", "Zebra"]);
+  });
+
+  it("creates intermediate folders even when only a deep leaf has notes", () => {
+    const { folders } = buildFolderTree([note("a", "A/B/C")]);
+    expect(findFolder(folders, "A")).toBeDefined();
+    expect(findFolder(folders, "A/B")).toBeDefined();
+    const leaf = findFolder(folders, "A/B/C");
+    expect(leaf!.notes.map((n) => n.id)).toEqual(["a"]);
+    // Intermediates carry no notes.
+    expect(findFolder(folders, "A")!.notes).toEqual([]);
+    expect(findFolder(folders, "A/B")!.notes).toEqual([]);
+  });
+
+  it("separates root notes from foldered notes in the same input", () => {
+    const { rootNotes, folders } = buildFolderTree([
+      note("root1"),
+      note("foldered", "Docs"),
+      note("root2", ""),
+    ]);
+    expect(rootNotes.map((n) => n.id)).toEqual(["root1", "root2"]);
+    expect(folders).toHaveLength(1);
+    expect(folders[0].notes.map((n) => n.id)).toEqual(["foldered"]);
+  });
+});
diff --git a/src/components/notes/notes-view/buildFolderTree.ts b/src/components/notes/notes-view/buildFolderTree.ts
index a8ba1c935..0439e6c73 100644
--- a/src/components/notes/notes-view/buildFolderTree.ts
+++ b/src/components/notes/notes-view/buildFolderTree.ts
@@ -41,7 +41,7 @@ export function buildFolderTree(notes: Note[]): { rootNotes: Note[]; folders: Fo
   for (const node of folderMap.values()) {
     if (!node.path.includes("/")) topLevel.push(node);
   }
-  topLevel.sort((a, b) => a.name.localeCompare(b.name));
+  topLevel.sort((a, b) => a.name.localeCompare(b.name, "en", { sensitivity: "base" }));
 
   return { rootNotes, folders: topLevel };
 }
diff --git a/src/components/onboarding/StepCreateProject.component.test.tsx b/src/components/onboarding/StepCreateProject.component.test.tsx
new file mode 100644
index 000000000..0dcbdbe18
--- /dev/null
+++ b/src/components/onboarding/StepCreateProject.component.test.tsx
@@ -0,0 +1,143 @@
+/**
+ * Component tests for StepCreateProject (onboarding "create your first project").
+ *
+ * Covers the v2.3.2 presentational behavior that unit tests can't reach:
+ *  - icon picker selection + aria-pressed state
+ *  - submit gating on empty name
+ *  - all controls disabled while a create is in flight
+ *  - accessible labels on icon-only buttons
+ *
+ * Runs in the "component" vitest project (jsdom + Testing Library).
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { StepCreateProject } from "./StepCreateProject";
+
+type Props = React.ComponentProps<typeof StepCreateProject>;
+
+function renderStep(overrides: Partial<Props> = {}) {
+  const props: Props = {
+    name: "",
+    icon: "Folder",
+    submitting: false,
+    onBack: vi.fn(),
+    onNameChange: vi.fn(),
+    onIconChange: vi.fn(),
+    onSubmit: vi.fn((e) => e.preventDefault()),
+    onSkip: vi.fn(),
+    ...overrides,
+  };
+  const utils = render(<StepCreateProject {...props} />);
+  return { props, ...utils };
+}
+
+describe("StepCreateProject", () => {
+  it("renders the heading and primary actions", () => {
+    renderStep();
+    expect(screen.getByRole("heading", { name: /create your first project/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Create project" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Skip/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Go back to previous step" })).toBeInTheDocument();
+  });
+
+  it("disables submit when the name is empty", () => {
+    renderStep({ name: "" });
+    expect(screen.getByRole("button", { name: "Create project" })).toBeDisabled();
+  });
+
+  it("enables submit once a non-empty name is provided", () => {
+    renderStep({ name: "My Project" });
+    expect(screen.getByRole("button", { name: "Create project" })).toBeEnabled();
+  });
+
+  it("treats a whitespace-only name as empty (submit stays disabled)", () => {
+    renderStep({ name: "   " });
+    expect(screen.getByRole("button", { name: "Create project" })).toBeDisabled();
+  });
+
+  it("calls onNameChange as the user types", async () => {
+    const user = userEvent.setup();
+    const { props } = renderStep();
+    const input = screen.getByPlaceholderText(/My First Project/i);
+    await user.type(input, "Hi");
+    expect(props.onNameChange).toHaveBeenCalled();
+  });
+
+  it("exposes aria-pressed on the selected icon and aria-labels on each icon button", () => {
+    renderStep({ icon: "Rocket" });
+    const selected = screen.getByRole("button", { name: "Use Rocket icon" });
+    expect(selected).toHaveAttribute("aria-pressed", "true");
+
+    const other = screen.getByRole("button", { name: "Use Folder icon" });
+    expect(other).toHaveAttribute("aria-pressed", "false");
+  });
+
+  it("calls onIconChange with the picked icon name", async () => {
+    const user = userEvent.setup();
+    const { props } = renderStep({ icon: "Folder" });
+    await user.click(screen.getByRole("button", { name: "Use Rocket icon" }));
+    expect(props.onIconChange).toHaveBeenCalledWith("Rocket");
+  });
+
+  it("calls onSkip when the skip button is clicked", async () => {
+    const user = userEvent.setup();
+    const { props } = renderStep();
+    await user.click(screen.getByRole("button", { name: /Skip/i }));
+    expect(props.onSkip).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onBack when the back button is clicked", async () => {
+    const user = userEvent.setup();
+    const { props } = renderStep();
+    await user.click(screen.getByRole("button", { name: "Go back to previous step" }));
+    expect(props.onBack).toHaveBeenCalledTimes(1);
+  });
+
+  describe("while submitting", () => {
+    it("shows the loading label and disables the submit button", () => {
+      renderStep({ name: "My Project", submitting: true });
+      const submit = screen.getByRole("button", { name: "Creating…" });
+      expect(submit).toBeDisabled();
+    });
+
+    it("disables back, skip, and every icon button", () => {
+      renderStep({ name: "My Project", submitting: true });
+
+      expect(screen.getByRole("button", { name: "Go back to previous step" })).toBeDisabled();
+      expect(screen.getByRole("button", { name: /Skip/i })).toBeDisabled();
+
+      // Every icon picker button is disabled.
+      for (const btn of screen.getAllByRole("button", { name: /^Use .+ icon$/ })) {
+        expect(btn).toBeDisabled();
+      }
+    });
+
+    it("does not invoke handlers when disabled controls are clicked", async () => {
+      const user = userEvent.setup();
+      const { props } = renderStep({ name: "My Project", submitting: true });
+
+      await user.click(screen.getByRole("button", { name: "Go back to previous step" }));
+      await user.click(screen.getByRole("button", { name: /Skip/i }));
+      await user.click(screen.getByRole("button", { name: "Use Rocket icon" }));
+
+      expect(props.onBack).not.toHaveBeenCalled();
+      expect(props.onSkip).not.toHaveBeenCalled();
+      expect(props.onIconChange).not.toHaveBeenCalled();
+    });
+  });
+
+  it("limits the name input to 48 characters", () => {
+    renderStep();
+    const input = screen.getByPlaceholderText(/My First Project/i);
+    expect(input).toHaveAttribute("maxLength", "48");
+  });
+
+  it("submits the form when a valid name is present", async () => {
+    const user = userEvent.setup();
+    const { props } = renderStep({ name: "My Project" });
+    await user.click(screen.getByRole("button", { name: "Create project" }));
+    expect(props.onSubmit).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/components/onboarding/StepDone.component.test.tsx b/src/components/onboarding/StepDone.component.test.tsx
new file mode 100644
index 000000000..e111d1fae
--- /dev/null
+++ b/src/components/onboarding/StepDone.component.test.tsx
@@ -0,0 +1,39 @@
+/**
+ * Component test for StepDone — the final onboarding slide ("Open Cairn").
+ *
+ * Guards the UI half of the onboarding-completion chain: clicking "Open Cairn"
+ * must invoke onComplete with the tour-checkbox state. page.tsx wires that
+ * onComplete to completeOnboarding(), whose hydrate-before-exit ordering is
+ * unit-tested in src/lib/complete-onboarding.test.ts.
+ *
+ * Runs in the "component" vitest project (jsdom + Testing Library).
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { StepDone } from "./StepDone";
+
+describe("StepDone", () => {
+  it("calls onComplete(true) when the tour checkbox is left checked (default)", async () => {
+    const user = userEvent.setup();
+    const onComplete = vi.fn();
+    render(<StepDone onBack={vi.fn()} onComplete={onComplete} />);
+
+    await user.click(screen.getByRole("button", { name: /Open Cairn/i }));
+
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledWith(true);
+  });
+
+  it("calls onComplete(false) when the tour checkbox is unchecked", async () => {
+    const user = userEvent.setup();
+    const onComplete = vi.fn();
+    render(<StepDone onBack={vi.fn()} onComplete={onComplete} />);
+
+    await user.click(screen.getByRole("checkbox"));
+    await user.click(screen.getByRole("button", { name: /Open Cairn/i }));
+
+    expect(onComplete).toHaveBeenCalledWith(false);
+  });
+});
diff --git a/src/components/search/search-panel.tsx b/src/components/search/search-panel.tsx
index 3f79ddf0b..abefa71dc 100644
--- a/src/components/search/search-panel.tsx
+++ b/src/components/search/search-panel.tsx
@@ -7,6 +7,13 @@ import { CairnEvents } from "@/lib/events";
 import { Tooltip } from "@/components/ui/tooltip";
 import { useCairnStore, type SearchResult } from "@/store";
 import { useShallow } from "zustand/react/shallow";
+import {
+  filterSearchResults,
+  resolveFocusedResult,
+  clampFocus,
+  mergeSemanticResults,
+  type SearchFilterType,
+} from "./search-utils";
 
 interface ResultRowProps {
   result: SearchResult;
@@ -70,7 +77,7 @@ function ResultRow({ result, focused, onSelect, semanticScore }: ResultRowProps)
   );
 }
 
-type FilterType = "all" | "notes" | "tasks";
+type FilterType = SearchFilterType;
 
 const SEMANTIC_KEY = "search.semanticMode";
 
@@ -195,14 +202,7 @@ export function SearchPanel() {
           }
           // Merge: semantic hits that aren't already in keyword results get appended
           setSemanticScores(scoreMap);
-          setResults((prevKeyword) => {
-            const seen = new Set(prevKeyword.map((r) => r.id));
-            const merged = [...prevKeyword];
-            for (const s of enriched) {
-              if (!seen.has(s.id)) merged.push(s);
-            }
-            return merged;
-          });
+          setResults((prevKeyword) => mergeSemanticResults(prevKeyword, enriched));
         } catch {
           // embeddings worker may be down — silently fall back to keyword-only
         }
@@ -229,20 +229,17 @@ export function SearchPanel() {
   }
 
   function handleKeyDown(e: React.KeyboardEvent) {
+    const total = noteResults.length + taskResults.length;
     if (e.key === "ArrowDown") {
       e.preventDefault();
-      setFocused((f) => Math.min(f + 1, (noteResults.length + taskResults.length) - 1));
+      setFocused((f) => clampFocus(f + 1, total));
     } else if (e.key === "ArrowUp") {
       e.preventDefault();
-      setFocused((f) => Math.max(f - 1, 0));
+      setFocused((f) => clampFocus(f - 1, total));
     } else if (e.key === "Enter") {
       // Focus order matches UI order: notes first, then tasks.
-      if (focused < noteResults.length && noteResults[focused]) {
-        handleSelect(noteResults[focused]);
-      } else if (focused >= noteResults.length) {
-        const taskIdx = focused - noteResults.length;
-        if (taskResults[taskIdx]) handleSelect(taskResults[taskIdx]);
-      }
+      const result = resolveFocusedResult(focused, noteResults, taskResults);
+      if (result) handleSelect(result);
     } else if (e.key === "Escape") {
       toggleSearch();
     }
@@ -250,9 +247,7 @@ export function SearchPanel() {
 
   if (!searchOpen) return null;
 
-  const filtered = results
-    .filter((r) => filterType === "all" || (filterType === "notes" ? r.type === "note" : r.type === "card"))
-    .filter((r) => !filterProject || r.projectId === filterProject);
+  const filtered = filterSearchResults(results, filterType, filterProject);
 
   const noteResults = filtered.filter((r) => r.type === "note");
   const taskResults = filtered.filter((r) => r.type === "card");
diff --git a/src/components/search/search-utils.test.ts b/src/components/search/search-utils.test.ts
new file mode 100644
index 000000000..8af1647f4
--- /dev/null
+++ b/src/components/search/search-utils.test.ts
@@ -0,0 +1,116 @@
+/**
+ * Unit tests for search-panel pure logic (search-utils.ts).
+ *
+ *  - filterSearchResults: type ("tasks" → card) + project filtering.
+ *  - resolveFocusedResult / clampFocus: the two-list (notes then tasks)
+ *    keyboard-nav index translation — the classic subtle off-by-one on the
+ *    notes/tasks boundary.
+ *  - mergeSemanticResults: append-only dedupe of semantic hits over keyword hits.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  filterSearchResults,
+  resolveFocusedResult,
+  clampFocus,
+  mergeSemanticResults,
+} from "./search-utils";
+import type { SearchResult } from "@/store";
+
+const r = (id: string, type: "note" | "card", projectId = "p1"): SearchResult => ({
+  type,
+  id,
+  title: id,
+  snippet: "",
+  projectId,
+  projectName: projectId,
+});
+
+describe("filterSearchResults", () => {
+  const results = [r("n1", "note"), r("c1", "card"), r("n2", "note", "p2")];
+
+  it("returns everything for 'all' with no project filter", () => {
+    expect(filterSearchResults(results, "all", null)).toHaveLength(3);
+  });
+
+  it("keeps only notes for 'notes'", () => {
+    const out = filterSearchResults(results, "notes", null);
+    expect(out.map((x) => x.id)).toEqual(["n1", "n2"]);
+  });
+
+  it("maps the 'tasks' tab to card-type results", () => {
+    const out = filterSearchResults(results, "tasks", null);
+    expect(out.map((x) => x.id)).toEqual(["c1"]);
+  });
+
+  it("applies the project filter on top of the type filter", () => {
+    expect(filterSearchResults(results, "all", "p2").map((x) => x.id)).toEqual(["n2"]);
+    expect(filterSearchResults(results, "notes", "p1").map((x) => x.id)).toEqual(["n1"]);
+  });
+});
+
+describe("resolveFocusedResult", () => {
+  const notes = [r("n1", "note"), r("n2", "note")];
+  const tasks = [r("c1", "card"), r("c2", "card")];
+
+  it("resolves indices within the notes range", () => {
+    expect(resolveFocusedResult(0, notes, tasks)?.id).toBe("n1");
+    expect(resolveFocusedResult(1, notes, tasks)?.id).toBe("n2");
+  });
+
+  it("translates indices past the notes into the tasks list", () => {
+    expect(resolveFocusedResult(2, notes, tasks)?.id).toBe("c1");
+    expect(resolveFocusedResult(3, notes, tasks)?.id).toBe("c2");
+  });
+
+  it("returns null for out-of-range or negative indices", () => {
+    expect(resolveFocusedResult(4, notes, tasks)).toBeNull();
+    expect(resolveFocusedResult(-1, notes, tasks)).toBeNull();
+  });
+
+  it("handles an empty notes list (all focus maps to tasks)", () => {
+    expect(resolveFocusedResult(0, [], tasks)?.id).toBe("c1");
+  });
+});
+
+describe("clampFocus", () => {
+  it("clamps within [0, total-1]", () => {
+    expect(clampFocus(-5, 3)).toBe(0);
+    expect(clampFocus(10, 3)).toBe(2);
+    expect(clampFocus(1, 3)).toBe(1);
+  });
+
+  it("returns 0 when there are no results", () => {
+    expect(clampFocus(5, 0)).toBe(0);
+  });
+});
+
+describe("mergeSemanticResults", () => {
+  it("appends only semantic hits not already present by id", () => {
+    const keyword = [r("a", "note"), r("b", "note")];
+    const semantic = [r("b", "note"), r("c", "note")]; // b is a dup
+    const merged = mergeSemanticResults(keyword, semantic);
+    expect(merged.map((x) => x.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("preserves keyword order and position (keyword wins)", () => {
+    const keyword = [r("a", "note")];
+    const semantic = [r("a", "card"), r("z", "note")];
+    const merged = mergeSemanticResults(keyword, semantic);
+    // 'a' keeps its keyword entry (type note), only 'z' is appended.
+    expect(merged.map((x) => `${x.id}:${x.type}`)).toEqual(["a:note", "z:note"]);
+  });
+
+  it("returns the keyword list unchanged when there are no semantic hits", () => {
+    const keyword = [r("a", "note")];
+    expect(mergeSemanticResults(keyword, [])).toEqual(keyword);
+  });
+
+  it("dedupes repeated semantic hits against each other", () => {
+    // Two semantic hits share id "c"; only the first should be appended.
+    const keyword = [r("a", "note")];
+    const semantic = [r("c", "note"), r("c", "note"), r("d", "note")];
+    const merged = mergeSemanticResults(keyword, semantic);
+    expect(merged.map((x) => x.id)).toEqual(["a", "c", "d"]);
+  });
+});
diff --git a/src/components/search/search-utils.ts b/src/components/search/search-utils.ts
new file mode 100644
index 000000000..e424650ed
--- /dev/null
+++ b/src/components/search/search-utils.ts
@@ -0,0 +1,69 @@
+import type { SearchResult } from "@/store";
+
+/**
+ * Pure search-result logic extracted from search-panel.tsx so the type/project
+ * filtering, two-list keyboard-navigation index translation, and semantic-hit
+ * merge/dedupe can be unit-tested without the panel or the embeddings worker.
+ */
+
+export type SearchFilterType = "all" | "notes" | "tasks";
+
+/**
+ * Apply the type filter ("all" | "notes" | "tasks") and an optional project
+ * filter. Note the mapping: the "tasks" tab matches results of type "card".
+ */
+export function filterSearchResults(
+  results: SearchResult[],
+  filterType: SearchFilterType,
+  filterProject: string | null,
+): SearchResult[] {
+  return results
+    .filter((r) =>
+      filterType === "all" || (filterType === "notes" ? r.type === "note" : r.type === "card"),
+    )
+    .filter((r) => !filterProject || r.projectId === filterProject);
+}
+
+/**
+ * Translate a flat keyboard-focus index into the actual result, given the UI
+ * order: notes first, then tasks. Returns null if the index is out of range.
+ *
+ * This is the canonical subtle keyboard-nav bug surface — getting the
+ * notes/tasks boundary wrong selects the wrong row on Enter.
+ */
+export function resolveFocusedResult(
+  focused: number,
+  noteResults: SearchResult[],
+  taskResults: SearchResult[],
+): SearchResult | null {
+  if (focused < 0) return null;
+  if (focused < noteResults.length) return noteResults[focused] ?? null;
+  const taskIdx = focused - noteResults.length;
+  return taskResults[taskIdx] ?? null;
+}
+
+/** Clamp a focus index to the combined results length (min 0). */
+export function clampFocus(focused: number, total: number): number {
+  if (total <= 0) return 0;
+  return Math.max(0, Math.min(focused, total - 1));
+}
+
+/**
+ * Merge semantic hits into the existing keyword results: append only hits whose
+ * id isn't already present (keyword results win and keep their position).
+ */
+export function mergeSemanticResults(
+  keyword: SearchResult[],
+  semantic: SearchResult[],
+): SearchResult[] {
+  const seen = new Set(keyword.map((r) => r.id));
+  const merged = [...keyword];
+  for (const s of semantic) {
+    if (seen.has(s.id)) continue;
+    // Track each semantic id as it's accepted so a later semantic hit with the
+    // same id is deduped against earlier semantic ones, not just the keyword set.
+    seen.add(s.id);
+    merged.push(s);
+  }
+  return merged;
+}
diff --git a/src/lib/complete-onboarding.test.ts b/src/lib/complete-onboarding.test.ts
new file mode 100644
index 000000000..a66269a09
--- /dev/null
+++ b/src/lib/complete-onboarding.test.ts
@@ -0,0 +1,115 @@
+/**
+ * Regression tests for completeOnboarding — the onboarding-completion flow.
+ *
+ * The bug this guards: a brand-new user finished onboarding but the store was
+ * never re-hydrated from SQLite, so they had no access to their projects on
+ * first run (workaround: reopen the app). The fix hydrates BEFORE dismissing
+ * onboarding. These tests pin both the hydration call and its ordering.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { completeOnboarding, type CompleteOnboardingDeps } from "./complete-onboarding";
+import type { NewFeature } from "./new-features-registry";
+
+const feat = (id: string, version: string): NewFeature => ({
+  id,
+  version,
+  title: id,
+  category: "Test",
+  description: "",
+  highlights: [],
+});
+
+function makeDeps(overrides: Partial<CompleteOnboardingDeps> & { seenFeatures?: string[] } = {}): {
+  deps: CompleteOnboardingDeps;
+} {
+  const { seenFeatures, ...rest } = overrides;
+  const deps: CompleteOnboardingDeps = {
+    hydrateFromElectron: vi.fn(async () => {}),
+    setOnboardingState: vi.fn(),
+    setPendingTutorial: vi.fn(),
+    setTutorialActive: vi.fn(),
+    getSeenFeatures: () => seenFeatures ?? [],
+    registry: [feat("v1.0-a", "v1.0")],
+    ...rest,
+  };
+  return { deps };
+}
+
+describe("completeOnboarding", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("hydrates from the backend and only then exits onboarding (the core fix)", async () => {
+    // Control hydrate's resolution so we can prove setOnboardingState is GATED
+    // on it — not merely that the final recorded order happens to be right.
+    let resolveHydrate!: () => void;
+    const hydrateFromElectron = vi.fn(
+      () => new Promise<void>((resolve) => { resolveHydrate = resolve; }),
+    );
+    const { deps } = makeDeps({ hydrateFromElectron });
+
+    // Start the flow but do NOT await — hydrate is still pending.
+    const done = completeOnboarding(false, deps);
+    await Promise.resolve(); // flush any microtasks up to the first await
+
+    expect(deps.hydrateFromElectron).toHaveBeenCalledTimes(1);
+    // Onboarding must NOT be dismissed while hydration is in flight, otherwise
+    // the main app renders against an empty store (no projects on first run).
+    expect(deps.setOnboardingState).not.toHaveBeenCalled();
+
+    // Resolve hydration; the dismiss should now run.
+    resolveHydrate();
+    await done;
+    expect(deps.setOnboardingState).toHaveBeenCalledWith(false);
+  });
+
+  it("does not start any tour when startTour is false", async () => {
+    const { deps } = makeDeps();
+    await completeOnboarding(false, deps);
+
+    expect(deps.setPendingTutorial).not.toHaveBeenCalled();
+    expect(deps.setTutorialActive).not.toHaveBeenCalled();
+  });
+
+  it("defers the tour when there are unseen latest-version features", async () => {
+    const { deps } = makeDeps({ seenFeatures: [], registry: [feat("v9.9-new", "v9.9")] });
+    await completeOnboarding(true, deps);
+
+    expect(deps.setPendingTutorial).toHaveBeenCalledWith(true);
+    expect(deps.setTutorialActive).not.toHaveBeenCalled();
+  });
+
+  it("starts the tour immediately when the latest feature is already seen", async () => {
+    const { deps } = makeDeps({
+      seenFeatures: ["v9.9-new"],
+      registry: [feat("v9.9-new", "v9.9")],
+    });
+    await completeOnboarding(true, deps);
+
+    expect(deps.setTutorialActive).toHaveBeenCalledWith(true);
+    expect(deps.setPendingTutorial).not.toHaveBeenCalled();
+  });
+
+  it("gates exit AND tour start on hydration when starting the tour", async () => {
+    let resolveHydrate!: () => void;
+    const hydrateFromElectron = vi.fn(
+      () => new Promise<void>((resolve) => { resolveHydrate = resolve; }),
+    );
+    // seenFeatures empty + unseen latest → tour is deferred via setPendingTutorial.
+    const { deps } = makeDeps({ hydrateFromElectron, registry: [feat("v9.9-new", "v9.9")] });
+
+    const done = completeOnboarding(true, deps);
+    await Promise.resolve();
+
+    expect(deps.hydrateFromElectron).toHaveBeenCalledTimes(1);
+    // Nothing past the await should have run while hydration is pending.
+    expect(deps.setOnboardingState).not.toHaveBeenCalled();
+    expect(deps.setPendingTutorial).not.toHaveBeenCalled();
+    expect(deps.setTutorialActive).not.toHaveBeenCalled();
+
+    resolveHydrate();
+    await done;
+    expect(deps.setOnboardingState).toHaveBeenCalledWith(false);
+    expect(deps.setPendingTutorial).toHaveBeenCalledWith(true);
+  });
+});
diff --git a/src/lib/complete-onboarding.ts b/src/lib/complete-onboarding.ts
new file mode 100644
index 000000000..d09550181
--- /dev/null
+++ b/src/lib/complete-onboarding.ts
@@ -0,0 +1,57 @@
+import type { NewFeature } from "./new-features-registry";
+import { getUnseenLatestFeatures } from "./new-features-registry";
+
+/**
+ * Dependencies for {@link completeOnboarding}, injected so the flow can be
+ * unit-tested without rendering the whole app shell.
+ */
+export interface CompleteOnboardingDeps {
+  /** Re-sync the Zustand store from the SQLite backend (workspaces, projects, …). */
+  hydrateFromElectron: () => Promise<void>;
+  /** Exit the onboarding wizard and show the main app. */
+  setOnboardingState: (v: false) => void;
+  /** Defer the interactive tour until the "What's New" modal is dismissed. */
+  setPendingTutorial: (v: boolean) => void;
+  /** Activate the interactive tour immediately. */
+  setTutorialActive: (v: boolean) => void;
+  /**
+   * Reads the feature ids the user has already seen (for tour gating).
+   *
+   * MUST be a getter, not a captured snapshot: `hydrateFromElectron()` can
+   * refresh `seenFeatures` from the backend, so reading a value captured before
+   * the flow started would gate the tour on stale data.
+   */
+  getSeenFeatures: () => string[];
+  /** The "What's New" feature registry (for tour gating). */
+  registry: NewFeature[];
+}
+
+/**
+ * Runs when the onboarding wizard finishes ("Open Cairn").
+ *
+ * CRITICAL ORDERING (regression guard): `hydrateFromElectron()` MUST complete
+ * before `setOnboardingState(false)`. On a brand-new install the project is
+ * created inside the wizard but the store is only authoritative after a
+ * snapshot hydrate; dismissing onboarding first left the user with no projects
+ * until they reopened the app (the bug this flow fixes).
+ *
+ * Tour gating mirrors NewFeatureModal: only unseen features from the LATEST
+ * registry version defer the tour behind the "What's New" modal; otherwise the
+ * tour starts immediately.
+ */
+export async function completeOnboarding(
+  startTour: boolean,
+  deps: CompleteOnboardingDeps,
+): Promise<void> {
+  await deps.hydrateFromElectron();
+  deps.setOnboardingState(false);
+  if (!startTour) return;
+  // Read seenFeatures AFTER hydration so the gate reflects the refreshed store.
+  const hasUnseenLatest =
+    getUnseenLatestFeatures(deps.registry, deps.getSeenFeatures()).length > 0;
+  if (hasUnseenLatest) {
+    deps.setPendingTutorial(true);
+  } else {
+    deps.setTutorialActive(true);
+  }
+}
diff --git a/src/lib/new-features-registry.test.ts b/src/lib/new-features-registry.test.ts
new file mode 100644
index 000000000..ddb36f7db
--- /dev/null
+++ b/src/lib/new-features-registry.test.ts
@@ -0,0 +1,130 @@
+/**
+ * Unit tests for getUnseenLatestFeatures — the pure gate shared by
+ * NewFeatureModal and the boot logic in page.tsx. It decides which features the
+ * "What's New" modal surfaces (and whether the tour is deferred at boot).
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  getUnseenLatestFeatures,
+  NEW_FEATURES_REGISTRY,
+  type NewFeature,
+} from "./new-features-registry";
+
+const feat = (id: string, version: string): NewFeature => ({
+  id,
+  version,
+  title: `Feature ${id}`,
+  category: "Test",
+  description: "",
+  highlights: [],
+});
+
+describe("getUnseenLatestFeatures", () => {
+  it("returns the entire registry when forceOpen is true (Settings entrypoint)", () => {
+    const registry = [feat("a", "v1.0.0"), feat("b", "v2.0.0")];
+    expect(getUnseenLatestFeatures(registry, [], true)).toEqual(registry);
+  });
+
+  it("returns the entire registry when forceOpen is true even if all are seen", () => {
+    const registry = [feat("a", "v1.0.0"), feat("b", "v2.0.0")];
+    expect(getUnseenLatestFeatures(registry, ["a", "b"], true)).toEqual(registry);
+  });
+
+  it("returns [] for an empty registry", () => {
+    expect(getUnseenLatestFeatures([], [])).toEqual([]);
+  });
+
+  it("returns only unseen features from the LATEST version", () => {
+    const registry = [
+      feat("old", "v1.0.0"),
+      feat("latest-1", "v2.0.0"),
+      feat("latest-2", "v2.0.0"),
+    ];
+    // Nothing seen — both latest-version features surface; the old one never does.
+    const result = getUnseenLatestFeatures(registry, []);
+    expect(result.map((f) => f.id)).toEqual(["latest-1", "latest-2"]);
+  });
+
+  it("ignores unseen features from OLDER versions", () => {
+    const registry = [feat("old", "v1.0.0"), feat("latest", "v2.0.0")];
+    // The old feature is unseen but belongs to a previous version — excluded.
+    const result = getUnseenLatestFeatures(registry, ["latest"]);
+    expect(result).toEqual([]);
+  });
+
+  it("filters out already-seen features within the latest version", () => {
+    const registry = [
+      feat("latest-1", "v2.0.0"),
+      feat("latest-2", "v2.0.0"),
+    ];
+    const result = getUnseenLatestFeatures(registry, ["latest-1"]);
+    expect(result.map((f) => f.id)).toEqual(["latest-2"]);
+  });
+
+  it("returns [] when every latest-version feature has been seen", () => {
+    const registry = [
+      feat("latest-1", "v2.0.0"),
+      feat("latest-2", "v2.0.0"),
+    ];
+    expect(getUnseenLatestFeatures(registry, ["latest-1", "latest-2"])).toEqual([]);
+  });
+
+  it("derives the latest version from the LAST registry entry, not by string comparison", () => {
+    // The function trusts registry order: the latest version is the last entry's
+    // version. A higher version number appearing earlier must NOT be treated as latest.
+    const registry = [
+      feat("higher-but-earlier", "v9.0.0"),
+      feat("actual-latest", "v2.0.0"),
+    ];
+    const result = getUnseenLatestFeatures(registry, []);
+    expect(result.map((f) => f.id)).toEqual(["actual-latest"]);
+  });
+});
+
+// ── Real registry ordering invariant ──────────────────────────────────────────
+// getUnseenLatestFeatures trusts registry ORDER (last entry = latest version).
+// These checks tie that contract to the actual shared registry the modal and
+// onboarding logic consume, so an out-of-order append is caught here.
+describe("NEW_FEATURES_REGISTRY ordering invariant", () => {
+  const toTuple = (version: string): number[] =>
+    version.replace(/^v/, "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+
+  const cmp = (a: number[], b: number[]): number => {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+      const diff = (a[i] ?? 0) - (b[i] ?? 0);
+      if (diff !== 0) return diff;
+    }
+    return 0;
+  };
+
+  it("is non-empty and every entry has a unique id", () => {
+    expect(NEW_FEATURES_REGISTRY.length).toBeGreaterThan(0);
+    const ids = NEW_FEATURES_REGISTRY.map((f) => f.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("is sorted by ascending version (no entry exceeds a later one)", () => {
+    for (let i = 1; i < NEW_FEATURES_REGISTRY.length; i++) {
+      const prev = toTuple(NEW_FEATURES_REGISTRY[i - 1].version);
+      const curr = toTuple(NEW_FEATURES_REGISTRY[i].version);
+      // Equal versions are allowed (multiple features per release).
+      expect(cmp(prev, curr)).toBeLessThanOrEqual(0);
+    }
+  });
+
+  it("ends with the maximum version — the last entry is genuinely the latest", () => {
+    const lastVersion = toTuple(NEW_FEATURES_REGISTRY[NEW_FEATURES_REGISTRY.length - 1].version);
+    for (const f of NEW_FEATURES_REGISTRY) {
+      expect(cmp(toTuple(f.version), lastVersion)).toBeLessThanOrEqual(0);
+    }
+  });
+
+  it("surfaces only features whose version matches the last entry's version", () => {
+    const latestVersion = NEW_FEATURES_REGISTRY[NEW_FEATURES_REGISTRY.length - 1].version;
+    const surfaced = getUnseenLatestFeatures(NEW_FEATURES_REGISTRY, []);
+    expect(surfaced.length).toBeGreaterThan(0);
+    expect(surfaced.every((f) => f.version === latestVersion)).toBe(true);
+  });
+});
diff --git a/src/lib/new-features-registry.ts b/src/lib/new-features-registry.ts
index 604dd662c..49045d548 100644
--- a/src/lib/new-features-registry.ts
+++ b/src/lib/new-features-registry.ts
@@ -7,6 +7,31 @@ export interface NewFeature {
   highlights: string[];
 }
 
+/**
+ * Compute which features to surface in the "What's New" modal.
+ *
+ * - When `forceOpen` is true (e.g. opened from Settings), return the entire
+ *   registry so the user can browse all releases.
+ * - Otherwise, return only the unseen features belonging to the latest
+ *   version in the registry. This is the boot-time gate: the modal/tour only
+ *   appears when there is something new the user hasn't acknowledged yet.
+ *
+ * Pure function — shared by NewFeatureModal and the boot logic in page.tsx so
+ * the gating cannot drift between the two call sites.
+ */
+export function getUnseenLatestFeatures(
+  registry: NewFeature[],
+  seenFeatures: string[],
+  forceOpen = false,
+): NewFeature[] {
+  if (forceOpen) return registry;
+  if (registry.length === 0) return [];
+  const latestVersion = registry[registry.length - 1].version;
+  return registry.filter(
+    (f) => f.version === latestVersion && !seenFeatures.includes(f.id),
+  );
+}
+
 export const NEW_FEATURES_REGISTRY: NewFeature[] = [
   {
     id: "v1.5.0-obsidian",
diff --git a/src/lib/utils.test.ts b/src/lib/utils.test.ts
new file mode 100644
index 000000000..c3b4f593d
--- /dev/null
+++ b/src/lib/utils.test.ts
@@ -0,0 +1,90 @@
+/**
+ * Unit tests for pure date/formatting helpers in src/lib/utils.ts.
+ * These use fake timers to pin "now" so the relative/boundary math is
+ * deterministic.
+ */
+
+import { beforeEach, afterEach, describe, expect, it, vi } from "vitest";
+import { formatRelative, getDueDateStatus } from "./utils";
+
+const NOW = new Date("2026-06-15T12:00:00.000Z");
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(NOW);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("formatRelative", () => {
+  const ago = (ms: number) => new Date(NOW.getTime() - ms).toISOString();
+  const SEC = 1000;
+  const MIN = 60 * SEC;
+  const HOUR = 60 * MIN;
+  const DAY = 24 * HOUR;
+
+  it("returns 'just now' for under a minute", () => {
+    expect(formatRelative(ago(30 * SEC))).toBe("just now");
+    expect(formatRelative(ago(59 * SEC))).toBe("just now");
+  });
+
+  it("returns minutes for 1–59 minutes", () => {
+    expect(formatRelative(ago(1 * MIN))).toBe("1m ago");
+    expect(formatRelative(ago(59 * MIN))).toBe("59m ago");
+  });
+
+  it("returns hours for 1–23 hours", () => {
+    expect(formatRelative(ago(1 * HOUR))).toBe("1h ago");
+    expect(formatRelative(ago(23 * HOUR))).toBe("23h ago");
+  });
+
+  it("returns days for 1–6 days", () => {
+    expect(formatRelative(ago(1 * DAY))).toBe("1d ago");
+    expect(formatRelative(ago(6 * DAY))).toBe("6d ago");
+  });
+
+  it("falls back to an absolute date at 7+ days", () => {
+    // At/after 7 days it delegates to formatDate (an absolute "Mon D, YYYY").
+    const result = formatRelative(ago(7 * DAY));
+    expect(result).not.toMatch(/ago|just now/);
+    expect(result).toContain("2026");
+  });
+});
+
+describe("getDueDateStatus", () => {
+  // getDueDateStatus compares LOCAL calendar days (it normalises to local
+  // midnight). Build inputs from a local-day offset so the test is independent
+  // of the machine timezone.
+  const localDay = (offsetDays: number): string => {
+    const d = new Date(NOW);
+    d.setHours(12, 0, 0, 0); // midday avoids DST edge ambiguity
+    d.setDate(d.getDate() + offsetDays);
+    return d.toISOString();
+  };
+
+  it("returns 'none' for null/undefined/empty", () => {
+    expect(getDueDateStatus(null)).toBe("none");
+    expect(getDueDateStatus(undefined)).toBe("none");
+    expect(getDueDateStatus("")).toBe("none");
+  });
+
+  it("returns 'today' for the current calendar day regardless of time", () => {
+    // Same local day, different times → still today (day-level compare).
+    const startOfToday = new Date(NOW); startOfToday.setHours(0, 5, 0, 0);
+    const endOfToday = new Date(NOW); endOfToday.setHours(23, 55, 0, 0);
+    expect(getDueDateStatus(startOfToday.toISOString())).toBe("today");
+    expect(getDueDateStatus(endOfToday.toISOString())).toBe("today");
+  });
+
+  it("returns 'overdue' for a past calendar day", () => {
+    expect(getDueDateStatus(localDay(-1))).toBe("overdue");
+    expect(getDueDateStatus(localDay(-30))).toBe("overdue");
+  });
+
+  it("returns 'upcoming' for a future calendar day", () => {
+    expect(getDueDateStatus(localDay(1))).toBe("upcoming");
+    expect(getDueDateStatus(localDay(200))).toBe("upcoming");
+  });
+});
diff --git a/src/store/slices/board.test.ts b/src/store/slices/board.test.ts
new file mode 100644
index 000000000..6dbebdc82
--- /dev/null
+++ b/src/store/slices/board.test.ts
@@ -0,0 +1,262 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Unit tests for the pure state transitions in the board slice:
+ *   - moveCard   — cross/same-column reindex math
+ *   - getReadyCards — blocker-resolution + done/archived filtering
+ *
+ * Runs in the node env (isElectron() === false), so IPC is a no-op. The
+ * historyManager singleton is touched by moveCard but its side effects don't
+ * affect the assertions here.
+ */
+
+import { describe, it, expect } from "vitest";
+import { createBoardSlice } from "./board";
+import type { BoardColumn, TaskCard } from "@/types";
+
+const col = (id: string, projectId: string, type: string, order = 0): BoardColumn =>
+  ({ id, projectId, workspaceId: "ws-1", name: id, type, order, createdAt: "", updatedAt: "" } as unknown as BoardColumn);
+
+const card = (
+  id: string,
+  columnId: string,
+  order: number,
+  extra: Partial<TaskCard> = {},
+): TaskCard =>
+  ({
+    id,
+    columnId,
+    projectId: "proj-1",
+    workspaceId: "ws-1",
+    title: id,
+    tagIds: [],
+    priority: "medium",
+    linkedNoteIds: [],
+    blockedByIds: [],
+    order,
+    createdAt: "",
+    updatedAt: "",
+    ...extra,
+  } as unknown as TaskCard);
+
+function setup(initial: any = {}) {
+  let state: any = { persist: () => {}, columns: [], cards: [], notes: [], ...initial };
+  const mockSet = (updater: any) => {
+    const next = typeof updater === "function" ? updater(state) : updater;
+    state = { ...state, ...next };
+  };
+  const mockGet = () => state;
+  const slice = createBoardSlice(mockSet, mockGet, {} as any);
+  state = { ...state, ...slice, ...initial };
+  return { get: () => state };
+}
+
+// Helper: cards in a column sorted by order, as [id, order] pairs.
+const colState = (get: () => any, columnId: string) =>
+  get().cards
+    .filter((c: TaskCard) => c.columnId === columnId)
+    .sort((a: TaskCard, b: TaskCard) => a.order - b.order)
+    .map((c: TaskCard) => [c.id, c.order] as const);
+
+describe("moveCard", () => {
+  it("reorders within the same column (move to front)", () => {
+    const { get } = setup({
+      columns: [col("c1", "proj-1", "todo")],
+      cards: [card("a", "c1", 0), card("b", "c1", 1), card("x", "c1", 2)],
+    });
+
+    get().moveCard("x", "c1", 0);
+
+    expect(colState(get, "c1")).toEqual([
+      ["x", 0],
+      ["a", 1],
+      ["b", 2],
+    ]);
+  });
+
+  it("reorders within the same column (move to end)", () => {
+    const { get } = setup({
+      columns: [col("c1", "proj-1", "todo")],
+      cards: [card("a", "c1", 0), card("b", "c1", 1), card("x", "c1", 2)],
+    });
+
+    get().moveCard("a", "c1", 2);
+
+    expect(colState(get, "c1")).toEqual([
+      ["b", 0],
+      ["x", 1],
+      ["a", 2],
+    ]);
+  });
+
+  it("moves a card to another column and reindexes both", () => {
+    const { get } = setup({
+      columns: [col("c1", "proj-1", "todo"), col("c2", "proj-1", "in_progress")],
+      cards: [
+        card("a", "c1", 0),
+        card("b", "c1", 1),
+        card("c", "c2", 0),
+      ],
+    });
+
+    // Move "a" into c2 at index 0.
+    get().moveCard("a", "c2", 0);
+
+    // Source column reindexed contiguously.
+    expect(colState(get, "c1")).toEqual([["b", 0]]);
+    // Target column has the moved card at front, existing card shifted.
+    expect(colState(get, "c2")).toEqual([
+      ["a", 0],
+      ["c", 1],
+    ]);
+    // The moved card's columnId updated.
+    expect(get().cards.find((c: TaskCard) => c.id === "a").columnId).toBe("c2");
+  });
+
+  it("clamps an out-of-range targetIndex to the end of the column", () => {
+    const { get } = setup({
+      columns: [col("c1", "proj-1", "todo"), col("c2", "proj-1", "done")],
+      cards: [card("a", "c1", 0), card("c", "c2", 0)],
+    });
+
+    get().moveCard("a", "c2", 99);
+
+    expect(colState(get, "c2")).toEqual([
+      ["c", 0],
+      ["a", 1],
+    ]);
+  });
+
+  it("leaves cards in unrelated columns untouched", () => {
+    const { get } = setup({
+      columns: [
+        col("c1", "proj-1", "todo"),
+        col("c2", "proj-1", "in_progress"),
+        col("c3", "proj-1", "review"),
+      ],
+      cards: [
+        card("a", "c1", 0),
+        card("other", "c3", 0),
+      ],
+    });
+
+    get().moveCard("a", "c2", 0);
+
+    expect(colState(get, "c3")).toEqual([["other", 0]]);
+  });
+
+  it("is a no-op for an unknown card id", () => {
+    const { get } = setup({
+      columns: [col("c1", "proj-1", "todo")],
+      cards: [card("a", "c1", 0)],
+    });
+
+    get().moveCard("does-not-exist", "c1", 0);
+
+    expect(colState(get, "c1")).toEqual([["a", 0]]);
+  });
+});
+
+describe("getReadyCards", () => {
+  it("returns active cards with no blockers", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [card("a", "todo", 0), card("b", "todo", 1)],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id).sort()).toEqual(["a", "b"]);
+  });
+
+  it("excludes cards in a done column", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [card("a", "todo", 0), card("finished", "done", 0)],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["a"]);
+  });
+
+  it("excludes archived cards", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [card("a", "todo", 0), card("arch", "todo", 1, { archivedAt: "2026-01-01" } as any)],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["a"]);
+  });
+
+  it("excludes a card whose blocker is unresolved", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [
+        card("blocker", "todo", 0),
+        card("blocked", "todo", 1, { blockedByIds: ["blocker"] }),
+      ],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["blocker"]);
+  });
+
+  it("includes a card whose blocker is resolved (in a done column)", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [
+        card("blocker", "done", 0),
+        card("blocked", "todo", 0, { blockedByIds: ["blocker"] }),
+      ],
+    });
+
+    // blocker is in done (excluded from ready), blocked becomes ready.
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["blocked"]);
+  });
+
+  it("includes a card whose blocker is archived (resolved)", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [
+        card("blocker", "todo", 0, { archivedAt: "2026-01-01" } as any),
+        card("blocked", "todo", 1, { blockedByIds: ["blocker"] }),
+      ],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["blocked"]);
+  });
+
+  it("treats an orphan blocker (deleted card) as resolved", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [card("blocked", "todo", 0, { blockedByIds: ["ghost"] })],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["blocked"]);
+  });
+
+  it("requires ALL blockers resolved (mixed → not ready)", () => {
+    const { get } = setup({
+      columns: [col("todo", "proj-1", "todo"), col("done", "proj-1", "done")],
+      cards: [
+        card("done-blocker", "done", 0),
+        card("open-blocker", "todo", 0),
+        card("blocked", "todo", 1, { blockedByIds: ["done-blocker", "open-blocker"] }),
+      ],
+    });
+
+    const ready = get().getReadyCards("proj-1").map((c: TaskCard) => c.id);
+    expect(ready).toContain("open-blocker");
+    expect(ready).not.toContain("blocked");
+  });
+
+  it("scopes results to the given project", () => {
+    const { get } = setup({
+      columns: [
+        col("todo1", "proj-1", "todo"),
+        col("todo2", "proj-2", "todo"),
+      ],
+      cards: [
+        card("a", "todo1", 0, { projectId: "proj-1" }),
+        card("b", "todo2", 0, { projectId: "proj-2" }),
+      ],
+    });
+
+    expect(get().getReadyCards("proj-1").map((c: TaskCard) => c.id)).toEqual(["a"]);
+  });
+});
diff --git a/src/store/slices/selectors.test.ts b/src/store/slices/selectors.test.ts
new file mode 100644
index 000000000..00abafdfe
--- /dev/null
+++ b/src/store/slices/selectors.test.ts
@@ -0,0 +1,165 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Unit tests for the pure selector slice: searchAll plus the sort/filter
+ * behavior of getProjectNotes and getWorkspaceProjects.
+ */
+
+import { describe, it, expect } from "vitest";
+import { createSelectorsSlice } from "./selectors";
+import type { Note, TaskCard, Project } from "@/types";
+
+const note = (id: string, projectId: string, extra: Partial<Note> = {}): Note =>
+  ({
+    id,
+    projectId,
+    workspaceId: "ws-1",
+    title: id,
+    content: "",
+    contentText: "",
+    tagIds: [],
+    linkedNoteIds: [],
+    linkedCardIds: [],
+    isPinned: false,
+    type: "note",
+    folder: "",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-01T00:00:00.000Z",
+    ...extra,
+  } as unknown as Note);
+
+const cardItem = (id: string, projectId: string, extra: Partial<TaskCard> = {}): TaskCard =>
+  ({
+    id,
+    columnId: "c1",
+    projectId,
+    workspaceId: "ws-1",
+    title: id,
+    tagIds: [],
+    priority: "medium",
+    linkedNoteIds: [],
+    blockedByIds: [],
+    order: 0,
+    createdAt: "",
+    updatedAt: "",
+    ...extra,
+  } as unknown as TaskCard);
+
+const project = (id: string, workspaceId: string, extra: Partial<Project> = {}): Project =>
+  ({ id, workspaceId, name: id, status: "active", priority: "medium", tagIds: [], codeDirectory: null, createdAt: "", updatedAt: "", ...extra } as unknown as Project);
+
+function setup(initial: any = {}) {
+  let state: any = { notes: [], cards: [], projects: [], columns: [], ...initial };
+  const mockGet = () => state;
+  const slice = createSelectorsSlice(() => {}, mockGet, {} as any);
+  state = { ...state, ...slice, ...initial };
+  return { get: () => state };
+}
+
+describe("searchAll", () => {
+  it("returns [] for an empty or whitespace query", () => {
+    const { get } = setup({ notes: [note("n1", "p1", { title: "hello" })] });
+    expect(get().searchAll("")).toEqual([]);
+    expect(get().searchAll("   ")).toEqual([]);
+  });
+
+  it("matches notes by title (case-insensitive) and includes project name", () => {
+    const { get } = setup({
+      projects: [project("p1", "ws-1", { name: "Alpha" })],
+      notes: [note("n1", "p1", { title: "Meeting Notes" })],
+    });
+    const results = get().searchAll("meeting");
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({ type: "note", id: "n1", title: "Meeting Notes", projectName: "Alpha" });
+  });
+
+  it("matches notes by contentText and builds a 120-char snippet", () => {
+    const longText = "x".repeat(200);
+    const { get } = setup({
+      notes: [note("n1", "p1", { title: "T", contentText: `needle ${longText}` })],
+    });
+    const results = get().searchAll("needle");
+    expect(results).toHaveLength(1);
+    expect(results[0].snippet.length).toBe(120);
+  });
+
+  it("matches cards by title and description", () => {
+    const { get } = setup({
+      cards: [
+        cardItem("c1", "p1", { title: "Fix bug" }),
+        cardItem("c2", "p1", { title: "Other", description: "contains keyword here" }),
+      ],
+    });
+    expect(get().searchAll("fix").map((r: any) => r.id)).toEqual(["c1"]);
+    expect(get().searchAll("keyword").map((r: any) => r.id)).toEqual(["c2"]);
+  });
+
+  it("skips archived notes and cards", () => {
+    const { get } = setup({
+      notes: [note("n1", "p1", { title: "archived match", archivedAt: "2026-01-01" } as any)],
+      cards: [cardItem("c1", "p1", { title: "archived match", archivedAt: "2026-01-01" } as any)],
+    });
+    expect(get().searchAll("match")).toEqual([]);
+  });
+
+  it("falls back to empty strings for missing project name / description", () => {
+    const { get } = setup({
+      // No project registered for p1 → projectName "".
+      cards: [cardItem("c1", "p1", { title: "match" })], // no description → snippet ""
+    });
+    const results = get().searchAll("match");
+    expect(results[0].projectName).toBe("");
+    expect(results[0].snippet).toBe("");
+  });
+
+  it("caps results at 50", () => {
+    const notes = Array.from({ length: 80 }, (_, i) => note(`n${i}`, "p1", { title: `match ${i}` }));
+    const { get } = setup({ notes });
+    expect(get().searchAll("match")).toHaveLength(50);
+  });
+
+  it("returns both note and card matches together", () => {
+    const { get } = setup({
+      notes: [note("n1", "p1", { title: "shared" })],
+      cards: [cardItem("c1", "p1", { title: "shared" })],
+    });
+    const types = get().searchAll("shared").map((r: any) => r.type).sort();
+    expect(types).toEqual(["card", "note"]);
+  });
+});
+
+describe("getProjectNotes", () => {
+  it("sorts pinned notes first, then by updatedAt desc", () => {
+    const { get } = setup({
+      notes: [
+        note("old", "p1", { updatedAt: "2026-01-01T00:00:00.000Z" }),
+        note("new", "p1", { updatedAt: "2026-06-01T00:00:00.000Z" }),
+        note("pinned", "p1", { isPinned: true, updatedAt: "2025-01-01T00:00:00.000Z" }),
+      ],
+    });
+    expect(get().getProjectNotes("p1").map((n: Note) => n.id)).toEqual(["pinned", "new", "old"]);
+  });
+
+  it("excludes archived notes and notes from other projects", () => {
+    const { get } = setup({
+      notes: [
+        note("keep", "p1"),
+        note("archived", "p1", { archivedAt: "2026-01-01" } as any),
+        note("other", "p2"),
+      ],
+    });
+    expect(get().getProjectNotes("p1").map((n: Note) => n.id)).toEqual(["keep"]);
+  });
+});
+
+describe("getWorkspaceProjects", () => {
+  it("returns non-archived projects for the workspace", () => {
+    const { get } = setup({
+      projects: [
+        project("p1", "ws-1"),
+        project("p2", "ws-1", { archivedAt: "2026-01-01" } as any),
+        project("p3", "ws-2"),
+      ],
+    });
+    expect(get().getWorkspaceProjects("ws-1").map((p: Project) => p.id)).toEqual(["p1"]);
+  });
+});
diff --git a/src/store/slices/ui.test.ts b/src/store/slices/ui.test.ts
index b9fddd919..b18a6d67d 100644
--- a/src/store/slices/ui.test.ts
+++ b/src/store/slices/ui.test.ts
@@ -1,6 +1,20 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { describe, it, expect } from "vitest";
-import { createUISlice } from "./ui";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createUISlice, SEEN_FEATURES_KEY } from "./ui";
+
+// Mock the persistence layer so we can assert markFeatureAsSeen's storage
+// contract (node project has no window, so storage.set is otherwise a no-op).
+// The spy lives in vi.hoisted() because vi.mock() is hoisted above normal
+// declarations and its factory closes over storageSet.
+const { storageSet } = vi.hoisted(() => ({ storageSet: vi.fn() }));
+vi.mock("@/lib/storage", () => ({
+  storage: {
+    get: vi.fn(() => null),
+    set: (...args: unknown[]) => storageSet(...args),
+    delete: vi.fn(),
+    clear: vi.fn(),
+  },
+}));
 
 describe("createUISlice", () => {
   it("initializes with overview as activeView and lastContentView", () => {
@@ -113,3 +127,83 @@ describe("createUISlice", () => {
     expect(state.activePreviewItem).toBeNull();
   });
 });
+
+// ── Tour / What's New feature state ──────────────────────────────────────────
+
+describe("createUISlice — tour & seen-features state", () => {
+  beforeEach(() => {
+    storageSet.mockClear();
+  });
+
+  function setup() {
+    let state: any = {};
+    const mockSet = (updater: any) => {
+      const next = typeof updater === "function" ? updater(state) : updater;
+      state = { ...state, ...next };
+    };
+    const mockGet = () => state;
+    const slice = createUISlice(mockSet, mockGet, {} as any);
+    state = { ...state, ...slice };
+    return { get: () => state };
+  }
+
+  it("initializes tour/feature state to defaults", () => {
+    const { get } = setup();
+    expect(get().seenFeatures).toEqual([]);
+    expect(get().tutorialActive).toBe(false);
+    expect(get().tutorialStepIndex).toBe(0);
+  });
+
+  it("markFeatureAsSeen appends an unseen feature id", () => {
+    const { get } = setup();
+    get().markFeatureAsSeen("v2.3.2-onboarding-tour");
+    expect(get().seenFeatures).toEqual(["v2.3.2-onboarding-tour"]);
+    // Persists the new array under the seen-features key.
+    expect(storageSet).toHaveBeenLastCalledWith(SEEN_FEATURES_KEY, ["v2.3.2-onboarding-tour"]);
+  });
+
+  it("markFeatureAsSeen is idempotent for an already-seen id", () => {
+    const { get } = setup();
+    get().markFeatureAsSeen("a");
+    get().markFeatureAsSeen("a");
+    expect(get().seenFeatures).toEqual(["a"]);
+    // Re-persists the unchanged array (no duplicate id).
+    expect(storageSet).toHaveBeenLastCalledWith(SEEN_FEATURES_KEY, ["a"]);
+  });
+
+  it("markFeatureAsSeen accumulates distinct ids in order", () => {
+    const { get } = setup();
+    get().markFeatureAsSeen("a");
+    get().markFeatureAsSeen("b");
+    get().markFeatureAsSeen("a"); // duplicate, ignored
+    get().markFeatureAsSeen("c");
+    expect(get().seenFeatures).toEqual(["a", "b", "c"]);
+    // Final persisted value matches the in-memory ordered set.
+    expect(storageSet).toHaveBeenLastCalledWith(SEEN_FEATURES_KEY, ["a", "b", "c"]);
+  });
+
+  it("setTutorialActive(true) activates the tour and resets the step index", () => {
+    const { get } = setup();
+    // Advance the step first so the reset side-effect is observable.
+    get().setTutorialStepIndex(3);
+    expect(get().tutorialStepIndex).toBe(3);
+
+    get().setTutorialActive(true);
+    expect(get().tutorialActive).toBe(true);
+    expect(get().tutorialStepIndex).toBe(0); // reset on activate
+  });
+
+  it("setTutorialActive(false) deactivates the tour and resets the step index", () => {
+    const { get } = setup();
+    get().setTutorialStepIndex(2);
+    get().setTutorialActive(false);
+    expect(get().tutorialActive).toBe(false);
+    expect(get().tutorialStepIndex).toBe(0);
+  });
+
+  it("setTutorialStepIndex updates the step index", () => {
+    const { get } = setup();
+    get().setTutorialStepIndex(4);
+    expect(get().tutorialStepIndex).toBe(4);
+  });
+});
diff --git a/src/store/slices/workspace.test.ts b/src/store/slices/workspace.test.ts
new file mode 100644
index 000000000..e9020ef6b
--- /dev/null
+++ b/src/store/slices/workspace.test.ts
@@ -0,0 +1,158 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Unit tests for the project-creation portion of the workspace slice.
+ *
+ * Focus: the v2.3.2 fix that threads the chosen project icon through, plus the
+ * optimistic state (project row + 5 default columns) created synchronously
+ * before the IPC round-trip. The first block runs with no window.electron, so
+ * the IPC branch is skipped and only local state transitions run; a second block
+ * stubs window.electron to exercise the desktop replace-placeholders path.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { createWorkspaceSlice } from "./workspace";
+
+function setup(initial: any = {}) {
+  // Seed board state owned by other slices that createProject reads/writes
+  // (columns lives in the board slice; projects is re-declared by this slice).
+  let state: any = { persist: () => {}, projects: [], columns: [] };
+  const mockSet = (updater: any) => {
+    const next = typeof updater === "function" ? updater(state) : updater;
+    state = { ...state, ...next };
+  };
+  const mockGet = () => state;
+  const slice = createWorkspaceSlice(mockSet, mockGet, {} as any);
+  // Slice first (it re-declares projects: []), then caller overrides so seeded
+  // existing projects/columns survive.
+  state = { ...state, ...slice, ...initial };
+  return { get: () => state };
+}
+
+describe("createProject", () => {
+  it("adds the project to state with the given name and workspace", async () => {
+    const { get } = setup();
+    const proj = await get().createProject("ws-1", "My Project");
+
+    expect(proj.name).toBe("My Project");
+    expect(proj.workspaceId).toBe("ws-1");
+    expect(proj.status).toBe("active");
+    expect(proj.priority).toBe("medium");
+    expect(get().projects).toContainEqual(proj);
+  });
+
+  it("persists the chosen icon when provided (v2.3.2 onboarding fix)", async () => {
+    const { get } = setup();
+    const proj = await get().createProject("ws-1", "Iconic", "Rocket");
+
+    expect(proj.icon).toBe("Rocket");
+    // And the project stored in state carries the icon too.
+    expect(get().projects.find((p: any) => p.id === proj.id)?.icon).toBe("Rocket");
+  });
+
+  it("omits the icon field entirely when no icon is provided", async () => {
+    const { get } = setup();
+    const proj = await get().createProject("ws-1", "No Icon");
+
+    expect("icon" in proj).toBe(false);
+  });
+
+  it("creates exactly 5 default columns with correct types and order", async () => {
+    const { get } = setup();
+    const proj = await get().createProject("ws-1", "With Columns");
+
+    const cols = get().columns.filter((c: any) => c.projectId === proj.id);
+    expect(cols).toHaveLength(5);
+    expect(cols.map((c: any) => c.type)).toEqual([
+      "backlog",
+      "todo",
+      "in_progress",
+      "review",
+      "done",
+    ]);
+    expect(cols.map((c: any) => c.order)).toEqual([0, 1, 2, 3, 4]);
+    // All columns belong to the same workspace as the project.
+    expect(cols.every((c: any) => c.workspaceId === "ws-1")).toBe(true);
+  });
+
+  it("appends to existing projects and columns rather than replacing them", async () => {
+    const existingProject = { id: "p-existing", workspaceId: "ws-1", name: "Old" };
+    const existingColumn = { id: "c-existing", projectId: "p-existing", workspaceId: "ws-1", name: "X", type: "todo", order: 0 };
+    const { get } = setup({ projects: [existingProject], columns: [existingColumn] });
+
+    const proj = await get().createProject("ws-1", "New");
+
+    expect(get().projects).toContainEqual(existingProject);
+    expect(get().projects.some((p: any) => p.id === proj.id)).toBe(true);
+    expect(get().columns).toContainEqual(existingColumn);
+    expect(get().columns.filter((c: any) => c.projectId === proj.id)).toHaveLength(5);
+  });
+
+  it("assigns each created project a unique id", async () => {
+    const { get } = setup();
+    const a = await get().createProject("ws-1", "A");
+    const b = await get().createProject("ws-1", "B");
+    expect(a.id).not.toBe(b.id);
+  });
+});
+
+// ── Electron path ─────────────────────────────────────────────────────────────
+// In the desktop runtime createProject performs an atomic IPC call and then
+// replaces the optimistic placeholder columns with the authoritative server
+// rows. The node tests above skip this branch (no window.electron); here we stub
+// it to verify the placeholders are swapped out for server-owned columns.
+
+describe("createProject — Electron path", () => {
+  afterEach(() => {
+    delete (globalThis as any).window;
+  });
+
+  it("replaces the 5 placeholder columns with the server's authoritative rows", async () => {
+    const serverColumns = [
+      { id: "srv-backlog", projectId: "", workspaceId: "ws-1", name: "Backlog", type: "backlog", order: 0 },
+      { id: "srv-todo",    projectId: "", workspaceId: "ws-1", name: "Todo",    type: "todo",    order: 1 },
+      { id: "srv-done",    projectId: "", workspaceId: "ws-1", name: "Done",    type: "done",    order: 2 },
+    ];
+    let createArg: any;
+    const projectCreate = (arg: any) => {
+      createArg = arg;
+      // Server stamps the real project id onto its columns.
+      const columns = serverColumns.map((c) => ({ ...c, projectId: arg.id }));
+      return Promise.resolve({ data: { project: arg, columns } });
+    };
+    (globalThis as any).window = { electron: { project: { create: projectCreate } } };
+
+    const { get } = setup();
+    const proj = await get().createProject("ws-1", "Desktop Project", "Rocket");
+
+    // The IPC call received the optimistic project plus the columns flag.
+    expect(createArg.id).toBe(proj.id);
+    expect(createArg.workspaceId).toBe("ws-1");
+    expect(createArg.withDefaultColumns).toBe(true);
+
+    // Placeholder columns are gone; only the 3 authoritative server rows remain,
+    // and they carry the client project id (client/server ids stay in sync).
+    const cols = get().columns.filter((c: any) => c.projectId === proj.id);
+    expect(cols.map((c: any) => c.id)).toEqual(["srv-backlog", "srv-todo", "srv-done"]);
+    expect(cols.every((c: any) => c.projectId === proj.id)).toBe(true);
+  });
+
+  it("keeps the optimistic placeholders when the server returns no columns", async () => {
+    (globalThis as any).window = {
+      electron: { project: { create: () => Promise.resolve({ data: { columns: [] } }) } },
+    };
+
+    const { get } = setup();
+    const proj = await get().createProject("ws-1", "Fallback Project");
+
+    // No authoritative rows → the 5 optimistic placeholders survive.
+    const cols = get().columns.filter((c: any) => c.projectId === proj.id);
+    expect(cols).toHaveLength(5);
+    expect(cols.map((c: any) => c.type)).toEqual([
+      "backlog",
+      "todo",
+      "in_progress",
+      "review",
+      "done",
+    ]);
+  });
+});
diff --git a/tests/e2e/smoke.test.ts b/tests/e2e/smoke.test.ts
index d2c6c80e7..bd657a53c 100644
--- a/tests/e2e/smoke.test.ts
+++ b/tests/e2e/smoke.test.ts
@@ -13,6 +13,11 @@
 
 import { test, expect, type Page, type ConsoleMessage } from "@playwright/test";
 import { buildIpcMock, NOTE_1 } from "../fixtures/ipc-mock";
+import { NEW_FEATURES_REGISTRY, getUnseenLatestFeatures } from "../../src/lib/new-features-registry";
+
+// Derive the latest-release feature from the registry rather than hard-coding a
+// specific entry — these assertions then stay valid as new releases are added.
+const LATEST_FEATURE = getUnseenLatestFeatures(NEW_FEATURES_REGISTRY, [])[0];
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -269,3 +274,110 @@ test.describe("Cairn smoke tests", () => {
     });
   });
 });
+
+// ── "What's New" feature modal ────────────────────────────────────────────────
+// Uses an isolated browser context per assertion so seenFeatures (persisted in
+// localStorage / the store) starts clean and is independent of test order.
+
+test.describe("What's New modal", () => {
+  /** Boot a fresh page with the IPC mock + store bridge installed. */
+  async function bootFreshPage(browser: import("@playwright/test").Browser): Promise<Page> {
+    const context = await browser.newContext();
+    const p = await context.newPage();
+    await p.addInitScript({ content: buildIpcMock() });
+    await p.addInitScript({ content: STORE_ATTACH_SCRIPT });
+    await p.goto("/");
+    await p.waitForSelector("[data-testid='sidebar'], nav, aside", { timeout: 20_000 });
+    return p;
+  }
+
+  test("appears on boot when the latest-version feature is unseen", async ({ browser }) => {
+    const p = await bootFreshPage(browser);
+    try {
+      // The fixture starts with no seen features, so the latest release modal shows.
+      await expect(p.getByRole("heading", { name: /What's New in Cairn/i })).toBeVisible({ timeout: 10_000 });
+      // The latest registry feature title is rendered.
+      await expect(p.getByText(LATEST_FEATURE.title)).toBeVisible();
+    } finally {
+      await p.context().close();
+    }
+  });
+
+  test("clicking Done marks the feature seen and the modal does not reappear", async ({ browser }) => {
+    const p = await bootFreshPage(browser);
+    try {
+      const heading = p.getByRole("heading", { name: /What's New in Cairn/i });
+      await expect(heading).toBeVisible({ timeout: 10_000 });
+
+      // Close via the primary action (single latest feature → "Done").
+      await p.getByRole("button", { name: "Done" }).click();
+
+      // Modal closes...
+      await expect(heading).toHaveCount(0, { timeout: 5_000 });
+
+      // ...and the feature is now recorded as seen in the store.
+      const seen = await p.evaluate(() => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (window as any).__cairnStore?.getState?.()?.seenFeatures ?? [];
+      });
+      expect(seen).toContain(LATEST_FEATURE.id);
+
+      // Navigating around does not re-open it (gate is empty now).
+      await p.evaluate(() => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (window as any).__cairnStore?.getState?.()?.setView?.("board");
+      });
+      await p.waitForTimeout(300);
+      await expect(heading).toHaveCount(0);
+    } finally {
+      await p.context().close();
+    }
+  });
+
+  test("does not appear on boot when the latest feature is already seen", async ({ browser }) => {
+    const context = await browser.newContext();
+    const p = await context.newPage();
+    await p.addInitScript({ content: buildIpcMock() });
+    await p.addInitScript({ content: STORE_ATTACH_SCRIPT });
+    // Pre-seed seenFeatures in localStorage before the app boots. The storage
+    // layer prefixes keys with "cairn:v1:" (see src/lib/storage.ts).
+    await p.addInitScript({
+      content: `localStorage.setItem("cairn:v1:seenFeatures", JSON.stringify([${JSON.stringify(LATEST_FEATURE.id)}]));`,
+    });
+    try {
+      await p.goto("/");
+      await p.waitForSelector("[data-testid='sidebar'], nav, aside", { timeout: 20_000 });
+      // Give the modal a chance to (not) render.
+      await p.waitForTimeout(500);
+      await expect(p.getByRole("heading", { name: /What's New in Cairn/i })).toHaveCount(0);
+    } finally {
+      await p.context().close();
+    }
+  });
+});
+
+// ── Onboarding wizard entry ───────────────────────────────────────────────────
+// The full wizard spans many steps; here we assert the onboarding path is wired
+// (it appears on a fresh install) and the choose-folder entry step renders.
+// Component-level StepCreateProject behaviors (icon persistence, disabled
+// states, aria-pressed) are covered by unit tests (workspace.test.ts) since the
+// renderer has no DOM-unit harness.
+
+test.describe("Onboarding wizard", () => {
+  test("shows the wizard on a fresh install (needs workspace setup)", async ({ browser }) => {
+    const context = await browser.newContext();
+    const p = await context.newPage();
+    // Override the mock to simulate a fresh install: workspace setup required.
+    // Baked into the same synchronous script that defines window.electron so the
+    // app never reads the default `false` before the override applies.
+    await p.addInitScript({ content: buildIpcMock({ needsWorkspaceSetup: true }) });
+    await p.addInitScript({ content: STORE_ATTACH_SCRIPT });
+    try {
+      await p.goto("/");
+      // The choose-folder step heading should render instead of the app shell.
+      await expect(p.getByText("Choose a workspace folder")).toBeVisible({ timeout: 20_000 });
+    } finally {
+      await p.context().close();
+    }
+  });
+});
diff --git a/tests/fixtures/ipc-mock.ts b/tests/fixtures/ipc-mock.ts
index f4c23fb73..c47c0408e 100644
--- a/tests/fixtures/ipc-mock.ts
+++ b/tests/fixtures/ipc-mock.ts
@@ -150,14 +150,20 @@ export const FIXTURE_FLOW = {
  * and during view rendering.
  *
  * Pass the result to `page.addInitScript({ content: buildIpcMock() })`.
+ *
+ * `opts.needsWorkspaceSetup` overrides the default fresh-install probe so the
+ * value is baked into the same synchronous script that defines `window.electron`
+ * — avoiding a race where the app reads the default before a deferred override
+ * runs.
  */
-export function buildIpcMock(): string {
+export function buildIpcMock(opts?: { needsWorkspaceSetup?: boolean }): string {
   // Embed fixture data as JSON so the script is fully self-contained
   const snapshot = JSON.stringify(FIXTURE_SNAPSHOT);
   const graph = JSON.stringify(FIXTURE_GRAPH);
   const flow = JSON.stringify(FIXTURE_FLOW);
   const wsId = JSON.stringify(WS_ID);
   const projId = JSON.stringify(PROJ_ID);
+  const needsSetup = JSON.stringify(opts?.needsWorkspaceSetup ?? false);
 
   return /* js */ `
 (function () {
@@ -166,6 +172,7 @@ export function buildIpcMock(): string {
   const flowData = ${flow};
   const wsId = ${wsId};
   const projId = ${projId};
+  const needsSetup = ${needsSetup};
 
   // No-op that returns a resolved promise (used for write calls)
   const noop = () => Promise.resolve(null);
@@ -197,7 +204,7 @@ export function buildIpcMock(): string {
     // ── Boot sequence ────────────────────────────────────────
     snapshot:              () => Promise.resolve(snap),
     hasData:               () => Promise.resolve(true),
-    needsWorkspaceSetup:   () => Promise.resolve(false),
+    needsWorkspaceSetup:   () => Promise.resolve(needsSetup),
 
     // ── Workspace ─────────────────────────────────────────────
     workspace: {
@@ -295,7 +302,7 @@ export function buildIpcMock(): string {
     revealAssets:          noop,
     selectWorkspaceFolder: () => Promise.resolve(null),
     getWorkspacePath:      () => Promise.resolve("/mock/workspace"),
-    needsWorkspaceSetup:   () => Promise.resolve(false),
+    needsWorkspaceSetup:   () => Promise.resolve(needsSetup),
     setTheme:              noop,
     initWorkspace:         () => Promise.resolve({ requiresRestart: false }),
     relaunch:              noop,
diff --git a/vitest.config.ts b/vitest.config.ts
index 40062784f..690ce73c7 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,4 +1,5 @@
 import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
 import path from "path";
 import { config as loadDotenv } from "dotenv";
 
@@ -6,24 +7,46 @@ import { config as loadDotenv } from "dotenv";
 // The file is gitignored; missing is fine — variables simply won't be set.
 loadDotenv({ path: path.resolve(__dirname, ".env.test"), override: false });
 
+const sharedAlias = {
+  // Redirect better-sqlite3 so it loads via nativeBinding from vitest-native/
+  "better-sqlite3": path.resolve(__dirname, "vitest-sqlite-shim.cjs"),
+  "@": path.resolve(__dirname, "./src"),
+};
+
 export default defineConfig({
+  resolve: { alias: sharedAlias },
   test: {
-    environment: "node",
-    include: ["electron/**/*.test.ts", "src/**/*.test.ts"],
     globals: true,
-    // Tell the vitest-sqlite-shim.cjs where to find the system-Node-ABI binary.
-    // vitest-native/ holds the build for the currently-running Node (saved by
-    // `npm run rebuild`); pkg-native/ is Node 22 ABI for the pkg-bundled MCP
-    // binary and would mismatch on Node != 22.
-    env: {
-      BETTER_SQLITE3_BINDING: path.resolve(__dirname, "vitest-native/better_sqlite3.node"),
-    },
-  },
-  resolve: {
-    alias: {
-      // Redirect better-sqlite3 so it loads via nativeBinding from vitest-native/
-      "better-sqlite3": path.resolve(__dirname, "vitest-sqlite-shim.cjs"),
-      "@": path.resolve(__dirname, "./src"),
-    },
+    // Two projects:
+    //  - "node": the default fast suite (store/lib/electron logic, native sqlite).
+    //    Component tests (*.component.test.tsx) are excluded here.
+    //  - "component": React component tests rendered in jsdom via Testing Library.
+    projects: [
+      {
+        plugins: [react()],
+        resolve: { alias: sharedAlias },
+        test: {
+          name: "node",
+          environment: "node",
+          globals: true,
+          include: ["electron/**/*.test.ts", "src/**/*.test.ts", "src/**/*.test.tsx"],
+          exclude: ["src/**/*.component.test.tsx"],
+          env: {
+            BETTER_SQLITE3_BINDING: path.resolve(__dirname, "vitest-native/better_sqlite3.node"),
+          },
+        },
+      },
+      {
+        plugins: [react()],
+        resolve: { alias: sharedAlias },
+        test: {
+          name: "component",
+          environment: "jsdom",
+          globals: true,
+          include: ["src/**/*.component.test.tsx"],
+          setupFiles: ["./vitest.setup.components.ts"],
+        },
+      },
+    ],
   },
 });
diff --git a/vitest.setup.components.ts b/vitest.setup.components.ts
new file mode 100644
index 000000000..00aa4a2d4
--- /dev/null
+++ b/vitest.setup.components.ts
@@ -0,0 +1,15 @@
+/**
+ * Vitest setup for the "component" project (jsdom + Testing Library).
+ *
+ * - Registers @testing-library/jest-dom matchers (toBeInTheDocument, toBeDisabled,
+ *   toHaveAttribute, etc.).
+ * - Auto-cleans the rendered DOM after every test to isolate cases.
+ */
+
+import "@testing-library/jest-dom/vitest";
+import { afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+afterEach(() => {
+  cleanup();
+});