feat(expose): add preview snapshot contract

[TraderSamwise]

Summary

• add an explicit optional Exposé preview snapshot contract for switchable agent items
• pass snapshots through fast-control serialization for project and global Exposé item APIs
• seed the TUI preview cache from API snapshots before live capture refreshes

Validation

• yarn vitest run src/fast-control.test.ts src/tmux/expose-model.test.ts src/tmux/expose.test.ts
• yarn typecheck
• yarn lint
• yarn build
• yarn test

Summary by CodeRabbit

• New Features

  • Added preview snapshots to fast-control and switchable-item data.
  • Preview tiles now display available snapshot output immediately when the expose view loads or refreshes.
  • Preview content remains visible when live capture is temporarily unavailable.
  • Snapshot details may include capture time, source, window information, and line ranges.

• Bug Fixes

  • Improved expose-view behavior so available previews are not blank while awaiting a live capture.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jul 20, 2026 2:06pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c4d6491a-d47a-4aa8-8b09-49766be7ef14

📥 Commits

Reviewing files that changed from the base of the PR and between 87ab737 and 7dce235.

📒 Files selected for processing (6)

• src/fast-control.test.ts
• src/fast-control.ts
• src/project-api-contract.ts
• src/tmux/expose-model.test.ts
• src/tmux/expose.test.ts
• src/tmux/expose.ts

---

📝 Walkthrough

Walkthrough

Changes

The PR adds typed previewSnapshot data to fast-control and switchable-agent contracts, preserves it through expose scope loading, and seeds the tmux exposé with snapshot output before or when live capture is unavailable.

Preview snapshot flow

Layer / File(s)	Summary
Snapshot contracts and serialization src/project-api-contract.ts, src/fast-control.ts, src/fast-control.test.ts	Defines preview snapshot types, adds the optional field to fast-control items, serializes it, and tests field preservation.
Scope item preservation src/tmux/expose-model.test.ts	Verifies loaded expose items retain their preview snapshots from the scope-item API.
Exposé preview seeding src/tmux/expose.ts, src/tmux/expose.test.ts	Seeds captures from snapshot output during initialization and reload, and tests rendering when live capture throws.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ScopeItemAPI
  participant loadExposeScopeItems
  participant runTmuxExpose
  participant TmuxRuntimeManager
  ScopeItemAPI->>loadExposeScopeItems: return items with previewSnapshot
  loadExposeScopeItems->>runTmuxExpose: provide expose scope items
  runTmuxExpose->>runTmuxExpose: seed preview captures
  runTmuxExpose->>TmuxRuntimeManager: request live capture
  TmuxRuntimeManager-->>runTmuxExpose: capture output or unavailable error
  runTmuxExpose-->>runTmuxExpose: render snapshot preview

Loading

Possibly related PRs

• TraderSamwise/aimux#122: Introduces the exposé TUI used by this preview pipeline.
• TraderSamwise/aimux#169: Also modifies exposé preview initialization and rendering timing.
• TraderSamwise/aimux#275: Reworks the same tmux exposé implementation.

Suggested reviewers: bhanuprasad14

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a preview snapshot contract for expose-related items.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/expose-preview-contract

---

_{Comment @coderabbitai help to get the list of available commands.}