@osolmaz/pi-workflows 0.1.0 → 0.2.0

package/docs/plans/piw-viewer-experience-implementation-plan.md

@@ -0,0 +1,674 @@
+# PIW viewer experience implementation plan
+
+## Objective
+
+Make `piw` a state-rich, terminal-native workflow viewer with Catppuccin as
+its complete default visual system, a Herdr-style theme picker, clearer replay
+and run states, a useful inspector, a real timeline, and resilient remote
+viewing.
+
+The result is verified by styled ratatui buffer tests, graph parity fixtures,
+remote reconnect tests, real-run end-to-end tests, and manual PTY checks across
+dark, light, narrow, and wide terminal layouts.
+
+## Boundaries
+
+- Keep `piw` a standalone Rust TUI. Do not imitate browser-only effects such
+  as shadows, smooth camera animation, or fractional text animation.
+- Do not modify Pi internals or undocumented Pi APIs.
+- Do not write or rewrite Pi session history.
+- Do not change the workflow run-bundle schemas or persisted run documents.
+- Persist only viewer preferences under the user's normal config directory.
+  Do not store replay positions, run data, or session data there.
+- Preserve the existing TypeScript/Rust graph layout contract. Any textual or
+  geometric graph change must be made in both renderers and reflected in the
+  shared fixtures.
+- Keep compact line nodes as an optional density mode; bordered nodes remain
+  the default.
+- Keep all remote access loopback-only unless the existing SSH-tunnel workflow
+  is used.
+
+## Product decisions
+
+### Terminal-native ACPX parity
+
+Adopt ACPX ideas that improve inspection and state comprehension:
+
+- semantic, surface-backed graph nodes;
+- separate running and replay-focus presentation;
+- a visible timeline and playback speed controls;
+- detailed attempt and event inspection;
+- graph-node selection;
+- a collapsible run browser;
+- structured tool-call and tool-result rendering; and
+- reliable live reconnection.
+
+Do not adopt ELK, React Flow, browser card decoration, smooth zoom, animated
+edges, multiple ACP-session concepts, or character-by-character replay.
+
+### Stable full node cards
+
+Box mode is the canonical graph presentation. Each node is a full card with a
+border, an interior surface, and enough padding to keep its outer dimensions
+stable. Compact line mode remains an explicit density option and does not set
+the box-mode contract.
+
+The graph computes one card width and one card height before it runs layout.
+Every real node uses those dimensions. The calculation uses the largest card
+required by the immutable definition and reserves fixed rows for every runtime
+field. Shorter cards receive blank padding. A status change, timer tick, new
+attempt, replay seek, selection change, or live event may replace text inside a
+reserved slot, but it must never resize a node or move the graph. Terminal
+resize changes the viewport only. A small viewport pans over the graph instead
+of shrinking or clipping cards.
+
+A full card contains the same classes of information as an ACPX workflow card:
+
+- the exact node id and full node type;
+- a status symbol with its text label;
+- semantic markers for start, branch count, and terminal position;
+- every branch label associated with the node;
+- not-visited or attempt-count metadata;
+- live elapsed time or final duration; and
+- the complete node `statusDetail` or short terminal outcome when present.
+
+Use the established symbols consistently:
+
+| Meaning       | Symbol |
+| ------------- | ------ |
+| queued        | `·`    |
+| running       | `◐`    |
+| replay focus  | `◆`    |
+| completed     | `✓`    |
+| failed        | `✗`    |
+| timed out     | `×`    |
+| waiting       | `⏸`    |
+| cancelled     | `~`    |
+| start node    | `▶`    |
+| branch node   | `◇N`   |
+| terminal node | `■`    |
+
+Node-card fields must not use ellipses or disappear because another state needs
+the space. Long fixed text wraps during the initial card measurement, and all
+nodes are padded to the resulting graph-wide dimensions. Prompts, outputs,
+errors, tool payloads, and other unbounded attempt details remain in the
+inspector; they are not node-card fields.
+
+### Theme model
+
+Use a purpose-built `piw` theme contract rather than Pi's 51-token theme JSON
+format. `piw` is a standalone viewer and needs graph, timeline, run-state, and
+node-surface tokens that Pi themes do not define.
+
+Use the same operating model as Herdr:
+
+- Catppuccin Mocha is the default;
+- built-in dark and light themes are selectable;
+- moving through the picker previews immediately;
+- Apply persists the choice;
+- Cancel restores the exact original palette;
+- config and CLI selection are supported; and
+- optional per-token overrides layer on top of a built-in palette.
+
+The initial built-in list should match Herdr's user-facing list and names:
+
+- `catppuccin`
+- `catppuccin-latte`
+- `terminal`
+- `tokyo-night`
+- `tokyo-night-day`
+- `dracula`
+- `nord`
+- `gruvbox`
+- `gruvbox-light`
+- `one-dark`
+- `one-light`
+- `solarized`
+- `solarized-light`
+- `kanagawa`
+- `kanagawa-lotus`
+- `rose-pine`
+- `rose-pine-dawn`
+- `vesper`
+
+Theme names are normalized by lowercasing and replacing spaces and underscores
+with hyphens. Unknown names produce a visible diagnostic and fall back to
+Catppuccin instead of panicking.
+
+### Surface hierarchy
+
+Every frame must be painted from theme tokens. Do not rely on the terminal's
+default background except in the explicit `terminal` theme.
+
+For Catppuccin Mocha, use a clear hierarchy:
+
+- application background: Crust (`#11111b`);
+- panel background: Mantle (`#181825`);
+- graph canvas: Base (`#1e1e2e`);
+- ordinary node surface: Surface 0 (`#313244`);
+- selected/running node surface: Surface 1 (`#45475a`);
+- main text: Text (`#cdd6f4`);
+- secondary text: Subtext 0 (`#a6adc8`);
+- muted lines: Overlay 0 (`#6c7086`);
+- accent/running: Blue (`#89b4fa`);
+- replay focus: Mauve (`#cba6f7`);
+- completed: Green (`#a6e3a1`);
+- waiting: Yellow (`#f9e2af`);
+- failed: Red (`#f38ba8`);
+- timed out/interrupted: Peach (`#fab387`);
+- branch/tool accent: Teal (`#94e2d5`).
+
+A node box must always have a background distinct from its graph canvas. State
+is carried primarily by the border, glyph, and accent text rather than by
+painting every state a different card color.
+
+## Theme architecture
+
+### Semantic palette
+
+Add `tui/src/theme/` with a `Theme` or `Palette` value containing semantic
+colors rather than component-specific ad hoc styles. At minimum, define:
+
+- surfaces: `appBg`, `panelBg`, `canvasBg`, `nodeBg`, `nodeFocusBg`,
+  `selectionBg`, `surfaceDim`;
+- structure: `border`, `borderFocused`, `edge`, `edgeBack`, `edgeTaken`;
+- text: `text`, `subtext`, `muted`;
+- interaction: `accent`, `replayFocus`;
+- state: `running`, `success`, `warning`, `error`, `timedOut`, `cancelled`;
+- content: `branch`, `user`, `assistant`, `tool`; and
+- timeline: `timelineTrack`, `timelineFill`, `timelineThumb`.
+
+Components must request semantic styles from the active theme. Remove direct
+`Color::Cyan`, `Color::Green`, and similar choices from `tui/src/ui/` and
+`tui/src/ui/conversation.rs`. Literal colors should remain only in built-in
+palette definitions, color parsing, and theme tests.
+
+### Canvas roles and node backgrounds
+
+The current `CanvasStyle` combines node and edge meanings, and sparse spaces
+cannot carry a background. Replace it with semantic canvas roles that
+separate:
+
+- ordinary text;
+- muted text;
+- queued, taken, active, and back edges; and
+- queued, running, replay-focused, completed, failed, timed-out, waiting, and
+  cancelled nodes.
+
+Add an intentional-space/fill operation to `CharCanvas` so every cell inside a
+bordered node carries `nodeBg` or `nodeFocusBg`. Draw the node surface before
+its border and content, and ensure graph edges cannot bleed through node
+interiors.
+
+Node content should use separate roles for the status glyph, node id, node
+type, and metadata instead of applying one color to the whole line. Plain-text
+fixture output must remain deterministic.
+
+### Configuration
+
+Add viewer configuration at:
+
+1. `PIW_CONFIG_PATH`, when set;
+2. `$XDG_CONFIG_HOME/piw/config.toml`; or
+3. `~/.config/piw/config.toml`.
+
+Use this shape:
+
+```toml
+[theme]
+name = "catppuccin"
+auto_switch = false
+dark_name = "catppuccin"
+light_name = "catppuccin-latte"
+
+[theme.custom]
+# canvas_bg = "#1e1e2e"
+# node_bg = "#313244"
+# accent = "#89b4fa"
+```
+
+Color values accept `#rrggbb`, `#rgb`, `rgb(r,g,b)`, named terminal colors,
+and `reset` aliases. Invalid overrides are reported and ignored individually;
+they do not invalidate the entire theme.
+
+Configuration precedence is:
+
+1. an explicit picker selection made during the current session;
+2. `--theme <name>`;
+3. `PIW_THEME`;
+4. config file; and
+5. `catppuccin`.
+
+Add `--list-themes`. A picker Apply writes only the theme selection, preserves
+unknown config keys and comments, and uses a same-directory temporary file plus
+atomic rename. Applying a manual theme disables `auto_switch`, matching Herdr.
+
+Host light/dark detection and automatic sibling switching are a final theme
+phase, not a prerequisite for manual theme selection. When added, query the
+host terminal background only through standard terminal escape sequences,
+restore terminal modes on exit, and retain the manually configured theme when
+the terminal does not answer.
+
+### Theme picker
+
+Add a modal opened with `,`:
+
+- list every built-in theme;
+- show compact color swatches;
+- preview on Up/Down, `j`/`k`, or mouse selection;
+- Apply with Enter;
+- Cancel with Escape and restore the original palette exactly;
+- mark the persisted/current theme with a checkmark; and
+- show config write errors inside the modal without closing it.
+
+The modal must be usable at 80x24, clip or scroll at smaller sizes, and paint
+its own panel background. Update the footer help to advertise the picker
+without displacing essential replay controls.
+
+## State presentation
+
+Replace the current overloaded active state with these distinct graph states:
+
+- queued;
+- running;
+- replay focus;
+- completed;
+- failed;
+- timed out;
+- waiting;
+- cancelled.
+
+Requirements:
+
+- Running uses the active glyph, active color, live elapsed timer, and heavy
+  border.
+- Replay focus uses a distinct glyph/color and heavy border, but never says or
+  looks like it is currently running.
+- Timed out has a width-stable glyph and the `timedOut` color instead of using
+  the failed presentation.
+- Waiting remains distinct.
+- `paused: true` is visible in the graph title and transport even if the run's
+  persisted status is `running`.
+- `statusDetail`, `waitingOn`, and run errors are shown consistently without
+  overflowing node cells.
+- `(live)`, `(latest)`, and `(replay)` remain separate from the persisted run
+  outcome.
+
+Where glyph or node text changes affect graph fixture output, update both
+`src/render/` and `tui/src/render.rs`, regenerate the fixtures, and retain
+byte-for-byte plain rendering parity.
+
+## Inspector
+
+Refactor the inspector out of `tui/src/ui/mod.rs` into focused modules and make
+it useful for debugging without changing bundle data.
+
+### Steps
+
+- Keep the visible attempt list.
+- Provide summary and expanded detail modes.
+- Render full wrapped prompt, output, and error content in expanded mode.
+- Render complete action receipts: action type, command, arguments, working
+  directory, exit code, signal, and duration.
+- Show the selected attempt id and timestamps.
+- Resolve local artifact-backed fields within existing containment and size
+  limits.
+- Use a side-by-side attempt-list/detail layout when wide and a stacked layout
+  when narrow.
+
+### Trace
+
+Make trace rows selectable and add three explicit scopes:
+
+- selected attempt;
+- replay-visible trace; and
+- full run.
+
+For replay-visible trace, derive the cutoff from events associated with the
+visible attempt ids and include run-level events only up to that sequence. The
+full-run mode must be labeled because it can reveal events after the current
+replay position.
+
+Enter expands the selected event's sanitized JSON payload. Preserve trace tail
+following only while the user is at the bottom and the scope includes live
+events.
+
+### Info
+
+Keep and theme the existing run Info tab. Continue showing source, status,
+status detail, error, counts, interruption warning, and final output.
+
+Store selection and scroll state per inspector tab so switching tabs does not
+lose the user's place.
+
+## Replay timeline
+
+Replace the text-only footer with a responsive terminal timeline:
+
+- a Unicode track, completed segment, and playhead;
+- `step n/m`, before-first, latest, and LIVE labels;
+- mouse click and drag seeking;
+- previous, play/pause, next, start, and latest hit areas;
+- 1x, 2x, 5x, and 10x playback speeds;
+- the existing `[`, `]`, Space, Home, End, `g`, `G`, and `L` controls; and
+- `{` and `}` for slower/faster playback.
+
+Playback remains discrete. At 1x, retain the current 700 ms step interval;
+other speeds divide that interval. Do not synthesize fractional attempt state.
+
+Use two footer rows when the terminal has enough height and a compact one-row
+fallback in short terminals. Seeking backward detaches from live; selecting
+latest rejoins live. Appended steps advance automatically only when the viewer
+was already following latest.
+
+## Remote reliability and artifacts
+
+Refactor `RemoteRuns` into a reconnecting client:
+
+- bounded exponential backoff with jitter;
+- explicit connecting, reconnecting, connected, and disconnected states;
+- automatic `watch_runs` and selected-run resubscription after reconnect;
+- existing revision-gap resnapshot behavior;
+- cached data remains visible with a prominent stale/disconnected label; and
+- dropping the client stops and joins the background worker cleanly.
+
+Do not treat commands sent while offline as delivered. Keep desired
+subscriptions in shared state and reconcile them after each successful hello.
+
+Wire the existing artifact protocol into the inspector. Cache bounded artifact
+content by `(runId, path)`, serialize requests so the current protocol's errors
+can be associated with the outstanding request, and retain path containment
+and maximum-size checks. Do not change the replay protocol schema for this
+feature.
+
+## Graph and run-browser interaction
+
+### Graph semantics
+
+Replace the current one-line box interior with the stable full-card contract.
+Every boxed node shows identity, type, current status, semantic markers, and
+branch labels. It also shows attempt metadata and timing plus the available
+short detail or outcome. The exact node id remains visible.
+
+Compute canonical graph-wide card dimensions before placing ranks and routing
+edges. Pass those fixed bounds into layout, drawing, camera targeting, mouse hit
+testing, and edge attachment. Fill unused rows and columns with intentional
+node-surface padding. Live and replay updates redraw card cells without
+re-running layout.
+
+Keep branch labels on edges as routing labels and repeat them inside branch
+cards as node metadata, matching ACPX. Show all labels instead of taking a
+fixed prefix.
+
+Implement card measurement and rendering in both graph renderers, regenerate
+parity fixtures, and verify that every replay position has identical
+`NodeBounds` for each node.
+
+### Graph selection
+
+Return node bounds with the rendered canvas. Use those bounds for:
+
+- precise active/replay camera targeting instead of searching styled text;
+- mouse hit testing; and
+- selecting the latest visible attempt for a clicked node.
+
+A queued node click may focus the definition node but must not invent an
+attempt. Panning and clicking must remain distinguishable by a drag threshold.
+
+### Run browser
+
+Add expanded and collapsed browser modes:
+
+- expanded retains title, status, elapsed time, and interrupted marker;
+- collapsed is a narrow status rail;
+- `b` toggles the mode;
+- a single directly opened run continues to hide the browser; and
+- narrow terminals start collapsed without overwriting an explicit user
+  toggle during that session.
+
+Theme selected rows with `selectionBg` and preserve a visible status color in
+both modes.
+
+## Conversation rendering
+
+Keep Pi's recorded session entries and explicit conversation ranges as the
+authoritative source.
+
+- Preserve replay-safe progressive reveal; do not show future messages while
+  rewound.
+- Preserve the selected attempt's visible gutter.
+- Render tool calls with tool name and a compact argument summary.
+- Render tool results with running/success/error state and a short preview.
+- Let Enter expand the selected tool payload as sanitized JSON.
+- Add sticky live auto-follow: remain at the bottom while new entries arrive,
+  detach when the user scrolls upward, and reattach with End.
+- Keep thinking text distinguishable but readable under every built-in theme.
+
+Do not add a multiple-session selector; the current bundle contract records one
+Pi conversation per run.
+
+## Responsive layout
+
+Introduce explicit layout tiers rather than relying only on percentages:
+
+- **wide:** run browser, graph, and split attempt detail use available width;
+- **standard:** current graph-over-inspector layout;
+- **narrow:** collapsed browser, compact timeline, and stacked inspector; and
+- **very short:** one-row transport and minimum viable pane titles.
+
+Every tier must preserve access to run status, replay position, graph content,
+and inspector tabs. Avoid silently dropping information solely because the
+terminal resized.
+
+## Implementation sequence
+
+### 1. Theme foundation
+
+- Add semantic palette, built-ins, parser, config loader, CLI override, and
+  Catppuccin default.
+- Paint the full frame and every panel from palette surfaces.
+- Replace all hard-coded UI colors.
+- Add node-surface canvas roles and filled node rectangles.
+- Add styled buffer tests for Catppuccin and one light theme.
+
+Exit criterion: Catppuccin is visibly applied to the whole viewer, and every
+boxed node has a surface color distinct from the graph background.
+
+### 2. Theme picker and persistence
+
+- Add the `,` modal with preview/apply/cancel and mouse support.
+- Persist atomically while preserving unrelated config.
+- Add all Herdr-aligned built-ins and custom overrides.
+- Add invalid-config diagnostics and `--list-themes`.
+
+Exit criterion: a user can preview, cancel, apply, restart, and retain any
+built-in theme.
+
+### 3. State correctness
+
+- Split running from replay focus.
+- Add timed-out and paused presentation.
+- Apply semantic state colors consistently to graph, run rows, inspector, and
+  timeline.
+- Update both renderers and fixtures where plain graph output changes.
+
+Exit criterion: no historical replay position appears live, and every persisted
+run/node state has a distinct tested presentation.
+
+### 4. Inspector depth
+
+- Refactor inspector modules.
+- Add full attempt details and complete action receipts.
+- Add selectable trace scopes and expandable payloads.
+- Preserve per-tab selection and scroll state.
+
+Exit criterion: all existing step and trace fields can be inspected without
+opening bundle files manually.
+
+### 5. Replay timeline
+
+- Add the responsive timeline, hit areas, seeking, and speeds.
+- Keep discrete deterministic playback and live-follow semantics.
+
+Exit criterion: keyboard and mouse can seek any recorded step and reliably
+return to live.
+
+### 6. Remote resilience
+
+- Add reconnect state machine, resubscription, cancellation, and server-restart
+  tests.
+- Connect remote artifact fetching to expanded inspector fields.
+
+Exit criterion: restarting `piw serve` does not require restarting the viewer,
+and cached data is never presented as current while disconnected.
+
+### 7. Graph and browser interaction
+
+- Replace one-line boxed interiors with stable full node cards.
+- Measure one canonical card size from all node-card fields before layout.
+- Add node bounds and click selection.
+- Add start/end semantics and branch metadata in both renderers. Include status
+  and attempt counts. Timing and the short detail use their own slots.
+- Add collapsed run browser and responsive layout tiers.
+
+Exit criterion: every node-card field is visible, node bounds stay unchanged
+across every live and replay state, graph nodes are selectable, and an
+80-column terminal remains usable through panning.
+
+### 8. Conversation polish and host-theme switching
+
+- Add structured tool rows, expansion, and sticky auto-follow.
+- Add optional host appearance detection and dark/light sibling switching.
+- Verify terminal state restoration after normal exit, errors, and Ctrl-C.
+
+Exit criterion: live tool activity remains readable and auto-switching never
+leaves terminal modes or colors altered after exit.
+
+## Expected file changes
+
+Likely additions:
+
+```text
+tui/src/theme/mod.rs
+tui/src/theme/builtins.rs
+tui/src/theme/config.rs
+tui/src/ui/theme_picker.rs
+tui/src/ui/timeline.rs
+tui/src/ui/inspector.rs
+tui/src/ui/runs.rs
+```
+
+Likely modifications:
+
+```text
+tui/Cargo.toml
+tui/src/main.rs
+tui/src/lib.rs
+tui/src/canvas.rs
+tui/src/render.rs
+tui/src/client.rs
+tui/src/ui/mod.rs
+tui/src/ui/graph.rs
+tui/src/ui/conversation.rs
+src/render/*                 # only for shared graph text/geometry changes
+fixtures/layout/*            # regenerated only when shared output changes
+docs/tui-viewer.md
+docs/development.md
+README.md
+```
+
+Avoid leaving theme logic split between components. Palette definitions,
+parsing, resolution, and style derivation belong under `tui/src/theme/`.
+
+## Verification
+
+### Unit tests
+
+- Every built-in theme resolves by canonical name and documented aliases.
+- Catppuccin is the default.
+- Invalid theme names and colors fall back predictably with diagnostics.
+- Config precedence and atomic save behavior are deterministic.
+- Picker preview, Cancel, and Apply preserve the correct palette.
+- Every non-terminal built-in has distinct `canvasBg` and `nodeBg` values.
+- Styled ratatui buffers contain the expected frame, panel, canvas, node, and
+  focused-node backgrounds.
+- No state shares the wrong semantic role, especially failed/timed-out and
+  running/replay-focus.
+- Timeline coordinate mapping is correct at step `-1`, first, middle, latest,
+  and after terminal resize.
+- Trace replay cutoffs cannot reveal later attempt events.
+- Node hit testing accounts for viewport offsets.
+- Every boxed node in one graph has the same outer dimensions.
+- Node bounds remain identical across every runtime state. Selection and replay
+  focus also leave the bounds unchanged.
+- Long node ids, status details, and branch labels wrap without truncation and
+  without changing the graph-wide card size after layout.
+- Every documented status and semantic symbol appears with the matching text
+  label and color role.
+
+### Integration tests
+
+- Existing plain graph parity fixtures are regenerated for the full-card
+  geometry and continue to match between TypeScript and Rust.
+- Shared fixtures assert identical node bounds at every replay position.
+- Theme changes do not alter plain fixture output unless an intentional shared
+  graph change updates both renderers.
+- A remote client reconnects after a server restart and receives a fresh
+  snapshot.
+- Subscription changes made while disconnected are reconciled after reconnect.
+- Local and remote expanded artifact views enforce the same size and path
+  limits.
+- Narrow and wide TestBackend layouts retain all required controls.
+
+### Manual PTY checks
+
+Exercise at least:
+
+- Catppuccin Mocha at 80x24 and 140x40;
+- Catppuccin Latte on a light terminal;
+- `terminal` theme with a custom terminal palette;
+- a completed run, a live run, a waiting run, a timed-out run, and a cancelled
+  run;
+- replay before the first step, detached replay, and return to live;
+- theme preview followed by Cancel and Apply;
+- a stopped and restarted remote server; and
+- tool calls, action receipts, long output, and artifact-backed values;
+- a graph containing every node state and semantic symbol; and
+- long ids, status details, and branch labels in an 80-column viewport.
+
+### Repository checks
+
+Before finishing each coherent implementation slice, run the relevant focused
+Rust tests. Before finishing the complete work, run:
+
+```bash
+cargo fmt --check --manifest-path tui/Cargo.toml
+cargo clippy --manifest-path tui/Cargo.toml --all-targets -- -D warnings
+cargo test --manifest-path tui/Cargo.toml
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+## Completion criteria
+
+The work is complete when:
+
+1. Catppuccin Mocha is the default and colors every visible viewer surface.
+2. Boxed nodes are full cards with one stable graph-wide size, intentional
+   padding, and every documented card field visible without truncation.
+3. Users can preview, apply, persist, and cancel built-in theme choices from
+   the TUI.
+4. No component chooses ad hoc colors outside the theme layer.
+5. Running, replay focus, completed, failed, timed out, waiting, cancelled,
+   paused, latest, replay, and live states are unambiguous.
+6. Full attempt, action, trace, run, and conversation details are inspectable.
+7. The timeline supports keyboard and mouse seeking plus playback speeds.
+8. Remote viewing reconnects safely and labels stale cached data.
+9. Graph selection and the collapsed browser work in narrow terminals.
+10. Node status and semantic markers use the documented ACPX-style slots and
+    symbols. Attempt counts and timing use reserved slots, as do short details,
+    without changing node bounds.
+11. Graph parity, bundle schemas, Pi session state, and Pi internals remain
+    unchanged except for intentional shared renderer fixture updates.