# Scene 10 Guided Product Moment Design

## Purpose

Scene 10 should be the strongest product proof in the defense presentation. It
shows that `lda.chat` owns a durable run, pauses at a typed human boundary,
accepts an operator decision, resumes the same run, and leaves inspectable
output/trace evidence.

The current implementation is functionally correct but still reads like several
widgets placed on a slide. The next slice should turn it into a guided product
moment: one dominant visual per beat, immediate readiness on deep links, and
clear transitions from decision to proof.

## Problem

The approval beat currently has three UX problems:

1. **Delayed readiness:** a direct link to
   `#scene/interrupt-evidence/approval` starts replay from the beginning, so the
   approval controls remain disabled until autoplay reaches the interrupt.
2. **Weak hierarchy:** graph, receipt, schema approval, continuity rail, and
   discussion links compete. The viewer must infer which part matters now.
3. **Unclear consequence:** after Submit or Cancel, the UI changes technically,
   but it does not strongly explain what happened to the persisted run.

These are not backend problems. They are presentation-state and composition
problems.

## Design Goal

Make Scene 10 feel like a product flow:

```text
paused persisted run
  -> schema-backed operator decision
  -> same run resumes
  -> output appears outside chat
  -> trace/evidence remains inspectable
```

The presenter should be able to say less because the screen already answers:

- What is waiting?
- What decision is required?
- What happens after Submit?
- Why is Cancel not fake evidence?
- Where is the proof?

## Scope

In scope:

- Scene 10 and immediately related demo timeline projection.
- Replay readiness for direct hashes in Scenes 9 and 10.
- Visual hierarchy for approval/resume/output/trace beats.
- Clear copy for live vs replay proof.
- Tests that pin direct-link readiness and post-decision outcomes.

Out of scope:

- Replacing chat with AI Elements or AI SDK.
- Building a presenter companion.
- Adding a new workflow graph engine.
- Changing Python workflow runtime behavior.
- Adding a new cancelled replay recording.

## Core Interaction

### Direct route readiness

When the route opens a demo beat, replay state should be primed to the minimum
event boundary needed by that beat.

Examples:

- `workflow-demo/operation`: needs `run_start`.
- `workflow-demo/interrupt`: needs `interrupt`.
- `interrupt-evidence/approval`: needs `interrupt`.
- `interrupt-evidence/resume`: needs `run_resume`.
- `interrupt-evidence/output`: needs `completed` or `run_resume` output.
- `interrupt-evidence/trace`: needs `trace_read` or `completed` trace.

This is a presentation projection, not a runtime mutation. Live mode still
executes sequentially when the operator starts the prepared workflow.

### Approval

On the approval beat:

- Submit is enabled immediately when replay has been primed to the interrupt.
- Submit applies the existing submitted replay branch and jumps to `resume`.
- Cancel marks the decision as cancelled and stays on approval.
- Cancel must not display `workflow.runs.resume` in replay.
- The UI should state that replay has no cancelled run evidence.

### Hierarchy

Each beat gets one dominant visual:

- Approval: schema-backed decision surface.
- Resume: operation block for `workflow.runs.resume`.
- Output: result/output panel.
- Trace: trace/evidence receipt.

The graph is context, not the hero, during approval and resume. It may remain as
a compact strip or mini-map, but it must not compete with the decision or
operation proof.

## Components

### Beat Readiness Projection

Add a small model that maps beat IDs to required replay stages.

```ts
export type DemoBeatRequirement = {
  readonly requiredStage: DemoEvent["stage"] | null;
  readonly reason: string;
};
```

This model should live near the existing demo presentation model, not in the
generic timeline reducer. It is presentation-specific.

### Guided Product Moment

Add a presentation component for Scene 10 composition. It can reuse existing
building blocks but owns the hierarchy.

```tsx
<GuidedProductMoment
  beat={beat}
  demo={demo}
  contract={contract}
  operation={operation}
  approvalActions={approvalActions}
  openEvidence={openEvidence}
/>
```

It should avoid nested cards. Use a clear primary region, a slim context region,
and a proof footer/receipt.

### Decision Status Copy

The approval surface should show one of these states:

- Ready: "Run is paused. Submit resumes this same run."
- Submitted: "Submitted. Same run resumed."
- Cancelled: "Cancelled in presentation replay. No resume evidence is shown."

Do not describe replay cancellation as a real persisted cancelled run unless a
live run actually produced that evidence.

## Data Flow

```text
PresentationRoute location
  -> beat readiness requirement
  -> useDemoTimeline primes replay events for that beat
  -> SceneBody/DemoWorkflowScene receives ready demo state
  -> GuidedProductMoment renders the single dominant proof
```

Approval actions stay route-owned:

```text
SchemaApprovalSurface
  -> DemoApprovalActions
  -> PresentationRoute
  -> useDemoTimeline submit/cancel
  -> hash jump or local cancelled state
```

## Testing Requirements

Route tests:

- Direct approval hash renders enabled Submit/Cancel without waiting for
  autoplay.
- Direct resume hash renders `workflow.runs.resume` without waiting for
  autoplay.
- Submit advances to resume and shows resume proof.
- Cancel stays on approval, shows cancelled copy, and does not show resume
  evidence after a delay.

Model tests:

- Beat requirement mapping covers all demo beats.
- Unknown beat returns no requirement.

Component tests:

- Approval beat marks the decision surface as the hero.
- Resume beat marks the operation block as the hero.
- Output/trace beats do not show approval controls.

Visual smoke:

- Capture approval, resume, output, and trace at 1280x720.
- Approval should have one dominant decision surface.
- Resume should have one dominant operation proof.

## Success Criteria

- A direct link to approval is immediately interactive.
- Submit and Cancel consequences are clear without verbal explanation.
- No fake cancelled replay evidence appears.
- Scene 10 reads as one product flow rather than a collection of widgets.
- Existing `/console` behavior is unchanged.