Voice-to-text edit mode (Variant C) + adopt shared @aymurai/ui

.claude/CLAUDE.md

@@ -0,0 +1,38 @@
+# Project-local Claude instructions
+
+This repo's renderer (`src/renderer/`) uses:
+
+- **Panda CSS** for styling. See `.claude/rules/panda-css.md`.
+- **Radix UI** primitives wrapped under `src/renderer/src/components/ui/`.
+  See `.claude/rules/radix-ui.md`.
+- **TanStack Router** for file-based routing in `src/renderer/src/routes/`.
+- **TanStack React Query** for backend data; query/mutation factories live in
+  `src/renderer/src/services/aymurai/queries.ts`.
+- **i18next** for Spanish UI strings under
+  `src/renderer/src/constants/i18n/locales/es/`.
+
+When adding code to the renderer, the rules above apply. When uncertain about a
+library API, prefer `mcp__plugin_context7_context7__query-docs` over guessing
+from training data.
+
+## Tooling
+
+- Package manager: **pnpm** (`pnpm-lock.yaml` is authoritative). `npm install`
+  is unsupported in this repo.
+- `pnpm prepare` runs `panda codegen && lefthook install`. Run after a fresh
+  clone or after pulling changes that touch `panda.config.ts`.
+- Pre-commit gate (lefthook): biome (autoformat + lint), panda codegen,
+  forbidden-pattern grep (`console.log`, `debugger`, leftover merge markers,
+  `.only(`, `@stitches/react`).
+- Pre-push gate: `pnpm typecheck` and `pnpm knip`.
+
+## Migration in progress
+
+Stitches CSS-in-JS is being replaced by Panda CSS. Files under `components/ui/`,
+`components/voice-to-text/`, `components/finish/`, `components/anonymizer/`,
+`components/home/`, and `components/layout/` are already on Panda. Older
+components (under `components/{checkbox,radio,file-*,validation-form,...}` and
+`components/{label,title,text,subtitle,spinner,uncontrolled-input}`) still
+import from `@/styles/stitches.config`. Migrate any of these you touch; the
+biome rule banning `@stitches/react` is **not yet enabled** because of this
+backlog.

.claude/rules/panda-css.md

@@ -0,0 +1,95 @@
+# Panda CSS Rules (this repo)
+
+The renderer uses [Panda CSS](https://panda-css.com) for all styling. The legacy
+Stitches setup (`@stitches/react`, `@/styles/stitches.config`) is being phased
+out — do not introduce new stitches usage; migrate any file you touch.
+
+## Setup
+
+- Config: `panda.config.ts` at repo root.
+- Generated output: `src/renderer/src/styled/` (gitignored). Regenerated by
+  `pnpm prepare` (which runs `panda codegen`) and on pre-commit by lefthook
+  whenever `panda.config.ts` or any source file changes.
+- PostCSS plugin wires the runtime: `postcss.config.cjs`.
+- `strictTokens: true` is enabled — arbitrary values must use the `[bracket]`
+  escape syntax (e.g. `width: "[36px]"`, `bg: "[#9F99A5]"`).
+
+## Authoring
+
+Pick the lightest tool that fits:
+
+1. **`css({ ... })`** — one-off styles attached via `className={...}`.
+2. **`cva({ base, variants })`** — components with prop-driven variants
+   (button-like, with active/disabled/size states).
+3. **`sva({ slots, base, variants })`** — slot recipes (e.g. dialog with
+   overlay/content/header slots).
+
+Prefer layout primitives from `@/styled/jsx` over raw divs:
+
+- `<Stack>` (vertical), `<HStack>` (horizontal), `<Grid>`, `<Box>`, `<Divider>`
+- `<styled.h1 textStyle="title.md.strong">` for typography that already has a
+  named text style — use them instead of repeating `fontSize`/`lineHeight`.
+
+## Tokens
+
+Defined in `panda.config.ts theme.semanticTokens`:
+
+- `colors.brand.{primary,secondary,tertiary}`
+- `colors.text.{default,lighter,onbutton-default,onbutton-alternative,onbutton-disabled}`
+- `colors.action.{default,disabled,alt-default,hover,pressed,focus}`
+- `colors.bg.{primary,secondary,primary-alternative,primary-highlight,secondary-highlight}`
+- `colors.system.{success,success-secondary,error,error-secondary,warning,warning-secondary,info,info-secondary}`
+- `borders.{primary,secondary,primary-alt,error}`
+- `gradients.primary`
+
+Text styles: `title.md.{strong,default}`, `subtitle.{md,sm}.{strong,default}`,
+`paragraph.{md,sm,xsm}.{strong,default}`, `cta.{md,sm}.{strong,default}`,
+`label.{md,sm}.{strong,default}`.
+
+Reference tokens by dotted path: `color: "text.default"`, never raw hex unless
+bracketed (`color: "[#FFE066]"`).
+
+## Conditions
+
+Use Panda's `_hover` / `_focus` / `_disabled` style props in recipes, **or** the
+nested `&:hover` / `&:focus-visible` / `&:disabled` selector form inside `css()`
+— both are valid. Pick one style per component for consistency.
+
+```ts
+const button = cva({
+  base: { ... },
+  variants: { variant: { primary: { bg: "action.default", _hover: { bg: "action.hover" } } } },
+});
+```
+
+## Workflow
+
+- After changes to `panda.config.ts`, run `pnpm panda codegen` (lefthook does
+  this on commit, but the IDE needs the regenerated types to type-check).
+- New tokens: add to `theme.semanticTokens` instead of inlining bracketed
+  values across many files.
+- Animations: add `keyframes` + `tokens.animations` to `panda.config.ts` rather
+  than inline `<style>{@keyframes …}</style>` (only acceptable as a temporary
+  bridge — flag with TODO).
+
+## Don'ts
+
+- Don't import from `@stitches/react` in new code.
+- Don't inline raw hex without `[bracket]` — strictTokens will reject it.
+- Don't bypass `strictTokens: true` by editing the config; if a value is needed
+  often, add a token.
+- Don't write Tailwind-style `className="hover:bg-blue"`. Panda does not parse
+  utility class strings.
+
+## Quick reference for migration from Stitches
+
+| Stitches | Panda |
+|---|---|
+| `styled("div", { color: "$primary" })` | inline `<div className={css({ color: "text.default" })}>` |
+| `styled("button", { variants: { ... } })` | `const button = cva({ base, variants })` then `<button className={button({ ... })}>` |
+| `keyframes({ ... })` | `theme.extend.keyframes` in `panda.config.ts` + `animationName: "myAnim"` token |
+| `$primary`, `$primaryAlt`, `$bgSecondary` etc. | semantic tokens in `panda.config.ts` |
+| `css={{ ... }}` JSX prop | `className={css({ ... })}` |
+
+When uncertain about a recent Panda CSS API, look it up via
+`mcp__plugin_context7_context7__query-docs` rather than guessing.

.claude/rules/radix-ui.md

@@ -0,0 +1,85 @@
+# Radix UI Rules (this repo)
+
+The renderer uses [Radix UI primitives](https://www.radix-ui.com/primitives)
+for accessible UI building blocks (dialog, popover, select, switch, tooltip).
+Visuals are layered on top with Panda CSS recipes.
+
+## Where primitives live
+
+All wrapped primitives are exported from `src/renderer/src/components/ui/`:
+
+- `ui/dialog.tsx` — wraps `@radix-ui/react-dialog`
+- `ui/popover.tsx` — wraps `@radix-ui/react-popover`
+- `ui/select.tsx` — wraps `@radix-ui/react-select`
+- `ui/switch.tsx` — wraps `@radix-ui/react-switch`
+- `ui/tooltip.tsx` — wraps `@radix-ui/react-tooltip`
+- Plus visual primitives without a Radix dependency: `button`, `card`, `input`,
+  `back-button`, `callout`, `suggestion`, `toast`.
+
+Feature code imports from `@/components/ui/*`, **never** directly from
+`@radix-ui/react-*`. If a primitive isn't wrapped yet, add it to `ui/` first.
+
+## Composition pattern (shadcn-style)
+
+Each primitive exports the parts the consumer needs:
+
+```tsx
+import {
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent>
+    <DialogTitle>...</DialogTitle>
+    ...
+  </DialogContent>
+</Dialog>
+```
+
+- Open/close state lives in the consumer (`open` + `onOpenChange`).
+- Content goes inside the matching `*Content`.
+- Don't re-export every Radix part — only what the codebase actually uses.
+
+## Styling
+
+- Each `ui/` file owns its visuals via Panda's `css()` / `cva()` / `sva()`.
+- Apply styles via `className={cx(internalStyles, className)}` so callers can
+  pass extra utility classes when needed.
+- Animations use the `animations` panda tokens (`fadeIn`, `fadeOut`); keyframes
+  live in `panda.config.ts theme.extend.keyframes`.
+
+## Accessibility
+
+- Trust Radix to manage focus traps, `aria-*` attributes, escape/click-outside
+  behavior. Don't replicate it manually.
+- Always pair form primitives with a `<label>` (or `aria-label`).
+- Forward `ref` through your wrapper so consumers can use `useRef`.
+- Do not add `autoFocus` props to dialog inputs — Radix focuses the first
+  focusable element on open. If a different element should be focused, use
+  `onOpenAutoFocus` to redirect.
+
+## Adding a new primitive wrapper
+
+1. Install the radix package as a devDep (e.g. `pnpm add -D @radix-ui/react-X`).
+2. Create `src/renderer/src/components/ui/<name>.tsx` and re-export the parts
+   the codebase will use, wrapped in a Panda recipe.
+3. Use `forwardRef` if the primitive accepts a ref.
+4. Co-locate styles in the same file. If the recipe grows past ~100 lines,
+   split into a `ui/<name>.styles.ts`.
+
+## Don'ts
+
+- Don't import `@radix-ui/*` directly from feature code.
+- Don't reimplement focus management, escape handling, or click-outside logic.
+- Don't add `autoFocus` to dialog inputs.
+- Don't keep state inside `ui/` primitives that should be in the consumer
+  (open/value/checked etc.).
+
+## Quick check before reaching for Radix
+
+If the UI is purely visual (a card, a button, a callout), skip Radix and use a
+Panda recipe directly. Radix is for primitives that need keyboard/focus/ARIA
+choreography.

.claude/skills/panda-css/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: panda-css
+description: Use when authoring or refactoring styles in the Electron renderer of this repo. Triggers on edits to .tsx files that import from @/styled/css or @/styled/jsx, when adding tokens to panda.config.ts, or when migrating Stitches code to Panda.
+---
+
+# Panda CSS
+
+This repo's styling stack is Panda CSS. Read the full reference at
+`.claude/rules/panda-css.md` — it lists tokens, text styles, escape syntax, and
+the Stitches → Panda migration table.
+
+Quick checklist when you're about to touch styling:
+
+1. **Pick the right tool**: `css()` for one-offs, `cva()` for variants, `sva()`
+   for slot recipes. Layout uses `<Stack>` / `<HStack>` / `<Grid>` from
+   `@/styled/jsx`.
+2. **strictTokens is on**. Raw values need `[bracket]` escape (e.g.
+   `width: "[36px]"`).
+3. **Use semantic tokens** for colors (`text.default`, `bg.secondary`,
+   `brand.primary`) — never raw hex unless bracketed.
+4. **Run `pnpm panda codegen`** after editing `panda.config.ts` (lefthook
+   handles this on commit, but the IDE needs it to type-check).
+5. **Don't import from `@stitches/react`**. Migrate any Stitches code you touch.
+
+For unfamiliar APIs, query the latest docs:
+`mcp__plugin_context7_context7__query-docs` with library `panda-css`.

.claude/skills/radix-ui/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: radix-ui
+description: Use when adding or modifying Radix UI primitives in this repo's renderer (dialog, popover, select, switch, tooltip) or wiring accessible interactive components. Triggers on edits under src/renderer/src/components/ui/ or imports from @radix-ui/*.
+---
+
+# Radix UI
+
+This repo wraps Radix primitives in `src/renderer/src/components/ui/`. The full
+guidelines are in `.claude/rules/radix-ui.md` — read it before adding a new
+primitive or refactoring an existing one.
+
+Quick checklist:
+
+1. **Import from `@/components/ui/*`** in feature code, never directly from
+   `@radix-ui/react-*`. Wrap missing primitives under `ui/` first.
+2. **State stays with the consumer** (`open` + `onOpenChange`). The primitive
+   is presentational.
+3. **Don't add `autoFocus` to dialog inputs** — Radix manages focus on open;
+   use `onOpenAutoFocus` to redirect if a specific element must be focused.
+4. **Style with Panda** (`css()`, `cva()`, `sva()`) — see
+   `.claude/rules/panda-css.md`. Animations come from panda's `animations`
+   tokens.
+5. **Forward refs** through the wrapper so `useRef` works in callers.
+6. **Trust Radix's a11y**: focus traps, ARIA, escape/outside-click. Don't
+   replicate.
+
+For unfamiliar APIs, query the latest docs:
+`mcp__plugin_context7_context7__query-docs` with library `radix-ui`.

.env.example

@@ -0,0 +1,4 @@
+VITE_USE_MOCK_STT=false
+VITE_STT_MOCK_DELAY_MS=4000
+# Transcription cache on the ASR backend. Defaults to true in prod builds, false in dev.
+VITE_ASR_USE_CACHE=false

.gitignore

@@ -1,5 +1,8 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
+# git worktrees
+.worktrees/
+
 # dependencies
 /node_modules
 node_modules/*

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
+  "uiMergePreview.devCommand": "pnpm run dev:web",
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
     "source.fixAll": "explicit",

README.md

@@ -8,7 +8,7 @@
 tools
 - ⚡ **Electron** as the _deployment and packaging tool_. It also serves the
 purpose of communicating the webapp with the _NodeJS_ process.
-- 🪡 **Stitches** as the _styling library_
+- 🐼 **Panda CSS** as the _styling library_ (migrating off legacy Stitches)
 - 🛣️ **Tanstack React Router** as the _routing library_ to navigate across the webapp
 - 📄 **Mammoth** + **ExcelJS** as the _libraries_ to read and write `.docx` and
 datasheet files
@@ -17,6 +17,7 @@ datasheet files
 
 - **pnpm** as _package manager_
 - **biome** as code _linter and formatter_
+- **lefthook** for git hooks (pre-commit + pre-push gates)
 
 ##  Getting started
 
@@ -28,6 +29,14 @@ datasheet files
     pnpm install
     ```
 
+1. Run `prepare` to generate the Panda CSS runtime and install the lefthook
+   git hooks (also runs automatically after `pnpm install`, but re-run it
+   after pulling changes that touch `panda.config.ts` or `lefthook.yml`):
+
+    ```bash
+    pnpm prepare
+    ```
+
 1. Start the app in development mode with
 
    ```bash
@@ -72,6 +81,8 @@ datasheet files
 - `typecheck:node`: runs type checking on the _Electron_ application
 - `typecheck:web`: runs type checking on the _React_ application
 - `validate`: runs linting and type checking on both React and renderer
+- `prepare`: runs `panda codegen` and installs lefthook git hooks (auto-runs after `pnpm install`)
+- `knip`: detects unused exports and dependencies (also gated on `pre-push`)
 - `pre-commit`: runs _LintStaged_
 
 ### Deployment

biome.json

@@ -48,6 +48,9 @@
           "level": "error"
         }
       },
+      "suspicious": {
+        "noConsoleLog": "warn"
+      },
       "a11y": {
         "noSvgWithoutTitle": "off",
         "useKeyWithClickEvents": "off"