docs: plan presentation live replay activation
This commit is contained in:
@@ -0,0 +1,406 @@
|
||||
# Presentation Live/Replay Activation Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Restore an explicit Scene 10 live/replay launch surface and make the existing workflow RPC timeline reliable without changing authoring replay or the broader storyboard.
|
||||
|
||||
**Architecture:** Keep `callOperation` as the only browser operation path and keep `useDemoTimeline` as the only live/replay execution owner. Add a small target-status controller for health retry, expose an explicit run-mode method on `TimelineAgentController`, and render a scene-owned launch control on Scene 10's operation beat because Scenes 10–12 hide chat. Direct deep links continue to prime replay; only an explicit launch starts live or replay.
|
||||
|
||||
**Tech Stack:** React 19, TypeScript, Valibot-backed RPC DTOs, Vitest/Testing Library, Vite, existing BEM/CSS presentation surfaces.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Do not add a second transport or call `wf-rpc-server` directly from the browser.
|
||||
- Preserve the existing path: browser `:5173` -> web server `:8787` -> workflow RPC `:8765/rpc`.
|
||||
- Scenes 8 and 9 remain deterministic authoring replay and must not call workflow authoring RPC operations.
|
||||
- Direct Scene 10–12 hashes remain replay-backed until the presenter explicitly launches a mode.
|
||||
- A live failure must remain visibly live/failed; replay fallback must be an explicit action.
|
||||
- Do not touch the unrelated user edit in `web/apps/console/src/presentation/authoring/Scene8ChatEntry.tsx`.
|
||||
- Use existing `callOperation`, `resolvePresentationTarget`, `usePresentationTargetStatus`, and `useDemoTimeline` seams rather than introducing a new store.
|
||||
- Run scoped tests before broad verification; do not stage generated `.superpowers` scratch files.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Separate target health from replay playback and add retry
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/apps/console/src/presentation/presentation-target-status.ts`
|
||||
- Modify: `web/apps/console/src/presentation/presentation-target-status.test.ts`
|
||||
- Modify: `web/apps/console/src/presentation/usePresentationTargetStatus.ts`
|
||||
- Modify: `web/apps/console/src/presentation/usePresentationTargetStatus.test.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/PresentationRoute.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/PresentationStage.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- `usePresentationTargetStatus` must return the existing `status` plus `retryHealth: () => void` and `liveTargetReady: boolean`.
|
||||
- `liveTargetReady` is true only when a configured HTTP target has a successful `workflow.health` probe. It remains true while replay is being displayed after a direct hash; replay playback must not erase target readiness.
|
||||
- `retryHealth` must rerun the existing `callOperation("workflow.health", target, {})` request without changing the demo timeline mode.
|
||||
|
||||
- [ ] **Step 1: Write failing status tests**
|
||||
|
||||
Add tests that prove a healthy target remains available while replay is active and that retry causes a second health call after a failed probe. Assert the returned status and `liveTargetReady` separately; do not infer live readiness from the playback label.
|
||||
|
||||
```tsx
|
||||
it("keeps live target readiness visible while direct replay is active", async () => {
|
||||
const result = renderHook(() => usePresentationTargetStatus(
|
||||
{ mode: "live", target: TARGET, source: "default" },
|
||||
{ mode: "replay", phase: "paused", events: [], appliedCount: 0, autoplay: false, error: null },
|
||||
));
|
||||
|
||||
await waitFor(() => expect(result.current.status.kind).toBe("replay"));
|
||||
expect(result.current.liveTargetReady).toBe(true);
|
||||
});
|
||||
|
||||
it("retries health without changing playback state", async () => {
|
||||
mockedCallOperation
|
||||
.mockResolvedValueOnce(failedHealthResponse)
|
||||
.mockResolvedValueOnce(healthyResponse);
|
||||
|
||||
const result = renderHook(() => usePresentationTargetStatus(
|
||||
{ mode: "live", target: TARGET, source: "default" },
|
||||
replayState,
|
||||
));
|
||||
|
||||
await waitFor(() => expect(result.current.status.kind).toBe("failed"));
|
||||
act(() => result.current.retryHealth());
|
||||
await waitFor(() => expect(result.current.liveTargetReady).toBe(true));
|
||||
expect(result.current.status.kind).toBe("replay");
|
||||
expect(mockedCallOperation).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused tests and verify they fail**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test -- src/presentation/presentation-target-status.test.ts src/presentation/usePresentationTargetStatus.test.tsx
|
||||
```
|
||||
|
||||
Expected: FAIL because the hook does not expose `retryHealth` or `liveTargetReady` yet.
|
||||
|
||||
- [ ] **Step 3: Implement the health controller**
|
||||
|
||||
Add a probe-generation state/ref or equivalent stable retry key to `usePresentationTargetStatus`. On retry, set the probe to `checking`, clear the previous failure, and rerun the existing effect. Preserve the existing presentation status labels, but calculate `liveTargetReady` from the probe result independently of `demoState.mode`.
|
||||
|
||||
Keep the hook's cleanup guard so a response from an obsolete probe cannot overwrite newer status.
|
||||
|
||||
- [ ] **Step 4: Thread retry and readiness to the stage**
|
||||
|
||||
Extend `PresentationStage` props with:
|
||||
|
||||
```ts
|
||||
readonly retryHealth: () => void;
|
||||
readonly liveTargetReady: boolean;
|
||||
```
|
||||
|
||||
Pass both values from `PresentationRoute`. Do not render UI in this task; the values are needed by the launch control task.
|
||||
|
||||
- [ ] **Step 5: Run the focused tests**
|
||||
|
||||
Run the same command from Step 2. Expected: all target-status tests pass.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```powershell
|
||||
git add web/apps/console/src/presentation/presentation-target-status.ts web/apps/console/src/presentation/presentation-target-status.test.ts web/apps/console/src/presentation/usePresentationTargetStatus.ts web/apps/console/src/presentation/usePresentationTargetStatus.test.tsx web/apps/console/src/presentation/PresentationRoute.tsx web/apps/console/src/presentation/PresentationStage.tsx
|
||||
git commit -m "feat: expose retryable presentation target health"
|
||||
```
|
||||
|
||||
### Task 2: Allow the timeline agent to launch an explicit mode
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/apps/console/src/demo/agent/timelineAgent.ts`
|
||||
- Modify: `web/apps/console/src/demo/agent/timelineAgent.test.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/OperatorChat.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/OperatorChat.test.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Change `runPreparedWorkflow` to accept `mode?: TimelineAgentMode`.
|
||||
- Calling it without an argument preserves current behavior for the chat action.
|
||||
- Calling `runPreparedWorkflow("live")` must call `demo.start("live")` even when the current direct-link state is replay, but only when the configured target is live-capable.
|
||||
- Add `canRunLive: boolean` to `TimelineAgentController`, derived from the configured presentation mode and current status/readiness.
|
||||
|
||||
- [ ] **Step 1: Write failing tests for explicit live launch from replay**
|
||||
|
||||
Add a controller test with a healthy configured target and `demo.state.mode === "replay"`. Assert:
|
||||
|
||||
```tsx
|
||||
await act(async () => result.current.runPreparedWorkflow("live"));
|
||||
expect(start).toHaveBeenCalledWith("live");
|
||||
```
|
||||
|
||||
Add a failed-target test asserting `canRunLive === false` and that the live launch does not call `start("live")`.
|
||||
|
||||
- [ ] **Step 2: Run the focused tests and verify they fail**
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test -- src/demo/agent/timelineAgent.test.tsx src/presentation/OperatorChat.test.tsx
|
||||
```
|
||||
|
||||
Expected: FAIL because `runPreparedWorkflow` has no mode argument and the controller has no explicit live capability.
|
||||
|
||||
- [ ] **Step 3: Implement the explicit mode seam**
|
||||
|
||||
Use the existing `TimelineAgentOptions.mode` and target status/readiness to calculate `canRunLive`. Keep the normal chat action using its current derived mode. Make the explicit mode parameter choose the call to `demo.start`, while guarding against `inFlight` and non-ready phases.
|
||||
|
||||
Do not append a second or duplicate message chain for the Scene 10 control; the existing timeline-agent message projection remains the single chat history source.
|
||||
|
||||
- [ ] **Step 4: Update OperatorChat's existing action call**
|
||||
|
||||
Keep its current behavior and update the function call only as required by the widened signature. The hidden demo scenes must not regain a chat launch button.
|
||||
|
||||
- [ ] **Step 5: Run focused tests**
|
||||
|
||||
Expected: all timeline-agent and OperatorChat tests pass.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```powershell
|
||||
git add web/apps/console/src/demo/agent/timelineAgent.ts web/apps/console/src/demo/agent/timelineAgent.test.tsx web/apps/console/src/presentation/OperatorChat.tsx web/apps/console/src/presentation/OperatorChat.test.tsx
|
||||
git commit -m "feat: support explicit live demo launch"
|
||||
```
|
||||
|
||||
### Task 3: Add the Scene 10 launch surface
|
||||
|
||||
**Files:**
|
||||
- Create: `web/apps/console/src/presentation/DemoRunLaunchControl.tsx`
|
||||
- Create: `web/apps/console/src/presentation/DemoRunLaunchControl.test.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/DemoWorkflowScene.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/DemoWorkflowScene.test.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/SceneBody.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/PresentationStage.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/styles/demo-workflow.css`
|
||||
|
||||
**Interfaces:**
|
||||
|
||||
```tsx
|
||||
type DemoRunLaunchControlProps = {
|
||||
readonly status: PresentationTargetHealth;
|
||||
readonly liveTargetReady: boolean;
|
||||
readonly demo: DemoTimelineController;
|
||||
readonly timelineAgent: TimelineAgentController | undefined;
|
||||
readonly retryHealth: () => void;
|
||||
};
|
||||
```
|
||||
|
||||
The control renders only when `scene.id === "run-from-deployment"` and
|
||||
`beat.id === "operation"`. It must not appear on graph/input/Scene 11/Scene 12
|
||||
beats.
|
||||
|
||||
- [ ] **Step 1: Write component tests**
|
||||
|
||||
Cover these exact states:
|
||||
|
||||
1. healthy target: `Run prepared workflow` is visible and enabled;
|
||||
2. replay direct-link with healthy target: `Run prepared workflow` is still
|
||||
visible and launches live, not replay;
|
||||
3. checking: visible `Checking live service` state and no duplicate start;
|
||||
4. failed target: visible `Play replay walkthrough` and `Retry live service`;
|
||||
5. active/running: duplicate launch is disabled;
|
||||
6. non-operation beat: component renders nothing.
|
||||
|
||||
- [ ] **Step 2: Run tests and verify they fail**
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test -- src/presentation/DemoRunLaunchControl.test.tsx src/presentation/DemoWorkflowScene.test.tsx
|
||||
```
|
||||
|
||||
Expected: FAIL because the component and Scene 10 wiring do not exist.
|
||||
|
||||
- [ ] **Step 3: Implement the control**
|
||||
|
||||
Use explicit, factual labels. The primary action must call
|
||||
`timelineAgent.runPreparedWorkflow("live")` when `liveTargetReady` is true.
|
||||
When the target is unavailable, the primary action calls
|
||||
`timelineAgent.runPreparedWorkflow("replay")`; this is explicitly labelled as
|
||||
replay. `retryHealth` is a separate action and never starts a run.
|
||||
|
||||
The control should expose `role="status"` for the current target/run state and
|
||||
stable accessible names for the actions. Keep the markup compact enough to sit
|
||||
inside Scene 10's operation stage without opening the hidden chat rail.
|
||||
|
||||
- [ ] **Step 4: Thread props and mount only on Scene 10 operation**
|
||||
|
||||
Thread `timelineAgent`, `targetStatus`, `liveTargetReady`, and `retryHealth`
|
||||
through `SceneBody` to `DemoWorkflowScene`. Mount the control beside the
|
||||
operation block only for the operation beat. The rest of the existing graph,
|
||||
approval, output, and trace layout remains unchanged.
|
||||
|
||||
- [ ] **Step 5: Add focused integration tests**
|
||||
|
||||
Assert direct `#scene/run-from-deployment/operation` includes the launch
|
||||
control, while `#scene/run-from-deployment/graph` and
|
||||
`#scene/typed-human-boundary/approval` do not. Assert that clicking the live
|
||||
action calls the explicit live method and does not produce a replay start.
|
||||
|
||||
- [ ] **Step 6: Add scoped CSS**
|
||||
|
||||
Add only `.demo-run-launch-control` styles to
|
||||
`styles/demo-workflow.css`. Use existing presentation tokens, avoid a new
|
||||
theme, and make the live/replay distinction textual and structural rather than
|
||||
relying only on color.
|
||||
|
||||
- [ ] **Step 7: Run focused tests**
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test -- src/presentation/DemoRunLaunchControl.test.tsx src/presentation/DemoWorkflowScene.test.tsx src/presentation/PresentationRoute.test.tsx
|
||||
```
|
||||
|
||||
Expected: all focused tests pass.
|
||||
|
||||
- [ ] **Step 8: Commit**
|
||||
|
||||
```powershell
|
||||
git add web/apps/console/src/presentation/DemoRunLaunchControl.tsx web/apps/console/src/presentation/DemoRunLaunchControl.test.tsx web/apps/console/src/presentation/DemoWorkflowScene.tsx web/apps/console/src/presentation/DemoWorkflowScene.test.tsx web/apps/console/src/presentation/SceneBody.tsx web/apps/console/src/presentation/PresentationStage.tsx web/apps/console/src/presentation/styles/demo-workflow.css
|
||||
git commit -m "feat: expose Scene 10 live replay launch"
|
||||
```
|
||||
|
||||
### Task 4: Preserve truthful mode transitions and fallback
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/apps/console/src/presentation/presentation-target-status.ts`
|
||||
- Modify: `web/apps/console/src/presentation/presentation-target-status.test.ts`
|
||||
- Modify: `web/apps/console/src/presentation/PresentationRoute.tsx`
|
||||
- Modify: `web/apps/console/src/presentation/PresentationRoute.test.tsx`
|
||||
- Modify: `web/apps/console/src/demo/useDemoTimeline.ts`
|
||||
- Modify: `web/apps/console/src/demo/useDemoTimeline.test.tsx`
|
||||
|
||||
- [ ] **Step 1: Add route-level regression tests**
|
||||
|
||||
Test these flows with mocked `callOperation` responses:
|
||||
|
||||
```tsx
|
||||
it("keeps a direct operation hash replay-backed until launch", async () => {
|
||||
// Render direct operation hash; wait for replay facts; assert no live start call.
|
||||
});
|
||||
|
||||
it("starts live only after the Scene 10 action", async () => {
|
||||
// Render direct operation hash with healthy health response; click the launch.
|
||||
// Assert deployment inspect is the first non-health operation.
|
||||
});
|
||||
|
||||
it("offers explicit replay after health failure", async () => {
|
||||
// Reject health; assert the replay action is visible and no run RPC occurred.
|
||||
});
|
||||
```
|
||||
|
||||
Add a timeline test proving that after a live event has been appended, replay
|
||||
priming cannot replace the live event list while the live run is active.
|
||||
|
||||
- [ ] **Step 2: Run tests and verify any missing behavior**
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test -- src/presentation/PresentationRoute.test.tsx src/demo/useDemoTimeline.test.tsx
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Fix mode synchronization**
|
||||
|
||||
Ensure the existing ready-state synchronization does not switch an explicitly
|
||||
started live timeline back to replay merely because the current URL requires a
|
||||
replay stage. The synchronization may prime replay only while the timeline is
|
||||
still `ready` and no explicit live launch has happened.
|
||||
|
||||
When replay is explicitly selected after a failed health check, set replay mode
|
||||
and keep the status copy truthful. Do not synthesize live evidence from the
|
||||
canonical recording.
|
||||
|
||||
- [ ] **Step 4: Verify approval and trace continuation**
|
||||
|
||||
Use the existing `submitSelectedIssues`, `requestRevision`, and trace-read
|
||||
paths. Confirm live resume sends the typed payload and that trace evidence is
|
||||
recorded after the live resume; do not introduce new resume logic in this task.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```powershell
|
||||
git add web/apps/console/src/presentation/presentation-target-status.ts web/apps/console/src/presentation/presentation-target-status.test.ts web/apps/console/src/presentation/PresentationRoute.tsx web/apps/console/src/presentation/PresentationRoute.test.tsx web/apps/console/src/demo/useDemoTimeline.ts web/apps/console/src/demo/useDemoTimeline.test.tsx
|
||||
git commit -m "test: preserve truthful live replay transitions"
|
||||
```
|
||||
|
||||
### Task 5: Documentation and end-to-end verification
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/README.md`
|
||||
- Modify: `docs/current_roadmap.md`
|
||||
- Move: `docs/superpowers/plans/2026-07-12-presentation-live-replay-activation.md` -> `docs/historical/superpowers/plans/2026-07-12-presentation-live-replay-activation.md`
|
||||
|
||||
- [ ] **Step 1: Update user-facing run instructions**
|
||||
|
||||
Document the exact local process:
|
||||
|
||||
```powershell
|
||||
pnpm --dir web dev
|
||||
uv run wf-rpc-server --config examples/lda_report_workflow/wf.config.json --host 127.0.0.1 --port 8765
|
||||
```
|
||||
|
||||
Explain that `5173` is the browser, `8787` is the console server, and
|
||||
`8765/rpc` is the workflow server. Explain that Scene 10's operation beat has
|
||||
the explicit live/replay launch and that direct links remain replay until
|
||||
launch.
|
||||
|
||||
- [ ] **Step 2: Mark the roadmap item complete and archive the plan**
|
||||
|
||||
Replace the stale “Live/replay truth and run activation” entry with a link to
|
||||
the historical plan. Do not alter the separate visual-pass or story-flow
|
||||
items.
|
||||
|
||||
- [ ] **Step 3: Run repository verification**
|
||||
|
||||
```powershell
|
||||
pnpm --dir web --filter @lda/console test
|
||||
pnpm --dir web typecheck
|
||||
pnpm --dir web --filter @lda/console build
|
||||
git diff --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
Expected: all console tests pass, typecheck/build pass with only the known Vite
|
||||
chunk-size warning, diff check has no new whitespace errors, and the only
|
||||
unrelated worktree change remains `Scene8ChatEntry.tsx`.
|
||||
|
||||
- [ ] **Step 4: Run live browser smoke**
|
||||
|
||||
With both servers running, open:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:5173/present#scene/run-from-deployment/operation
|
||||
```
|
||||
|
||||
Verify the following sequence:
|
||||
|
||||
1. `Run prepared workflow` is visible.
|
||||
2. Clicking it sends `workflow.deployments.inspect` through `/api/rpc`.
|
||||
3. The run reaches the typed interrupt without replay replacement.
|
||||
4. Scene 11 approval sends the selected typed payload through
|
||||
`workflow.runs.resume`.
|
||||
5. Scene 12 trace shows live trace evidence.
|
||||
6. Stopping the workflow server produces a visible failure; clicking the
|
||||
explicit replay action starts the canonical recording instead.
|
||||
7. Starting the workflow server again and clicking `Retry live service`
|
||||
restores the live-ready action without a page reload.
|
||||
|
||||
- [ ] **Step 5: Run the final review**
|
||||
|
||||
Run the repository's review workflow against the slice, inspect the diff for
|
||||
accidental `.superpowers` files, and verify that the user-owned
|
||||
`Scene8ChatEntry.tsx` edit is not staged.
|
||||
|
||||
- [ ] **Step 6: Commit documentation/archive changes**
|
||||
|
||||
```powershell
|
||||
git add web/README.md docs/current_roadmap.md docs/historical/superpowers/plans/2026-07-12-presentation-live-replay-activation.md
|
||||
git rm docs/superpowers/plans/2026-07-12-presentation-live-replay-activation.md
|
||||
git commit -m "docs: complete presentation live replay activation"
|
||||
```
|
||||
|
||||
## Self-Review
|
||||
|
||||
- The plan covers target retry, explicit live launch, replay fallback, direct
|
||||
hash behavior, approval/trace continuation, documentation, and browser
|
||||
verification.
|
||||
- No task changes the Scene 1 merge, beat fact checking, or visual cleanup.
|
||||
- All new interfaces are named consistently: `retryHealth`, `liveTargetReady`,
|
||||
`runPreparedWorkflow(mode?)`, and `DemoRunLaunchControl`.
|
||||
- The only intentionally external prerequisite is the already documented
|
||||
`wf-rpc-server`; no new service or dependency is introduced.
|
||||
Reference in New Issue
Block a user