diff --git a/docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md b/docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md new file mode 100644 index 0000000..cb2d4ee --- /dev/null +++ b/docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md @@ -0,0 +1,306 @@ +--- +name: Phase 9 — Polish debt (design) +description: Design spec for Corbie Phase 9. Closes six polish-debt items from the feature-complete roadmap plus the Phase 8 carryover backlog. File-system save dialog, bulk History export, on-demand LLM content tags, progressive-disclosure Settings restructure, visual polish, accessibility sweep. +type: spec +tags: [spec, phase-9, corbie, polish, accessibility, settings, export, llm] +created: 2026/04/24 +status: approved +phase: 9 +roadmap: docs/roadmap/2026-04-23-corbie-feature-complete-roadmap.md +author: Wren (CORBEL's resident agent) on behalf of Jake Sames +--- + +# Phase 9 — Polish debt + +## Summary + +Close the last polish-debt items before Phase 10 (QC + rename + release). Six items from the roadmap plus the Phase 8 carryover backlog. + +1. **File-system `.md` save dialog** — replaces clipboard-only export on HistoryPage + DictationPage + FilesPage. +2. **Bulk select + bulk export in History** — multi-select rows, export as a directory of `.md` files. +3. **LLM content tags** — on-demand `topic:*` + `intent:*` extraction using `kon-llm`, persisted on history rows. +4. **Settings UX overhaul** — progressive disclosure. High-frequency settings always-visible; advanced behind `
` groups. Phase 8 sparkline toggle relocated out of Rituals. +5. **Visual polish pass** — spacing, typography, motion curves, dark-mode parity. Absorbs Phase 8 motion backlog on badge + sparkline. +6. **Accessibility pass** — keyboard navigation, focus order, screen reader labels (friendlier sparkline aria copy), WCAG AA contrast. Absorbs Phase 8 a11y backlog. + +No new Rust crates. No new dependencies (`tauri-plugin-dialog` + `@tauri-apps/plugin-dialog` both already installed; capability already allowed). + +This is the last phase before Phase 10. On completion: cargo + clippy + fmt + svelte-check + npm build all clean; manual dogfood walkthrough of items 1-6 passes; roadmap + HANDOVER updated. + +## Design decisions locked 2026/04/24 + +1. **Save dialog** — no silent clipboard fallback if user cancels. Default filename derived from transcript title via the existing slug path (`-<YYYY-MM-DD>.md`). +2. **Bulk export format** — directory of per-transcript files (chosen via `open({ directory: true })`). Concatenated single-file is not offered; users can copy-paste or open selected items to achieve it. +3. **LLM tags** — on-demand per row plus a batch "Tag all untagged" affordance. Stored on `item.llmTags: string[]` alongside existing `manualTags`. Grammar-constrained JSON extraction: `{ topic: string, intent: enum }` with intent from a closed set. Re-generation replaces prior `llmTags` for that row (no history). +4. **Settings restructure** — progressive disclosure. Top group "Start here" always expanded (model, microphone, hotkey, theme). Six collapsed `<details>` groups below: Transcription, Tasks, Rituals, Notifications, Accessibility, Advanced. Phase 8 sparkline toggle moves from Rituals to Tasks. +5. **Visual polish + a11y — include in Phase 9**, not deferred to post-v0.1. Matches roadmap as written. Polish + a11y constrained to a checklist (see §Visual polish + §Accessibility below), not an open-ended pass. + +## Architecture + +### Item 1 — File-system `.md` save dialog + +**Rust side** (`src-tauri/src/commands/fs.rs`, new file — or added to an existing commands file if the one-command-per-file convention is loose): + +```rust +#[tauri::command] +pub async fn write_text_file_cmd(path: String, contents: String) -> Result<(), String> { + // Safety: + // - Path comes from a user-selected save dialog. We do not validate + // traversal or extension — the OS file picker already constrains + // the user's choice to what they can write to. + // - Parent directory is expected to exist (save dialog guarantees it). + // - Writes UTF-8 via tokio::fs. No atomic-rename dance — a transcript + // save is not mid-flight safety-critical; clobber on overwrite is fine. + tokio::fs::write(&path, contents) + .await + .map_err(|e| format!("Failed to write {path}: {e}")) +} +``` + +**Frontend call sites** — replace the `navigator.clipboard.writeText(md)` tail with: + +```typescript +import { save } from "@tauri-apps/plugin-dialog"; + +const defaultName = suggestedFilename(item); // "<slug>-<YYYY-MM-DD>.md" +const path = await save({ + title: "Save transcript as Markdown", + defaultPath: defaultName, + filters: [{ name: "Markdown", extensions: ["md"] }], +}); +if (!path) return; // user cancelled — no toast, no fallback +await invoke("write_text_file_cmd", { path, contents: md }); +toasts.success(`Saved to ${basename(path)}`); +``` + +A new utility `src/lib/utils/saveMarkdown.ts` centralises `suggestedFilename` + `saveTranscriptAsMarkdown(item)` so three pages (HistoryPage / DictationPage / FilesPage) each call one function. + +**Call site scope.** HistoryPage `exportMarkdown` (line 343) is the primary target. DictationPage + FilesPage currently do clipboard-only copies of raw transcript text (not markdown); they are out of scope for a markdown export button in Phase 9 — their clipboard semantics are right for their UX. Only HistoryPage exposes an "Export .md" button. + +### Item 2 — Bulk select + bulk export in History + +**Selection model.** New frontend-only state on HistoryPage: `let selected: Set<string> = $state(new Set())`. Not persisted across refresh. Selection toolbar appears when `selected.size > 0`. + +**Selection UI.** +- Checkbox on each row, left of existing content. Row click still opens the expanded view; only the checkbox toggles selection. +- A header bar surfaces when selection is non-empty: "`N selected` · Select all / Clear · Export selected · Delete selected". +- "Delete selected" uses existing `deleteFromHistory`, looped, with one confirm. + +**Bulk export.** +- `save` dialog in directory mode: `await open({ directory: true, title: "Choose export folder" })`. +- For each selected item, call the same `buildMarkdown` path, then `write_text_file_cmd({ path: `${dir}/${suggestedFilename(item)}`, contents })`. +- Collision handling: if a filename already exists in the chosen dir, append ` (N)` suffix until unique. Implement in the frontend (single OS-call query per filename is simpler than a Rust batch). +- Toast on completion: "Exported N transcripts to …". + +**Keyboard.** `Escape` clears selection. `Ctrl/Cmd+A` selects all visible rows when the HistoryPage has focus. + +### Item 3 — LLM content tags + +**Data model.** Add `llmTags: string[]` to history entries alongside `manualTags`. Persisted via the existing `saveHistory` path; columnar storage already serialises arrays as comma-joined strings (see `page.svelte.ts:290`). + +**Tag schema.** +- `topic:<1-3 noun phrase>` — free-form, lowercase, hyphen-joined. Examples: `topic:interview-prep`, `topic:grant-application`, `topic:personal-finance`. Limit one per transcript (the dominant subject). +- `intent:<enum>` — closed set: `planning | reflection | venting | capture | decision | question`. Limit one. + +**Generation.** New function in `crates/llm/src/prompts.rs`: + +```rust +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ContentTags { + pub topic: String, // hyphen-joined, lowercase, 1-3 tokens + pub intent: String, // one of INTENT_CLOSED_SET +} + +pub const INTENT_CLOSED_SET: &[&str] = &[ + "planning", "reflection", "venting", "capture", "decision", "question", +]; + +pub async fn extract_content_tags( + engine: &LlamaEngine, + transcript: &str, +) -> Result<ContentTags, EngineError>; +``` + +Grammar-constrained GBNF in `crates/llm/src/grammars.rs` that restricts output to the schema: + +``` +root ::= "{" ws "\"topic\":" ws topic "," ws "\"intent\":" ws intent ws "}" +topic ::= "\"" [a-z0-9-]{3,60} "\"" +intent ::= "\"planning\"" | "\"reflection\"" | "\"venting\"" | "\"capture\"" | "\"decision\"" | "\"question\"" +ws ::= [ \t\n]* +``` + +Prompt sketch (British English, deterministic, temperature 0.0): + +``` +You tag a transcript with ONE topic and ONE intent. + +TOPIC is a 1-3 token lowercase hyphen-joined noun phrase naming the dominant +subject. Examples: "interview-prep", "grant-application", "daily-standup". + +INTENT is exactly one of: planning, reflection, venting, capture, decision, +question. + +Return JSON only, with this exact shape: +{"topic":"...","intent":"..."} + +Transcript: +<<< +{{transcript}} +>>> +``` + +Guardrails: +- Truncate transcript to the last 2000 chars if longer (LLM context budget). +- On any error (JSON-parse, grammar rejection, timeout): return `Err`. Caller surfaces "Tagging failed — try again" toast, writes nothing. +- Re-tagging a previously-tagged row replaces `llmTags`; no history. + +**Tauri command.** `extract_content_tags_cmd(transcript: String) -> Result<ContentTags, String>` in `src-tauri/src/commands/llm.rs` (co-located with existing LLM commands, or a new file if absent). + +**Frontend UX.** +- "Tag" button per history row, in the row's action cluster (next to "Export .md"). Icon: `Tag` from `lucide-svelte`. +- Click → spinner → on resolve: `llmTags = [`topic:${topic}`, `intent:${intent}`]`, `saveHistory()`. +- Chips render in the tag area alongside manual tags but with a distinct visual treatment: `border-dashed`, italicised, subtly lighter ink. Click-through to promote to manual (`manualTags`), with animation-free chip move. +- Batch affordance: on the History toolbar, "Tag all untagged" button (only shows if ≥ 1 untagged row). Iterates and calls the same command. Progress toast: "Tagged N / M…" updating every item. + +### Item 4 — Settings restructure + +**Pattern.** Single page (`SettingsPage.svelte`), flat scroll, no sidebar or tabs. Top block always expanded. Below it, six `<details>` groups each with a clear `<summary>` label. + +**Architecture.** +- New file `src/lib/components/SettingsGroup.svelte` — reusable `<details>` wrapper with styled chevron, summary padding, animated open/close (`@starting-style` + `interpolate-size: allow-keywords` for modern browsers; fall back to no animation). +- Search box at the page top (new). Filters the visible controls by label text; empty filter shows everything. Non-matching groups collapse; matching groups open. +- Settings content itself is not rewritten — only re-ordered + re-grouped. Each control keeps its current markup and behaviour. + +**Group membership.** + +| Group | Expanded by default? | Contents | +|---|---|---| +| **Start here** | Yes | Model download + status, microphone picker, global hotkey, theme (light/dark/system) | +| **Transcription** | No | Whisper / Parakeet backend, language, punctuation, vocabulary profile, file-upload defaults | +| **Tasks** | No | Match-my-energy default, WIP limit, **Show momentum sparkline** *(Phase 8, relocated)*, MicroSteps generation preset | +| **Rituals** | No | Morning triage on/off + time, Evening shutdown on/off | +| **Notifications** | No | Notifications enabled/muted, per-trigger toggles (inactivity, pending triage, micro-step idle), TTS nudge voice + rate | +| **Accessibility** | No | Font size, line height, bionic reading, reduced motion, high contrast | +| **Advanced** | No | Database path / open-data-dir button, export app data, reset settings, model tier override, debug logging | + +**Phase 8 toggle relocation.** The `showMomentumSparkline` toggle moves from its current Rituals placement into the new **Tasks** group. Discovered in Phase 8 code review (carryover backlog). + +**Open/close state.** Not persisted — groups reset to default on each app launch. Persisting open-state adds storage noise for marginal value; users who live in Settings can bookmark their group with a search query instead. + +### Item 5 — Visual polish (bounded checklist) + +Scoped list. Not an open-ended pass. + +- **Motion on Phase 8 badge + sparkline.** Badge enters via a 180 ms opacity + 2 px translate-y on `todayCount` increment. Sparkline bars ease in with a 30 ms stagger on mount only (not per refresh). `prefers-reduced-motion` disables both. +- **Typography scale audit.** One read-through of every page's `<h1>/<h2>/<h3>`; normalise to the three-step scale already used on `TasksPage`. No new fonts. +- **Dark-mode parity check.** Toggle every page in dark mode once. Fix contrast regressions against WCAG AA minimum (see §Accessibility) and fix any baked-in `text-black` / `text-white` strings to `text-text` / `text-text-inverse`. +- **Spacing pass on SettingsPage only.** Consistent `py-3` rows inside groups, `gap-4` between label + control, `pt-6` on group open. Other pages already converged in Phase 2. +- **Lucide icon audit.** Any custom SVG chip or inline path that could swap to a Lucide icon — swap for visual consistency. List before changing (expect ≤ 5 swaps). + +Deliberately **out of scope**: redesigning layouts, introducing new colours, changing the typographic scale, animating page transitions. + +### Item 6 — Accessibility (bounded checklist) + +- **Sparkline aria-label rewrite.** Replace numeric list (`"0, 1, 3, 2, 0, 4, 3"`) with friendlier summary: `"3 completed today. 14 total over the last 7 days."` Expose to any SR on focus of the sparkline SVG (add `tabindex="0"`, keyboard-focusable). +- **Sparkline per-day tooltip.** On hover / keyboard-focus of each bar, show `<title>` with absolute date + count. Purely additive; doesn't change the existing aria-label structure. +- **Keyboard traversal of every Phase 1-8 page.** Tab order starts top-left, ends bottom-right. No hidden focus sinks. Checklist per page. +- **Focus-visible rings.** Every interactive element has a visible focus ring in both themes. The existing Tailwind `focus-visible:` ring utility is present but inconsistently applied — sweep. +- **Screen reader labels on icon-only buttons.** Every `<button>` whose content is a Lucide icon gets an `aria-label`. Run a `grep -n 'aria-label' src/lib/pages src/lib/components` audit; flag missing ones. +- **Contrast audit against WCAG AA.** Use the Chromium DevTools contrast panel on every page-level text colour in both themes. Target ratios: 4.5:1 body, 3:1 large headings / UI. Fix variables in the Tailwind theme, not per-site overrides. +- **`prefers-reduced-motion` respected on every animation** added in Phase 5-9. Timers, sparkline, badge, settings accordion all guard the motion block. + +## Testing + +### Rust (`cargo test` in the touched crates) +- `write_text_file_cmd` — round-trip a small UTF-8 string; assert file contents match and that nonexistent parent dir errors with a readable message. +- `extract_content_tags` — integration test in `crates/llm/tests/` against a fixture transcript. Uses the real engine with a tiny tier-0 model. Assert topic matches a regex, intent is in the closed set, JSON parse succeeds. +- Grammar unit test — feed a few malformed completions through the grammar parser and assert rejection. + +### Frontend (`npm run check`) +- `suggestedFilename` tests (new `src/lib/utils/saveMarkdown.test.ts` if a vitest config appears; otherwise covered in smoke dogfood). +- `svelte-check` must be zero-zero across 3955+ files. + +### Manual dogfood (folds into Phase 10a QC) +- Export one transcript via save dialog. File written to chosen path. Cancel dialog → no toast, no write. +- Select 3 history rows, export to a folder. Three files land with `suggestedFilename` names. Collision: repeat the export to the same folder; confirm ` (2)` / ` (3)` suffixes appear. +- Tag one history row. Chip appears with dashed border. Click to promote; chip moves to manual and the dashed border disappears. +- "Tag all untagged" processes remaining rows; toast updates progress; no duplicates. +- Settings page: top group expanded; other groups collapsed. Search "sparkline" — filters to the Tasks group, opens it. Clear search — returns to default state. +- Keyboard-only traversal of Dictation → Tasks → History → Settings pages. Every control reachable. Focus rings visible in both themes. +- `prefers-reduced-motion` on — badge / sparkline / details animations all stop. + +### Automated a11y gate (new) +- Add a one-shot axe-core run to the dev cycle via `@axe-core/cli` invoked on `npm run build`'s preview URL. Document in HANDOVER but don't block merge on it (axe flags non-determinism that needs human triage); the CI gate stays `npm run check` + `cargo test`. + +## Invariants + +- `write_text_file_cmd` is only called with a path that came from a save / open dialog. Never hard-coded, never concatenated from user text input elsewhere. (Path-traversal risk is mitigated at the UI layer.) +- LLM tags are additive to `manualTags`, never replace them. Promoted LLM tags leave `llmTags` untouched (no moving-between-arrays mutation). +- Settings groups reset to their default expansion on each launch. The search box is the only persistence surface, and even it is not persisted. +- No new user-facing string anywhere violates §Conventions: British English, no em / en dashes. +- Motion in all Phase 9 additions respects `prefers-reduced-motion`. + +## Acceptance (from roadmap) + +All of: + +1. Export one transcript from HistoryPage → `save()` dialog opens → file is written to the chosen path. +2. Select 3 rows → Export selected → directory of 3 `.md` files lands in the chosen folder. +3. Click "Tag" on one row → `topic:*` + `intent:*` chips appear within a few seconds. +4. Settings page — top "Start here" group expanded; every other group collapsed; search filters + opens matching groups. +5. Phase 8 sparkline toggle appears in Tasks group, not Rituals. +6. Every interactive element in Dictation / Tasks / History / Settings is reachable by keyboard with a visible focus ring in both themes. +7. Sparkline SR label reads: "3 completed today. 14 total over the last 7 days." (or the current day's equivalent numbers). +8. `prefers-reduced-motion` disables badge entrance + sparkline stagger + settings accordion animation. + +## Out of scope + +- Atomic file writes (rename-after-write) for the save dialog — a mid-write crash on a transcript export is not data-loss territory; the source stays intact in the History store. +- Server-side or cloud tag storage. Tags stay local. +- Re-training LLM on user corrections to tags. Tags are one-shot outputs. +- Search-across-transcripts UI. Settings search is the only search surface added in Phase 9. +- Moving SettingsPage to multiple files / router sub-routes. Stays as one scroll-view with groups. +- Per-group open-state persistence (covered under "Open/close state" above). + +## File map + +### Created +- `src-tauri/src/commands/fs.rs` *(or addition to existing commands file)* — `write_text_file_cmd`. +- `src/lib/utils/saveMarkdown.ts` — `suggestedFilename`, `saveTranscriptAsMarkdown`, `exportTranscriptsToDir`. +- `src/lib/components/SettingsGroup.svelte` — `<details>` wrapper with chevron + animation. +- `crates/llm/tests/content_tags_smoke.rs` — integration test for `extract_content_tags`. +- `docs/superpowers/plans/2026-04-24-phase9-polish-debt.md` — implementation plan (companion to this spec). + +### Modified +- `src-tauri/src/lib.rs` — register `write_text_file_cmd` + `extract_content_tags_cmd`. +- `crates/llm/src/prompts.rs` — add `ContentTags`, `INTENT_CLOSED_SET`, `extract_content_tags`. +- `crates/llm/src/grammars.rs` — add content-tag GBNF grammar. +- `crates/llm/src/lib.rs` — re-export the new symbols. +- `src-tauri/src/commands/*.rs` — add `extract_content_tags_cmd` (file choice depends on the existing LLM command placement). +- `src/lib/pages/HistoryPage.svelte` — save dialog, bulk select, bulk export, LLM tag button, llmTags chip rendering. +- `src/lib/pages/SettingsPage.svelte` — full regrouping into the 7 groups (Start here + 6 collapsed). Sparkline toggle relocation. +- `src/lib/types/app.ts` — `llmTags` field on history entry type; optional `ContentTags` type. +- `src/lib/stores/page.svelte.ts` — hydrate / persist `llmTags` alongside `manualTags`. +- `src/lib/utils/frontmatter.ts` — include `llmTags` in `buildFrontmatter`'s `tags` union. +- `src/lib/components/CompletionSparkline.svelte` — friendlier aria-label, per-bar `<title>` tooltips, `tabindex="0"` for SR focus. +- `src/lib/pages/TasksPage.svelte` — badge motion on increment (behind `prefers-reduced-motion`). +- Tailwind theme if contrast audit forces colour variable changes. + +### Deleted +None. + +## Effort estimate + +1 to 2 days of focused work. Items 1 + 2 ≈ half day. Item 3 ≈ half day (includes the grammar + smoke test). Item 4 ≈ half day (the regrouping + search). Items 5 + 6 ≈ half day combined (checklists, not discoveries). + +Natural split for the plan: 9a (items 1 + 2), 9b (item 3), 9c (item 4), 9d (items 5 + 6). + +## Anchors + +- Roadmap: [docs/roadmap/2026-04-23-corbie-feature-complete-roadmap.md](../../roadmap/2026-04-23-corbie-feature-complete-roadmap.md) +- Phase 8 plan + spec + handover — for task-format reference and carryover backlog. +- Phase 8 gotchas to respect in this phase: + - `$derived` does not export at `.svelte.ts` module scope — use `export function` instead. + - `#[derive(sqlx::FromRow)]` is not available in `kon-storage` (no change in Phase 9, but noted if schema work drifts there). +- Progressive-disclosure pattern reference: NN/g on progressive disclosure; Material Design settings patterns; UX Collective on settings redesign.