docs: reconcile consolidated defense story
This commit is contained in:
@@ -1,709 +0,0 @@
|
||||
# Defense Presentation Storyboard Design
|
||||
|
||||
## Status
|
||||
|
||||
Current narrative and composition contract for the lda.chat thesis defense.
|
||||
|
||||
This document defines what the presentation must communicate and how the stage
|
||||
changes while it does so. It complements the
|
||||
[React presentation mode design](2026-07-03-react-presentation-mode-design.md),
|
||||
which defines the existing route and component architecture, and the
|
||||
[constrained demo agent design](2026-07-03-constrained-demo-agent-design.md),
|
||||
which defines the prepared replay driver.
|
||||
|
||||
## Purpose
|
||||
|
||||
The defense must explain a systems contribution, demonstrate a real product
|
||||
surface, and survive unreliable network or model access. The current `/present`
|
||||
route proves that the components can be composed, but it does not yet provide a
|
||||
coherent defense story or fit the content into a `1280x720` viewport.
|
||||
|
||||
The presentation is not a conventional slide deck wrapped around a separate
|
||||
demo. It is a staged React compositor. Thesis claims, architecture diagrams,
|
||||
chat, workflow graphs, operations, interrupt approval, outputs, and evidence
|
||||
occupy the same stable stage and move between semantic scenes.
|
||||
|
||||
The listed scene budgets total 8 minutes 36 seconds. Rehearsal should target a
|
||||
10-to-11-minute main path after transitions, approval interaction, and natural
|
||||
pauses. This leaves margin in a 15-minute slot without forcing the presenter to
|
||||
rush.
|
||||
|
||||
## Speaking Voice
|
||||
|
||||
The spoken script primarily uses personal defense voice:
|
||||
|
||||
- "I designed and implemented ..."
|
||||
- "I evaluated ..."
|
||||
- "I deliberately excluded ..."
|
||||
|
||||
Technical invariants remain neutral where precision matters:
|
||||
|
||||
- "The runtime validates the payload before execution."
|
||||
- "A deployment binds logical requirements to concrete sources."
|
||||
|
||||
This keeps ownership clear without making the system sound subjective.
|
||||
|
||||
## Claim Discipline
|
||||
|
||||
Every scene carries one claim class. The visual treatment must make the class
|
||||
clear without requiring the presenter to recite a disclaimer.
|
||||
|
||||
- **Motivation:** problem framing or design rationale; not an empirical result.
|
||||
- **Implemented:** supported by current code, tests, or a product operation.
|
||||
- **Evaluated:** supported by the thesis case studies or the audited 36-trial
|
||||
challenge cohort.
|
||||
- **External context:** a cited result from another organization; not evidence
|
||||
about lda.chat.
|
||||
- **Future work:** a plausible extension that is not part of the submitted
|
||||
implementation.
|
||||
|
||||
Each scene definition must retain an evidence pointer. An evidence pointer may
|
||||
be a thesis section, repository path, deterministic replay event, test group, or
|
||||
external source. A scene without an evidence pointer may present motivation or
|
||||
transition language, but it may not introduce a new factual claim.
|
||||
|
||||
## Stable Stage Geography
|
||||
|
||||
The presentation uses three canonical layers:
|
||||
|
||||
- **Editorial Canvas:** the persistent warm, light visual identity used for the
|
||||
spoken argument, figures, and transitions.
|
||||
- **Product Surface:** a real application or evidence surface that expands from
|
||||
an inline trigger when the story requires product proof.
|
||||
- **Presentation Frame:** the thin remainder of the Editorial Canvas that stays
|
||||
visible around an expanded Product Surface.
|
||||
|
||||
The presentation is therefore an editorial thesis deck that temporarily
|
||||
transforms into the product. It is not a dashboard or chat application used as
|
||||
a decorative container for every scene.
|
||||
|
||||
The stage has two stable content regions and one transient inspection layer:
|
||||
|
||||
```text
|
||||
+----------------+--------------------------------+
|
||||
| agent / chat | primary graph, model, output |
|
||||
| optional | always owns visual focus |
|
||||
+----------------+--------------------------------+
|
||||
| progress and compact evidence receipt |
|
||||
+-------------------------------------------------+
|
||||
```
|
||||
|
||||
The regions may expand, collapse, or overlap, but they do not swap meanings.
|
||||
The audience should learn the geography once. A Product Surface may occupy
|
||||
roughly 80 percent of the stage, but it does not erase the Presentation Frame;
|
||||
the audience must still read it as evidence inside the argument rather than an
|
||||
accidental application switch.
|
||||
|
||||
- **Left:** agent conversation and operation intent.
|
||||
- **Center:** the primary explanation, workflow graph, output, or evaluation
|
||||
result.
|
||||
- **Overlay:** raw and interpreted evidence, trace, schemas, or source details.
|
||||
|
||||
Narrative scenes hide chat. Demo scenes may show chat as `full`, `rail`, or
|
||||
`dock`. Evidence appears as a compact progress-row receipt unless the presenter
|
||||
explicitly opens the centered inspector.
|
||||
|
||||
The dock remains visible in a corner when chat is otherwise hidden. Pointer
|
||||
hover may preview it, but opening chat requires a click, keyboard action, or
|
||||
presenter control so the interaction remains usable without a precise mouse.
|
||||
|
||||
Vertical stacking is forbidden on the main path. Across supported logical
|
||||
canvases from `960x720` through `1280x720`, the presenter must not scroll to
|
||||
discover the graph, approval control, output, or next action.
|
||||
|
||||
The audience route keeps a deterministic `720px` logical height and adapts its
|
||||
logical width continuously from `960px` to `1280px`, covering `4:3` through
|
||||
`16:9`. Container queries adapt placement without omitting information.
|
||||
Unsupported extreme ratios letterbox. Presenter and audience views preserve
|
||||
the same semantic content and Focus Path. See the
|
||||
[adaptive presentation canvas design](2026-07-05-adaptive-presentation-canvas-design.md).
|
||||
|
||||
## Unified Presentation Identity
|
||||
|
||||
The Editorial Canvas keeps one warm, light identity from introduction through
|
||||
conclusion. Product surfaces may use their native light or dark appearance,
|
||||
but entering a product surface does not switch the theme of the entire deck.
|
||||
Chat remains independently positioned because it is a product element, not the
|
||||
presentation's visual identity:
|
||||
|
||||
See [ADR 0005](../../adr/0005-editorial-canvas-around-shared-product-surfaces.md).
|
||||
|
||||
Major claims use an editorial display serif, provisionally Newsreader. Source
|
||||
Sans 3 remains the explanatory and interface face, while IBM Plex Mono is
|
||||
reserved for commands, identifiers, schemas, and evidence. Condensed all-caps
|
||||
type is an accent rather than the default title treatment.
|
||||
|
||||
```ts
|
||||
type PresentationAppearance = {
|
||||
readonly chatMode: "hidden" | "full" | "rail" | "dock";
|
||||
readonly productExpansion: "inline" | "expanded";
|
||||
};
|
||||
```
|
||||
|
||||
A rehearsal toolbar may override chat position, product expansion, motion,
|
||||
playback mode, and scene selection. It is hidden during the defense.
|
||||
|
||||
Remote or phone control is not required for the redesign. Presentation actions
|
||||
remain input-agnostic so a later remote can dispatch them, but keyboard and
|
||||
pointer operation are the supported defense controls.
|
||||
|
||||
## Defense Chrome
|
||||
|
||||
The audience-facing route persistently shows only a quiet scene number or
|
||||
progress marker. The full scene rail, replay status, discussion index,
|
||||
presenter controls, and prepared-agent trigger are hidden until explicitly
|
||||
summoned.
|
||||
|
||||
On first visit, a dismissible presenter onboarding overlay explains navigation
|
||||
and rehearsal controls. Afterwards, `?` opens a presenter-only command and
|
||||
shortcut palette. Presenter controls are therefore discoverable without
|
||||
becoming persistent audience chrome; the existing secret `P` shortcut is not a
|
||||
sufficient interface.
|
||||
|
||||
A separate `/presenter` companion route shows the current and next beat,
|
||||
speaker notes, timer, Discussion Library, and presentation controls without
|
||||
exposing them on the projected `/present` route. A temporary notes overlay on
|
||||
`/present` remains the single-screen fallback.
|
||||
|
||||
Audience and presenter routes communicate through a typed **Presentation
|
||||
Transport** that carries reducer actions. The first adapter uses
|
||||
`BroadcastChannel` for same-browser windows. A future authenticated WebSocket
|
||||
relay may connect different machines or networks using the same event contract;
|
||||
that relay does not execute workflows or own presentation semantics.
|
||||
|
||||
The presenter palette includes a searchable **Discussion Library** instead of
|
||||
an audience-facing discussion button. Opening a prepared question stores the
|
||||
exact scene, beat, and Focus Path. Closing the discussion restores that return
|
||||
location.
|
||||
|
||||
The prepared workflow starts from the chat surface, provisionally through a
|
||||
button or slash command, rather than through a detached corner action. This
|
||||
entry point is part of the product story and may later be replaced by a fuller
|
||||
chat framework without changing the presentation contract.
|
||||
|
||||
A **Guided Run** is the prepared agent sequence used during the defense. The
|
||||
presentation timeline owns its pacing. After emitting the content permitted by
|
||||
the current beat, the driver waits at a **Beat Gate** until the presenter
|
||||
advances. Advancing releases at most the next audience-relevant operation;
|
||||
internal or repetitive actions remain hidden.
|
||||
|
||||
The chat starts a Guided Run through a visible **Prompt Macro**, provisionally
|
||||
`/demo report`. Invoking it expands into the full natural-language request, and
|
||||
the transcript displays that expanded request rather than a raw slash command.
|
||||
Expandable provenance may identify the originating macro.
|
||||
|
||||
The audience sees a quiet execution provenance label, `Prepared replay` or
|
||||
`Live server`, but no mode controls. Live and replay drivers must produce the
|
||||
same Guided Run and Beat Gate structure. If live setup fails, replay replaces
|
||||
it without changing the presentation narrative or interaction sequence.
|
||||
|
||||
Only one audience-relevant operation may cross a Beat Gate at a time. If a live
|
||||
operation is still running, further advance input does not launch another
|
||||
operation or skip the gate. The beat shows a restrained working state, and a
|
||||
presenter-only action may replace that operation with its prepared replay.
|
||||
|
||||
If a live operation fails, its failed Chat Tool Receipt remains visible. The
|
||||
presenter may explicitly choose `Continue with prepared replay`; the
|
||||
continuation changes the provenance label and never rewrites the failed live
|
||||
evidence.
|
||||
|
||||
An audience-relevant operation has two independent projections from the same
|
||||
canonical event:
|
||||
|
||||
- **Chat Tool Receipt:** a subtle collapsed chat row, expandable on demand into
|
||||
a bounded, scrollable terminal-style detail. A future chat framework should
|
||||
own its interaction and accessibility.
|
||||
- **Stage Projection:** a curated operation view rendered only when the current
|
||||
argument needs that operation as evidence.
|
||||
|
||||
The Chat Tool Receipt does not physically morph into the Stage Projection.
|
||||
Their continuity is semantic and timeline-driven, which avoids coupling chat
|
||||
layout to presentation choreography.
|
||||
|
||||
A pending typed interrupt creates one **Approval Session** with synchronized
|
||||
chat and Product Surface projections. Chat presents a compact approval card and
|
||||
selection summary; the Product Surface presents the full schema-backed list or
|
||||
form. Edits from either projection update the same draft response. Submission
|
||||
from either resolves the interrupt exactly once, then both projections become
|
||||
read-only with the same result.
|
||||
|
||||
Both projections consume a reusable **Schema Form Surface** rather than
|
||||
hand-built interrupt fields. It accepts JSON Schema, a draft value, validation
|
||||
state, read-only state, and custom widget registrations. Typed interrupts are
|
||||
the first consumer; deployment inputs, run inputs, and future configuration
|
||||
surfaces may reuse the same boundary. Domain-specific interactions such as
|
||||
issue selection are custom widgets over the generic form contract.
|
||||
|
||||
The Schema Form Surface lives in a small shared web package. Console and
|
||||
presentation surfaces import that package, while app-specific widgets and
|
||||
Approval Session orchestration remain in their owning applications.
|
||||
|
||||
Chat rendering uses source-owned, established AI-chat primitives rather than
|
||||
project-specific message and tool-call components. The adopted surface must
|
||||
cover conversation, message, collapsed tool receipt, bounded terminal detail,
|
||||
and prompt input. It owns rendering and accessibility only;
|
||||
`AgentMessagePart`, `AgentDriver`, Guided Run, and Beat Gate semantics remain
|
||||
project contracts.
|
||||
|
||||
Tailwind and shadcn-compatible styling may be introduced additively for these
|
||||
source-owned primitives and new presentation components. Existing console CSS
|
||||
is not subject to a wholesale rewrite; it migrates only when a component is
|
||||
replaced. See [ADR 0004](../../adr/0004-adopt-tailwind-additively-for-source-owned-ui.md).
|
||||
|
||||
## Motion Contract
|
||||
|
||||
Motion uses only three primitives:
|
||||
|
||||
- **Reveal:** a fast opacity transition introduces genuinely new explanatory
|
||||
content.
|
||||
- **Expand:** an existing object grows into a Product Surface while preserving
|
||||
its identity.
|
||||
- **Reframe:** existing content moves aside to retain context while another
|
||||
surface takes focus.
|
||||
|
||||
Unchanged objects do not remount or replay entrance animation between beats.
|
||||
Blur, bounce, generic stagger, and decorative typewriter effects are forbidden.
|
||||
Reduced-motion mode replaces Expand and Reframe with immediate layout changes
|
||||
and keeps Reveal brief.
|
||||
|
||||
## Interactive Figures
|
||||
|
||||
Architecture, authoring, workflow, and evidence diagrams use a shared
|
||||
**Interactive Figure** model rather than scene-specific card layouts. An
|
||||
Interactive Figure contains addressable **Figure Nodes** and relationships.
|
||||
Graph-shaped figures may use the existing React Flow and Dagre dependencies;
|
||||
linear figures may use lighter SVG or HTML renderers over the same interaction
|
||||
contract.
|
||||
|
||||
A Figure Node may reference a child figure. Activating it pushes the node onto
|
||||
a single **Focus Path** and reframes the canvas around that child figure.
|
||||
Ancestors remain available through a compact breadcrumb, and `Escape` pops one
|
||||
focus level. A child figure may contain further expandable nodes, but only one
|
||||
Focus Path is active; the interface never stacks nested modals or sidebars.
|
||||
|
||||
Normal figures are authored as declarative TypeScript definitions containing
|
||||
nodes, relationships, semantic types, child-figure references, and canonical
|
||||
Focus Paths. The shared renderer owns layout, focus, keyboard behavior, and
|
||||
motion. A custom React renderer is an explicit escape hatch for exceptional
|
||||
figures rather than the default scene-authoring mechanism.
|
||||
|
||||
Factual architecture and evaluation nodes carry evidence pointers in their
|
||||
definitions. Those pointers remain hidden during the normal path and become
|
||||
available through focused inspection, Q&A, or the evidence surface.
|
||||
Motivational nodes may omit evidence pointers.
|
||||
|
||||
Main-path Figure Node labels use system concepts such as “Runtime” or “Source
|
||||
providers.” Focused detail may reveal concrete packages, public operations,
|
||||
tests, or symbols such as `wf_core` and `wf_api`.
|
||||
|
||||
Initial figure layout supports only layered, flow, and explicit-position modes.
|
||||
Dagre may calculate spacing inside the first two. A new reusable layout mode is
|
||||
added only after at least two concrete figures require it; the presentation is
|
||||
not a general diagram-layout engine.
|
||||
|
||||
Interactive Figures expose keyboard navigation: `Tab` reaches Figure Nodes,
|
||||
arrow keys move spatially between related nodes, `Enter` expands the focused
|
||||
node, and `Escape` pops one Focus Path level. Breadcrumbs remain pointer and
|
||||
keyboard accessible. The presenter `?` palette lists these controls when figure
|
||||
focus is active.
|
||||
|
||||
While a Figure Node owns focus, arrow keys belong to the figure. `Escape`
|
||||
returns focus to the presentation stage, after which arrows navigate beats.
|
||||
`Space` remains a global advance shortcut except while focus is inside chat,
|
||||
forms, terminal detail, or another text-entry control.
|
||||
|
||||
Each beat may declare a canonical Focus Path for deterministic playback.
|
||||
Presenter interaction may temporarily replace it for explanation or Q&A.
|
||||
Advancing to another beat applies that beat's canonical Focus Path, preventing
|
||||
manual exploration from making later scenes nondeterministic.
|
||||
|
||||
Canonical deep links encode scene, beat, and optional Focus Path so an
|
||||
interactive figure state can be reproduced directly. Ephemeral UI state such
|
||||
as chat scroll, expanded Chat Tool Receipts, and presenter-palette visibility
|
||||
does not enter the URL.
|
||||
|
||||
Editorial figures use restrained semantic color:
|
||||
|
||||
- blue identifies planner or client intent;
|
||||
- green identifies deterministic runtime execution;
|
||||
- orange identifies human boundaries or intervention.
|
||||
|
||||
The warm canvas and black typography remain dominant. Labels, connector styles,
|
||||
and node shapes must carry the same distinction when color is unavailable.
|
||||
|
||||
The renderer exposes a small **Figure Vocabulary** rather than one universal
|
||||
rounded node: actors, operations, artifacts, runtime systems, human boundaries,
|
||||
and evidence. Scenes compose those primitives differently so they share
|
||||
interaction behavior without looking mechanically generated from one template.
|
||||
|
||||
Visual personality primarily comes from expressive scale, asymmetry, direct
|
||||
figure manipulation, memorable scene transformations, and occasional
|
||||
purpose-built illustration or iconography. Decorative gradients, badges, and
|
||||
background effects are permitted only when they support a specific scene; they
|
||||
are not the default source of visual interest.
|
||||
|
||||
The workflow graph in the product demonstration is not reconstructed through
|
||||
the Figure Vocabulary. It embeds the real console graph component, driven by
|
||||
the canonical workflow and run state, inside an expanded Product Surface.
|
||||
Editorial annotations may explain it without replacing the product evidence.
|
||||
|
||||
Product Surfaces use the console's shared components and design tokens rather
|
||||
than a presentation-only skin. Improving graph, form, receipt, or evidence
|
||||
styling therefore improves both `/console` and `/present`; presentation code
|
||||
controls only framing, scale, and when a surface is shown.
|
||||
|
||||
The main defense path uses the console's light product theme to remain coherent
|
||||
with the warm Editorial Canvas. Dark mode remains available in the console but
|
||||
is not part of the main defense sequence. Terminal and code insets may remain
|
||||
dark when that treatment communicates their actual content type.
|
||||
|
||||
## Scene Semantics
|
||||
|
||||
A scene is larger than a slide. It is a semantic chapter composed from several
|
||||
visual states. Text, diagrams, operations, graphs, and evidence may enter,
|
||||
leave, expand, or collapse while the scene id remains stable.
|
||||
|
||||
Advancing within a scene changes a **beat**. Advancing after the final beat
|
||||
changes the **scene**. Discussion branches can return to the exact scene and
|
||||
beat from which they were opened.
|
||||
|
||||
Each beat definition carries its short visible claim, speaker notes, timing
|
||||
budget, evidence pointer, visual or figure id, canonical Focus Path, and
|
||||
optional Beat Gate. Components render that definition; they do not own the
|
||||
spoken script or duplicate scene-specific content.
|
||||
|
||||
At `1280x720`, each beat presents one primary visual, one short claim, and at
|
||||
most three supporting labels. A command, schema, or evidence view may replace
|
||||
the primary visual but does not compete beside another primary visual. Speaker
|
||||
notes carry details that do not fit this composition budget.
|
||||
|
||||
## Main Storyboard
|
||||
|
||||
The sequence below preserves the current argument and evidence order, but its
|
||||
exact scene boundaries and beat counts are not frozen. Visual redesign may
|
||||
merge, split, or re-time scenes when the claim order, evidence coverage,
|
||||
discussion returns, and overall defense budget remain intact.
|
||||
|
||||
Visual review uses a Playwright-generated gallery of selected beats at
|
||||
`1280x720` plus manual traversal in the browser. Automated checks cover state,
|
||||
keyboard behavior, accessibility, overflow, and interaction contracts. The
|
||||
gallery supports human approval and is not initially enforced through brittle
|
||||
pixel-diff thresholds.
|
||||
|
||||
The redesign preserves public navigation, canonical replay evidence, and
|
||||
useful reducer actions. It removes obsolete internal contracts cleanly,
|
||||
including whole-stage theme switching, one-off diagram components, persistent
|
||||
audience chrome, and presentation-only product skins. Unused UI APIs do not
|
||||
receive compatibility wrappers.
|
||||
|
||||
### Scene 1: Thesis
|
||||
|
||||
- **Time:** 0:20
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** "I began with the goal of building an AI agent for creating
|
||||
and automating workspace workflows. That exposed a more fundamental need: a
|
||||
typed system for creating, validating, running, and inspecting the workflows
|
||||
that an agent proposes. This thesis implements that substrate."
|
||||
- **Primary visual:** title and one-sentence thesis.
|
||||
- **Composition:** warm Editorial Canvas; chat hidden; no evidence panel.
|
||||
- **Evidence pointer:** thesis Abstract and Introduction.
|
||||
- **Transition:** the title contracts into a small persistent lda.chat mark.
|
||||
|
||||
### Scene 2: The Problem
|
||||
|
||||
- **Time:** 0:40
|
||||
- **Claim class:** Motivation
|
||||
- **Spoken intent:** direct agent tool calls can perform actions, but reusable
|
||||
automation also needs typed contracts, lifecycle state, source bindings,
|
||||
deterministic execution, persistence, traceability, and recovery boundaries.
|
||||
- **Primary visual:** an unstable sequence of direct tool calls contrasted with
|
||||
a durable workflow record; the missing responsibilities appear around it.
|
||||
- **Composition:** warm Editorial Canvas; chat hidden.
|
||||
- **Evidence pointer:** thesis problem statement, requirements, and research
|
||||
question.
|
||||
- **Transition:** the requirements arrange into a landscape of related systems.
|
||||
|
||||
### Scene 3: Positioning and Related Systems
|
||||
|
||||
- **Time:** 0:50
|
||||
- **Claim class:** Motivation
|
||||
- **Spoken intent:** direct tool loops maximize flexibility, generated scripts
|
||||
maximize simplicity, hosted automation platforms provide mature triggers and
|
||||
integrations, agent graph frameworks provide durable agent execution, and
|
||||
MCP standardizes capability access. lda.chat explores a different center of
|
||||
gravity: typed lifecycle contracts and provider-neutral sources intended for
|
||||
external-agent operation.
|
||||
- **Primary visual:** related approaches progressively occupy distinct positions
|
||||
around lda.chat; do not reproduce the thesis comparison table.
|
||||
- **Composition:** warm Editorial Canvas; each approach enters while the positioning axis
|
||||
remains stable.
|
||||
- **Evidence pointer:** thesis Positioning and Related Systems chapter.
|
||||
- **Transition:** lda.chat's position resolves into the planner/runtime boundary.
|
||||
|
||||
### Scene 4: Planner and Runtime
|
||||
|
||||
- **Time:** 0:40
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** the external planner proposes or revises workflow
|
||||
structure; the deterministic runtime validates, executes, records, and
|
||||
resumes it.
|
||||
- **Primary visual:** a two-sided planner/runtime boundary with explicit
|
||||
operations crossing it.
|
||||
- **Composition:** warm Editorial Canvas; chat hidden; the planner/runtime
|
||||
boundary carries its own semantic color and shape treatment.
|
||||
- **Evidence pointer:** thesis architecture overview and workflow API boundary.
|
||||
- **Transition:** the runtime side expands into the lifecycle.
|
||||
|
||||
### Scene 5: Lifecycle
|
||||
|
||||
- **Time:** 1:00
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** explain Draft, Artifact, Deployment, and Run as distinct
|
||||
records with different mutability and responsibility.
|
||||
- **Primary visual:** lifecycle records, including both draft-save and direct
|
||||
plan-import paths into an immutable artifact.
|
||||
- **Composition:** warm Editorial Canvas; center focus; the progress row may
|
||||
show one compact evidence receipt.
|
||||
- **Evidence pointer:** thesis lifecycle chapter and lifecycle explorer.
|
||||
- **Transition:** selecting a deployment zooms into the runtime architecture.
|
||||
|
||||
### Scene 6: Architecture Zoom
|
||||
|
||||
- **Time:** 1:25
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** walk from client operations through JSON-RPC, WorkflowApi,
|
||||
providers and stores, then into the graph runner and one `NodeUse` execution.
|
||||
- **Primary visual:** semantic zoom through four levels rather than four
|
||||
unrelated diagrams.
|
||||
- **Composition:** warm Editorial Canvas; chat hidden; the evidence receipt
|
||||
exposes concrete package or operation names without resizing the figure.
|
||||
- **Evidence pointer:** thesis architecture diagrams, `docs/project_map.md`, and
|
||||
`docs/source_architecture.md`.
|
||||
- **Transition:** the semantic zoom backs out into the public authoring surface.
|
||||
|
||||
### Scene 7: Author, Validate, Repair
|
||||
|
||||
- **Time:** 0:45
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** show discovery, focused draft operations, validation
|
||||
diagnostics, repair hints, compilation, and save as one machine-operable
|
||||
loop.
|
||||
- **Primary visual:** an operation sequence with one structured diagnostic and
|
||||
its repair action.
|
||||
- **Composition:** warm Editorial Canvas; chat hidden; a locally dark operation
|
||||
or terminal block may occupy center while the evidence receipt updates below.
|
||||
- **Evidence pointer:** CLI documentation, draft authoring API, and challenge
|
||||
UX findings.
|
||||
- **Transition:** the operation block becomes the first card in the agent UI.
|
||||
|
||||
### Scene 8: Agent Handoff
|
||||
|
||||
- **Time:** 0:20
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** "The submitted contribution is the substrate. This prepared
|
||||
agent interaction shows how a thin external interface can operate it."
|
||||
- **Primary visual:** a standard AI application surface enters full-screen.
|
||||
- **Composition:** source-owned light chat surface expands within the warm
|
||||
Editorial Canvas; evidence hidden.
|
||||
- **Evidence pointer:** constrained demo agent design and prepared replay recipe.
|
||||
- **Transition:** the operator request and first operation appear immediately.
|
||||
|
||||
### Scene 9: Workflow Takes the Stage
|
||||
|
||||
- **Time:** 0:45
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** the prepared agent invokes the report workflow; the visible
|
||||
tool call expands into raw and interpreted operation output; the workflow
|
||||
graph becomes primary.
|
||||
- **Primary visual:** operation card transforming into the report workflow
|
||||
graph.
|
||||
- **Composition:** chat moves from full to rail; graph owns center; evidence
|
||||
remains collapsed.
|
||||
- **Evidence pointer:** prepared recording events and
|
||||
`examples/lda_report_workflow/`.
|
||||
- **Transition:** execution stops at the typed `issue_review` interrupt.
|
||||
|
||||
### Scene 10: Interrupt, Resume, Evidence
|
||||
|
||||
- **Time:** 1:30
|
||||
- **Claim class:** Implemented
|
||||
- **Spoken intent:** explain the typed approval contract, approve selected
|
||||
issues, resume the same run, then show the generated report, issue-board
|
||||
writes, trace frames, and raw/interpreted evidence.
|
||||
- **Primary visual:** interrupt approval followed by output and trace projection.
|
||||
- **Composition:** chat rail during approval, then dock; center alternates
|
||||
between interrupt, output, and trace; the centered evidence inspector opens
|
||||
once through an explicit action.
|
||||
- **Evidence pointer:** deterministic replay recording, typed interrupt schemas,
|
||||
run inspect result, and trace events.
|
||||
- **Failure fallback:** if the live server or operation fails, switch to the
|
||||
reviewed replay at the current semantic event without resetting the layout or
|
||||
explaining a new UI.
|
||||
- **Transition:** trace frames collapse into evaluation evidence.
|
||||
|
||||
### Scene 11: Evaluation
|
||||
|
||||
- **Time:** 1:25
|
||||
- **Claim class:** Evaluated
|
||||
- **Spoken intent:** present the 36-trial cohort as bounded agent-operability and
|
||||
longitudinal product evidence, not a model leaderboard or broad success-rate
|
||||
estimate.
|
||||
- **Primary visual:** cohort structure, audited validity, failure classes, and
|
||||
selected product improvements discovered through trials.
|
||||
- **Composition:** warm Editorial Canvas; chat hidden; one chart at a time; the
|
||||
evidence receipt links to the audit/run records.
|
||||
- **Evidence pointer:** thesis evaluation chapter, Appendix C, generated cohort
|
||||
figures, and challenge reports.
|
||||
- **Transition:** limitations remain while the charts simplify into the final
|
||||
planner/runtime boundary.
|
||||
|
||||
### Scene 12: Limits and Conclusion
|
||||
|
||||
- **Time:** 1:00
|
||||
- **Claim class:** Future work
|
||||
- **Spoken intent:** distinguish implemented substrate from a future live LLM
|
||||
interface, production security, scheduling, broader model evaluation, and
|
||||
comparative studies; end on the planner/runtime separation.
|
||||
- **Primary visual:** implemented core in focus, future layers around it, then
|
||||
the one-sentence thesis.
|
||||
- **Composition:** warm Editorial Canvas; chat dock may remain as a
|
||||
subtle reminder that the agent is a client of the substrate.
|
||||
- **Evidence pointer:** thesis limitations and future-work chapters.
|
||||
- **Transition:** none; hold a stable conclusion frame for questions.
|
||||
|
||||
## Presenter Controls
|
||||
|
||||
The presenter needs a hidden or unobtrusive rehearsal surface with:
|
||||
|
||||
- next and previous scene;
|
||||
- direct scene jump by number or hash;
|
||||
- current and next speaker note;
|
||||
- elapsed and planned time;
|
||||
- audience progress and current Focus Path;
|
||||
- motion reduction toggle;
|
||||
- replay/live indicator and forced replay fallback;
|
||||
- reset to the start of the current scene;
|
||||
- open Q&A index.
|
||||
|
||||
The audience view must not expose these controls unless explicitly opened.
|
||||
The same semantic control actions may later be exposed to a phone or second
|
||||
device. This storyboard does not choose the remote-control transport, host, or
|
||||
deployment topology.
|
||||
|
||||
## Discussion Branches
|
||||
|
||||
Discussion branches are prepared scenes outside the main timer. They attach to
|
||||
the main story at semantically relevant points and return to the originating
|
||||
scene and beat.
|
||||
|
||||
Scene 3 owns the first branch group:
|
||||
|
||||
- **3A Direct orchestration:** dynamic adaptation versus durable reusable
|
||||
procedure.
|
||||
- **3B Generated scripts:** simplicity and debuggability versus managed
|
||||
lifecycle records.
|
||||
- **3C Hosted automation:** integrations, triggers, scheduling, and operational
|
||||
maturity. A concrete future-work example may ask an agent to prepare a
|
||||
recurring workflow that starts a headless coding agent with a prompt. The
|
||||
exact command must be verified before presentation; scheduling remains
|
||||
outside the implemented lda.chat scope.
|
||||
- **3D Durable agent graphs:** overlap with LangGraph-style persistence and
|
||||
human-in-the-loop execution, and the distinct artifact/deployment/source
|
||||
binding emphasis in this work.
|
||||
- **3E MCP and agent-facing scale:** MCP as a capability protocol rather than a
|
||||
workflow lifecycle, plus progressive discovery, CLI surfaces, and Code Mode.
|
||||
External measurements remain explicitly attributed: Cloudflare reports
|
||||
roughly 1,000 tokens for two Code Mode tools versus 1.17 million for an
|
||||
equivalent flat MCP surface, while Anthropic reports a worked example
|
||||
reducing tool context from 150,000 to 2,000 tokens. These are external
|
||||
examples, not lda.chat measurements:
|
||||
[Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/) and
|
||||
[Anthropic code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp).
|
||||
|
||||
Additional branch groups may attach to architecture, evaluation, and future
|
||||
work, but they must follow the same claim-class and evidence-pointer rules as
|
||||
the main path.
|
||||
|
||||
## Q&A Index
|
||||
|
||||
Q&A material is not the next numbered main scene. It is a separate deep-link
|
||||
index that can open focused views without replaying the main story.
|
||||
|
||||
Required entries:
|
||||
|
||||
- where the AI agent is and what is actually submitted;
|
||||
- Draft versus Artifact versus Deployment versus Run;
|
||||
- raw-plan import versus draft authoring;
|
||||
- source-provider boundary and MCP status;
|
||||
- schema validation and repair hints;
|
||||
- deterministic execution and reducer-aware state;
|
||||
- typed interrupt and resume contract;
|
||||
- persistence and recovery boundaries;
|
||||
- challenge methodology and validity limits;
|
||||
- security and sandboxing non-goals;
|
||||
- why not direct tool calling, generated scripts, LangGraph, Temporal, or n8n;
|
||||
- live demo failure and replay provenance.
|
||||
|
||||
Each entry should deep-link to an existing component or evidence record. Avoid a
|
||||
second, disconnected slide deck.
|
||||
|
||||
## Chat Component Direction
|
||||
|
||||
The next visual slice should copy source-owned primitives from Vercel AI
|
||||
Elements rather than invent another chat UI or adopt a second agent runtime.
|
||||
Useful primitives include conversation scrolling, messages, Markdown response,
|
||||
prompt input, and tool-call presentation.
|
||||
|
||||
The copied components adapt to the existing `AgentMessagePart` and
|
||||
`AgentDriver` contracts. Do not adopt `useChat`, model selection, attachments,
|
||||
accounts, or a complete ChatGPT shell until a live AI SDK driver exists.
|
||||
|
||||
The chat remains a supporting presentation surface. It must never push the
|
||||
graph, approval, or evidence below the fold.
|
||||
|
||||
## Content and Visual Freeze
|
||||
|
||||
Content freezes before visual polish:
|
||||
|
||||
1. approve scene order, claims, evidence pointers, and spoken intent;
|
||||
2. implement the compositor states and navigation;
|
||||
3. replace chat primitives and establish visual tokens;
|
||||
4. tune motion and final scene styling;
|
||||
5. rehearse timing and revise wording without restructuring components.
|
||||
|
||||
This ordering prevents the presentation from becoming visually polished while
|
||||
still telling the wrong story.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
The storyboard implementation is acceptable when:
|
||||
|
||||
1. all 12 main scenes are directly addressable and navigable without page
|
||||
scroll;
|
||||
2. the main path fits within 12 minutes in rehearsal;
|
||||
3. every factual scene has a claim class and evidence pointer;
|
||||
4. external measurements are visibly attributed and never presented as
|
||||
lda.chat evaluation;
|
||||
5. chat, graph, approval, output, and evidence retain stable stage geography;
|
||||
6. stage and chat themes can be controlled independently;
|
||||
7. live failure can fall back to the matching replay event without layout
|
||||
reset;
|
||||
8. the full main path is readable from `960x720` through `1280x720` logical
|
||||
canvases with browser zoom at 100%;
|
||||
9. reduced-motion mode preserves all information and controls;
|
||||
10. discussion branches and the Q&A index open focused evidence and return to
|
||||
the originating scene without replaying the presentation;
|
||||
11. the spoken script primarily uses personal defense voice while technical
|
||||
invariants remain precise;
|
||||
12. the existing `/console` product route remains independent from cinematic
|
||||
presentation styling.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- a live general-purpose LLM planner;
|
||||
- a second slide framework or Astro shell;
|
||||
- a generic drag-and-drop presentation editor;
|
||||
- redesigning the normal console in the presentation's cinematic style;
|
||||
- reproducing every thesis diagram or code listing;
|
||||
- presenting historical challenge waves as a controlled benchmark;
|
||||
- adding claims merely because a visual component can display them.
|
||||
@@ -6,7 +6,7 @@ Approved design contract for adapting the thesis presentation between `4:3`
|
||||
and `16:9` displays and replacing the persistent evidence drawer.
|
||||
|
||||
This specification narrows and updates the geometry and evidence behavior in
|
||||
the [defense presentation storyboard](2026-07-04-defense-presentation-storyboard-design.md).
|
||||
the [historical defense presentation storyboard](../../historical/superpowers/specs/2026-07-04-defense-presentation-storyboard-design.md).
|
||||
The storyboard remains authoritative for narrative order, claims, and scene
|
||||
content.
|
||||
|
||||
|
||||
@@ -1,142 +0,0 @@
|
||||
# Presentation Lifecycle Story Expansion Design
|
||||
|
||||
## Purpose
|
||||
|
||||
The defense presentation currently proves run and interrupt behavior, but it
|
||||
does not give enough screen time to the rest of the thesis contribution. The
|
||||
result feels dense and narrow: too much run-state detail in one scene, but too
|
||||
little lifecycle context around draft, artifact, deployment, source bindings,
|
||||
and evidence ownership.
|
||||
|
||||
The next presentation slice should expand the demo climax into more scenes. It
|
||||
should first show the product lifecycle as durable substrate state, then zoom
|
||||
into run start, typed interrupt, resume, output, and trace.
|
||||
|
||||
## Problem
|
||||
|
||||
The current Scenes 9 and 10 try to cover too many jobs:
|
||||
|
||||
- agent handoff into a workflow operation
|
||||
- reusable workflow graph
|
||||
- prepared deployment
|
||||
- run input
|
||||
- interrupt payload
|
||||
- operator resume form
|
||||
- resume operation
|
||||
- output artifacts
|
||||
- trace frames
|
||||
- live/replay truth
|
||||
|
||||
This creates the wrong hierarchy. The run inspector becomes visually dominant
|
||||
before the viewer understands what larger lifecycle it belongs to. It also
|
||||
makes chat feel detached: the chat says "run prepared workflow", while the
|
||||
screen jumps straight into run evidence instead of showing what already exists
|
||||
as draft, artifact, deployment, and configured sources.
|
||||
|
||||
## Design Goal
|
||||
|
||||
Make the product story read as:
|
||||
|
||||
```text
|
||||
External agent or operator request
|
||||
-> draft-like authoring surface
|
||||
-> saved artifact
|
||||
-> deployment with source bindings
|
||||
-> run from deployment
|
||||
-> typed interrupt
|
||||
-> resume payload
|
||||
-> output and trace evidence
|
||||
```
|
||||
|
||||
The presentation may still use a prepared replay, but the viewer should see
|
||||
which parts are durable product state and which part is the active run moment.
|
||||
|
||||
## Scene Structure
|
||||
|
||||
Replace the current two-scene climax with four product scenes.
|
||||
|
||||
### Scene 9: Prepared Workflow Lifecycle
|
||||
|
||||
Purpose: show that the prepared report workflow is not just a chat transcript.
|
||||
|
||||
Beats:
|
||||
|
||||
- `draft`: show authoring/draft intent and focused operations.
|
||||
- `artifact`: show immutable artifact identity/version.
|
||||
- `deployment`: show source bindings and drift policy.
|
||||
- `ready-run`: show the deployment is ready to start a run.
|
||||
|
||||
Dominant visual: lifecycle rail with one large factual panel per beat.
|
||||
|
||||
### Scene 10: Run Starts From Deployment
|
||||
|
||||
Purpose: show the run begins from the deployment and receives workflow input.
|
||||
|
||||
Beats:
|
||||
|
||||
- `input`: selected documents and issue-board path.
|
||||
- `operation`: `workflow.runs.start` operation proof.
|
||||
- `graph`: reusable graph with run id and current node context.
|
||||
|
||||
Dominant visual: operation and graph. Chat may narrate, but should not own the
|
||||
screen.
|
||||
|
||||
### Scene 11: Typed Human Boundary
|
||||
|
||||
Purpose: show the interrupt as a typed product boundary.
|
||||
|
||||
Beats:
|
||||
|
||||
- `interrupt`: interrupt payload and resume contract.
|
||||
- `approval`: operator decision form with large report preview.
|
||||
- `cancel`: honest replay cancellation state.
|
||||
|
||||
Dominant visual: interrupt payload and operator decision. The output panel is
|
||||
not shown before resume.
|
||||
|
||||
### Scene 12: Resume, Output, Evidence
|
||||
|
||||
Purpose: show the same run resumes and leaves product evidence.
|
||||
|
||||
Beats:
|
||||
|
||||
- `resume`: `workflow.runs.resume` operation proof.
|
||||
- `output`: report and issue-board output.
|
||||
- `trace`: trace frames and protocol evidence.
|
||||
|
||||
Dominant visual: output/report/trace. Evidence receipt remains inspectable.
|
||||
|
||||
Existing evaluation and conclusion scenes move after these scenes.
|
||||
|
||||
## Data Rules
|
||||
|
||||
- Do not invent lifecycle facts. If draft data is not in the recording, label it
|
||||
as prepared authoring context and point to `examples/lda_report_workflow`.
|
||||
- Artifact and deployment facts should be derived from the recorded deployment
|
||||
inspect event where possible.
|
||||
- Run input, interrupt payload, resume payload, output, and trace should be
|
||||
derived from the canonical recording or live run state.
|
||||
- Replay cancellation remains an honest presentation branch. Do not show
|
||||
submitted resume evidence after cancel.
|
||||
- Live/replay truth badge remains visible but should not dominate the story.
|
||||
|
||||
## Interaction Rules
|
||||
|
||||
- Hash deep links must prime replay state for the scene beat being opened.
|
||||
- Content panes may scroll internally. The whole presentation viewport must not
|
||||
scroll.
|
||||
- Scrollbars may be visually hidden in presentation mode, but native wheel and
|
||||
trackpad scrolling must still work.
|
||||
- Chat is secondary. It can introduce a scene or run the prepared workflow, but
|
||||
it should not crowd graph/evidence scenes.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- The viewer can answer where draft, artifact, deployment, run, interrupt, and
|
||||
trace fit.
|
||||
- Scene 11 approval no longer wastes space on pre-resume output.
|
||||
- Scene 12 output and trace can scroll and remain readable at 1280x720.
|
||||
- The run story is still factual and replay-backed.
|
||||
- The route count may grow past 12 scenes; clarity wins over forcing everything
|
||||
into the old scene count.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
Scenes 13 and 14 close the defense with evidence, claim boundaries, and a clear
|
||||
Scenes 12 and 13 close the defense with evidence, claim boundaries, and a clear
|
||||
statement of the thesis contribution. They must not read as a model leaderboard
|
||||
or as a generic list of limitations. The ending should move from bounded
|
||||
evaluation evidence, through supported future work, back to the stable
|
||||
@@ -92,9 +92,9 @@ The scene keeps the existing evidence pointer to the thesis Evaluation and
|
||||
Appendix C. The existing `evaluation-validity` discussion branch remains
|
||||
available from the scene discussion rail.
|
||||
|
||||
## Scene 14: Boundary, Future Layers, And Questions
|
||||
## Scene 13: Boundary, Future Layers, And Questions
|
||||
|
||||
Scene 14 uses a stable contribution line as its central visual:
|
||||
Scene 13 uses a stable contribution line as its central visual:
|
||||
|
||||
```text
|
||||
External planner -> typed workflow substrate -> deterministic runtime
|
||||
@@ -165,7 +165,7 @@ canonical discussion-branch catalog; it must not duplicate branch titles or
|
||||
answers in a second data structure.
|
||||
|
||||
The Questions beat is a reusable presentation component but is only exposed as
|
||||
the final Scene 14 beat in this slice. A future presenter shortcut may open it
|
||||
the final Scene 13 beat in this slice. A future presenter shortcut may open it
|
||||
globally without changing the component.
|
||||
|
||||
## Component Boundaries
|
||||
@@ -239,11 +239,11 @@ Implementation follows test-driven development.
|
||||
|
||||
Automated coverage must include:
|
||||
|
||||
- exact Scene 13 cohort and outcome counts;
|
||||
- exact Scene 12 cohort and outcome counts;
|
||||
- absence of percentages and model-ranking language;
|
||||
- validity reconciliation counts and claim-boundary wording;
|
||||
- all six observed UX findings;
|
||||
- all three Scene 14 non-claims;
|
||||
- all three Scene 13 non-claims;
|
||||
- all five supported future-work branches;
|
||||
- stable closing contribution wording;
|
||||
- the fourth `questions` beat and direct hash route;
|
||||
|
||||
@@ -1,200 +0,0 @@
|
||||
# Presentation Agent Authoring Story Design
|
||||
|
||||
## Purpose
|
||||
|
||||
Scenes 8 and 9 should make the defense's agent-facing claim concrete without
|
||||
claiming that lda.chat contains an autonomous planning model. Scene 8 introduces
|
||||
an external planner through a full-screen conversation. Scene 9 proves the
|
||||
durable authoring work through a prepared, inspectable command trace and a
|
||||
matching workflow lifecycle projection.
|
||||
|
||||
The design replaces the current disconnected combination of a generic agent
|
||||
handoff and a chat-free lifecycle scene. It does not replace the existing live
|
||||
run, interrupt, output, or trace proof in Scenes 10 through 12.
|
||||
|
||||
## Scope
|
||||
|
||||
This slice contains:
|
||||
|
||||
- A full-screen, read-only Scene 8 conversation with operator/assistant turns
|
||||
interleaved with prepared tool activity.
|
||||
- A continuous Scene 8 to Scene 9 conversation transition.
|
||||
- A deterministic prepared-authoring recording with literal `wf` commands,
|
||||
command results, and phase-specific workflow projections.
|
||||
- A Scene 9 workflow canvas with a synchronized compact chat dock.
|
||||
- Expandable tool groups inside the dock instead of a separate trace modal.
|
||||
- Keyboard, route, and responsive behavior for the new surfaces.
|
||||
|
||||
This slice excludes:
|
||||
|
||||
- Live LLM calls, credentials, or a chat backend.
|
||||
- A new assistant runtime or `AssistantRuntimeProvider` adapter.
|
||||
- A user-editable composer or slash command execution.
|
||||
- Any claim that a model made the recorded authoring decisions.
|
||||
- Changes to the factual live run path in Scenes 10 through 12.
|
||||
|
||||
## Assistant UI Boundary
|
||||
|
||||
The repository already owns `@assistant-ui/react` tool fallback and tool-group
|
||||
components. The official `thread.json`, `assistant-modal.json`, and
|
||||
`composer-trigger-popover.json` registry templates were inspected as visual and
|
||||
interaction references.
|
||||
|
||||
The generated `Thread` requires a full assistant-ui runtime and brings a
|
||||
composer, attachments, suggestions, reasoning, message action bars, and other
|
||||
interactive controls. `assistant-modal.json` embeds that same generated Thread,
|
||||
and `composer-trigger-popover.json` requires the unstable runtime composer
|
||||
primitive. Installing either generated component unchanged would conflict with
|
||||
the deterministic source-owned transcript projection.
|
||||
|
||||
Therefore this slice keeps `AssistantOperatorThread` as a read-only renderer.
|
||||
It uses the source-owned assistant-ui tool fallback and tool-group components
|
||||
for both the full thread and compact dock. A later live-agent slice may
|
||||
introduce a real assistant runtime, `thread.json`, and a truthful slash-command
|
||||
composer together.
|
||||
|
||||
References:
|
||||
|
||||
- [assistant-ui Thread](https://www.assistant-ui.com/docs/ui/thread)
|
||||
- [assistant-ui Assistant Modal](https://www.assistant-ui.com/docs/ui/assistant-modal)
|
||||
- [assistant-ui Tool Fallback](https://www.assistant-ui.com/docs/ui/tool-fallback)
|
||||
- [assistant-ui Composer Trigger Popover](https://www.assistant-ui.com/docs/ui/composer-trigger-popover)
|
||||
|
||||
## Story And Composition
|
||||
|
||||
### Scene 8: Agent Handoff
|
||||
|
||||
Scene 8 is a full-screen conversation with no graph, lifecycle rail, evidence
|
||||
receipt, or console chrome competing for attention. It must read as a real
|
||||
chat screen: visibly separated user and assistant turns, normal message
|
||||
spacing, and prepared tool groups interleaved with assistant narration. It has
|
||||
two beats:
|
||||
|
||||
1. `request`: the operator asks for a reusable thesis-readiness workflow from
|
||||
selected documents and an issue board.
|
||||
2. `handoff`: the external agent explains that it will discover the available
|
||||
workflow surface, author the reusable graph, validate it, and prepare a
|
||||
deployment.
|
||||
|
||||
The assistant's final handoff response contains a concise factual summary of
|
||||
the five prepared authoring phases. It must say these are prepared operations,
|
||||
not hidden reasoning or autonomous live execution. The request and handoff
|
||||
beats use the same conversation source, revealing additional already-recorded
|
||||
turns and tool groups rather than synthesizing new text at render time.
|
||||
|
||||
### Transition: Continuous Conversation Dock
|
||||
|
||||
Scene 9 keeps the same assistant thread visible as a compact dock at the bottom
|
||||
of the stage. The dock is not a screenshot, receipt, or second transcript. It
|
||||
projects the same stable message IDs and tool-call IDs used by Scene 8.
|
||||
|
||||
On scene entry the thread container contracts while the workflow canvas takes
|
||||
the upper stage. The active phase's tool group is expanded and scrolled into
|
||||
view; completed groups collapse to one-line status receipts. The dock may be
|
||||
manually expanded, but it never covers the primary workflow projection.
|
||||
|
||||
### Scene 9: Prepared Workflow Lifecycle
|
||||
|
||||
The Scene 9 canvas is primary. It shows one lifecycle projection per beat. The
|
||||
conversation dock is secondary and remains anchored below it. There is no
|
||||
separate `Agent trace` modal.
|
||||
|
||||
Each Scene 9 beat selects exactly one authoring phase:
|
||||
|
||||
| Beat | Canvas projection | Active dock group |
|
||||
| --- | --- | --- |
|
||||
| `discover` | Required sources, capabilities, and input schema | Discover |
|
||||
| `draft` | Draft graph with nodes and declared outcome routes | Draft |
|
||||
| `validate` | Invalid binding/diagnostic followed by repair status | Validate and repair |
|
||||
| `artifact` | Immutable artifact identifier and version | Compile artifact |
|
||||
| `deployment` | Concrete local source bindings and deployment validation | Deploy and validate |
|
||||
|
||||
Other tool groups stay collapsed. The presenter can expand them manually, but
|
||||
changing a group does not alter the active canvas phase.
|
||||
|
||||
The five canvas projections use distinct factual visual forms:
|
||||
|
||||
- `discover`: source inventory plus capability and schema contract.
|
||||
- `draft`: a compact directed graph with declared outcome routes.
|
||||
- `validate`: diagnostic before/after repair with the corrected projection.
|
||||
- `artifact`: immutable artifact identity, version, and required sources.
|
||||
- `deployment`: logical-to-concrete source bindings and validation status.
|
||||
|
||||
## Prepared Authoring Recording
|
||||
|
||||
Create a canonical, versioned recording separate from
|
||||
`lda-report-success.v1.json`. It is authored evidence for workflow construction,
|
||||
not a proxy for an LLM trace. Each phase includes a label, a concise narrator
|
||||
line, multiple literal CLI commands, bounded result data, and a canvas
|
||||
projection.
|
||||
|
||||
The command sequence is:
|
||||
|
||||
1. **Discover**: `wf source list`, `wf cap list`, and `wf schema` inspect the
|
||||
configured capability inventory and public input shapes.
|
||||
2. **Draft**: `wf draft create`, `wf draft add-step`, and declared route
|
||||
operations create the reusable graph.
|
||||
3. **Validate and repair**: bindings are applied, validation returns a bounded
|
||||
diagnostic, and the corrected binding/route operation produces a valid draft.
|
||||
4. **Compile artifact**: `wf draft compile` and `wf artifact inspect` show the
|
||||
immutable versioned workflow definition.
|
||||
5. **Deploy and validate**: `wf deploy save` and `wf deploy validate` bind
|
||||
logical requirements to the local report, issue-board, and document sources.
|
||||
|
||||
Command text must use the public `wf` surface and match the example's supported
|
||||
commands. Result text must stay short enough for the dock. Longer JSON or
|
||||
diagnostics are expandable, scroll-contained details rather than default
|
||||
content.
|
||||
|
||||
## Data Boundaries
|
||||
|
||||
The recording owns the authoring facts. A pure projection function maps the
|
||||
selected phase to:
|
||||
|
||||
- the Scene 9 lifecycle/canvas model;
|
||||
- dock messages and active tool group;
|
||||
- the active Scene 9 beat.
|
||||
|
||||
`PresentationRoute` remains the route owner. It maps a Scene 9 hash to a phase;
|
||||
it must not create another chat state store or call the workflow RPC server.
|
||||
`AssistantOperatorThread` remains a renderer of projected messages. A small
|
||||
presentation-owned wrapper controls only full-thread versus dock layout and the
|
||||
active expanded tool group.
|
||||
|
||||
If the recording cannot decode, Scene 9 renders a compact unavailable state
|
||||
with the evidence pointer and does not invent authoring facts. The dock shows a
|
||||
single unavailable message rather than fabricated tool results.
|
||||
|
||||
## Accessibility And Responsive Rules
|
||||
|
||||
- Tool groups are buttons with `aria-expanded`; their literal commands remain
|
||||
copyable text.
|
||||
- At 1280 by 720, the dock occupies no more than 30 percent of the stage. At
|
||||
1024 by 768 and narrower, it remains full-width below the canvas with its own
|
||||
scroll containment.
|
||||
- Canvas content may scroll inside its own region; the presentation viewport
|
||||
must not acquire page-level scrollbars.
|
||||
- Motion is limited to a 150–250 ms thread-container resize and canvas
|
||||
crossfade. Do not blur, scale, or pan unchanged thread content. Motion honors
|
||||
`prefers-reduced-motion` and the existing presentation motion toggle.
|
||||
|
||||
## Verification
|
||||
|
||||
- Unit-test recording decoding and phase projection, including rejected/missing
|
||||
recording data.
|
||||
- Unit-test dock projection, active-group synchronization, and stable IDs.
|
||||
- Component-test full-thread/dock layout, tool expansion, and compact
|
||||
unavailable state.
|
||||
- Route-test all five Scene 9 hashes and Scene 8 to Scene 9 transition state.
|
||||
- Browser-smoke the full-screen Scene 8 thread and each synchronized Scene 9
|
||||
phase at 1280 by 720 and 1024 by 768.
|
||||
- Run console tests, console typecheck, console build, and `git diff --check`.
|
||||
|
||||
## Follow-On Work
|
||||
|
||||
The following needs its own design because it changes the interaction contract:
|
||||
|
||||
- an assistant-ui runtime adapter backed by a real agent service;
|
||||
- a truthful live composer and slash command popover;
|
||||
- optional commands that focus figures, run lifecycle operations, or open
|
||||
evidence using the same tool/action contract as the live agent.
|
||||
@@ -7,7 +7,7 @@ Approved design direction for the next presentation slice.
|
||||
## Problem
|
||||
|
||||
The presentation currently renders the live-target truth badge in the footer of
|
||||
every main scene. It also renders launch controls inside the Scene 10 operation
|
||||
every main scene. It also renders launch controls inside the Scene 9 operation
|
||||
content. The target-health model mixes service availability with replay/live
|
||||
playback, so a healthy live service can appear as `Replay evidence` while a
|
||||
direct replay route is being primed. These independent state changes produce
|
||||
@@ -42,13 +42,13 @@ paths, not file contents or a read operation.
|
||||
|
||||
The demo control rail is visible only for the prepared workflow arc:
|
||||
|
||||
- Scene 8: `agent-handoff`
|
||||
- Scene 9: `prepared-lifecycle`
|
||||
- Scene 10: `run-from-deployment`
|
||||
- Scene 11: `typed-human-boundary`
|
||||
- Scene 12: `resume-output-evidence`
|
||||
- Scene 7: `agent-handoff`
|
||||
- Scene 8: `prepared-lifecycle`
|
||||
- Scene 9: `run-from-deployment`
|
||||
- Scene 10: `typed-human-boundary`
|
||||
- Scene 11: `resume-output-evidence`
|
||||
|
||||
Scene 8 (`agent-handoff`) remains a scripted conversation, but gains the same
|
||||
Scene 7 (`agent-handoff`) remains a scripted conversation, but gains the same
|
||||
small footer control rail so the presenter can start the prepared run without
|
||||
adding another large button to the chat composition. All narrative,
|
||||
architecture, evaluation, conclusion, and discussion locations hide the target
|
||||
@@ -94,7 +94,7 @@ height. It shows exactly one of these states:
|
||||
footprint.
|
||||
- While running: a non-interactive `Running workflow...` information label,
|
||||
not a disabled button.
|
||||
- While `demo.state.phase === "review"` on Scene 11
|
||||
- While `demo.state.phase === "review"` on Scene 10
|
||||
(`typed-human-boundary`): `Run paused - review required`. This is the only
|
||||
scene that exposes the paused label.
|
||||
- After completion: `Run complete`.
|
||||
@@ -125,17 +125,17 @@ current static rows.
|
||||
The implementation must test:
|
||||
|
||||
- title and non-demo scenes render no target badge or demo controls;
|
||||
- every Scene 8–12 beat renders exactly one compact demo rail;
|
||||
- every Scene 7–11 beat renders exactly one compact demo rail;
|
||||
- the pre-run demo rail renders the run action without an in-scene launch panel;
|
||||
- a running demo renders an information label instead of a disabled run button;
|
||||
- Scene 11 alone renders the review-required information label while the
|
||||
- Scene 10 alone renders the review-required information label while the
|
||||
decision form is waiting;
|
||||
- submitting or denying/revising the decision removes the paused label before
|
||||
the next scene is shown;
|
||||
- a completed demo renders the terminal information label;
|
||||
- a healthy target remains `Live target ready` while the timeline is replaying;
|
||||
- failed health renders replay fallback only inside demo scope;
|
||||
- backtracking between Scene 8–12 updates the rail from current state without
|
||||
- backtracking between Scene 7–11 updates the rail from current state without
|
||||
retaining stale copy;
|
||||
- backtracking from the demo arc to title removes the rail immediately;
|
||||
- checking does not change footer dimensions or mount a stale replay label;
|
||||
|
||||
@@ -11,14 +11,14 @@ reviewed recording only through an explicit replay action or an unavailable
|
||||
service.
|
||||
|
||||
This slice does not change the Scene 1/2 story, fact-check storyboard content,
|
||||
Scene 8/9 authoring recording, chat framework, or visual theme system.
|
||||
Scene 7/8 authoring recording, chat framework, or visual theme system.
|
||||
|
||||
## Current Problem
|
||||
|
||||
The live timeline controller and RPC executor already exist, but the visible
|
||||
action is owned by `OperatorChat`. Scenes 10–12 currently hide that chat, so a
|
||||
action is owned by `OperatorChat`. Scenes 9–11 currently hide that chat, so a
|
||||
prepared run can be implemented without a visible way to start it. Direct
|
||||
Scene 10–12 hashes also prime replay state by design, while the target health
|
||||
Scene 9–11 hashes also prime replay state by design, while the target health
|
||||
status is only probed on mount. This makes the system look disconnected even
|
||||
when `wf-rpc-server` is running.
|
||||
|
||||
@@ -27,8 +27,8 @@ when `wf-rpc-server` is running.
|
||||
### Launch surface
|
||||
|
||||
Expose one compact prepared-run control in `PresentationFooter` throughout
|
||||
Scenes 8-12. It is demo chrome, not a reintroduced chat rail or a scene-owned
|
||||
launch panel. Scene 10 remains the semantic execution start even when the
|
||||
Scenes 7-11. It is demo chrome, not a reintroduced chat rail or a scene-owned
|
||||
launch panel. Scene 9 remains the semantic execution start even when the
|
||||
presenter starts or prepares the run from an earlier demo scene.
|
||||
|
||||
The control communicates the current action:
|
||||
@@ -85,12 +85,12 @@ discussion views should not gain a persistent live-service badge or run action.
|
||||
## Acceptance Criteria
|
||||
|
||||
1. With `wf-rpc-server` and the web server running, the compact footer rail on
|
||||
Scenes 8-12 exposes `Run prepared workflow` and starts a live timeline.
|
||||
Scenes 7-11 exposes `Run prepared workflow` and starts a live timeline.
|
||||
2. A live run records deployment inspection, run start, interrupt, resume, and
|
||||
trace evidence using the existing `callOperation` path.
|
||||
3. The typed approval form remains the only way to provide the resume decision;
|
||||
both submitted and revision-requested outcomes are sent to the live server.
|
||||
4. A direct Scene 10–12 hash without an active run still shows the reviewed
|
||||
4. A direct Scene 9–11 hash without an active run still shows the reviewed
|
||||
replay, not a fabricated live state.
|
||||
5. When health fails, the presenter sees the reason and an explicit replay
|
||||
action; no live operation is silently represented as replay evidence.
|
||||
@@ -98,7 +98,7 @@ discussion views should not gain a persistent live-service badge or run action.
|
||||
recovered with retry, without reloading the page or reconnecting manually.
|
||||
7. The launch control cannot issue duplicate starts while an operation is in
|
||||
flight or a live run is already active.
|
||||
8. Scene 8 chat Send and Scene 9 staged messages remain deterministic authoring
|
||||
8. Scene 7 chat Send and Scene 8 staged messages remain deterministic authoring
|
||||
replay and do not call workflow authoring RPC operations. Their separate
|
||||
footer control may start the prepared run.
|
||||
|
||||
@@ -109,8 +109,8 @@ visibility, duplicate-start protection, explicit replay fallback, and live
|
||||
versus replay operation calls. A browser smoke run must verify:
|
||||
|
||||
```text
|
||||
Scene 10 operation -> live start -> interrupt -> approval -> resume -> trace
|
||||
Scene 10 direct hash with server unavailable -> explicit replay
|
||||
Scene 9 operation -> live start -> interrupt -> approval -> resume -> trace
|
||||
Scene 9 direct hash with server unavailable -> explicit replay
|
||||
server started after page load -> retry -> live-ready action
|
||||
```
|
||||
|
||||
|
||||
@@ -1,174 +0,0 @@
|
||||
# Presentation Visual Scale And Color Pass Design
|
||||
|
||||
## Purpose
|
||||
|
||||
This slice improves the remaining weak presentation scenes without changing the
|
||||
storyboard, RPC transport, live/replay behavior, chat framework, or workflow
|
||||
facts. The target is a readable defense deck at both the adaptive 16:9 and 4:3
|
||||
canvas shapes already supported by `/present`.
|
||||
|
||||
The presentation should feel like an intentional product explanation: one
|
||||
dominant visual per beat, enough space to understand it, and restrained color
|
||||
used to communicate state rather than decorate every surface.
|
||||
|
||||
## Current Problem
|
||||
|
||||
The current deck is functional but uneven. Some scenes still use too much
|
||||
framing, too much blue on editorial surfaces, or too many small elements at
|
||||
once. The main targets are:
|
||||
|
||||
- Scene 1 has weak title hierarchy, excess framing, and insufficient title-box
|
||||
padding/contrast.
|
||||
- Scene 2 is taller and more card-like than a normal conversation/problem
|
||||
explanation should be; its editorial surface also carries unnecessary blue.
|
||||
- Scene 7's authoring visuals are too small and Validate/Repair are not
|
||||
visually distinct enough across beats.
|
||||
- Scene 9's lifecycle visuals lose scale when supporting chat and proof content
|
||||
compete with them.
|
||||
- Scenes 13 and 14 rely on small diagrams or text blocks where one larger focal
|
||||
visual would carry the argument better.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- Scene 1 title hierarchy, padding, contrast, and removal of duplicate framing.
|
||||
- Scene 2 composition height, visual balance, and non-demo color reduction.
|
||||
- Scene 7 authoring visual scale and Validate/Repair distinction.
|
||||
- Scene 9 prepared-lifecycle focal visual scale and supporting-surface balance.
|
||||
- Scene 13 evaluation visual scale and information hierarchy.
|
||||
- Scene 14 conclusion visual scale and removal of unnecessary blue.
|
||||
- Screenshot smoke checks at `1280x720` and `1024x768`.
|
||||
- Tests for stable structure, beat emphasis, and presentation-surface contracts.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Changing scene order, storyboard claims, or speaker script.
|
||||
- Adding live workflow operations or changing replay truth.
|
||||
- Replacing assistant-ui/shadcn chat components.
|
||||
- Adding a real file browser to the Scene 10 input beat.
|
||||
- Introducing a theme toggle or a third presentation theme.
|
||||
- Rewriting the adaptive canvas or reintroducing `transform: scale(...)`.
|
||||
- Reworking Scenes 3-6, 8, 10-12 unless a targeted regression is required.
|
||||
|
||||
## Design Rules
|
||||
|
||||
1. **One focal artifact per beat.** Supporting text, chat, receipts, and
|
||||
discussion affordances must not compete with the beat's main visual.
|
||||
2. **Editorial surfaces are neutral.** Paper/editorial scenes may use cyan for
|
||||
a selected state or link, but should not be blue panels on white backgrounds.
|
||||
3. **Demo surfaces keep operational color.** Scenes 8-12 may retain their
|
||||
darker operational treatment and state colors because they are the product
|
||||
demonstration. This is not a reason to recolor the rest of the deck.
|
||||
4. **Scale before decoration.** Increase usable diagram area and reduce
|
||||
surrounding chrome before adding new labels, badges, or cards.
|
||||
5. **Beat changes must be legible.** A changed beat should change emphasis,
|
||||
content, or position; do not rely on a tiny border or a nearly invisible
|
||||
opacity change.
|
||||
6. **Use existing tokens and primitives.** Prefer existing editorial tokens,
|
||||
scene components, icons, figure layouts, and chat surfaces. Do not add a new
|
||||
generic card system for this pass.
|
||||
7. **Protect the canvas.** Validate both supported aspect-ratio extremes. A
|
||||
diagram may scroll inside its own frame, but the presentation page must not
|
||||
acquire accidental outer scroll.
|
||||
|
||||
## Scene Targets
|
||||
|
||||
### Scene 1: Thesis
|
||||
|
||||
The title beat should read as a title page, not as a generic content card.
|
||||
Keep the title, subtitle, and planner/tool/platform decomposition available
|
||||
across beats, but establish a clear title-first hierarchy.
|
||||
|
||||
Acceptance points:
|
||||
|
||||
- One primary title treatment is visible; duplicate boxes do not frame the same
|
||||
content.
|
||||
- Title padding is visibly generous at `1280x720`.
|
||||
- Text contrast remains readable on the editorial surface.
|
||||
- The decomposition can enter on later beats without shrinking the title beat.
|
||||
|
||||
### Scene 2: Problem
|
||||
|
||||
The scene should read left-to-right as a conversation/problem explanation, not
|
||||
as two tall dashboard cards. Keep the transcript and reusable-automation
|
||||
contrast, but make both blocks shorter and better balanced.
|
||||
|
||||
Acceptance points:
|
||||
|
||||
- The transcript reads as a chat/tool loop in normal reading order.
|
||||
- The durable automation side is shorter and does not dominate by height.
|
||||
- Blue is removed from the editorial background, borders, and decorative fills;
|
||||
only meaningful emphasis remains.
|
||||
- The two sides remain understandable at `1024x768`.
|
||||
|
||||
### Scene 7: Author, Validate, Repair
|
||||
|
||||
The authoring loop is the visual argument. The active phase must become large
|
||||
enough to explain while the rest of the loop remains a readable map.
|
||||
|
||||
Acceptance points:
|
||||
|
||||
- The loop has a clear primary visual and a compact phase rail.
|
||||
- Validate shows diagnostics or contract checking as its own visual state.
|
||||
- Repair shows a correction/revision state, not the same Validate card with a
|
||||
different label.
|
||||
- Existing icons and factual commands remain available without turning the
|
||||
scene into a wall of CLI text.
|
||||
|
||||
### Scene 9: Prepared Workflow Lifecycle
|
||||
|
||||
The lifecycle scene should explain Draft, Artifact, Deployment, and Run with a
|
||||
large lifecycle visual. The authoring assistant remains a supporting surface;
|
||||
it must not compress the lifecycle into unreadable cards.
|
||||
|
||||
Acceptance points:
|
||||
|
||||
- The lifecycle rail or active phase occupies the dominant area.
|
||||
- The active phase is readable at both canvas shapes.
|
||||
- Chat and proof support remain present only where the beat calls for them.
|
||||
- The scene does not duplicate the demo footer rail or live target badge.
|
||||
|
||||
### Scenes 13-14: Evaluation And Conclusion
|
||||
|
||||
These scenes should close with evidence and a clear contribution, not a dense
|
||||
summary wall.
|
||||
|
||||
Acceptance points:
|
||||
|
||||
- Scene 13 gives the evaluation numbers one dominant visual treatment, with
|
||||
methodology limits as supporting content.
|
||||
- Scene 14 gives the contribution/limits relationship one dominant visual
|
||||
treatment and removes unnecessary blue from the editorial surface.
|
||||
- Icons or existing visual primitives may carry categories, but must not replace
|
||||
the factual labels needed for the defense.
|
||||
- The final beat remains readable without opening a discussion panel.
|
||||
|
||||
## Verification Contract
|
||||
|
||||
- Existing presentation tests remain green.
|
||||
- Add or update focused tests for Scene 1, Scene 2, Scene 7, Scene 9, Scene 13,
|
||||
and Scene 14 structure and beat emphasis.
|
||||
- Verify no presentation route gets accidental outer scroll at `1280x720` and
|
||||
`1024x768`.
|
||||
- Capture representative screenshots for the title, problem, authoring,
|
||||
lifecycle, evaluation, and conclusion scenes.
|
||||
- Run `pnpm --dir web test`, `pnpm --dir web typecheck`, and
|
||||
`pnpm --dir web build` before completion.
|
||||
|
||||
## Deferred Follow-up: Real Input File Browser
|
||||
|
||||
The current Scene 10 input beat intentionally says `included in prepared run`.
|
||||
That wording is factual, but it is not a file browser. A later slice may add a
|
||||
real, read-only file browser for `#scene/run-from-deployment/input` backed by
|
||||
the prepared recording and live run facts.
|
||||
|
||||
That follow-up must define what is actually known before showing it:
|
||||
|
||||
- canonical file paths and file count;
|
||||
- whether a file was merely declared, selected, read, or produced;
|
||||
- whether content preview is available from the live or replay source;
|
||||
- how missing or unavailable previews are represented.
|
||||
|
||||
Until those facts exist, do not imply that the presentation selected or read
|
||||
files merely because they appear in the prepared input manifest.
|
||||
@@ -1,219 +0,0 @@
|
||||
# Scene 8 Chat Entry Design
|
||||
|
||||
## Status
|
||||
|
||||
Approved design for the first slice of the Scene 8–14 defense recomposition.
|
||||
|
||||
## Goal
|
||||
|
||||
Turn Scene 8 into a convincing full-screen assistant entry surface: the
|
||||
audience sees the presentation title, a familiar empty chat state, and a
|
||||
composer containing the report-workflow request. Sending that request reveals
|
||||
the first prepared authoring turn without starting the workflow run.
|
||||
|
||||
## Context
|
||||
|
||||
Scene 8 currently renders a prepared authoring transcript inside a custom stage
|
||||
layout with a phase rail and a separate `Run prepared workflow` button. That
|
||||
mixes two different stories:
|
||||
|
||||
- authoring begins as an external-agent conversation;
|
||||
- workflow execution begins later in the Run From Deployment scene.
|
||||
|
||||
The revised scene must make that distinction visible. The chat entry is a
|
||||
presentation interaction backed by the deterministic authoring recording. It is
|
||||
not an LLM call and it is not the live workflow start operation.
|
||||
|
||||
## Design
|
||||
|
||||
### Scene Composition
|
||||
|
||||
Scene 8 retains the existing `StageCaption` title and caption. Below it, the
|
||||
primary region becomes one full-height chat surface:
|
||||
|
||||
```text
|
||||
Stage title and framing
|
||||
|
|
||||
assistant-style thread
|
||||
welcome / turns / tools
|
||||
|
|
||||
composer + Send
|
||||
```
|
||||
|
||||
The old five-step phase rail is removed from Scene 8. The lifecycle sequence is
|
||||
shown by Scene 9, where the authoring canvas is the primary artifact and the
|
||||
conversation becomes a secondary modal.
|
||||
|
||||
The standalone in-scene `Run prepared workflow` action is removed from Scene 8.
|
||||
The later demo-chrome slice owns one compact footer rail across Scenes 8-12.
|
||||
That separate footer may expose the prepared-run action, while chat Send remains
|
||||
local and never starts a workflow.
|
||||
|
||||
### Chat Surface Boundary
|
||||
|
||||
Use the assistant-ui Thread/Composer template and shadcn-owned primitives for
|
||||
the visual vocabulary: message spacing, composer shell, send affordance,
|
||||
empty-state layout, focus treatment, and tool-group treatment.
|
||||
|
||||
Do not introduce an assistant-ui runtime in this slice. The presentation keeps
|
||||
`AgentMessage`, `projectPreparedAuthoringThread`, and the existing deterministic
|
||||
recording as the source of truth. The Scene 8 adapter owns only the local
|
||||
entry-state transition and delegates the rendered turns to the existing
|
||||
projection path.
|
||||
|
||||
This boundary is deliberate:
|
||||
|
||||
- it avoids a second chat state store;
|
||||
- it avoids reintroducing the duplicate-message/runtime problem previously
|
||||
found with an external assistant runtime;
|
||||
- it keeps replay deterministic and inspectable;
|
||||
- it leaves a future live AI SDK driver compatible with the same visual shell.
|
||||
|
||||
### Entry State
|
||||
|
||||
On the Scene 8 request beat, render:
|
||||
|
||||
- the Scene 8 title and caption;
|
||||
- an assistant-style welcome heading or short framing line;
|
||||
- an empty conversation viewport;
|
||||
- a composer with the request text prefilled:
|
||||
`We need to author a report workflow for the lda_report scenario. What sources and capabilities are available?`;
|
||||
- an enabled Send button;
|
||||
- no workflow operation, run ID, deployment ID, or live target action inside
|
||||
the chat surface. The separate demo footer rail may show target and run state.
|
||||
|
||||
The prefilled text is editable. The scene does not require the presenter to
|
||||
retype the request during the defense.
|
||||
|
||||
### Send Transition
|
||||
|
||||
When Send is activated with non-empty text:
|
||||
|
||||
1. prevent the native form submission;
|
||||
2. record the local submitted request in the Scene 8 controller state;
|
||||
3. replace the empty state with the first prepared authoring conversation turn;
|
||||
4. reveal the first assistant response and the Discover tool group from the
|
||||
canonical recording;
|
||||
5. clear the composer or replace it with a read-only continuation state;
|
||||
6. keep the current location at `#scene/agent-handoff/request`.
|
||||
|
||||
The send action must not call `workflow.runs.start`, `workflow.runs.resume`, or
|
||||
any other workflow RPC. It is a scripted presentation entry event.
|
||||
|
||||
Scene 8 has no second handoff beat. Advancing with `ArrowRight` moves directly
|
||||
to Scene 9's first lifecycle beat, where the full prepared authoring
|
||||
conversation becomes visible through the existing phase projection.
|
||||
|
||||
If the composer is empty or contains only whitespace, Send is disabled and no
|
||||
state transition occurs.
|
||||
|
||||
### Replay and Reload Behavior
|
||||
|
||||
The Scene 8 entry state is local presentation state. Reloading the request beat
|
||||
returns to the empty composer. The canonical authoring recording remains the
|
||||
source for all revealed turns.
|
||||
|
||||
Scene 8 chat must work with no workflow server and must not change live/replay
|
||||
state. The later demo truth slice owns the separate footer badge and launch
|
||||
control across the demo arc.
|
||||
|
||||
### Responsive Behavior
|
||||
|
||||
The surface must remain readable at the reviewed `16:9` and `4:3` canvases:
|
||||
|
||||
- the composer remains visible without scrolling at `1280x720`;
|
||||
- the composer remains reachable at `1024x768`;
|
||||
- the conversation viewport may scroll internally once the prepared turns are
|
||||
taller than the available stage;
|
||||
- long request text wraps inside the composer and never causes horizontal
|
||||
overflow;
|
||||
- the assistant-ui shell must not inherit the old dark-stage palette in Scene
|
||||
8's editorial surface;
|
||||
- reduced-motion users receive an immediate state transition or a short
|
||||
opacity-only transition.
|
||||
|
||||
## Data Flow
|
||||
|
||||
```text
|
||||
prefilled request
|
||||
|
|
||||
v
|
||||
Scene8ChatEntry local reducer
|
||||
|
|
||||
+--> submitted request / entry state
|
||||
|
|
||||
+--> projectPreparedAuthoringThread("discover")
|
||||
|
|
||||
v
|
||||
assistant-ui visual shell
|
||||
```
|
||||
|
||||
The local state should be a small discriminated union, for example:
|
||||
|
||||
```ts
|
||||
type Scene8EntryState =
|
||||
| { readonly phase: "empty"; readonly draft: string }
|
||||
| { readonly phase: "submitted"; readonly draft: string; readonly request: string };
|
||||
```
|
||||
|
||||
The exact reducer location may follow the existing presentation module
|
||||
conventions, but the state must not be added to the global presentation
|
||||
reducer. Scene 8 entry state is not navigation state and does not need to be
|
||||
encoded in the URL hash.
|
||||
|
||||
## Accessibility
|
||||
|
||||
- The composer is a labelled form control with an accessible name such as
|
||||
`Message input`.
|
||||
- Send is a real button and exposes disabled state when the draft is blank.
|
||||
- Enter submits the request; Shift+Enter inserts a newline if the chosen
|
||||
assistant-ui composer supports multiline input.
|
||||
- The conversation is exposed as a log with a useful accessible label.
|
||||
- Focus moves to the first revealed assistant content after send without
|
||||
stealing focus from the composer while the user is editing.
|
||||
- Keyboard scene navigation remains owned by the existing presentation route;
|
||||
text input events must not advance the scene.
|
||||
|
||||
## Failure and Boundary States
|
||||
|
||||
- Blank draft: Send disabled; no message is revealed.
|
||||
- Whitespace-only draft: treated as blank.
|
||||
- Send while already submitted: disabled or ignored; it must not duplicate the
|
||||
prepared conversation.
|
||||
- Missing recording data: preserve the existing bounded presentation fallback
|
||||
and render an explicit unavailable state rather than inventing a live result.
|
||||
|
||||
## Testing Contract
|
||||
|
||||
Add or update tests for:
|
||||
|
||||
1. request beat renders the title, empty conversation state, prefilled composer,
|
||||
and enabled Send button;
|
||||
2. blank and whitespace-only drafts keep Send disabled;
|
||||
3. sending reveals the prepared request/assistant/Discover content and does not
|
||||
call workflow RPC operations;
|
||||
4. sending twice does not duplicate the first conversation;
|
||||
5. Scene 8 no longer renders the standalone `Run prepared workflow` button or
|
||||
the old phase rail;
|
||||
6. 1280x720 and 1024x768 browser smoke captures show the composer without
|
||||
clipping or horizontal overflow;
|
||||
7. reduced-motion mode does not hide the submitted conversation.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- Real LLM or AI SDK execution;
|
||||
- workflow run start or resume;
|
||||
- Scene 9 persistent prepared-agent assistant pane;
|
||||
- truth-badge scoping;
|
||||
- Scene 11 beat compression;
|
||||
- changes to the overall story order;
|
||||
- live authoring RPC calls;
|
||||
- a persistent chat transcript across reloads.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
The slice is complete when the presenter can open
|
||||
`#scene/agent-handoff/request`, see a credible full-screen chat entry, press
|
||||
Send, see the first prepared authoring turn, and continue directly into Scene 9
|
||||
without a standalone run button or a second chat state runtime. The behavior is
|
||||
covered by focused tests and 16:9/4:3 browser smoke.
|
||||
Reference in New Issue
Block a user