tenbo-dashboard 0.1.0

package/src/styles.css

@@ -0,0 +1,228 @@
+/*
+ * tenbo dashboard — design tokens
+ * Spec: DESIGN.md (north star: "The Side Console")
+ * Console palette is canonical. Legacy semantic vars (--bg, --fg, etc.)
+ * alias to Console tokens so existing component CSS inherits the new look.
+ */
+:root {
+  /* Console stack — neutrals, OKLCH hue 60 (warm rust tint) */
+  --console-black: #1a1816;
+  --console-soot: #211f1c;
+  --console-iron: #2a2724;
+  --console-mist: #36322e;
+  --console-steel: #524c46;
+  --console-smoke: #7a736d;
+  --console-fog: #aba39e;
+  --console-snow: #f1edeb;
+
+  /* Signals — single interactive accent + reserved status colors */
+  --signal-cyan: #4fc3d2;
+  --signal-cyan-deep: #2f96a3;
+  --live-green: #4dc089;
+  --slow-amber: #e8b85b;
+  --halt-red: #e0644f;
+
+  /* Geometry */
+  --r-sm: 4px;
+  --r-md: 8px;
+  --r-lg: 12px;
+  --r-full: 9999px;
+
+  /* Spacing — 8px base, with one half-step */
+  --s-half: 4px;
+  --s-1: 8px;
+  --s-2: 16px;
+  --s-3: 24px;
+  --s-4: 32px;
+  --s-6: 48px;
+  --s-8: 64px;
+
+  /* Motion */
+  --ease: cubic-bezier(0.25, 1, 0.5, 1);
+  --dur-state: 120ms;
+  --dur-entry: 200ms;
+
+  /* Elevation (modals only) */
+  --shadow-modal: 0 16px 48px -8px rgba(0, 0, 0, 0.6);
+
+  /* Legacy semantic aliases — point at Console tokens */
+  --bg: var(--console-black);
+  --bg-2: var(--console-soot);
+  --fg: var(--console-snow);
+  --muted: var(--console-fog);
+  --border: var(--console-mist);
+  --accent: var(--signal-cyan);
+  --status-now: var(--live-green);
+  --status-next: var(--signal-cyan);
+  --status-later: var(--console-steel);
+  --status-done: var(--console-smoke);
+  --error: var(--halt-red);
+  --warning: var(--slow-amber);
+
+  /* Forward-looking semantic aliases used by individual components */
+  --surface: var(--console-soot);
+  --surface-muted: var(--console-iron);
+  --foreground: var(--console-snow);
+  --text-muted: var(--console-fog);
+  --code-bg: var(--console-iron);
+
+  /* Layering — nav bars sit at 40–50; modals must clear them */
+  --z-drawer: 10;
+  --z-drawer-content: 11;
+  --z-header: 50;
+  --z-modal: 100;
+  --z-modal-content: 101;
+  --z-validate: 110;
+  --z-validate-content: 111;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font-family: 'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  font-feature-settings: 'cv11', 'ss03';
+  color: var(--fg);
+  background: var(--bg);
+  -webkit-font-smoothing: antialiased;
+}
+button {
+  font: inherit;
+  color: inherit;
+  background: transparent;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+}
+input, select, textarea {
+  font: inherit;
+  color: var(--fg);
+  background: var(--console-soot);
+  border: 1px solid var(--border);
+  border-radius: var(--r-md);
+  padding: 6px 10px;
+  outline: none;
+  transition: border-color var(--dur-state) var(--ease);
+}
+input::placeholder, textarea::placeholder { color: var(--console-smoke); }
+input:focus-visible, select:focus-visible, textarea:focus-visible {
+  border-color: var(--signal-cyan);
+}
+select {
+  appearance: none;
+  -webkit-appearance: none;
+  padding-right: 28px;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 24 24' fill='none' stroke='%23aba39e' stroke-width='1.75' stroke-linecap='round' stroke-linejoin='round'><polyline points='6 9 12 15 18 9'/></svg>");
+  background-repeat: no-repeat;
+  background-position: right 8px center;
+}
+hr { border: none; border-top: 1px solid var(--border); }
+:focus-visible { outline: 2px solid var(--signal-cyan); outline-offset: 2px; border-radius: var(--r-sm); }
+
+/* Anchor styling — Signal Cyan, no underline reset on bare links */
+a {
+  color: var(--signal-cyan);
+  text-decoration: none;
+  transition: color var(--dur-state) var(--ease);
+}
+a:hover { color: var(--console-snow); text-decoration: underline; text-underline-offset: 3px; }
+
+/* Tab-strip pattern: bare buttons with aria-pressed.
+   Applies wherever the codebase already uses this semantic. */
+nav button[aria-pressed] {
+  padding: 6px 10px;
+  margin-right: 4px;
+  border-radius: var(--r-md);
+  color: var(--console-fog);
+  font-weight: 600;
+  font-size: 13px;
+  transition: background var(--dur-state) var(--ease), color var(--dur-state) var(--ease);
+}
+nav button[aria-pressed]:hover { color: var(--console-snow); background: var(--console-soot); }
+nav button[aria-pressed="true"] { color: var(--console-snow); background: var(--console-iron); }
+@media (prefers-reduced-motion: reduce) {
+  * { transition: none !important; animation: none !important; }
+}
+
+/* Utility classes (used across components) */
+.link-button {
+  background: transparent;
+  border: none;
+  color: var(--accent);
+  cursor: pointer;
+  text-decoration: underline;
+  padding: 0;
+  font: inherit;
+}
+.muted-text {
+  color: var(--muted);
+  font-size: 12px;
+}
+.muted-small {
+  color: var(--muted);
+  font-size: 11px;
+}
+.bare-button {
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+}
+.outlined-button {
+  background: transparent;
+  color: var(--fg);
+  border: 1px solid var(--border);
+  border-radius: var(--r-md);
+  padding: 6px 10px;
+  cursor: pointer;
+  font: inherit;
+  transition: background var(--dur-state) var(--ease), border-color var(--dur-state) var(--ease);
+}
+.outlined-button:hover {
+  background: var(--console-soot);
+  border-color: var(--console-steel);
+}
+.close-x {
+  float: right;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  background: transparent;
+  border: none;
+  border-radius: var(--r-md);
+  color: var(--console-fog);
+  cursor: pointer;
+  transition: background var(--dur-state) var(--ease), color var(--dur-state) var(--ease);
+}
+.close-x:hover { background: var(--console-iron); color: var(--console-snow); }
+
+/* icon + label flex utility — gap matches Inter cap-height rhythm */
+.icon-text {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+/* Lucide icons inherit text color; align to baseline implicitly via flex */
+.bare-button {
+  display: inline-flex;
+  align-items: center;
+}
+.overlay-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.4);
+}
+.dim-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.3);
+}
+hr.section-divider {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 16px 0;
+}

package/src/test-setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/src/types.ts

@@ -0,0 +1,202 @@
+import type { Finding } from './api/lib/health/types';
+
+// Naming convention:
+// - snake_case fields mirror on-disk JSON/YAML keys (e.g., `description` from architecture.yaml,
+//   `file_count` from metrics.json). Do not rename these — they round-trip with the file format.
+// - camelCase fields are in-memory composed state assembled by the viewer (e.g., `crossCuttingRoadmap`,
+//   `layerDocs`). Renaming these is purely an internal refactor.
+
+export type Status = 'now' | 'next' | 'later' | 'done';
+
+/**
+ * Advisory priority marker. Does NOT affect roadmap ordering — items still execute
+ * in `status` bucket + file order (see Behavior 6). Priority is purely a flag agents
+ * and humans can use to highlight critical items in the viewer or in queries.
+ * Optional: most items leave it unset.
+ */
+export type Priority = 'p0' | 'p1' | 'p2' | 'p3';
+
+/**
+ * Optional per-phase progress entry for multi-phase roadmap items.
+ *
+ * Phases are ordered by their position in the YAML list. The numeric `id` is for
+ * stable references (`<item-id>.p<id>`); the validator checks ids are 1..N positional.
+ *
+ * When `phases:` is present on an item, the item's top-level `status` is derived
+ * (`done` if every phase is done; `now` if any phase is `now`; otherwise `next`
+ * if any phase is `next`; otherwise `later`). See `derivePhaseStatus` in
+ * `phases.ts`.
+ */
+export interface Phase {
+  id: number;
+  title: string;
+  status: Status;
+  /** YYYY-MM-DD; set when status becomes `done`. */
+  completed_at?: string;
+  notes?: string;
+}
+
+export interface Item {
+  id: string;                  // rm-NNN
+  title: string;
+  layer?: string;              // single-layer items
+  layers?: string[];           // cross-scope items
+  status: Status;
+  description: string;
+  links?: string[];
+  notes?: string;
+  /** layer ids touched by this item (bare ids for same-scope items, "<scope>:<layer>" for cross-scope items) */
+  affects?: string[];
+  /** 1–3 plain-language bullets defining "done" */
+  done_when?: string[];
+  /** repo-relative file paths that future implementers should read first */
+  files_to_read?: string[];
+  /** freeform bullets noting known unknowns or risks */
+  risks?: string[];
+  type?: 'feature' | 'bug' | 'refactor' | 'spike';
+  priority?: Priority;
+  /** Optional multi-phase progress. When present, item-level `status` is derived. */
+  phases?: Phase[];
+  /**
+   * At-most-one parent: the id of the roadmap item that surfaced/dispatched this one.
+   * Format matches the standard item id pattern (`<prefix>-NNN` or `x-NNN`).
+   * Convention (Behavior 5 DoD): when a subagent's report surfaces a follow-up item,
+   * the new item should set `spawned_from` to the dispatching item's id.
+   */
+  spawned_from?: string;
+  /**
+   * Peer relationships. Any number of ids in the same format. Order is not significant.
+   * Not parent–child — for that use `spawned_from`.
+   */
+  related?: string[];
+  /**
+   * Stamped during Behavior 5 DoD when this item flips to `done`.
+   * Either an ISO date (`YYYY-MM-DD`) confirming the layer's intent.md/code-map.md
+   * was updated as part of completing this item, OR `skipped — <reason>` for
+   * internal-only changes with no architecture surface impact. The validator
+   * (x-003 phase 3) warns when an item with status:done and type ∈ {feature,
+   * refactor, bug} lacks this field.
+   */
+  doc_update?: string;
+}
+
+export interface Layer {
+  id: string;
+  name: string;
+  description: string;
+  files: string[];
+  dependencies?: {
+    /** layer ids in same scope that import from this layer */
+    inbound?: string[];
+    /** layer ids in same scope that this layer imports from */
+    outbound?: string[];
+    /** package names or external service identifiers (e.g., "anthropic-sdk", "supabase-js"); not layer ids */
+    external?: string[];
+  };
+  parent?: string;
+}
+
+export interface Scope {
+  id: string;
+  path: string;
+  description: string;
+  layers: Layer[];
+  items: Item[];
+}
+
+export interface CrossCutting {
+  id: string;
+  description: string;
+  spans: string[];
+}
+
+export interface LayerMetrics {
+  file_count: number;
+  total_lines: number;
+  outbound_deps: number;
+  deep_dive_count: number;
+  intent_age_days: number | null;
+  pct_roadmap_in_now: number;
+}
+
+export interface ScopeMetrics {
+  /** ISO 8601 UTC timestamp */
+  generated_at: string;
+  layers: Record<string, LayerMetrics>;
+  /** Findings produced by health analyzers. Empty array until Phase 1 is wired. */
+  findings: Finding[];
+}
+
+/** In-memory file-presence flags; composed by tenboFs from filesystem checks. Not on disk. */
+export interface LayerDocs {
+  hasIntent: boolean;
+  hasCodeMap: boolean;
+  /** epoch milliseconds (matches fs.statSync().mtimeMs and Date.now()); null if intent.md absent */
+  intentMtime: number | null;
+  /** epoch milliseconds; null if code-map.md absent */
+  codeMapMtime: number | null;
+  /** true if intent.md exists but contains no non-comment, non-heading content */
+  intentEmpty: boolean;
+}
+
+export interface TenboState {
+  scopes: Scope[];
+  crossCutting: CrossCutting[];
+  narratives: Record<string, string>; // key: "<scope>/<layer>", value: markdown
+  workspaceContent: WorkspaceContent;
+  crossCuttingRoadmap?: Item[];
+  layerDocs?: Record<string, LayerDocs>;
+  metrics?: Record<string, ScopeMetrics>;
+  /**
+   * Set of repo-relative paths of every file present under `.tenbo/specs/`
+   * (including `.tenbo/specs/archive/`). Populated by tenboFs.readState; used
+   * by the validator to check that `links:` entries pointing into specs
+   * resolve to a real file. Absent when `.tenbo/specs/` does not exist.
+   */
+  specFiles?: Set<string>;
+}
+
+export type ValidateLevel = 'error' | 'warning';
+
+export interface ValidateIssue {
+  level: ValidateLevel;
+  message: string;          // plain language
+  scope?: string;
+  layerId?: string;
+  itemId?: string;
+}
+
+export interface ValidateResult {
+  errors: ValidateIssue[];
+  warnings: ValidateIssue[];
+}
+
+export interface RelatedDoc {
+  path: string;              // relative to repo root
+  itemId: string;            // tenbo_item value from frontmatter
+  title?: string;            // first heading or filename
+}
+
+export interface LayerDoc {
+  filename: string;
+  title: string | null;
+}
+
+export interface WorkspaceContent {
+  overviewMd: string;
+  principlesMd: string;
+  glossaryMd: string;
+  observationsMd: string;
+  overviewMtime: number | null;
+  principlesMtime: number | null;
+  glossaryMtime: number | null;
+  observationsMtime: number | null;
+}
+
+export interface LayerContent {
+  scope: string;
+  layer: string;
+  readme: string;
+  intentMd: string;
+  codeMapMd: string;
+}

package/src/ui/DotGrid.module.css

@@ -0,0 +1,7 @@
+.backdrop {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  overflow: hidden;
+  z-index: 0;
+}

package/src/ui/DotGrid.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from 'react';
+import styles from './DotGrid.module.css';
+
+const COLS = 48;
+const ROWS = 32;
+const SPACING = 40;
+const DOT_R = 1.5;
+const ACTIVE_COUNT = 5;
+const GLOW_DURATION = 5000;
+
+const NS = 'http://www.w3.org/2000/svg';
+const DOT_COLOR = '#36322e';   // --console-mist
+const GLOW_COLOR = '#aba39e';  // --console-fog
+
+export function DotGrid() {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const container = ref.current;
+    if (!container) return;
+
+    // Respect prefers-reduced-motion
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+    if (mq.matches) return;
+
+    const svg = document.createElementNS(NS, 'svg');
+    svg.setAttribute('width', '100%');
+    svg.setAttribute('height', '100%');
+    svg.setAttribute('viewBox', `0 0 ${COLS * SPACING} ${ROWS * SPACING}`);
+    svg.setAttribute('preserveAspectRatio', 'xMidYMid slice');
+    svg.style.cssText = 'position:absolute;inset:0;';
+
+    const dots: SVGCircleElement[] = [];
+    for (let r = 0; r < ROWS; r++) {
+      for (let c = 0; c < COLS; c++) {
+        const dot = document.createElementNS(NS, 'circle');
+        dot.setAttribute('cx', String(c * SPACING + SPACING / 2));
+        dot.setAttribute('cy', String(r * SPACING + SPACING / 2));
+        dot.setAttribute('r', String(DOT_R));
+        dot.setAttribute('fill', DOT_COLOR);
+        dot.setAttribute('opacity', '0.35');
+        svg.appendChild(dot);
+        dots.push(dot);
+      }
+    }
+
+    container.appendChild(svg);
+
+    let cancelled = false;
+
+    function pickRandom(n: number): number[] {
+      const indices = new Set<number>();
+      while (indices.size < n) {
+        indices.add(Math.floor(Math.random() * dots.length));
+      }
+      return [...indices];
+    }
+
+    function glowBatch() {
+      if (cancelled) return;
+      const chosen = pickRandom(ACTIVE_COUNT);
+
+      const animations = chosen.map((idx) =>
+        dots[idx].animate(
+          [
+            { fill: DOT_COLOR, opacity: 0.35 },
+            { fill: GLOW_COLOR, opacity: 0.9, offset: 0.15 },
+            { fill: GLOW_COLOR, opacity: 0.9, offset: 0.85 },
+            { fill: DOT_COLOR, opacity: 0.35 },
+          ],
+          { duration: GLOW_DURATION, easing: 'ease-in-out' },
+        ),
+      );
+
+      animations[animations.length - 1].onfinish = () => glowBatch();
+    }
+
+    glowBatch();
+
+    return () => {
+      cancelled = true;
+      container.removeChild(svg);
+    };
+  }, []);
+
+  return <div ref={ref} className={styles.backdrop} />;
+}

package/src/ui/EmptyState.module.css

@@ -0,0 +1,11 @@
+.empty {
+  padding: 64px 24px;
+  text-align: center;
+  color: var(--console-fog);
+  font-size: 13px;
+}
+.hint {
+  font-size: 13px;
+  color: var(--console-smoke);
+  margin-top: 8px;
+}

package/src/ui/EmptyState.tsx

@@ -0,0 +1,10 @@
+import styles from './EmptyState.module.css';
+
+export function EmptyState({ message }: { message: string }) {
+  return (
+    <div className={styles.empty}>
+      <p>{message}</p>
+      <p className={styles.hint}>Run <code>set up tenbo</code> in Claude Code, then reload.</p>
+    </div>
+  );
+}

package/src/ui/FindingModal/EvidenceSection.tsx

@@ -0,0 +1,51 @@
+import type { Finding } from '../../api/lib/health/types';
+import styles from './FindingModal.module.css';
+
+export function EvidenceSection({ finding }: { finding: Finding }) {
+  const d = finding.details;
+  return (
+    <section className={styles.section}>
+      <h3 className={styles.sectionTitle}>Evidence</h3>
+      {d.kind === 'hotspot-files' && (
+        <ul className={styles.kvList}>
+          <li><span>LOC</span><span>{d.loc.toLocaleString()}</span></li>
+          <li><span>Commits in last 30d</span><span>{d.commits_30d}</span></li>
+          {d.top_functions.length > 0 && (
+            <li><span>Top functions</span><span>{d.top_functions.map(fn => `${fn.name} (${fn.loc})`).join(', ')}</span></li>
+          )}
+        </ul>
+      )}
+      {d.kind === 'aging-todos' && (
+        <ul className={styles.kvList}>
+          <li><span>Line</span><span>{finding.target}:{d.line}</span></li>
+          <li><span>Age</span><span>{d.age_days} days</span></li>
+          <li><span>Author</span><span>{d.author}</span></li>
+          <li><span>Commit</span><span><code>{d.commit_hash.slice(0, 7)}</code></span></li>
+          <li><span>Text</span><span><code>{d.text}</code></span></li>
+        </ul>
+      )}
+      {d.kind === 'doc-drift' && (
+        <ul className={styles.kvList}>
+          <li><span>Drift type</span><span>{d.drift_type}</span></li>
+          <li><span>Doc</span><span>{d.doc_path}</span></li>
+          <li><span>Affected files</span><span>{d.affected_files.join(', ')}</span></li>
+        </ul>
+      )}
+      {d.kind === 'test-coverage' && (
+        <ul className={styles.kvList}>
+          <li><span>Suggested test path</span><span><code>{d.suggested_test_path}</code></span></li>
+        </ul>
+      )}
+      {d.kind === 'architecture-compliance' && (
+        <ul className={styles.kvList}>
+          <li><span>Expected</span><span><code>{d.expected_path_pattern}</code></span></li>
+          <li><span>Actual</span><span><code>{d.actual_path}</code></span></li>
+          <li><span>Rule</span><span>{d.rule}</span></li>
+        </ul>
+      )}
+      {(d.kind === 'dead-code' || d.kind === 'coupling' || d.kind === 'redundancy') && (
+        <pre className={styles.rawDetails}>{JSON.stringify(d, null, 2)}</pre>
+      )}
+    </section>
+  );
+}

package/src/ui/FindingModal/FindingModal.module.css

@@ -0,0 +1,31 @@
+.backdrop { z-index: var(--z-modal); background: rgba(0, 0, 0, 0.6); }
+.modal {
+  position: fixed;
+  top: 8vh;
+  left: 50%;
+  transform: translateX(-50%);
+  width: min(640px, calc(100vw - 32px));
+  max-height: 84vh;
+  overflow-y: auto;
+  background: var(--console-iron, #1a1a1a);
+  border-radius: var(--r-lg, 12px);
+  padding: 20px 24px 24px;
+  box-shadow: var(--shadow-modal, 0 20px 50px rgba(0, 0, 0, 0.5));
+  z-index: var(--z-modal-content);
+}
+.headline { margin-bottom: 16px; }
+.chips { display: flex; gap: 6px; margin-bottom: 8px; flex-wrap: wrap; }
+.chip { display: inline-flex; align-items: center; gap: 4px; font-size: 11px; padding: 2px 8px; border-radius: 12px; background: var(--hover, #1a1a1a); color: var(--muted, #aaa); }
+.title { font-size: 18px; font-weight: 600; margin: 0; }
+.targetLink { font-family: ui-monospace, monospace; font-size: 12px; color: var(--link, #4299e1); background: transparent; border: none; padding: 0; cursor: pointer; margin-bottom: 16px; }
+.section { margin-top: 20px; }
+.sectionTitle { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; color: var(--muted, #888); margin: 0 0 8px; }
+.suggestionSummary { font-weight: 500; margin: 4px 0; }
+.suggestionRationale { color: var(--muted, #aaa); font-size: 13px; margin: 4px 0; }
+.actionKind { font-size: 12px; color: var(--muted, #888); }
+.kvList { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 4px; font-size: 13px; }
+.kvList li { display: grid; grid-template-columns: 160px 1fr; gap: 12px; }
+.kvList li > span:first-child { color: var(--muted, #888); }
+.relatedList { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 4px; }
+.relatedLink { background: transparent; border: none; color: var(--link, #4299e1); cursor: pointer; padding: 0; text-align: left; font: inherit; font-size: 13px; }
+.rawDetails { font-family: ui-monospace, monospace; font-size: 11px; color: var(--muted, #888); white-space: pre-wrap; }

package/src/ui/FindingModal/FindingModal.test.tsx

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { FindingModal } from './index';
+import type { Finding } from '../../api/lib/health/types';
+
+const finding: Finding = {
+  id: 'editor.hotspot-files.foo', signal: 'hotspot-files', severity: 'critical',
+  confidence: 'high', layer: 'visual-canvas', target: 'apps/editor/src/foo.ts',
+  headline: 'foo.ts (1500 LOC)',
+  suggestion: { summary: 'Split foo.ts', rationale: 'Too big.', action_kind: 'split-file' },
+  details: { kind: 'hotspot-files', loc: 1500, top_functions: [], commits_30d: 5, split_candidates: [] },
+};
+
+describe('FindingModal', () => {
+  it('renders nothing when finding is null', () => {
+    const { container } = render(<FindingModal finding={null} allFindings={[]} onClose={vi.fn()} onOpenFile={vi.fn()} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders headline, target, suggestion summary, and rationale', () => {
+    render(<FindingModal finding={finding} allFindings={[finding]} onClose={vi.fn()} onOpenFile={vi.fn()} />);
+    expect(screen.getByText(/foo\.ts \(1500 LOC\)/)).toBeInTheDocument();
+    expect(screen.getByText(/apps\/editor\/src\/foo\.ts/)).toBeInTheDocument();
+    expect(screen.getByText(/Split foo\.ts/)).toBeInTheDocument();
+    expect(screen.getByText(/Too big\./)).toBeInTheDocument();
+  });
+
+  it('calls onClose when backdrop is clicked', () => {
+    const onClose = vi.fn();
+    render(<FindingModal finding={finding} allFindings={[finding]} onClose={onClose} onOpenFile={vi.fn()} />);
+    const backdrop = document.querySelector('.overlay-backdrop');
+    expect(backdrop).not.toBeNull();
+    (backdrop as HTMLElement).click();
+    expect(onClose).toHaveBeenCalled();
+  });
+});

package/src/ui/FindingModal/HeadlineSection.tsx

@@ -0,0 +1,17 @@
+import type { Finding } from '../../api/lib/health/types';
+import { SeverityIcon } from '../HealthPage/SeverityIcon';
+import styles from './FindingModal.module.css';
+
+export function HeadlineSection({ finding }: { finding: Finding }) {
+  return (
+    <div className={styles.headline}>
+      <div className={styles.chips}>
+        <span className={styles.chip}><SeverityIcon severity={finding.severity} /> {finding.severity}</span>
+        <span className={styles.chip}>{finding.signal}</span>
+        <span className={styles.chip}>{finding.layer}</span>
+        <span className={styles.chip}>confidence: {finding.confidence}</span>
+      </div>
+      <h2 className={styles.title}>{finding.headline}</h2>
+    </div>
+  );
+}