docs: design adaptive presentation evidence

docs/current_roadmap.md

@@ -37,6 +37,7 @@ Design contracts:
 - [`workflow console lifecycle explorer`](superpowers/specs/2026-07-02-workflow-console-lifecycle-explorer.md)
 - [`demo autoplay and replay`](superpowers/specs/2026-07-03-demo-autoplay-replay.md)
 - [`defense presentation storyboard`](superpowers/specs/2026-07-04-defense-presentation-storyboard-design.md)
+- [`adaptive presentation canvas and evidence inspector`](superpowers/specs/2026-07-05-adaptive-presentation-canvas-design.md)
 
 Implementation order:
 
@@ -101,12 +102,16 @@ Implementation order:
     [`defense presentation storyboard`](superpowers/specs/2026-07-04-defense-presentation-storyboard-design.md).
     Implementation:
     [`editorial canvas and Interactive Figure plan`](historical/superpowers/plans/2026-07-05-editorial-canvas-interactive-figure.md).
-12. Then: adopt source-owned AI Elements chat primitives against existing
+12. Then: adapt the logical presentation canvas continuously from `4:3` to
+    `16:9` and replace the resizing evidence drawer with a progress-row receipt
+    and centered inspector. Design:
+    [`adaptive presentation canvas and evidence inspector`](superpowers/specs/2026-07-05-adaptive-presentation-canvas-design.md).
+13. Then: adopt source-owned AI Elements chat primitives against existing
     `AgentMessagePart` / `AgentDriver` contracts.
-13. Future: implement Schema Form Surface and synchronized Approval Session.
+14. Future: implement Schema Form Surface and synchronized Approval Session.
-14. Future: implement Guided Run Beat Gates, presenter companion, Scene 10
+15. Future: implement Guided Run Beat Gates, presenter companion, Scene 10
     product graph, final scene visuals, evidence assets, and rehearsal timing.
-15. Add a static slide/appendix shell only after presentation mode is clear.
+16. Add a static slide/appendix shell only after presentation mode is clear.
     Astro remains an option, not the default next surface.
 
 Boundaries: this is not a production admin panel, generic visual workflow

docs/superpowers/specs/2026-07-03-constrained-demo-agent-design.md

@@ -179,7 +179,7 @@ Recipe stages:
    evidence.
 
 Each stage produces an agent event, and operation stages must carry the same
-operation metadata already used by `OperationBlock` and the evidence drawer.
+operation metadata already used by `OperationBlock` and the evidence surface.
 
 ## Architecture
 
@@ -252,7 +252,7 @@ PresentationRoute
 
 The prepared driver reads from the reviewed recording and emits agent events
 without a server. It passes operation evidence to the hook, which forwards it
-to the evidence drawer.
+to the evidence surface.
 
 In live mode, the driver calls the connected workflow server through the
 existing RPC operation path. Live mode is deferred to a future slice; the
@@ -301,7 +301,7 @@ The operator chat becomes a standard event-driven chat:
 - workflow tool calls are rendered compactly in chat and can expand to
   `OperationBlock`;
 - presentation tool calls are rendered compactly in chat and update the stage;
-- tool results link to the graph, trace, and evidence drawer;
+- tool results link to the graph, trace, and evidence inspector;
 - approval request focuses the existing typed review panel.
 
 The existing hard-coded chat copy should be replaced only where the agent event

docs/superpowers/specs/2026-07-03-demo-autoplay-replay.md

@@ -263,7 +263,7 @@ Replay timing is presentation timing, not the original network timing:
 - completion: immediate after the final event;
 - Pause and Next use the same reducer actions as live mode.
 
-The UI displays a persistent `Recorded replay` label. Raw evidence drawers may
+The UI displays a persistent `Recorded replay` label. The evidence inspector may
 show the recording's stored request and response, but must also identify the
 recording id.
 

docs/superpowers/specs/2026-07-03-react-presentation-mode-design.md

@@ -86,7 +86,7 @@ Primary controls:
 
 - `Space` / `ArrowRight`: next beat.
 - `ArrowLeft`: previous scripted beat.
-- `Esc`: close the current overlay or evidence drawer.
+- `Esc`: close the current overlay or evidence inspector.
 - Mouse/touch: inspect node, open evidence, submit approval, or jump timeline.
 
 Backward navigation only rewinds visual/script state. It must not undo live
@@ -206,7 +206,7 @@ Resume outcomes: submitted | cancelled
 
 The block can appear compact inside chat and expand into a terminal-like panel.
 The interpreted side may highlight graph nodes or stage elements. Raw evidence
-remains available through the global evidence drawer.
+remains available through the global evidence inspector.
 
 ## Graph
 
@@ -253,7 +253,9 @@ SaaS/chat clone.
 
 ## 720p Constraint
 
-Design for `1280x720` as a first-class target.
+Design for a `720px` logical height and adaptive logical widths from `960px`
+through `1280px`. See the
+[adaptive presentation canvas design](2026-07-05-adaptive-presentation-canvas-design.md).
 
 Rules:
 
@@ -281,9 +283,9 @@ Browser smoke should cover:
 2. verify replay is the default;
 3. advance through all beats with keyboard;
 4. open node spotlight;
-5. open evidence drawer;
+5. open the evidence inspector;
 6. jump to `#interrupt-approval`;
-7. complete the replay path on a `1280x720` viewport;
+7. complete the replay path on `1024x768` and `1280x720` viewports;
 8. verify the normal console route still works.
 
 ## Success Criteria
@@ -296,6 +298,6 @@ The slice is complete when:
 4. hash links jump to important beats;
 5. operation blocks make product calls visible and interpretable;
 6. graph, interrupt, output, trace, and evidence are available without clutter;
-7. the route is readable at `1280x720`;
+7. the route is readable from `4:3` through `16:9` supported ratios;
 8. the normal console remains product-like and is not forced into cinematic
    layout choices.

docs/superpowers/specs/2026-07-04-defense-presentation-storyboard-design.md

@@ -77,13 +77,15 @@ 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 three stable regions:
+The stage has two stable content regions and one transient inspection layer:
 
 ```text
-+----------------+--------------------------------+----------------+
++----------------+--------------------------------+
-| agent / chat   | primary graph, model, output   | evidence       |
+| agent / chat   | primary graph, model, output   |
-| optional       | always owns visual focus       | optional       |
+| optional       | always owns visual focus       |
-+----------------+--------------------------------+----------------+
++----------------+--------------------------------+
+| progress and compact evidence receipt           |
++-------------------------------------------------+
 ```
 
 The regions may expand, collapse, or overlap, but they do not swap meanings.
@@ -95,22 +97,26 @@ accidental application switch.
 - **Left:** agent conversation and operation intent.
 - **Center:** the primary explanation, workflow graph, output, or evaluation
   result.
-- **Right:** raw and interpreted evidence, trace, schemas, or source details.
+- **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 is collapsed unless the scene explicitly needs it.
+`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. At `1280x720`, the presenter
+Vertical stacking is forbidden on the main path. Across supported logical
-must not scroll to discover the graph, approval control, output, or next action.
+canvases from `960x720` through `1280x720`, the presenter must not scroll to
+discover the graph, approval control, output, or next action.
 
-The audience route renders a deterministic `1280x720` canvas and scales it
+The audience route keeps a deterministic `720px` logical height and adapts its
-proportionally to the available viewport, adding letterboxing when aspect
+logical width continuously from `960px` to `1280px`, covering `4:3` through
-ratios differ. Scenes do not reflow like a responsive website; presenter and
+`16:9`. Container queries adapt placement without omitting information.
-audience views must preserve the same composition and Focus Path.
+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
 
@@ -456,8 +462,8 @@ receive compatibility wrappers.
   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; evidence panel may show
+- **Composition:** warm Editorial Canvas; center focus; the progress row may
-  one compact record at a time.
+  show one compact evidence receipt.
 - **Evidence pointer:** thesis lifecycle chapter and lifecycle explorer.
 - **Transition:** selecting a deployment zooms into the runtime architecture.
 
@@ -469,8 +475,8 @@ receive compatibility wrappers.
   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; right evidence panel
+- **Composition:** warm Editorial Canvas; chat hidden; the evidence receipt
-  peeks for concrete package or operation names.
+  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.
@@ -485,7 +491,7 @@ receive compatibility wrappers.
 - **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 evidence peeks right.
+  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.
@@ -526,7 +532,8 @@ receive compatibility wrappers.
   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; right evidence panel opens once.
+  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
@@ -543,8 +550,8 @@ receive compatibility wrappers.
   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;
+- **Composition:** warm Editorial Canvas; chat hidden; one chart at a time; the
-  evidence panel links to the audit/run records.
+  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
@@ -681,7 +688,8 @@ The storyboard implementation is acceptable when:
 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 at `1280x720` with browser zoom at 100%;
+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;

docs/superpowers/specs/2026-07-05-adaptive-presentation-canvas-design.md

@@ -0,0 +1,199 @@
+# Adaptive Presentation Canvas and Evidence Inspector Design
+
+## Status
+
+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 storyboard remains authoritative for narrative order, claims, and scene
+content.
+
+## Problem
+
+The audience route currently renders one fixed `1280x720` logical canvas. A
+`4:3` projector therefore shows a smaller `16:9` composition with unnecessary
+letterboxing even though the available height could support a larger stage.
+
+Evidence also occupies a persistent right column. Beat-level evidence peeks
+resize the primary visual, repeatedly disturb graph layout, and expose a long
+scrolling surface that an audience cannot scan quickly. Evidence is necessary
+for defense credibility, but it must not compete with the current argument.
+
+## Design Principles
+
+1. The presentation preserves one logical height and adapts its width.
+2. Aspect ratio changes composition, not semantic content.
+3. The primary visual never reflows merely because evidence becomes available.
+4. Automatic evidence behavior remains quiet; detailed inspection is explicit.
+5. Compact and wide layouts share one state model and component tree.
+6. Unsupported extreme ratios letterbox rather than producing an unreviewed
+   composition.
+
+## Adaptive Logical Canvas
+
+The logical canvas height remains `720px`. Its logical width is derived from
+the viewport aspect ratio and clamped between `960px` and `1280px`:
+
+```text
+logicalHeight = 720
+logicalWidth = clamp(960, logicalHeight * viewportAspect, 1280)
+scale = min(viewportWidth / logicalWidth, viewportHeight / logicalHeight)
+```
+
+Representative results:
+
+| Viewport | Logical canvas | Result |
+|---|---:|---|
+| `1024x768` | `960x720` | fills a `4:3` display |
+| `1200x800` | `1080x720` | uses the intermediate ratio |
+| `1280x720` | `1280x720` | fills a `16:9` display |
+
+Viewports narrower than `4:3` or wider than `16:9` use the nearest supported
+logical ratio and letterbox the excess. There is no URL or hidden aspect-ratio
+override. Resizing the browser and Playwright viewport is the rehearsal and
+test mechanism.
+
+`PresentationCanvas` owns only logical dimensions, scale, and centering. The
+presentation stage responds to its logical inline size through container
+queries. This keeps geometry decisions in CSS and avoids a parallel JavaScript
+"compact mode" state.
+
+## Composition Across Ratios
+
+Wide layouts may keep chat as a rail beside the primary visual. As logical
+width decreases, chat becomes an overlay rather than reducing the primary
+visual below its useful width. The exact compact threshold is a visual tuning
+constant, initially around `1080px` of logical width rather than a product
+contract.
+
+The same claim, labels, controls, graph nodes, and evidence records remain
+available at every supported ratio. Compact layouts may change placement,
+line wrapping, or overlay treatment, but they must not omit content to fit.
+
+Chat and detailed evidence are mutually exclusive overlays in compact layouts.
+Opening one closes the other. Wide layouts may retain a chat rail while the
+evidence inspector overlays the stage; evidence never reintroduces a permanent
+right column.
+
+## Evidence States
+
+Evidence has three presentation states:
+
+```ts
+type EvidencePresentation = "hidden" | "receipt" | "inspector";
+```
+
+### Hidden
+
+No evidence affordance is emphasized. The stable bottom progress row remains.
+
+### Receipt
+
+The bottom progress row gains a compact evidence control. It shows the most
+relevant operation or evidence label, its status when available, and the record
+count. A typical row reads:
+
+```text
+6 / 12 · 2 / 4                    Evidence: workflow.runs.start · Inspect
+```
+
+Beat metadata may request a receipt. Entering such a beat updates or briefly
+emphasizes the receipt; it never opens detailed evidence automatically.
+
+### Inspector
+
+Activating the receipt or an explicit `View raw evidence` action opens a
+centered inspection overlay occupying approximately 70 percent of the logical
+canvas. The inspector overlays the stage without changing primary layout.
+
+The first view is interpreted evidence: operation, outcome, identifiers,
+duration, and a concise explanation. Raw JSON and equivalent CLI information
+are secondary views in the same inspector. The selected record remains stable
+when switching views.
+
+The inspector uses accessible dialog semantics, traps focus while open, returns
+focus to its trigger on close, and closes on `Escape`. Reduced-motion mode uses
+an immediate appearance or short crossfade rather than scale or travel.
+
+## State and Navigation
+
+Beat definitions may select `hidden` or `receipt`; they may not auto-select
+`inspector`. Explicit presenter or audience actions open the inspector.
+
+Changing beats closes the inspector and recomputes the receipt from the new
+beat. This prevents stale raw evidence from covering the next argument. The
+close-overlay order handles the inspector before discussion or figure focus.
+
+Scene, beat, and Figure Focus Path remain canonical URL state. Evidence and
+chat overlays are transient presentation state and do not enter the URL.
+
+The existing evidence data remains canonical. This change replaces only its
+presentation projection; it does not create another evidence store or transport.
+
+## Component Boundaries
+
+- `PresentationCanvas` calculates adaptive logical dimensions and viewport fit.
+- `PresentationStage` establishes the container-query context and coordinates
+  mutually exclusive overlays.
+- `EvidenceReceipt` renders the compact progress-row affordance.
+- `EvidenceInspector` renders interpreted and raw evidence in a dialog.
+- The existing `EvidenceDrawer` is removed once its callers migrate. It does
+  not receive a compatibility wrapper because it has no external contract.
+
+The state layer describes evidence intent without encoding drawer geometry.
+Names such as `peek` and `open` should migrate to `receipt` and `inspector` so
+future components consume the semantic behavior directly.
+
+## Error and Empty States
+
+- No records: the receipt says `Evidence unavailable`; the inspector action is
+  disabled.
+- A record missing optional interpreted fields: show `Unavailable` for that
+  field while preserving raw evidence.
+- Malformed raw data: show the bounded raw text and a decoding note rather than
+  failing the presentation route.
+- Viewport measurement unavailable during initial render: begin from the
+  `1280x720` logical canvas and recompute after measurement.
+
+## Verification
+
+Unit and component tests cover:
+
+- logical sizing at `1024x768`, `1200x800`, and `1280x720`;
+- clamping and letterboxing outside the supported ratio range;
+- no primary-stage dimension change between receipt and inspector states;
+- receipt content and explicit inspector opening;
+- inspector close, focus restoration, and `Escape` behavior;
+- chat and evidence overlay exclusivity in compact layouts;
+- inspector closure and receipt update on beat navigation;
+- reduced-motion behavior and empty/malformed evidence states.
+
+Playwright review captures the same representative viewports and verifies that
+the graph, current claim, progress row, and evidence receipt remain readable
+without page scroll. At least one screenshot per viewport includes the open
+inspector. Screenshot review is manual; brittle pixel-diff thresholds are not
+required.
+
+## Acceptance Criteria
+
+1. The audience route uses the available stage area continuously between `4:3`
+   and `16:9`.
+2. The primary visual exposes the same information at every supported ratio.
+3. Evidence availability never resizes the primary visual.
+4. Beat navigation never opens detailed evidence automatically.
+5. The progress row exposes concise evidence provenance when requested.
+6. The inspector is keyboard accessible and readable at all supported ratios.
+7. Compact chat and evidence overlays cannot obscure each other.
+8. Existing scene, beat, Focus Path, replay, and evidence data contracts remain
+   intact.
+
+## Out of Scope
+
+- arbitrary responsive layouts below `4:3` or above `16:9`;
+- mobile presentation authoring;
+- a URL-selectable aspect-ratio mode;
+- changing the evidence transport or canonical recording format;
+- redesigning individual scene visuals;
+- implementing the deferred child-figure Reveal motion.