feat(snippets): Snippets & Command History in the terminal context menu

[rockyway]

Implements docs/plan/029-snippets-and-command-history-menu.md (private, in termflow-fabric). Requirement was written as "Quick Inserts"; the shipped name is Snippets — iTerm2 names this exact feature that, and TermFlow already has a shortcuts category for keyboard bindings.

Right-click a terminal → Command History ▸ and Snippets ▸, each a flyout with a search box. Ctrl+Shift+S opens the Snippets list on its own, at the cursor. Snippets are user-managed (folders, tags, full CRUD in Settings, versioned import/export) and survive restart.

What to look at first

Insertion reuses the existing primitive. pasteToTerminal routes through the mounted xterm, so bracketed-paste markers are applied when the foreground app set DECSET 2004, and CRLF→CR is normalized. That one call is why multi-line text lands as a literal block in Claude Code/Gemini instead of executing line-by-line, why it works inside a TUI as well as at a bare prompt, and why nothing ever appends Enter. InputHandler.handlePasteText's body was extracted into insertTextIntoTerminal so clipboard paste, snippets and history all share one entry point and no future caller can skip the raw-write fallback.

The flyout renders inside the menu container, not portalled. ContextMenu closes on any mousedown where !menuRef.contains(target), so a portalled panel reads as "outside" and the first click on any row would close the menu before the click landed. Verified by mutation: wrapping the panel in createPortal turns three tests red.

Import/export is two narrow Tauri commands, not one general file-write. A general write_text_file would become an arbitrary-write primitive the moment someone wired it into a route, and the embedded Axum API and MCP sidecar must not gain that. A Rust test asserts neither command appears in api_server.rs, so the comment claiming it can't rot into a lie. Needed a new dialog:allow-save capability — the app had only dialog:allow-open and no fs plugin.

History does not use engine.insertCommand(). That erases the whole typed input line first, which is correct for the Shift+Enter popup completing what you're typing and destructive from a right-click. The popup itself is untouched; a test asserts insertCommand is unreachable from either flyout.

Round 2 — external review (agy)

Five defects, seven weak oracles, one unsupported comment. All fixed at the class level, all mutation-checked.

The headline one was a data-loss bug this document's own spec had talked itself into. The persist path snapshotted with state.snippets.map(s => ({ ...s })). A shallow spread copies tags by reference, leaving a revoked Immer proxy inside an otherwise-plain object — so one snippet carrying tags (an empty array is enough) makes the whole array unstringifiable, and the symptom is losing the entire library on restart. Five green tests missed it because the fixture omitted the one field that triggers it. Now one persistSnippets helper using current().

One test was actively holding the bug in place. The source-derived wiring test pinned the literal buggy expression, so fixing the code would have turned it red. It now pins the invariant — exactly one write site, reached through the helper, with a deep unwrap — instead of today's spelling of it.

Also fixed: edit could not clear a label/folder/tags; NaN/Infinity timestamps broke sort transitivity; the depth-1 flyout was clipped invisible by its own scroll container; and a flipped parent's child cascaded back over the root menu.

Round 3 — Tam's GUI pass

Seven changes, all from driving the real app.

Reported	Fix
Add-snippet dialog closes on an outside click	Overlay handler removed. ConfirmDialog dismisses that way and should — it holds a question; this holds a form, and a click landing beside the panel while reaching for the Folder field threw away everything typed. Escape / Cancel / ✕ remain.
Insert works but the terminal loses focus	Every terminal menu now refocuses on close, via one shared refocusTerminal. A property of the menu, not of the snippet row that exposed it — all four menus plus the dialog route through it.
No shortcut	Ctrl+Shift+S, at the cursor. Ctrl+Shift because bare Ctrl+S is XOFF and would freeze the terminal.
Submenu should open on hover	Hover opens; a click on the parent now only ever opens, never toggles — hover has already opened the panel by the time a click lands, so toggling would make clicking what you're pointing at the gesture that hides it. ~260ms grace close covers the diagonal into the panel.
Want a flat/folders view toggle, flat by default	Toggle beside the search box. Persisted as its own nine-link setting — the flyout is rebuilt on every open, so component state would have reset it silently each time.
Folder and tag are cut off	Panel widened to 380–640px, and the chip carries its own tooltip (Folder: … / Tags: …, one per line). The row's title is the snippet text, so a single row-wide tooltip could not serve both.
Narrow the folder-mode menu, keep the submenu wide	Root panel 200–300px in folder mode; the folder panel it opens keeps full width. narrow is depth-0 only and stripped on the way down, like headerToggle.
Shortcut shouldn't show the parent row	standaloneSubmenu draws the flyout alone. Escape/Tab then dismiss the whole thing — retiring just the panel would leave an invisible box still eating the next outside click.

One bug five green tests could not see. Stripping the standalone menu's chrome unset every paint property and left min-width: 200px behind; the empty host stretched to it, so the shortcut's panel rendered 200px right of the cursor. jsdom computes no layout. Pinned now by reading the CSS, the way the nested-panel clipping already is.

Settings category registration

Adding a category touches these sites in SettingsPage.tsx — listed by name rather than as a count, since a count goes stale the moment the class widens:

SettingsCategory union · CATEGORY_LABELS · isTracked() · the categories array · the duplicate union inside the deep-link isCategory() guard · the renderActiveCategory() switch · the requestCategoryChange dirty-guard hook-up.

settingsCategories.test.ts asserts the derivable sets are equal, so a stray extra entry fails as well as a missing one. The deep-link union is a second hand-maintained copy and is the one that drifts.

isTracked() is an exclusion list, so a new category is dirty-tracked by default. Snippets persists per mutation and has no Save button, so it's excluded — left alone, snapshotCategory() falls off the end of an exhaustive switch and returns undefined at runtime while type-checking clean.

Merged with develop

feature/terminal-automations (plan/028) landed first and added an automations category to the same sites. Resolved as predicted — three hunks, all "both branches added a member to the same list", nothing behavioural. Full suite green after the merge.

Verification

Suite	Result
bun jest (renderer)	3530 passed, 206 suites
bun run test:workspace (terminal-core)	777 passed, 48 suites
cargo test	754 passed
bun run typecheck	clean

GUI-signed-off by Tam — the gap called out as a merge blocker in round 2 is closed.

Mutation-checked rather than assumed, across all three rounds: the flyout's non-portal rendering, Escape's stopPropagation, the SnippetDialog re-seed effect, the snippets useSelector binding, the persistSnippets deep snapshot, and all twelve round-3 guards. Two of those twelve survived the first mutation pass and were rewritten — a builder-level assert that never reached the DOM, and a lazy [\s\S]*? source regex that matched a different focus() call in the same file.

Unrelated drive-by: sessionExitPersistence asserted a JSON blob does not contain '137' against a blob carrying a live Date.now(), which fails at random. Oracle narrowed to exclude the timestamp.

[rockyway]

Round-1 review response — all 5 D findings fixed (c3733a9)

Thanks — this round earned its keep. Summary of what changed and, where it matters, what I measured rather than assumed.

D-01 (blocker) — confirmed, and broader than reported

I probed it rather than reasoning about it. My first probe was too weak: it used addSnippet, whose action payload Immer never drafts, so nothing could have been revoked. Probing reducers that read pre-existing state:

Snippet shape	Persisted snapshot
has tags	unstringifiable
has tags: [] (empty)	unstringifiable
no tags key	fine
one tagged + one untagged	whole list unstringifiable

So the user-visible symptom isn't "tagged snippets don't save" — a single tagged snippet loses the entire library on restart, because the array is one payload. addSnippet and setSnippets were genuinely never broken.

Fixed at the class: the five call sites are now one persistSnippets helper using current(). Swept the rest of the slice for the same shape — agentColorSchemes and customKeybindings are Record<string,string> so their shallow spreads are safe, and shellProfiles persists from selector state which is already finalised. snippets was the only member.

D-04, D-05, A-01

Draft now sends explicit undefined and updateSnippet treats that as "clear", restricted to the optional keys so a stray undefined can't corrupt id/text/createdAt. Number.isFinite at both timestamp sites. Rename guard no longer blocks unfiling.

D-02 / D-03

Nested panel is now a sibling of .context-menu-flyout-list inside the parent panel — outside the clip, still inside menuRef by construction rather than by coordinate math, and the list stays scrollable. Flip direction cascades via a threaded parentFlippedLeft, still && fitsLeft so the left edge stops it.

On the B findings — you were right about the mechanism, not just the instances

B-07 is the one worth calling out. The wiring test pinned the literal state.snippets.map((s) => ({ ...s })), so it pinned the bug in place — correcting the code would have turned that test red. It now pins the invariant (one write site, a deep snapshot, and the old expression explicitly forbidden) rather than today's spelling.

B-03 explains why five green tests missed a data-loss bug: the fixture had no tags key, so the suite was blind to the only field that triggers it. Fixtures now carry tags, and the oracle is "does this still serialise after the reducer returns" — which is what invoke actually does — instead of "is it an array". Reverting the fix now turns 7 tests red.

The other oracles now assert actual expected values rather than ok === false / not.toContain.

Still open

bun jest 3164 passed · 9 Rust · typecheck clean. The GUI pass remains outstanding and I agree it is a blocker, not a follow-up — D-02 and D-03 were invisible to 31 passing tests precisely because jsdom implements no layout, so they're pinned structurally and against a rect simulator only. Nothing here has run in WebView2 yet.

🤖 Generated with Claude Code