AGENTS.md

1# `apps/web/src/components/Theater/` (Critique Theater, web side)
2 
3Module map agents enter when they need to change the visual surface of
4the Design Jury feature. The directory keeps the internal **Theater**
5name; the user-facing label "Design Jury" comes from a single i18n key,
6`critiqueTheater.userFacingName`, so the product name can be renamed
7without code churn.
8 
9## Layout
10 
11| File | Responsibility |
12|---|---|
13| `state/reducer.ts` | Pure state machine. Driven by `PanelEvent` from the contracts package plus a synthetic `__reset__` action the hooks dispatch on context changes. |
14| `state/sse.ts` | SSE channel manager + `sseToPanelEvent` which lifts the wire shape back to a `PanelEvent`. Runs per-variant validation so a malformed frame cannot reach the reducer. |
15| `hooks/useCritiqueStream.ts` | Subscribes to the project SSE stream and feeds the reducer. Tears down on `enabled=false` and on `projectId` change, dispatching `__reset__` so a prior project's state cannot bleed in. |
16| `hooks/useCritiqueReplay.ts` | Drives the same reducer from a recorded `.ndjson(.gz)` transcript. Parse + pace are split into two effects so pause / resume preserves the cursor. |
17| `CritiqueTheaterMount.tsx` | Drop-in mount the project view uses. Owns the kill-request handshake (`POST /api/projects/:id/critique/:runId/interrupt`) and the phase-aware swap from live stage to collapsed badge. |
18| `TheaterStage.tsx` | Live-debate container. Mounts five `PanelistLane`s + `ScoreTicker` + `RoundDivider` rail + `InterruptButton`. |
19| `PanelistLane.tsx` | One row per panelist. Keyed by `data-role` for CSS tinting; no hex literals in source. |
20| `ScoreTicker.tsx` | Composite trajectory with a threshold marker. |
21| `RoundDivider.tsx` | Round-by-round separator carrying composite vs threshold. |
22| `InterruptButton.tsx` | Click + Esc binding. Esc scopes itself to non-text-input focus so the prompt textarea is safe. |
23| `TheaterDegraded.tsx` | Single chip surface for runs the orchestrator could not score. `useId()` for the heading id so multiple chips on one page do not collide. |
24| `TheaterCollapsed.tsx` | Post-run summary: shipped, interrupted, failed. The interrupted branch uses `interruptedSummary`, not `shippedSummary`. |
25| `TheaterTranscript.tsx` | Read-only replay surface bound to `useCritiqueReplay`. |
26| `hooks/useCritiqueTheaterEnabled.ts` | Reads the Settings toggle from `open-design:config` localStorage and stays in sync with cross-tab `storage` events plus the same-tab `open-design:critique-theater-toggle` CustomEvent. Pairs with the `setCritiqueTheaterEnabled` setter so a Settings save reflects in every mounted hook without a reload. |
27| `index.ts` | Public barrel. Exports the mount, the four surface components plus the `InterruptButton`, the three hooks (`useCritiqueStream`, `useCritiqueReplay`, `useCritiqueTheaterEnabled`), the imperative setter (`setCritiqueTheaterEnabled`), and the reducer-derived contract types. Everything else stays internal. |
28 
29## Invariants
30 
31- **Reducer is pure.** All state lives in `useReducer`; no `useState`
32  for run state inside the components. The reducer's actions are the
33  contract-level `PanelEvent` union plus the host-synthesized
34  `{ type: '__reset__' }`.
35- **Role-keyed tinting via `data-role`.** Components carry the role as
36  a data attribute; CSS picks the right hue via `color-mix` over an
37  existing semantic token (`var(--accent)`, `var(--amber)`,
38  `var(--purple)`, `var(--green)`, `var(--blue)`). No hex literals
39  inside this directory.
40- **All strings go through the i18n registry.** Every visible string is
41  a `t(...)` call against the `critiqueTheater.*` key namespace.
42  Hardcoded English will fail review; the locale alignment test
43  enforces every locale carries the same keyset.
44- **Terminal phases are sticky.** Once the reducer is in `shipped`,
45  `degraded`, `interrupted`, or `failed`, only a `run_started` for a
46  new runId or a host-dispatched `__reset__` can leave that phase.
47  Late `parser_warning` events are accepted because they are
48  informational, not lifecycle.
49- **Interrupt is double-action.** Click or Esc dispatches the
50  optimistic local `interrupted` action AND issues `POST
51  /api/projects/:id/critique/:runId/interrupt`. A failed fetch is
52  swallowed with a dev-mode warning so the UI still moves to the
53  collapsed badge.
54- **Designer weight is frozen at 0.0 until v2 cast config lands.**
55  Mirror of the same invariant in
56  [`apps/daemon/src/critique/AGENTS.md`](../../../../daemon/src/critique/AGENTS.md):
57  the v1 weight distribution (designer 0 / critic 0.4 / brand 0.2 /
58  a11y 0.2 / copy 0.2) is wire-shape, not a tuning knob. The web
59  side reflects that by treating composite weights as read-only:
60  `ScoreTicker` and `TheaterCollapsed` read `composite` straight off
61  the wire and never recompute it from per-panelist scores. V2
62  lands per-skill cast configuration as a Settings surface
63  (`apps/web/src/components/SettingsDialog.tsx`) that writes to the project's
64  settings row; the daemon resolver reads that row and feeds the
65  per-run weight map into the composite computation, so the web
66  layer continues to render whatever number the daemon produces. Do
67  not add a `weights` prop to any component in this directory and
68  do not recompute the composite client-side until the contracts
69  package carries the v2 cast type.
70 
71## When you change anything here
72 
731. Update `packages/contracts/src/critique.ts` first if the wire shape
74   changes. The web reducer keys off `PanelEvent`; the SSE manager
75   keys off `CRITIQUE_SSE_EVENT_NAMES`. Both live in that one file.
762. Add an i18n key to `apps/web/src/i18n/types.ts`, then define it in
77   all 19 files under `apps/web/src/i18n/locales/`. The locale files
78   carry complete dictionaries rather than inheriting missing keys from
79   English.
803. Run `pnpm --filter @open-design/web exec vitest run tests/components/Theater`
81   before pushing. The suite has 100+ cases pinning the reducer
82   shape, SSE validation, host lifecycle, and component renders.
834. Visual regression: run `pnpm --filter @open-design/e2e test:ui:extended`
84   with `--update-snapshots` after any CSS change in
85   `apps/web/src/styles/viewer/theater.css`'s `.theater-*` block.
86 
87## Related
88 
89- Spec: `specs/current/critique-theater.md`
90- Plan: `specs/current/critique-theater-plan.md`
91- User docs: `docs/critique-theater.md`
92- Daemon counterpart: `apps/daemon/src/critique/AGENTS.md`
93