refactor: modularize completion system — extract from shell to dispatcher with CompletionController interface

[curtisman]

Summary

Extracts the completion infrastructure from the shell (Electron) package into a modular dispatcher/helpers/completion/ directory, introducing a clean CompletionController interface that both the shell and CLI consume as host adapters. The completion session state machine, trie index, and search menu logic are now fully DOM-free and independently unit-testable.

Motivation

Previously, PartialCompletionSession, the prefix trie (TST), and SearchMenuBase all lived inside the shell renderer — tightly coupled to Electron/DOM and impossible to test without a browser environment. The CLI duplicated completion filtering logic instead of reusing the session. This refactor:

• Makes completion logic reusable across shell and CLI via a single CompletionController interface
• Enables comprehensive unit testing with Jest (no DOM needed)
• Eliminates ~120 lines of duplicated completion logic in the CLI
• Establishes clean separation of concerns: state machine (dispatcher) vs rendering (shell/CLI)

Architecture

User keystroke → CompletionController.update()
                     ↓
              PartialCompletionSession (state machine: IDLE → PENDING → ACTIVE)
                     ↓
              ICompletionDispatcher.getCommandCompletion()
                     ↓
              Grammar result → SearchMenuIndex (TST trie) → CompletionState
                     ↓
              onUpdate callback → Host renders (shell SearchMenu / CLI ghost-text)

New module structure (dispatcher/src/helpers/completion/)

File	Responsibility
index.ts	Barrel re-exports for external consumers
controller.ts	CompletionController interface (7 methods) + createCompletionController factory
session.ts	PartialCompletionSession — core IDLE→PENDING→ACTIVE state machine
searchMenu.ts	SearchMenuItem, SearchMenuIndex interface, TSTSearchMenuIndex (TST-backed prefix index)
trie.ts	Ternary Search Tree (TST) data structure, normalizeMatchText()

Key abstractions

• CompletionController — consumer-facing interface: update(), accept(), dismiss(), hide(), getCompletionState(), setOnUpdate(), dispose()
• SearchMenuIndex — filterItems(), numItems(), setItems(), hasExactMatch() backed by TST
• CompletionState — { items, prefix, anchorIndex, generation } where generation is a monotonically-increasing counter for item-change detection
• NoMatchPolicy — internal tri-state (accept | refetch | slide) replacing scattered boolean checks
• ICompletionDispatcher — minimal interface the session needs from the dispatcher

Changes

Dispatcher (packages/dispatcher)

• Deleted src/helpers/completion.ts (old thin re-export shim)
• Added src/helpers/completion/ directory with 5 modules (see table above)
• PartialCompletionSession implements CompletionController directly (no wrapper class)
• Session uses generation counter so hosts can distinguish "items changed" from "prefix-only update"
• Type-ahead reconciliation: lastInput/lastDirection fields detect stale async results and re-fetch or re-filter as needed
• Package export path agent-dispatcher/helpers/completion preserved (target changed from dist/helpers/completion.js → dist/helpers/completion/index.js)

Shell (packages/shell)

• Deleted src/renderer/src/searchMenuBase.ts — replaced by dispatcher's SearchMenuIndex
• SearchMenu no longer extends a base class; now a flat class with explicit render(prefix, items) and updatePosition(prefix) methods
• Position computation injected via constructor (getPosition callback) instead of per-call arguments
• PartialCompletion creates a CompletionController via factory and uses setOnUpdate() for async render wiring
• Tracks lastGeneration and lastPrefix to decide render() vs updatePosition()
• templateEditor.ts imports from agent-dispatcher/helpers/completion instead of shell re-export layer
• Removed action-grammar dev dependency from shell

CLI (packages/cli)

• connect.ts imports createCompletionController from dispatcher and passes controller to enhanced console
• enhancedConsole.ts receives a CompletionController instead of managing its own completion state
• Replaced manual filtering logic (allCompletions, completionPrefix, inline filtering) with controller.getCompletionState() in render loop
• onUpdate callback triggers re-render on async completion arrival

Tests

Moved from shell → dispatcher (13 test files at dispatcher/test/partialCompletion/):

File	Coverage
controller.spec.ts	New — factory lifecycle, update/accept/dismiss/hide, setOnUpdate callback replacement
generation.spec.ts	New — CompletionState.generation counter semantics
searchMenuIndex.spec.ts	New — TST filtering, case insensitivity, diacritical normalization, setItems replacement
typeAhead.spec.ts	New — type-ahead reconciliation: fast typing, diverged input, direction changes during pending fetch
helpers.ts	New — shared utilities: makeSession, makeDispatcher, makeCompletionResult, flushPromises, loadedItems
direction.spec.ts	Updated to new API surface
errorHandling.spec.ts	Updated to new API surface
grammarE2E.spec.ts	Updated to new API surface
publicAPI.spec.ts	Updated to new API surface
resultProcessing.spec.ts	Updated to new API surface
separatorMode.spec.ts	Updated to new API surface
startIndexSeparatorContract.spec.ts	Updated to new API surface
stateTransitions.spec.ts	Updated to new API surface

Retained in shell (DOM-specific):

• renderDispatch.spec.ts — New — tests render() vs updatePosition() dispatch based on generation counter
• switchMode.spec.ts — SearchMenu.switchMode() inline↔expanded toggle

Docs

• Updated docs/architecture/completion.md with new module structure, CompletionController interface, and state machine description

Cleanup

• Removed needsSeparatorInAutoMode re-export wrapper (session imports directly)
• Removed unused shell re-export wrappers
• Jest config updated with moduleNameMapper for ../src/ → dist/ resolution