feat(dev): PDF page splitter + category pagination (10/page)

docs/spec/BTB-001-tool-json-formatter/BTB-001-architecture.md

@@ -0,0 +1,55 @@
+---
+specId: BTB-001
+title: tool-json-formatter — Architecture
+owner: Vincent
+status: implemented
+---
+
+# BTB-001-architecture.md
+
+## 1) Architecture design (OOP / module-level)
+
+### 1.1 Components and responsibilities
+
+- `src/tools/json-formatter/JsonFormatterTool.tsx`
+  - Tool page orchestration: buttons (Prettify/Minify/Validate), options (indent, sort keys), output + error/status.
+
+- `src/tools/json-formatter/JsonCodeEditor.tsx`
+  - CodeMirror 6 wrapper
+  - Provides:
+    - JSON syntax highlighting (`@codemirror/lang-json`)
+    - line numbers / basic setup
+    - lint diagnostics (inline range underline) based on JSON.parse
+
+- `src/lib/json.ts`
+  - `sortJsonKeysDeep` for recursive key sorting.
+
+### 1.2 Data model / types
+
+- Editor value: string
+- Validation status: { ok: boolean, message?: string, line?: number, column?: number }
+
+### 1.3 Key flows
+
+- Prettify/Minify:
+  1) read editor value
+  2) `JSON.parse`
+  3) optional `sortJsonKeysDeep`
+  4) `JSON.stringify` with indent (prettify) or none (minify)
+  5) set output
+
+- Validate:
+  1) run JSON.parse
+  2) if error has position, compute line/column
+  3) set CodeMirror diagnostic at that position
+
+### 1.4 Dependencies / constraints
+
+- CodeMirror 6 packages:
+  - `@codemirror/view`, `@codemirror/state`, `@codemirror/language`, `@codemirror/lang-json`, `@codemirror/lint`
+- Constraint: no server.
+
+### 1.5 Compatibility notes
+
+- Keep route `/tools/json-formatter` stable.
+- Existing output semantics preserved.

docs/spec/BTB-001-tool-json-formatter/BTB-001-requirements.md

@@ -0,0 +1,80 @@
+---
+specId: BTB-001
+title: tool-json-formatter — JSON prettify/minify/sort/validate with CodeMirror editor
+owner: Vincent
+status: implemented
+---
+
+# BTB-001-requirements.md
+
+## 0) Context
+
+- Problem:
+  - Users need to format/validate JSON quickly, with helpful inline error location.
+- Users/persona:
+  - Beginners + developers pasting JSON from APIs/logs.
+- Non-goals:
+  - No backend.
+  - No guarantee of accepting non-JSON variants (JSON5, comments) in v1.
+- Constraints:
+  - Runs 100% in-browser.
+  - Must handle large inputs reasonably without freezing.
+
+---
+
+## 1) Requirements
+
+### 1.1 Functional (expected)
+
+- [ ] BTB-001-REQ-001 (Functional / Expected): Provide an editor input for JSON with **line numbers**.
+- [ ] BTB-001-REQ-002 (Functional / Expected): Provide **Prettify** (indent) operation.
+- [ ] BTB-001-REQ-003 (Functional / Expected): Provide **Minify** operation.
+- [ ] BTB-001-REQ-004 (Functional / Expected): Provide **Sort keys (recursive)** option.
+- [ ] BTB-001-REQ-005 (Functional / Expected): Provide **Validate** operation.
+- [ ] BTB-001-REQ-006 (Functional / Expected): On invalid JSON, show an error message including **line/column**.
+- [ ] BTB-001-REQ-007 (Functional / Expected): On invalid JSON, show **inline error highlighting** in the editor.
+- [ ] BTB-001-REQ-008 (Functional / Expected): Editor should provide JSON syntax highlighting.
+- [ ] BTB-001-REQ-009 (Functional / Expected): Output panel supports copy and does not lose last successful output unnecessarily.
+
+### 1.2 Functional (forbidden)
+
+- [ ] BTB-001-REQ-010 (Functional / Forbidden): Must not send JSON content to any server.
+- [ ] BTB-001-REQ-011 (Functional / Forbidden): Must not embed unbounded JSON input into URL.
+
+### 1.3 Non-functional
+
+- [ ] BTB-001-REQ-012 (Non-functional): Must be usable on mobile widths (~420px).
+- [ ] BTB-001-REQ-013 (Non-functional): All repo quality gates must pass (test/lint/build/e2e).
+
+---
+
+## 2) Acceptance criteria
+
+- [ ] BTB-001-AC-001 (maps to BTB-001-REQ-001): Editor shows line numbers and accepts multi-line input.
+- [ ] BTB-001-AC-002 (maps to BTB-001-REQ-002): Prettify formats compact JSON into indented output.
+- [ ] BTB-001-AC-003 (maps to BTB-001-REQ-005/006/007): Validate on invalid JSON shows error message with line/col and an inline error marker.
+- [ ] BTB-001-AC-004 (maps to BTB-001-REQ-004): When sort keys is enabled, output JSON has recursively sorted object keys.
+
+---
+
+## 3) Test plan
+
+- Unit:
+  - `sortJsonKeysDeep` behavior.
+- E2E:
+  - `e2e/json-formatter.spec.ts` covers prettify + validate success/failure + inline marker.
+
+---
+
+## 4) Rollout / rollback
+
+- Rollout: Static deploy.
+- Rollback: revert commits affecting editor integration.
+- Risks:
+  - CodeMirror chunk size increase.
+
+---
+
+## 5) Open questions
+
+- Q1: Should we support JSON5 (comments/trailing commas) later?

docs/spec/BTB-002-ui-global-search/BTB-002-architecture.md

@@ -0,0 +1,44 @@
+---
+specId: BTB-002
+title: ui-global-search — Architecture
+owner: Vincent
+status: implemented
+---
+
+# BTB-002-architecture.md
+
+## 1) Architecture design (OOP / module-level)
+
+### 1.1 Components and responsibilities
+
+- `src/App.tsx` (Header + pages)
+  - Holds search query state.
+  - Syncs with short URL param `q`.
+  - When query changes off Home, navigates to Home.
+
+- Home page
+  - Filters `TOOLS` by query.
+  - Renders result count.
+
+### 1.2 Data model / types
+
+- Query: string (bounded for URL)
+
+### 1.3 Key flows
+
+- User types in header search:
+  - update state
+  - if not on Home, navigate to Home
+  - filter tool list
+
+- Enter key:
+  - if exactly one match → navigate `/tools/<id>`
+
+### 1.4 Dependencies / constraints
+
+- No dependencies.
+- Constraint: keep URL param short.
+
+### 1.5 Compatibility notes
+
+- Routes unchanged.

docs/spec/BTB-002-ui-global-search/BTB-002-requirements.md

@@ -0,0 +1,71 @@
+---
+specId: BTB-002
+title: ui-global-search — Header search across all tools
+owner: Vincent
+status: implemented
+---
+
+# BTB-002-requirements.md
+
+## 0) Context
+
+- Problem:
+  - As tool count grows, users need fast discovery without scrolling.
+- Users/persona:
+  - Users who remember partial tool names (e.g., “json”, “diff”).
+- Non-goals:
+  - No backend search.
+  - No fuzzy ranking beyond simple contains match in v1.
+- Constraints:
+  - Must work from any page.
+  - Search query should be bounded if stored in URL.
+
+---
+
+## 1) Requirements
+
+### 1.1 Functional (expected)
+
+- [ ] BTB-002-REQ-001 (Functional / Expected): Provide a search input in the header (desktop) and accessible on mobile.
+- [ ] BTB-002-REQ-002 (Functional / Expected): Search is global across all tools (name + description + id).
+- [ ] BTB-002-REQ-003 (Functional / Expected): Typing from any page navigates to Home and filters tool cards.
+- [ ] BTB-002-REQ-004 (Functional / Expected): Escape clears query.
+- [ ] BTB-002-REQ-005 (Functional / Expected): Enter with exactly one result navigates directly to that tool.
+- [ ] BTB-002-REQ-006 (Functional / Expected): Show result count when filtering.
+- [ ] BTB-002-REQ-007 (Functional / Expected): Support shareable short URL param `q` (bounded length).
+
+### 1.2 Functional (forbidden)
+
+- [ ] BTB-002-REQ-008 (Functional / Forbidden): Must not store unbounded queries in URL.
+- [ ] BTB-002-REQ-009 (Functional / Forbidden): Must not require backend.
+
+### 1.3 Non-functional
+
+- [ ] BTB-002-REQ-010 (Non-functional): Does not significantly degrade performance on Home.
+
+---
+
+## 2) Acceptance criteria
+
+- [ ] BTB-002-AC-001 (maps to BTB-002-REQ-003): From `/music`, typing in search returns to Home and filters results.
+- [ ] BTB-002-AC-002 (maps to BTB-002-REQ-005): With one match, Enter navigates to tool page.
+- [ ] BTB-002-AC-003 (maps to BTB-002-REQ-007): Loading `/#/?q=json` filters the Home tool list.
+
+---
+
+## 3) Test plan
+
+- E2E: `e2e/search.spec.ts` covers navigation, Enter, Esc, URL param.
+
+---
+
+## 4) Rollout / rollback
+
+- Rollout: static.
+- Rollback: revert UI/search commit.
+
+---
+
+## 5) Open questions
+
+- Q1: Add fuzzy matching / ranking?

docs/spec/BTB-003-ui-theme-system/BTB-003-architecture.md

@@ -0,0 +1,28 @@
+---
+specId: BTB-003
+title: ui-theme-system — Architecture
+owner: Vincent
+status: implemented
+---
+
+# BTB-003-architecture.md
+
+## 1) Architecture design (module-level)
+
+### 1.1 Components and responsibilities
+
+- `src/lib/theme.ts`
+  - Reads/writes `btb:theme`.
+  - Computes effective theme (`system` → light/dark).
+  - Applies `.dark` class on `<html>` and sets `color-scheme`.
+  - Sync: listens to media query changes when pref is `system`.
+
+- `src/styles/design-system.css` + `src/styles/theme.css`
+  - CSS variables for colors.
+  - `.dark { ... }` overrides.
+
+- `src/tools/settings/SettingsPage.tsx`
+  - Radio toggle for theme preference.
+
+- `src/App.tsx`
+  - Calls `initThemeSync()` on mount.

docs/spec/BTB-003-ui-theme-system/BTB-003-requirements.md

@@ -0,0 +1,46 @@
+---
+specId: BTB-003
+title: ui-theme-system — Light/Dark/System theme with Settings toggle
+owner: Vincent
+status: implemented
+---
+
+# BTB-003-requirements.md
+
+## 0) Context
+
+- Problem: Users need light/dark modes, ideally following system, with manual override.
+- Non-goals: No theming per-tool; no design overhaul.
+- Constraints: In-browser only; no backend.
+
+## 1) Requirements
+
+### 1.1 Functional (expected)
+
+- [ ] BTB-003-REQ-001: Provide theme preference values: `system | light | dark`.
+- [ ] BTB-003-REQ-002: Persist preference locally (localStorage key `btb:theme`).
+- [ ] BTB-003-REQ-003: Apply effective theme without full page reload.
+- [ ] BTB-003-REQ-004: `system` follows `prefers-color-scheme` changes.
+
+### 1.2 Functional (forbidden)
+
+- [ ] BTB-003-REQ-005: Must not store theme preference on a server.
+
+### 1.3 Non-functional
+
+- [ ] BTB-003-REQ-006: Theme must keep text/background contrast readable.
+
+## 2) Acceptance criteria
+
+- [ ] BTB-003-AC-001: Settings offers System/Light/Dark and switching updates UI immediately.
+- [ ] BTB-003-AC-002: With System selected, OS theme change updates the app.
+
+## 3) Test plan
+
+- Integration/manual: verify theme switch + system follow.
+- Optional e2e: could be added later.
+
+## 4) Rollout / rollback
+
+- Rollout: static.
+- Rollback: revert theme commits.

docs/spec/BTB-004-ui-settings-storage-reset/BTB-004-architecture.md

@@ -0,0 +1,20 @@
+---
+specId: BTB-004
+title: ui-settings-storage-reset — Architecture
+owner: Vincent
+status: implemented
+---
+
+# BTB-004-architecture.md
+
+## 1) Architecture design
+
+- `src/lib/localStorageAdmin.ts`
+  - Central mapping: toolId → key prefixes/keys.
+  - Implements `clearTool(toolId)` and `clearAll()`.
+
+- `src/tools/settings/SettingsPage.tsx`
+  - Renders clear-all and per-tool clear UI with confirm.
+
+- `src/components/ToolPage.tsx`
+  - Conditionally shows "Reset this tool" button for tools with storage mapping.

docs/spec/BTB-004-ui-settings-storage-reset/BTB-004-requirements.md

@@ -0,0 +1,36 @@
+---
+specId: BTB-004
+title: ui-settings-storage-reset — Clear per-tool and all-app saved data
+owner: Vincent
+status: implemented
+---
+
+# BTB-004-requirements.md
+
+## 0) Context
+
+- Problem: Tool inputs/options are stored locally; user needs a safe way to clear them.
+- Constraints: Must not delete unrelated site/app keys.
+
+## 1) Requirements
+
+### 1.1 Functional (expected)
+
+- [ ] BTB-004-REQ-001: Provide Settings page for clearing data.
+- [ ] BTB-004-REQ-002: Provide "Clear all saved data" for this app only.
+- [ ] BTB-004-REQ-003: Provide per-tool clear buttons.
+- [ ] BTB-004-REQ-004: Provide per-tool "Reset this tool" on tool pages (where applicable).
+- [ ] BTB-004-REQ-005: Confirm before destructive clear.
+
+### 1.2 Functional (forbidden)
+
+- [ ] BTB-004-REQ-006: Must not wipe unrelated localStorage keys.
+
+## 2) Acceptance criteria
+
+- [ ] BTB-004-AC-001: Settings clear-all removes only mapped keys.
+- [ ] BTB-004-AC-002: Per-tool clear removes only that tool’s keys.
+
+## 3) Test plan
+
+- E2E: confirm dialogs + key removal checks.