From 6d7738d538612a2a34cf13d2b1c52242a8b5e8ec Mon Sep 17 00:00:00 2001
From: User <user@example.com>
Date: Tue, 14 Jul 2026 10:17:26 +0200
Subject: [PATCH] docs: specify model activity layout and composer state

---
 ...tivity-layout-and-composer-state-design.md | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-14-model-activity-layout-and-composer-state-design.md

diff --git a/docs/superpowers/specs/2026-07-14-model-activity-layout-and-composer-state-design.md b/docs/superpowers/specs/2026-07-14-model-activity-layout-and-composer-state-design.md
new file mode 100644
index 00000000..8520594e
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-14-model-activity-layout-and-composer-state-design.md
@@ -0,0 +1,56 @@
+# Model activity layout and composer state
+
+## Scope
+
+Refine the frontend shell in three coordinated ways:
+
+1. Preserve readable line and message boundaries in the left **Model activity** panel.
+2. When that panel is open, hide the right session rail and divide the application area
+   between model activity (40%) and chat (60%).  Restore the existing conversation plus
+   right-session-rail layout when it is closed.
+3. Keep the composer white except while it is actively requesting reviewer input: after
+   **New session** starts a new question, or when an input widget/gate is pending.
+
+## Design
+
+`AppShell` remains the single owner of whether Model activity is open.  Its outer layout
+will apply a conditional grid/flex sizing variant while `showActivity` is true: the activity
+panel consumes 40% of the available application width, the conversation consumes 60%, and
+the right rail is not rendered.  With the panel closed, the current conversation and
+15vw session rail remain unchanged.
+
+`ModelActivityPanel` will display stream progress as distinct rows/paragraphs, preserving
+meaningful newline boundaries and ensuring consecutive model updates do not appear as one
+unbroken sentence.  It will continue to show only the activity stream, without changing
+its source data or persistence model.
+
+The composer gets an explicit `awaitingInput` condition.  It is true when a new-session
+action has put the landing composer into question-entry mode, and while a pending
+user-input widget requires a free-text response.  Its green `thot-awaiting-input` treatment
+is applied only for that condition; every other composer state uses the normal white card
+background.  The widget's own free-text textarea remains highlighted whenever it is rendered,
+because rendering it itself means that the workflow is awaiting input.
+
+## Error handling and compatibility
+
+No API, SSE contract, session persistence, or workflow-state changes are required.  The
+existing `showActivity`, session, and pending-widget state remain authoritative.  If the
+activity panel has no messages, opening it still uses the 40/60 layout and simply displays
+its current empty state.
+
+## Tests
+
+- Update/add shell tests verifying that opening Model activity hides the session rail and
+  applies the open-layout markers/classes, then restores them after closing.
+- Add activity-panel coverage for consecutive streamed text/newline rendering.
+- Update composer tests to assert the green awaiting-input marker is absent initially,
+  appears after **New session**, and is present when an input widget is pending.
+- Run frontend Vitest and TypeScript checks.
+
+## Explicit decisions
+
+- "Left sidebar" means the Model activity panel opened by the header arrow.
+- The requested 40%/60% allocation applies only while that panel is open.
+- The right session rail is hidden, rather than overlaid or resized, while Model activity is
+  open.
+- "Normally white" includes the initial landing state and free steering in an active session.