diff --git a/docs/superpowers/specs/2026-06-05-phase-9-advanced-tools-design.md b/docs/superpowers/specs/2026-06-05-phase-9-advanced-tools-design.md new file mode 100644 index 0000000..c739ce8 --- /dev/null +++ b/docs/superpowers/specs/2026-06-05-phase-9-advanced-tools-design.md @@ -0,0 +1,303 @@ +# Phase 9 — Advanced Tools Design + +> Companion to the parent plan: `docs/superpowers/plans/2026-06-05-react-ui-redesign.md` (Phase 9 is sketched at high level; this spec locks architecture, file map, and contracts so it can be planned task-by-task.) + +**Date:** 2026-06-05 +**Phase:** 9 of 10 (React + shadcn/ui UI redesign) +**Tag (on completion):** `phase-9-advanced-tools` + +--- + +## 1. Goal & Non-Goals + +**Goal:** Add 10 advanced tools to the React renderer. Group 1: Standalone dialogs (ASCII generator, Table generator, Word export, Find-in-files). Group 2: Global overlays (Zen mode, REPL, Print preview). Group 3: Editor/sidebar integrations (Minimap, Breadcrumbs-with-symbols, Git status). All triggered via the Phase 6 command store. + +**Non-goals (Phase 9):** +- True undo/redo stack (still not in scope) +- Snippet/template library +- Custom REPL with full JS eval (we chose markdown snippet preview for safety) +- Custom diff/merge UI (just shows git status, no in-app diffing) +- Plug-in extensions +- Multi-cursor editing +- LSP / language server integration + +**Decision summary (from brainstorming):** +- REPL = **markdown snippet preview** (no JS eval — safe in renderer) +- Word export = **`.docx` via `docx` lib in renderer**, with both Standard and Custom .dotx template modes +- Find-in-files = **recursive search with result navigation** (new IPC, regex support) + +--- + +## 2. Architecture + +### 2.1 Three mount strategies + +| Category | Mount | Examples | +|---|---|---| +| **Dialogs** | `` (Phase 7 pattern) | ASCII gen, Table gen, Word export, Find-in-files | +| **Global overlays** | Top-level in `App.tsx` (like ``) | Zen mode, REPL panel, Print preview | +| **Editor/sidebar integrations** | Extend existing components | Minimap, Breadcrumbs, Git status | + +The ModalLayer is the dispatcher for dialogs. The global overlays are mounted directly in `App.tsx` because they need to participate in the top-level layout (full-window, or pinned to the bottom). + +### 2.2 ModalState union extension + +The Phase 7 `ModalState` discriminated union (9 kinds) gets 4 new kinds for the new dialogs: + +```ts +export type ModalState = + | { kind: null } + | { kind: 'export-pdf'; props: { sourcePath: string } } + | { kind: 'export-docx'; props: { sourcePath: string } } + | { kind: 'export-html'; props: { sourcePath: string } } + | { kind: 'export-batch'; props: { sourcePaths: string[] } } + | { kind: 'export-word'; props: { sourcePath: string } } // NEW + | { kind: 'ascii-generator' } // NEW + | { kind: 'table-generator' } // NEW + | { kind: 'find-in-files' } // NEW + | { kind: 'settings' } + | { kind: 'about' } + | { kind: 'welcome' } + | { kind: 'confirm'; props: ConfirmProps }; +``` + +Three of the four new kinds (ascii, table, find-in-files) take no props — they read from the active buffer via `useExportSource` (for ascii/table) or from `useFileStore.rootPath` (for find-in-files). `export-word` takes `sourcePath` like the other export dialogs. + +### 2.3 New commands in command store + +| Command ID | Trigger | Opens | +|---|---|---| +| `tools.ascii` | new | `AsciiGeneratorDialog` | +| `tools.table` | new | `TableGeneratorDialog` | +| `tools.exportWord` | new | `WordExportDialog` | +| `tools.findInFiles` | new | `FindInFilesDialog` | +| `tools.repl` | new | toggles REPL panel | +| `view.zenMode` | existing (Phase 6) | toggles Zen mode overlay | +| `file.print` | new | opens `PrintPreview` overlay | +| `git.refresh` | new | re-fetches git status | + +All registered in `src/renderer/lib/commands/register-menu-commands.ts`. + +### 2.4 New IPC surface + +```ts +// src/renderer/lib/ipc.ts (additions) +ipc.file.search({ rootPath, query, isRegex, caseSensitive }: { + rootPath: string; + query: string; + isRegex: boolean; + caseSensitive: boolean; +}): Promise>>; + +ipc.file.gitStatus({ rootPath }: { rootPath: string }): Promise>>; + +ipc.file.print({ html }: { html: string }): Promise>; + +ipc.file.writeBuffer({ path, buffer }: { path: string; buffer: Uint8Array }): Promise>; +``` + +The main process counterparts are added to `src/main.js` (or a new `src/main/files-search.js`, etc.). For Phase 9, the spec covers the renderer-side design; main-process IPC handlers are assumed to follow the same `ipcMain.handle` pattern as the existing handlers. + +### 2.5 Settings additions (`useSettingsStore`) + +```ts +// zod schema additions: +docxCustomTemplatePath: z.string().nullable().default(null), // path to user .dotx file +replOpen: z.boolean().default(false), // REPL panel visibility +breadcrumbSymbols: z.boolean().default(true), // breadcrumbs show code symbols +// minimap already exists from Phase 7 (useSettingsStore.minimap: z.boolean().default(true)) +``` + +The `minimap` setting from Phase 7 is now wired (not just stored). + +--- + +## 3. File Map + +### 3.1 Created files + +**Dialogs (in `src/renderer/components/modals/`):** +- `AsciiGeneratorDialog.tsx` — input textarea, font select, output preview with copy button +- `TableGeneratorDialog.tsx` — rows × cols inputs, header checkbox, output preview +- `WordExportDialog.tsx` — template select (Standard / Custom .dotx), options, preview, export +- `FindInFilesDialog.tsx` — query input, regex/case toggles, results list with click-to-navigate + +**Global overlays (in `src/renderer/components/tools/`):** +- `ReplPanel.tsx` — bottom-pinned, textarea + rendered preview +- `PrintPreview.tsx` — full-window print preview + +**Editor/sidebar integrations:** +- `src/renderer/components/layout/ZenMode.tsx` — wraps/controls the editor in zen mode (or modify `AppShell.tsx` to hide chrome) +- `src/renderer/components/sidebar/GitStatusPanel.tsx` — file list with status badges + +**Lib:** +- `src/renderer/lib/docx-export.ts` — renderer-side `docx` lib integration (markdown → Blob) +- `src/renderer/hooks/use-zen-mode.ts` — small hook that reads `useSettingsStore.zenMode` + +**Modifications:** +- `src/renderer/App.tsx` — mount `` and `` alongside `` and `` +- `src/renderer/components/layout/AppShell.tsx` — when `zenMode === true`, hide all chrome except the editor +- `src/renderer/components/editor/CodeMirrorEditor.tsx` — add `@codemirror/minimap` (or `@replit/codemirror-minimap`) when `useSettingsStore.minimap` is true +- `src/renderer/components/layout/Breadcrumb.tsx` — extend to show symbols (headings, code blocks) using `@codemirror/langs-data` or a simple markdown AST walk +- `src/renderer/components/sidebar/Sidebar.tsx` — add a "Git" tab to the existing tab list +- `src/renderer/stores/settings-store.ts` — add 3 new fields +- `src/renderer/lib/validators.ts` — add 3 new fields to `settingsSchema` +- `src/renderer/lib/ipc.ts` — add 4 new IPC methods +- `src/renderer/lib/commands/register-menu-commands.ts` — add 8 new commands +- `src/main.js` (or split files) — add 4 main-process IPC handlers + +**Tests:** +- `tests/component/tools/ReplPanel.test.tsx` — smoke test +- `tests/component/tools/PrintPreview.test.tsx` — smoke test +- `tests/component/modals/AsciiGeneratorDialog.test.tsx` — 3 tests +- `tests/component/modals/TableGeneratorDialog.test.tsx` — 3 tests +- `tests/component/modals/WordExportDialog.test.tsx` — 4 tests +- `tests/component/modals/FindInFilesDialog.test.tsx` — 4 tests +- `tests/component/sidebar/GitStatusPanel.test.tsx` — 3 tests +- `tests/component/layout/Breadcrumb.test.tsx` — extend with symbols test +- `tests/integration/phase9-tools-smoke.test.tsx` — 6 tests (one per command-triggered tool) + +--- + +## 4. Data Flow + +### 4.1 Word export (most complex) + +1. User triggers `tools.exportWord` → `registerMenuCommands` opens the export-word modal via `useAppStore.openModal('export-word', { sourcePath: activeTabId })` +2. **Wait** — we need a new modal kind `export-word` in the `ModalState` union. Add it. +3. `WordExportDialog` (mounted by ModalLayer) shows: + - Template select: "Standard (bundled)" or "Custom .dotx (your file)" — pre-populated with `useSettingsStore.docxCustomTemplatePath` + - "Choose custom template..." button (file picker, saves to settings) + - Options: embed images (checkbox), include front matter (checkbox) + - Preview area: shows the generated docx structure (sizes, table of contents) +4. On submit: + - Renderer calls `lib/docx-export.ts#generateDocx(source, templatePath, options)` which uses the `docx` lib + - The lib takes a `Document` AST and produces a Blob + - ASCII tables are converted to monospace `` runs (using `applyAsciiTransform` from Phase 7) + - Images are extracted from markdown and embedded as base64 + - If a custom .dotx path is set, the renderer reads it via `ipc.file.read` and applies its styles (via `docx` lib's style support) + - User picks output path via `ipc.app.showSaveDialog` + - Writes Blob via `ipc.file.writeBuffer` (new) + - Toast success/failure + +### 4.2 Find-in-files + +1. User triggers `tools.findInFiles` → ModalLayer opens `FindInFilesDialog` +2. User types query, picks regex/literal, case-sensitive toggle +3. On submit: `ipc.file.search({ rootPath: useFileStore.rootPath, query, isRegex, caseSensitive })` +4. Backend walks the disk recursively, applies regex/literal match, returns `Array<{ filePath, line, content }>` +5. Dialog shows result list (file:line:content, clickable) +6. Click a result: + - `useFileStore.openFile(filePath)` if not already open + - Set the cursor in the editor to the matched line +7. Close the dialog + +### 4.3 REPL (markdown snippet preview) + +1. User triggers `tools.repl` → toggles `useSettingsStore.replOpen` (or a new dedicated `useReplStore`) +2. `ReplPanel` (mounted in App.tsx) is visible when `replOpen === true` +3. The panel has: + - Top half: textarea (user types/pastes markdown) + - Bottom half: rendered preview (uses `lib/markdown.ts` from Phase 1 + DOMPurify) +4. Updates are debounced (300ms) for the preview +5. Pure renderer-side, no IPC + +### 4.4 Zen mode + +1. User triggers `view.zenMode` → toggles `useSettingsStore.zenMode` +2. `AppShell` reads `zenMode` from store; when true, hides all chrome (header, tabs, toolbar, breadcrumb, status bar, sidebar) +3. Editor goes fullscreen +4. Pressing Esc exits zen mode (keydown listener in `use-zen-mode` hook) + +### 4.5 Print preview + +1. User triggers `file.print` → opens `PrintPreview` (full-window overlay) +2. The preview renders the current buffer's content as it would appear in print +3. Two buttons: "Print" (calls `ipc.file.print({ html })` which opens native print dialog) and "Close" + +### 4.6 Minimap + +1. `useSettingsStore.minimap` (existing setting) is read by `CodeMirrorEditor` +2. When true, the editor's extension includes `@replit/codemirror-minimap` (or a simpler custom implementation) +3. The minimap shows a shrunk version of the document on the right side of the editor +4. Toggling the setting adds/removes the extension dynamically + +### 4.7 Breadcrumbs-with-symbols + +1. The current `Breadcrumb` shows the file path. Extend it to also show markdown symbols (headings, code blocks) +2. Use a simple AST walk of the current buffer to extract heading levels +3. Show as a path-like navigation: `file.md > H1: Title > H2: Section > #line` +4. The `useSettingsStore.breadcrumbSymbols` toggle (default true) controls whether symbols are shown + +### 4.8 Git status + +1. On sidebar Git tab open, fetch `ipc.file.gitStatus({ rootPath: useFileStore.rootPath })` +2. The main process runs `git status --porcelain` (or equivalent) and returns the list +3. Show file list with status badges (M, A, D, ?) +4. Click a file opens it via `useFileStore.openFile` +5. `git.refresh` re-fetches + +--- + +## 5. Error Handling + +- **Word export failures:** `lib/docx-export.ts` catches `docx` lib errors → toast.error +- **Word export missing .dotx:** if custom template path is set but file doesn't exist, show inline banner in the dialog +- **Find-in-files failures:** if `ipc.file.search` throws (regex syntax error, IO error), show inline banner in the dialog +- **REPL:** no IPC, no error handling needed +- **Git status:** if folder isn't a git repo, return empty array. Panel shows "Not a git repository" message +- **Print:** if `ipc.file.print` fails (no printer, user cancels), toast.error or silent close +- **Minimap, Breadcrumbs:** renderer-side, no errors + +--- + +## 6. Testing Strategy + +- **Unit tests:** `lib/docx-export.ts` (markdown → docx conversion, ASCII handling), `lib/ascii-table.ts` (already tested) +- **Component tests:** 1-2 smoke tests per new component +- **Integration test:** `phase9-tools-smoke.test.tsx` covering the 6 command-triggered tools (dispatch opens correct modal/overlay) +- **Editor integrations:** minimap toggle, breadcrumbs render with symbols, git status panel render +- **Target: +30-40 new tests**, total ~290 + +--- + +## 7. Risks & Open Questions + +**Risks:** +- **`docx` lib bundle size (~500KB).** Acceptable for a desktop app but worth noting. Lazy-load if it becomes a concern. +- **Word export custom template parsing** — the `.dotx` format is a zip with XML inside. The `docx` lib may not fully support reading existing templates. v1 may need a simpler "styles only" extraction. +- **Find-in-files regex compilation** — invalid regex would throw. Validate on the renderer before calling IPC. +- **Minimap performance** — for large files, the minimap can slow down scrolling. CodeMirror's built-in minimap has performance options to configure. + +**Open questions (deferrable):** +- **REPL persistence** — should the textarea content survive across modal close/reopen? → Decision: NO for v1. Keep simple. +- **Git status auto-refresh** — should it auto-refresh every N seconds? → Decision: NO for v1. Manual via `git.refresh` command. +- **Find-in-files result count limit** — what if there are 10,000 matches? → Decision: limit to 500 results for v1, show "X more matches" message. + +--- + +## 8. Out of Scope (deferred to Phase 10 or later) + +- Custom undo/redo (still not in scope) +- Snippet/template library +- Multi-cursor editing +- LSP / language server +- Phase 10 will delete legacy files including the old `src/print-preview.js`, `src/wordTemplateExporter.js`, `src/welcome.js`, `src/zen-mode.js`, etc. + +--- + +## 9. Success Criteria + +Phase 9 is complete when: +- All 10 features implemented and accessible via the command store +- `lib/docx-export.ts` generates valid `.docx` files +- Find-in-files returns results from a recursive disk walk +- REPL renders markdown snippet previews +- Zen mode hides all chrome and Esc exits +- Print preview opens native print dialog +- Minimap appears when `useSettingsStore.minimap` is true +- Breadcrumbs show symbols by default +- Git status panel shows modified/added/deleted/untracked files +- ~+30-40 new tests, total ~290 +- `npx vite build` succeeds +- Branch tagged `phase-9-advanced-tools` and pushed to origin