Unify focused workflows in an expandable bottom overlay

[psabbagh]

Problem

Parrot currently presents its transient recording overlay and its focused workflows as visually and behaviorally separate surfaces. Correct Last Dictation, history, cleanup review, retained correction review, settings or model selection, and diagnostics can appear as detached modal windows even though they are continuations of work initiated from the menu bar and bottom overlay.

The result lacks a coherent spatial model, produces abrupt focus transitions, and encourages each workflow to invent its own sizing, keyboard, dismissal, and outcome behavior.

This should be treated as a surface architecture initiative, not as a restyling pass or a request to place every screen inside one oversized panel.

Product model

The bottom surface should support three deliberate presentation tiers:

1. Pill — recording state, progress, short-lived results, and compact actions.
2. Focused card — a bounded decision or small edit with a clear primary action.
3. Workspace — workflows that require longer text, collections, navigation, search, or settings.

Expansion and collapse should preserve spatial continuity with the existing bottom overlay. Each workflow must choose the smallest tier that satisfies its interaction requirements.

Focus and destination contract

Changing the shape of the surface does not by itself preserve the destination of an edit. Any workflow that may write back to another application must:

• capture and validate the original application, accessibility element, selected range, and relevant original text before the overlay takes keyboard focus;
• avoid relying on the original text field remaining focused while the user edits inside Parrot;
• apply only to the previously verified target and range;
• detect target changes or invalidation before mutation;
• fall back safely to the clipboard when direct replacement is unsupported;
• communicate the actual outcome, such as Applied or Copied, inside the same surface.

A non-activating panel may reduce visual and application-focus disruption, but it must not replace the saved-target contract. Text editing necessarily changes keyboard focus, and some Electron or custom controls may reject Accessibility replacement.

Workflow inventory

Evaluate at least:

• live recording, hands-free capture, transcription, delivery, and result states;
• Correct Last Dictation;
• cleanup review and retained correction review;
• history browse, search, recover, copy, and delete;
• model and durable settings;
• diagnostics and maintenance;
• startup, permission, shortcut, and failure guidance.

History and settings should use a workspace only if their actual interaction requirements justify it. The bottom surface is not an unlimited container.

Interaction requirements

• Expansion originates from and collapses back into the bottom surface.
• The surface has one predictable ownership model for activation, key status, and dismissal.
• Escape, Return, modified Return, Tab order, and click-outside behavior are specified per tier.
• Dirty edits receive appropriate dismissal protection.
• Primary actions are enabled only when meaningful.
• Applied, copied, cancelled, failed, and unavailable outcomes are visibly distinct.
• Screen changes do not cause arbitrary jumps between unrelated windows.
• Placement remains stable across displays, Spaces, Dock positions, and display-scale changes.
• VoiceOver labels, focus order, reduced motion, and full keyboard access are first-class behavior.

Proposed sequence

1. Define the shared state, focus, sizing, placement, animation, dismissal, and accessibility contracts.
2. Implement the reusable pill, focused-card, and workspace shell without migrating every workflow.
3. Migrate Correct Last Dictation as the first focused editing workflow.
4. Validate target preservation and clipboard fallback across native, web, Electron, and unsupported controls.
5. Migrate review workflows.
6. Evaluate history and settings independently against the workspace criteria.
7. Remove superseded modal controllers only after behavioral parity is proven.

Acceptance criteria

• The product has one documented surface and focus model for transient and focused workflows.
• A reusable expanded-overlay shell supports the three presentation tiers without workflow-specific window behavior.
• Keyboard focus, application activation, destination preservation, dismissal, and outcome reporting have explicit contracts.
• Correct Last Dictation demonstrates the complete edit-and-deliver lifecycle in the new surface.
• Unsupported direct replacement produces a visible clipboard fallback instead of silent ambiguity.
• History, review, settings, and diagnostic placement decisions are based on interaction requirements.
• Automated coverage exercises state transitions, focus changes, dirty-state dismissal, target invalidation, and result states.
• Native visual checks cover representative workflows at multiple display scales and screen configurations.
• Existing privacy, history retention, and clipboard semantics remain unchanged unless a separate issue explicitly changes them.

Non-goals

• Moving every current screen into the overlay in one change.
• Assuming a non-activating panel guarantees background text insertion.
• Making unsupported controls appear to support direct replacement.
• Replacing native macOS keyboard and accessibility conventions with custom behavior.