spec: render inline image protocols at shell startup (#10020)

[lonexreb]

Summary

Spec for issue #10020 — inline image-protocol escape sequences (Kitty graphics, iTerm2 inline image) emitted from shell init files (~/.zshrc, ~/.bashrc, etc.) are silently dropped, while the same bytes typed manually after the prompt render correctly. Other terminals (iTerm2, WezTerm, Kitty, Ghostty) render images at shell startup as documented in their respective protocol specs.

Investigation

Traced the routing end-to-end:

1. TerminalModel::handle_completed_iterm_image (terminal_model.rs:3354) → delegate! → BlockList.
2. BlockList::handle_completed_iterm_image (blocks.rs:3794) → delegate_to_block! → active block (intentionally bypasses the early-output gate).
3. Block::handle_completed_iterm_image (block.rs:3292) → block-level delegate! (block.rs:2882).
4. The block-level delegate! routes to header_grid when state == BlockState::BeforeExecution. The header_grid is the prompt area; its image placement is not rendered in the visible block body.
5. Once the user types a command, the block transitions out of BeforeExecution and image bytes land in output_grid, which renders. This is why typing the same command works.

The reporter's background-subshell case (( sleep 0.2 && fastfetch ) &!) hits the same branch via a different session phase: the post-prompt block is itself in BeforeExecution waiting for the user's first keystroke, so background output emitted during the is_early_output() window is also routed to header_grid.

What's in the spec

product.md — 7 testable behavior invariants (B1–B7), 6 acceptance criteria (A1–A6), explicit non-goals, and a preserved record of the reporter's diagnostic facts (verified byte sequences, alternative approaches that were tried and ruled out).

tech.md — picks the fix site with explicit reasoning against the two alternatives, names every file and line range touched, and lays out four unit tests + six integration tests (including a negative-space test for the WarpInput hidden bootstrap block and a feature-flag-off regression guard).

Architectural choices

• Fix at the block-level delegate! macro, not at BlockList and not at GridHandler. Rationale: BlockList does not know about header_grid vs output_grid; pushing the routing decision up would leak grid identity. GridHandler is downstream of the routing decision; pushing it down would require a redirect message back up. The block-level delegate! is exactly where the (state, grid) routing decision belongs.
• Carve out BootstrapStage::WarpInput. Warp's own injected bootstrap-script bytes must never accidentally render an image even after the fix.
• Add warn-level telemetry on every silent-drop path. The whole reason this bug was invisible for months is that drops were unlogged. Tightening this is the cheapest defense against the same family of bug regressing.

Test plan

• Unit tests T1–T4 in block_test.rs — verify routing per BlockState value and per bootstrap_stage.
• Integration tests IT1–IT6 in image_protocol_at_startup_test.rs (new file) — feed the exact byte sequences from the issue at each session phase, assert Event::ImageReceived dispatch and grid placement.
• Manual: fastfetch in ~/.zshrc with --logo-type kitty-direct (A1), --logo-type iterm (A2), and the background-subshell variant (A3).
• Manual: post-prompt typed fastfetch continues to render (A4 regression guard).
• Manual: FeatureFlag::ITermImages disabled produces no render and no warn-level log noise (A5 + B7).

Open questions for maintainer review

1. Macro naming: prefer delegate_image_completion! (sibling macro) or a boolean parameter on the existing delegate!?
2. Telemetry level for unexpected drops: log::warn! vs log::debug! + a separate metric?
3. The bootstrap-stage gates at blocks.rs:3789 (on_reset_grid), 3724 (precmd), and 3763 (preexec) are left alone. Confirm they are intentional and not symptoms of the same family.

Closes (spec-only) #10020 — implementation PR will follow once spec direction is confirmed.

[oz-for-oss]

@lonexreb

I ran into an unexpected error while working on this.

Powered by Oz