Builder rework: phase-centric editor + exhibit/quant picker (replaces Phase 7 of #22)

[ludakhris]

Goal

Rebuild the scenario builder so authoring a case feels like writing the case, not wiring a flowchart or hopping between form panels. A non-technical author should create and edit every step in one scrolling document — no YAML, no node graph, no ids, no formula syntax.

Originally tracked as Phase 7 of #22 — moved here because bolting seven more entity types onto the node-graph canvas makes the wrong model worse.

Why the current builder fails authors

• It only knows 3 node types. useBuilderCanvas maps decision / transition / feedback; choices are hardcoded A–D. Quant questions, all 5 exhibit kinds, phases, and KeyData panels have zero authoring UI today — they exist only because the YAML was hand-written.
• Too much technical knowledge. Authors hit raw nodeIds, exhibitIds arrays, {token} formula expressions, and quality-signal shapes.
• Too much clicking. The graph forces a select-node → open-side-panel → edit → close loop. You can't see and edit all the steps at once.

The reframe — the case is a document

An author thinks linearly: "Here's the setup. Candidate picks how to structure it. If bottom-up, good — show this table. Now size it, here's the formula. Then recommend; here are the ways it can land." That's a linear narrative with a few off-ramps that rejoin — which is exactly what all 6 cases already are (wrong paths were converted to redirect transitions). So the editor is a single top-to-bottom document where every block is edited in place.

Mockups

Document editor — phases rail on the left, the case as one scrolling document; every block (narrative, decision, exhibit, question) is expanded and editable where it sits. Phase order = the order the candidate walks the case.

Visual gallery picker — "+ insert block" opens a tabbed gallery (Exhibits / Quant / Decisions). Each card uses the real screenshots from /dev/exhibits + /dev/quant as previews. Pick → a working, pre-filled block drops in at that spot.

Plain-math quant editor — the author types ordinary math (new_BEV_homes × attach_rate × …); we tokenize it, find the variables, and they just label each one + pick units. Carry-forward is a dropdown ("from the TAM answer"). No {token} syntax, no nodeIds. Band by slider; optional hint capped at Proficient.

New-case start — blank, clone a template, or describe it in a sentence and let Claude scaffold the phases/exhibits/questions.

Locked decisions

• Document/outline editor, not a graph and not a side-panel inspector. One scroll, edit in place, everything expanded by default.
• Phase order carries the flow. An option with no explicit target just continues to the next block. Authors set a target only for exceptions (endings, redirects).
• Visual gallery picker for inserting blocks — card gallery with real screenshot previews + one-line blurb + hover help.
• Plain math field + tokenizer for formulas — author types normal math, we extract variables and ask only for labels/units. The {token} expression is generated, never shown.
• AI scaffold + template clone for starting a case (reduces the blank-page tax). Reuses the existing Anthropic client; the prompt string lives in prompts.config.ts.
• Same Scenario JSON blob (Prisma data field) — no new tables. The document is a humane view over it, so the 6 existing cases import with zero migration. YAML round-trip stays intact as a power-user fallback.
• Graph canvas demoted, not deleted — survives under /builder/:id/advanced for power users.
• Desktop-only. Mobile builder out of scope.

What the author never touches

Machine detail today	What the author sees instead
nodeId, exhibitId	nothing — auto-generated, referenced by label
exhibitIds: [] per phase	exhibit sits where you drop it; "show again later" = a toggle
formula expression: '{a}*{b}'	a plain math field; we tokenize and ask for labels/units
QuantVariable.source.{nodeId,fieldId}	"use the answer from ▾ [earlier question]" dropdown
rubricDimensions per phase	dimension chips clicked on/off in the phase header
qualitySignals[] shape	a Strong / Proficient / Developing ▾ dropdown per option
builderMeta.positions (graph geometry)	gone — phase order replaces it

Architecture keystone — the Entity Registry

One descriptor per kind drives the gallery card, the blank seed, the in-document editor, and the live preview. Add a kind once → it appears in the picker, seeds non-empty, gets an editor, and renders a preview. No per-kind logic scattered across files.

// apps/web/src/builder-v2/registry.ts
type EntityKind =
  | 'data-table' | 'profit-tree' | 'segmentation-matrix' | 'chart' | 'text-exhibit'
  | 'numeric-range' | 'structured-quant'
  | 'decision' | 'transition' | 'feedback'

interface EntityDescriptor<T> {
  kind: EntityKind
  group: 'exhibit' | 'quant' | 'node'
  label: string                       // "Data Table"
  blurb: string                       // gallery caption
  screenshot: string                  // docs/screenshots/{exhibits|quant}/NN.png
  helpHtml?: string                   // hover help, lifted from /dev galleries
  seed: (id: string) => T             // non-empty blank (placeholder title, 2 cols, 2 options…)
  Editor: React.FC<EntityEditorProps<T>>   // in-document editor
  Preview: React.FC<{ entity: T }>         // wraps the PRODUCTION renderer
}

Preview/Editor wrap the existing production components (DataTable, ProfitTree, SegmentationMatrix, ChartExhibit, TextExhibit, QuantNode, KeyDataPanel) → preview parity is free, not re-implemented.

Phased checklist

Phase A — Document editor shell

• Route /builder/v2/:scenarioId (legacy BuilderCanvasPage stays as /advanced).
• Two regions: phases rail (left, drag-reorder, status dots, "+ Add phase") | document (center, max ~840px).
• useBuilderDoc — single source of truth is the Scenario blob; immutable patches; debounced autosave via existing updateScenario PUT.
• First cut: read-only inline render of all 10 kinds in candidate order (reuse production renderers via registry Preview).
• Toolbar: editable title, save status, "Preview as candidate", advanced-mode link, Publish.

Phase B — Visual gallery picker + insertion

• builder-v2/registry.ts with all 10 descriptors + non-empty seeds.
• "+ insert block" between any two blocks opens a tabbed gallery modal (Exhibits / Quant / Decisions).
• Cards = screenshot from docs/screenshots/{exhibits,quant}/ + blurb + example use + hover help.
• Pick → seed(id) inserts at the click position and links it into the phase. Empty phase shows the gallery immediately.

Phase C — In-document editors (edit in place, no panel hop)

• text-exhibit: typed blocks (paragraph / bullets / quote), drag-reorder, quote attribution.
• data-table: grid editor (columns + rows), per-cell tone/emphasis, optional total row.
• profit-tree: nested node editor, add/remove children inline.
• segmentation-matrix: axis labels + 4 quadrant lists.
• chart: series rows, baseline, annotation.
• numeric-range / structured-quant: prompt + band sliders + plain math field with tokenizer (extracts vars → inline label/unit prompts → generates QuantFormula.expression) + hint + footnote with the "capped at Proficient" note.
• decision: option rows (text + Strong/Proficient/Developing dropdown + target); add/remove options (drops the A–D hardcode).

Phase D — Flow by order + exception wiring

• Target defaults to "continue" (next block); explicit target only for exceptions.
• Endings: "Wrap-up" section; final decision options map to endings by label dropdown.
• Redirect renders as an inline "↩ back to rephrase" badge.
• Carry-forward dropdown over prior quant nodes/fields (no nodeId typing).
• Phase rubric = clickable dimension chips; shared exhibit = "show again later" toggle.

Phase E — New-case start (AI scaffold + templates)

• /builder/v2/new: pick track + subcategory + minutes → blank / clone template / describe-to-Claude.
• Clone reuses duplicateScenario + prompts for new id/title.
• POST /api/scenarios/scaffold { description, track, subcategory, minutes } → { scenario }. Anthropic client pattern from ai-feedback.service.ts; prompt string in prompts.config.ts. Returns phases populated, placeholder exhibits in the right phases, narratives marked TODO.
• Export scenario JSON for power users.

Phase F — Preview parity + validation

• "Preview as candidate" → existing ?builderPreview=true flow via sessionStorage.
• Extend validateScenario with case rules: band min<max, ideal inside accepted, formula vars resolve, options have targets, exhibit/node refs resolve, phase non-empty. Plain-language messages (no nodeId jargon) in an Issues panel.
• Publish gate: published flips only when the Issues panel is empty.
• YAML round-trip fixture test per kind (scenarioToYaml / yamlToScenario).

Phase G — Decommission old builder

• Redirect /builder/:scenarioId → /builder/v2/:scenarioId.
• Graph canvas remains at /builder/:scenarioId/advanced for power users.
• Route telemetry on /advanced; delete dead graph code after 30 days of zero hits.

Risks / sequencing

• Build the registry (B) before the editors (C) — editors are just Editor slots in descriptors.
• Dropping the A–D hardcode touches validateScenario and useSimulation choice/scoring assumptions — audit those before Phase C lands.
• YAML round-trip must survive every new field — fixtures gate Phase F.

Out of scope

Multi-author permissions/workflows · version branches · real-time collab · marketplace · builder forms tuned for non-business-case tracks · mobile builder.

Acceptance

• A non-technical author builds biz-case-001 from scratch in v2 — no YAML, no graph, no docs — editing every step in one scrolling document.
• Clone biz-case-002 → working customized profitability case in < 15 min.
• Claude scaffold: blank → publishable draft in < 30 min for routine variants (was > 2 hrs).
• Validation blocks publishing structurally broken scenarios that reach production today.

[ludakhris]

Phase A — Document editor shell ✅

Live at /builder/v2/:scenarioId (admin-gated). Every block the candidate sees is now visible to the author in one scrollable document.

Document top — Briefing + Your Role & Key Facts

Structure phase — Key Data tiles + Decision block with quality signals

Sizing phase — Data table + Profit tree inline

---

What's working:

• Phases rail (left) with drag-to-reorder
• Briefing + sidebar rendered at document top
• All phase blocks in candidate order: text exhibits, data tables, profit trees, charts, segmentation matrices, decision options with quality signal badges, quant blocks with bands + hint indicators
• Key Data tiles (contextPanels) shown inline above each decision
• ▶ Preview as candidate → launches simulation, responses not saved, "← Back to builder" returns to v2
• Advanced ↗ → opens legacy graph canvas (auth fix applied to both builders)

Next: Phase B — visual gallery picker + insertion (the + block insert button)

[ludakhris]

Phase B — Gallery picker + insertion + phase rename

What shipped

BlockPicker modal — redesigned from card grid to full-preview layout:

• Tab order: Decisions & Flow (first) → Exhibits → Quant
• Kind selector pills switch the preview instantly
• Exhibits/Quant show real screenshot thumbnails at full modal width
• Decision/Transition/Ending show styled inline mockups (no screenshots needed)
• ＋ Insert [Kind] button in footer

Insertion wired end-to-end:

• Hover any block → ＋ insert block affordance appears between blocks
• Empty phase → ＋ Insert first block button opens picker immediately
• Pick → seed(kind, id) called → block appended to phase → autosave fires

Phase rename — hover pencil ✎ icon on any phase row → inline input → Enter/blur commits, Escape cancels

---

Screenshots

Insert affordance (hover)

Picker — Decisions & Flow (Decision selected)

Picker — Exhibits (Data Table selected)

After inserting a block (save status → Unsaved)

Phase rename — hover to reveal pencil

Phase rename — inline edit active

[ludakhris]

Phase C shipped — inline editors for all 10 block kinds

Commit: 33d2d5bd9c1ad55b199f765089f769a9cc28af54

All 10 block editors are wired in-place. Click ✎ Edit on any block to edit without leaving the document — Done commits and returns to read view.

What's in this drop

Editors built (9 new files in builder-v2/editors/)

• Decision — narrative, Key Data tiles (grouped cards), choices with quality signal + target dropdown
• Transition / Redirect — narrative + next-node select
• Ending — narrative textarea
• Numeric Range / Structured Quant — prompt, per-field bands, plain-math formula tokenizer, hint + footnote
• Text / Memo — single markdown-lite textarea (blank line = paragraph, - = bullets, > = quote)
• Data Table — column definitions with sub-headers, grid rows, total row in <tfoot>
• Profit Tree — multi-root support (roots?: ProfitTreeNode[]), "Add top-level node" button
• Segmentation Matrix — axis labels, quadrant headers, per-item label + caption fields
• Chart — series rows, baseline, annotation

Polish applied during review:

• Key Data tiles now each in their own grouped card (was: flat form row)
• DataTable total row aligned inside the table grid
• SegMatrix items show both label and caption (was: label only — "High need, sparse network" was missing)
• ProfitTree now supports multiple top-level nodes (was: single root only)
• Text/Memo editor replaced with a single textarea (markdown-lite syntax)
• ✎ Edit chip always visible on block header (was: hover-only pencil, invisible)
• BuilderListPage crash fixed (nodes defensive null-check)

Screenshots

Phase C — document view with ✎ Edit chips

Text/Memo editor — single textarea, markdown-lite

Sizing phase — quant + profit tree blocks

Decision editor — Key Data tiles in grouped cards, choices with quality signals

[ludakhris]

Phase D — Flow wiring + exception targeting ✅

What changed

Phase rail navigation
Clicking a phase in the left rail now smooth-scrolls the document to that phase section.

---

Decision option targets — grouped dropdown + "continue" default

Option targets now default to → continue (next block) (empty = implicit flow). The dropdown groups nodes by type so authors stop guessing raw nodeIds:

• 🏁 Endings — feedback/wrap-up nodes
• ↩ Redirects — transition nodes
• 🔀/🔢 Other nodes — decisions + quant

---

Transition redirect badge

Transition blocks now render an amber ↩ back to: <narrative> pill instead of the raw nodeId string.

---

Wrap-up section

Feedback/ending nodes that aren't assigned to any phase now appear in a dedicated amber-accented Wrap-up section at the bottom of the document. Authors can edit endings without hunting for orphaned nodes.

---

Clickable rubric chips + exhibit sharing

Phase header rubric dimension chips are now live toggle buttons — lit green = scoring this phase, dim = available but inactive. "↻ show again later" on exhibits is wired: clicking adds/removes the exhibit from all subsequent phases atomically.

---

Carry-forward dropdown on quant formula variables

Formula variables now show a ← carry fwd dropdown populated with prior quant nodes. Structured-quant sources also expose a field picker. No more typing raw nodeIds.

---

Phase D checklist

• Target defaults to "continue" (next block); explicit target only for exceptions
• Endings: "Wrap-up" section; final decision options map to endings by label dropdown
• Redirect renders as inline "↩ back to rephrase" badge
• Carry-forward dropdown over prior quant nodes/fields (no nodeId typing)
• Phase rubric = clickable dimension chips; shared exhibit = "show again later" toggle

Commit: a8d1e9b