Cmd Bar State Machine Design#

1. Current State Analysis#

1.1 Recent Changes (Last Week)#

Four commits touched cmd bar code in the past week, each addressing regressions or behavioral inconsistencies:

oyvpktvp — fix(cmd): restore param mode for connector commands, route item selection through execute

• Problem: Param mode (edit command's autocomplete) was bypassing execute() and directly publishing editor:open, which broke chaining, output handling, and lazy extension loading.
• Fix: acceptParamSuggestion() now routes item-type params through execute(). Added comments clarifying that param mode should enter for any command with params, including connector commands.
• Regression risk: The routing change means execute() must handle selectedItem in context, which was not part of the original contract.

ourylmsr — fix(cmd): editor:open lazy-load interceptor + cmd palette blink on hotkey

• Problem: When cmd panel fires editor:open before the editor extension is loaded, the event is lost. Also, the cmd panel would briefly flash visible then hide when triggered by hotkey while app was not focused (because did-resign-active was hiding all alwaysOnTop windows, including focusable ones like the cmd panel).
• Fix: Added registerLazyEventInterceptors() in main.ts to catch editor:open/editor:add and load the editor extension first. Fixed did-resign-active to skip focusable alwaysOnTop windows.
• Note: This fix is in main.ts, not panel.js, but it papers over a sequencing issue that a state machine should address (executing a command before its target extension is loaded).

llsxksrz — fix(cmd): param mode Tab fills text, Enter executes with correct item identity

• Problem: Tab in param mode was executing the command (calling acceptParamSuggestion), and Enter was passing item identity by search text (which could match the wrong item).
• Fix: Split into fillParamSuggestion() (Tab, text-only) and acceptParamSuggestion() (Enter, executes). Enter now passes selectedItem directly through execute(). The edit command checks ctx.selectedItem first.
• New tests added for Tab-fills and Enter-executes semantics.

nlxwwmyv — fix(cmd): restore two-tone inline suggestion styling (bold typed, dim completion)

• Problem: After Tab-cycling through suggestions, the inline ghost text was using state.typed (which now contains the completed command name) for the highlight boundary, making everything bold.
• Fix: Introduced state.originalTyped tracking and used it in updateCommandUI() so the bold/dim split reflects what the user actually typed, not what Tab inserted.

1.2 Architecture Overview#

The cmd bar system spans three execution contexts:

1. Background process (background.js): Owns the command registry. Handles registration/unregistration from other extensions. Opens the panel window.
2. Panel window (panel.js + commands.js): The interactive UI. Maintains local command copies via pubsub proxy. Handles all user interaction.
3. Commands module (commands.js): Bridges background registry to panel. Creates proxy commands that execute via pubsub round-trip.

The panel is a keepLive window -- it is created once and reused by hiding/showing. On visibility change, all modes are reset.

1.3 Current State Fields (from panel.js)#

state = {
  // Command matching
  commands: {},           // Object map of command name -> command object
  matches: [],            // Commands matching current typed text
  matchIndex: 0,          // Selected match index
  matchCounts: {},        // Frecency counts (persisted)
  adaptiveFeedback: {},   // Adaptive matching data (persisted)
  typed: '',              // Current input text
  originalTyped: '',      // Text before Tab completion
  lastExecuted: '',       // Last executed command name

  // UI visibility
  showResults: false,     // Whether results dropdown is visible

  // Output selection mode
  outputSelectionMode: false,
  outputItems: [],
  outputItemIndex: 0,
  outputMimeType: null,
  outputSourceCommand: null,

  // Chain mode
  chainMode: false,
  chainContext: null,      // { data, mimeType, title, sourceCommand }
  chainStack: [],

  // Param mode
  paramMode: false,
  paramCommand: null,
  paramSuggestions: [],
  paramIndex: -1,
  paramGeneration: 0,     // Stale async guard

  // Execution
  executing: false,
  executingCommand: null,
  executionTimeout: null,
  executionError: null,
}

1.4 Current Bugs and Inconsistencies#

1. Escape handler duplication: Both api.escape.onEscape() (IZUI flow, lines 555-606) and handleSpecialKey() Escape branch (lines 615-663) implement identical escape-layering logic. If the IZUI escape interception changes, they can drift apart.

2. No guard against concurrent execution: execute() can be called while a previous command is still running (the executing flag is checked nowhere before starting a new execution).

3. Click handler bypasses state machine: The click handler on result items (line 2619-2628) calls execute() directly and manually updates frecency, duplicating logic from the Enter key path.

4. acceptParamSuggestion for non-item params does not execute: For non-item-type params (tags, enums), acceptParamSuggestion() just fills text and refreshes suggestions -- same as fillParamSuggestion(). Enter in param mode only routes through acceptParamSuggestion for item-type params (line 670 guard). For tag params, Enter falls through to the normal command execution path, which may or may not work correctly depending on whether the typed text matches the command name.

5. originalTyped not reset on all paths: originalTyped is set in the input handler but not reset when the panel is re-shown via visibility change. It is also not cleared when entering chain mode or output selection mode.

6. Chain popup timing fragility: openChainPopup uses a hardcoded 300ms delay before publishing content to the popup (line 1210), relying on the popup's ES module loading within that window.

7. Mode indicator hidden for 'default': The CSS rule display: none on [data-mode="default"] means the mode indicator is invisible most of the time. Mode cycling requires clicking an invisible element first (unless in a non-default mode).

2. State Machine Specification#

2.1 States#

The cmd bar can be in exactly one of these states at any time:

2.2 State Transition Diagram#

                        +---------+
           panel shown  |  IDLE   |  panel hidden
          +------------>|         |<-----------+
          |             +----+----+            |
          |                  |                 |
          |          typing  |  ArrowDown      |
          |          chars   |  (matches>0)    |
          |                  v                 |
          |             +--------+             |
          |             | TYPING |<------+     |
          |             +---+----+       |     |
          |                 |            |     |
          |     ArrowDown   | input      |     |
          |     (matches>0) | changed    |     |
          |                 v            |     |
          |          +-----------+       |     |
          |          | RESULTS   |-------+     |
          |          | _OPEN     | typing      |
          |          +-----+-----+             |
          |                |                   |
          |   Tab/typed    | Enter/click       |
          |   cmd+space    |                   |
          |   (has params) |                   |
          |        v       v                   |
          |  +-----------+  +-----------+      |
          |  | PARAM     |  | EXECUTING |      |
          |  | _MODE     |  +-----+-----+      |
          |  +-----+-----+       |             |
          |        |        +----+----+----+   |
          |  Enter |        |    |    |    |   |
          |  (item)|  no    | array  chain | error
          |        |  output| output output|   |
          |        v  v     v    v    v    v   |
          |  +-----------+ +------+ +------+ +-+-----+
          |  | EXECUTING | |OUTPUT| |CHAIN | | ERROR |
          |  +-----------+ |SELECT| |_MODE | +-------+
          |                +------+ +--+---+
          |                         |
          |                   text/*|output
          |                         v
          |                  +----------+
          |                  |CHAIN     |
          |                  |_POPUP    |
          |                  +----------+
          |
          +--- Escape (layered: paramMode > outputSelect > chain > results > text > close)

2.3 Transitions#

Each transition is defined as: (CurrentState, Event) -> (NextState, Actions, Guards)

From IDLE#

From TYPING#

From RESULTS_OPEN#

From PARAM_MODE#

From EXECUTING#

From OUTPUT_SELECTION#

From CHAIN_MODE#

From CHAIN_POPUP#

From ERROR#

From CLOSING#

Terminal state. Panel hides and resets on next visibility change -> IDLE.

2.4 Guards#

Guards are boolean conditions that determine which transition fires when multiple transitions share the same (State, Event) pair:

2.5 Actions#

Side effects that occur during transitions:

2.6 Invariants#

The state machine must maintain these invariants at all times:

1. Mutual exclusivity of major modes: Exactly one of {paramMode, outputSelectionMode, chainMode} can be true, or all are false. They cannot overlap.
2. paramCommand requires paramMode: If paramMode is false, paramCommand must be null.
3. chainContext requires chainMode: If chainMode is false, chainContext must be null and chainStack must be empty.
4. executing blocks new execution: While executing is true, no new execute() call should be started.
5. matchIndex in bounds: matchIndex must be >= 0 and < matches.length (or 0 when matches is empty).
6. paramIndex in bounds: paramIndex must be >= -1 and < paramSuggestions.length.
7. outputItemIndex in bounds: When in output selection mode, outputItemIndex >= 0 and < outputItems.length.
8. Escape layering order: Escape always exits the innermost active mode first: paramMode -> outputSelection -> chainMode -> showResults -> clearText -> close.

3. Test Coverage Plan#

3.1 State Entry/Exit Tests#

Each test verifies a single transition fires correctly:

IDLE transitions:

• IDLE + character input -> TYPING (typed set, matches computed)
• IDLE + ArrowDown with matches -> RESULTS_OPEN
• IDLE + ArrowDown with no matches -> IDLE (no-op)
• IDLE + Escape -> CLOSING
• IDLE + Enter with empty input -> IDLE (no-op)

TYPING transitions:

• TYPING + input changed -> TYPING (matches recomputed)
• TYPING + input cleared -> IDLE
• TYPING + ArrowDown -> RESULTS_OPEN
• TYPING + Tab (has params) -> PARAM_MODE
• TYPING + Tab (no params) -> TYPING (name completed)
• TYPING + Tab cycling (already completed) -> TYPING (next match)
• TYPING + Shift+Tab -> TYPING (previous match)
• TYPING + Enter with URL -> CLOSING (URL opened)
• TYPING + Enter with committed command -> EXECUTING
• TYPING + Enter with no match -> CLOSING (search opened)
• TYPING + Escape with text -> IDLE (text cleared)
• TYPING + Escape with empty text -> CLOSING
• TYPING + typed cmdName + space (cmd has params) -> PARAM_MODE (auto-enter)

RESULTS_OPEN transitions:

• RESULTS_OPEN + input changed -> TYPING (results hidden)
• RESULTS_OPEN + ArrowDown -> RESULTS_OPEN (index incremented)
• RESULTS_OPEN + ArrowDown at end -> RESULTS_OPEN (no-op)
• RESULTS_OPEN + ArrowUp -> RESULTS_OPEN (index decremented)
• RESULTS_OPEN + ArrowUp at 0 -> RESULTS_OPEN (no-op)
• RESULTS_OPEN + Tab -> RESULTS_OPEN or PARAM_MODE
• RESULTS_OPEN + Enter -> EXECUTING
• RESULTS_OPEN + click item -> EXECUTING
• RESULTS_OPEN + Escape -> TYPING (results hidden)

PARAM_MODE transitions:

• PARAM_MODE + input (still matches cmd) -> PARAM_MODE (suggestions updated)
• PARAM_MODE + input (no longer matches cmd) -> TYPING (param mode exited)
• PARAM_MODE + input cleared -> IDLE
• PARAM_MODE + ArrowDown -> PARAM_MODE (paramIndex incremented)
• PARAM_MODE + ArrowUp -> PARAM_MODE (paramIndex decremented)
• PARAM_MODE + Tab -> PARAM_MODE (text filled, not executed)
• PARAM_MODE + Enter (item-type) -> EXECUTING (with selectedItem)
• PARAM_MODE + Enter (tag-type) -> EXECUTING (with typed params)
• PARAM_MODE + Escape -> TYPING
• PARAM_MODE + click suggestion (item-type) -> EXECUTING

EXECUTING transitions:

• EXECUTING + complete (no output) -> CLOSING
• EXECUTING + complete (item output, single) -> CLOSING (editor opened)
• EXECUTING + complete (item output, array) -> OUTPUT_SELECTION
• EXECUTING + complete (chainable output, single) -> CHAIN_MODE
• EXECUTING + complete (chainable output, array, has downstream) -> CHAIN_MODE
• EXECUTING + complete (output, array, no downstream) -> OUTPUT_SELECTION
• EXECUTING + complete (action=prompt) -> IDLE
• EXECUTING + error -> ERROR
• EXECUTING + timeout -> ERROR
• EXECUTING + cancel click -> IDLE

OUTPUT_SELECTION transitions:

• OUTPUT_SELECTION + ArrowDown -> OUTPUT_SELECTION (navigate)
• OUTPUT_SELECTION + ArrowUp -> OUTPUT_SELECTION (navigate)
• OUTPUT_SELECTION + Enter (item type) -> CLOSING (editor)
• OUTPUT_SELECTION + Enter (other type) -> CHAIN_MODE
• OUTPUT_SELECTION + ArrowRight -> same as Enter
• OUTPUT_SELECTION + click item -> same as Enter
• OUTPUT_SELECTION + Escape -> IDLE

CHAIN_MODE transitions:

• CHAIN_MODE + input -> CHAIN_MODE (filtered matches)
• CHAIN_MODE + Enter (command selected) -> EXECUTING
• CHAIN_MODE + Escape (stack > 1) -> CHAIN_MODE (undo)
• CHAIN_MODE + Escape (stack <= 1) -> IDLE
• CHAIN_MODE + cancel click -> IDLE
• CHAIN_MODE + popup result (done) -> CLOSING
• CHAIN_MODE + popup result (data) -> CHAIN_MODE (updated context)

ERROR transitions:

• ERROR + 5s timeout -> IDLE
• ERROR + input -> TYPING
• ERROR + Escape -> IDLE

3.2 Edge Case Tests#

• Rapid typing during async param suggestions: Type fast, verify only the latest generation's results are applied (stale guard via paramGeneration)
• Escape during execution: Currently unhandled -- verify graceful behavior
• Double Enter: Press Enter twice quickly -- verify second execute is blocked by executing guard
• Tab then immediate Enter: Tab fills param, Enter executes -- verify correct item identity
• Panel re-show resets all state: Hide panel, re-show -- verify all modes cleared
• Chain mode Escape layering: In chain mode with param mode active, Escape exits param first, then chain
• Click during param mode: Click a result item while in param mode -- verify correct execution path
• URL typed in chain mode: Type a URL while in chain mode -- verify it doesn't bypass chain
• Empty input Enter in chain mode: Verify no crash or unexpected behavior
• Command not found during execution: Verify error state shown
• Panel visibility change during execution: Verify execution state cleaned up
• originalTyped preserved across Tab cycles: Tab through 3 matches, verify ghost text always shows original input bold
• Param mode auto-entry from typing: Type "edit " (with space) -- verify param mode entered without Tab
• Param mode auto-exit from backspace: In param mode, backspace to remove space -- verify param mode exited

3.3 Integration Tests (Full Sequences)#

• Basic command: Open panel -> type "tags" -> ArrowDown -> Enter -> verify command executed -> panel closed
• Tab completion -> param mode -> select item: Open -> type "ed" -> Tab (completes "edit ") -> wait for suggestions -> ArrowDown -> Enter -> verify editor opened with correct item
• Chain mode flow: Open -> type "list notes" -> Enter -> (output selection if array) -> select item -> chain mode -> type next command -> Enter -> verify chaining worked
• URL opening: Open -> type "github.com" -> Enter -> verify URL opened -> panel closed
• Search fallback: Open -> type "xyzzy" (no match) -> Enter -> verify search view opened
• Escape layering full sequence: Open -> type "edit " (param mode) -> Escape (exits param) -> Escape (clears text) -> Escape (closes panel)
• Mode cycling: Open -> click mode indicator -> verify mode cycles -> verify commands filtered by mode
• Error recovery: Open -> execute failing command -> verify error shown -> type new command -> verify error hidden -> execute succeeds

4. Implementation Notes#

4.1 Refactoring Strategy#

The current panel.js implements the state machine implicitly through scattered if/else checks in event handlers. To make it explicit:

1. Define a currentState variable that holds the current state name (string enum).
2. Create a transition table as a data structure mapping (state, event) -> {guard, nextState, actions}.
3. Centralize event dispatch through a single dispatch(event, payload) function that:
   • Looks up valid transitions for (currentState, event)
   • Evaluates guards
   • Runs actions
   • Updates currentState
   • Logs the transition for debugging
4. Wire DOM events to dispatch calls rather than directly manipulating state.

4.2 Suggested State Object Simplification#

Instead of flat boolean flags, group state into mode-specific sub-objects:

// Current (flat, error-prone)
state.paramMode = true;
state.paramCommand = 'edit';
state.outputSelectionMode = false; // Must be kept in sync

// Proposed (discriminated union)
state.mode = {
  type: 'param',          // 'idle' | 'typing' | 'results' | 'param' | 'executing' | 'output' | 'chain' | 'error'
  command: 'edit',        // Only present in 'param' mode
  suggestions: [...],     // Only present in 'param' mode
  selectedIndex: 0,       // Only present in 'param' mode
};

This makes invalid states unrepresentable -- you cannot have paramMode=true and outputSelectionMode=true simultaneously.

4.3 Key Principles#

1. Commands are data, not control flow: The state machine should never contain command-specific logic. Commands provide metadata (params, accepts, produces), and the state machine uses that metadata to choose transitions.

2. Actions are pure side effects: Each action function should do exactly one thing (update DOM, send IPC, etc.) and should be independently testable.

3. Escape is always layered: The escape handler should be a simple lookup: "what is the innermost active layer?" -> exit it. No duplicate implementations.

4. Execution is a state, not an action: While a command is executing, the state machine is in EXECUTING state. No other transitions (except cancel/error) should be valid.

5. originalTyped should be first-class: Instead of patching it in post-hoc, the state machine should distinguish between "user typed text" and "machine-completed text" as separate state fields from the start.

4.4 Migration Path#

1. Phase 1: Extract the state enum and transition table as documentation (this document).
2. Phase 2: Add the currentState variable and dispatch() function alongside existing code. Both run in parallel; dispatch logs but doesn't act.
3. Phase 3: Migrate one state at a time, starting with IDLE and TYPING. Verify tests pass after each migration.
4. Phase 4: Remove old if/else chains once all states are migrated.
5. Phase 5: Add the executing guard to prevent concurrent execution.

4.5 Testing Infrastructure#

Tests should use the existing pattern from smoke.spec.ts:

• Open cmd panel via app.window.open()
• Access internal state via window._cmdState
• Simulate input via cmdWindow.fill() and cmdWindow.keyboard.press()
• Wait for state changes via cmdWindow.waitForFunction()
• Verify side effects via pubsub event listeners on bgWindow

For unit tests of the state machine itself (no DOM/IPC), extract the transition table and dispatch logic into a separate module that can be tested with yarn test:unit.