+ );
+}
+
+// ---------------------------------------------------------------------------
+// BriefingFindings
+// ---------------------------------------------------------------------------
+
+/**
+ * The severity-ranked findings list for the Briefing tab. Renders nothing when
+ * there are no findings.
+ */
+export function BriefingFindings({ findings, onJumpTo }: BriefingFindingsProps) {
+ if (findings.length === 0) return null;
+ const ranked = sortFindingsBySeverity(findings);
+
+ return (
+
+
+
+
+ Findings ({String(ranked.length)})
+
+
+ advisory — never blocks
+
+
+
+ {ranked.map((finding) => (
+
+ ))}
+
+
+ );
+}
diff --git a/app/src/components/BriefingTab.tsx b/app/src/components/BriefingTab.tsx
new file mode 100644
index 0000000..ab3146b
--- /dev/null
+++ b/app/src/components/BriefingTab.tsx
@@ -0,0 +1,151 @@
+/**
+ * The Briefing tab — the review workspace's read-forward landing surface.
+ *
+ * Top to bottom: the agent's distilled intent (the "agent's read"), a curated
+ * instrument row of deterministic signals, the severity-ranked findings, and
+ * the visual recap (Excalidraw scenes + MDX). When a review has none of these —
+ * no intent, no findings, no recap, not stale — it shows a centered empty state
+ * offering to run the advisory pre-review.
+ *
+ * Findings and evidence come from the review + the existing evidence command;
+ * the recap comes from the store's `fetchRecap`. A finding's "Jump" hands off to
+ * the Diff tab via {@link BriefingTabProps.onJumpToDiff}.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Sparkles } from "lucide-react";
+import type { Review } from "../bindings/Review";
+import type { DiffSide } from "../bindings/DiffSide";
+import type { EvidenceSummary } from "../bindings/EvidenceSummary";
+import type { RecapPayload } from "../bindings/RecapPayload";
+import { useAppStore } from "../store";
+import { recapStale } from "@/lib/recap";
+import { findingsBreakdown } from "./FindingsPanel";
+import { IntentHero } from "./IntentHero";
+import { InstrumentRow } from "./InstrumentRow";
+import { BriefingFindings } from "./BriefingFindings";
+import { RecapView } from "./RecapView";
+import { EmptyState } from "./EmptyState";
+
+/** No findings are dismissed on the Briefing; it is a read-forward surface. */
+const NO_DISMISSED: ReadonlySet = new Set();
+
+interface BriefingTabProps {
+ /** The review being briefed. */
+ readonly review: Review;
+ /** Whether this tab is currently visible (gates the lazy Excalidraw mount). */
+ readonly active: boolean;
+ /** Reveal a finding's line in the Diff tab, side-aware. */
+ readonly onJumpToDiff: (path: string, side: DiffSide, line: number) => void;
+}
+
+/** The Briefing tab body. */
+export function BriefingTab({ review, active, onJumpToDiff }: BriefingTabProps) {
+ const fetchEvidence = useAppStore((s) => s.fetchEvidence);
+ const fetchRecap = useAppStore((s) => s.fetchRecap);
+ const preReview = useAppStore((s) => s.preReview);
+ const recap = useAppStore((s) => s.recaps[review.pr] ?? null);
+ const appTheme = useAppStore((s) => s.config?.app_theme ?? "dark");
+ const dark = appTheme !== "light";
+
+ const reviewPr = review.pr;
+ const reviewHead = review.head_sha;
+
+ // -- Evidence for the instrument row, refetched on head change. --
+ const [evidence, setEvidence] = useState(null);
+ useEffect(() => {
+ let cancelled = false;
+ void fetchEvidence(reviewPr).then((e) => {
+ if (!cancelled) setEvidence(e);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [reviewPr, reviewHead, fetchEvidence]);
+
+ // -- Recap payload, refetched on head change (also on `agent-completed`). --
+ useEffect(() => {
+ void fetchRecap(reviewPr);
+ }, [reviewPr, reviewHead, fetchRecap]);
+
+ // -- Regenerate / run-pre-review (advisory; refuses while an agent runs). --
+ const [preReviewing, setPreReviewing] = useState(false);
+ const handlePreReview = useCallback(async () => {
+ setPreReviewing(true);
+ try {
+ await preReview(reviewPr);
+ } finally {
+ setPreReviewing(false);
+ }
+ }, [preReview, reviewPr]);
+
+ const findingsCount = useMemo(
+ () => findingsBreakdown(review.review_findings, NO_DISMISSED),
+ [review.review_findings],
+ );
+
+ const intent = review.distilled_intent;
+ const hasFindings = review.review_findings.length > 0;
+ const stale = recapStale(review.recap_sha, review.head_sha);
+ const hasRecapContent =
+ recap !== null && (recap.mdx !== null || recap.scenes.length > 0);
+ const agentRunning = review.agent !== null;
+ const regenerateDisabled = preReviewing || agentRunning;
+
+ // The whole Briefing is empty only when there is no intent, no findings, no
+ // recap content, and nothing stale to nudge about.
+ const empty = intent === null && !hasFindings && !hasRecapContent && !stale;
+
+ if (empty) {
+ return (
+
+
+
+ );
+ }
+
+ // Show the recap block when there is content or a stale nudge to raise; feed
+ // an empty payload while the fetch is still in flight so the nudge is instant.
+ const effectiveRecap: RecapPayload = recap ?? {
+ mdx: null,
+ scenes: [],
+ sha: review.recap_sha,
+ };
+ const showRecap = hasRecapContent || stale;
+
+ return (
+
+ );
+}
diff --git a/app/src/components/DiffView.tsx b/app/src/components/DiffView.tsx
index f375882..75f5079 100644
--- a/app/src/components/DiffView.tsx
+++ b/app/src/components/DiffView.tsx
@@ -1736,6 +1736,24 @@ export function DiffView({
[],
);
+ // Cross-tab jump: consume a `pendingDiffJump` published by a sibling tab (e.g.
+ // a Briefing finding's "Jump"), reusing the same reveal machinery as the
+ // in-tab findings/evidence jumps. Keyed on the request nonce so an identical
+ // target still re-fires, and scoped to this review's PR.
+ const pendingDiffJump = useAppStore((s) => s.pendingDiffJump);
+ const consumedJumpNonceRef = useRef(-1);
+ useEffect(() => {
+ if (pendingDiffJump === null) return;
+ if (pendingDiffJump.pr !== review.pr) return;
+ if (pendingDiffJump.nonce === consumedJumpNonceRef.current) return;
+ consumedJumpNonceRef.current = pendingDiffJump.nonce;
+ handleJumpTo(
+ pendingDiffJump.path,
+ pendingDiffJump.side,
+ pendingDiffJump.line,
+ );
+ }, [pendingDiffJump, review.pr, handleJumpTo]);
+
// -- Findings panel: auto-expand on entry only when a Critical finding
// exists; otherwise leave the header collapsed-but-visible. Keyed on the PR
// so switching reviews recomputes the default without clobbering a manual
diff --git a/app/src/components/ExcalidrawCanvas.tsx b/app/src/components/ExcalidrawCanvas.tsx
new file mode 100644
index 0000000..3625c9c
--- /dev/null
+++ b/app/src/components/ExcalidrawCanvas.tsx
@@ -0,0 +1,66 @@
+/**
+ * The heavy Excalidraw viewer, isolated in its own module so it (and the
+ * `@excalidraw/excalidraw` dependency + its CSS) land in a lazy chunk, never in
+ * the main bundle. Only {@link ExcalidrawScene} imports this — dynamically.
+ *
+ * The scene JSON is external data from disk, so it is narrowed with a type
+ * guard (no `as`) into the loose `ImportedDataState` shape and passed through
+ * Excalidraw's own `restore`, which re-validates every field at runtime. The
+ * viewer is strictly read-only (`viewModeEnabled` + `zenModeEnabled`).
+ */
+
+import { useMemo } from "react";
+import { Excalidraw, restore, THEME } from "@excalidraw/excalidraw";
+import type { ImportedDataState } from "@excalidraw/excalidraw/data/types";
+import "@excalidraw/excalidraw/index.css";
+
+/** The subset of an imported scene we feed to `restore`. */
+type SceneInput = Pick;
+
+/**
+ * Narrow untyped parsed JSON to a scene input: an object with an `elements`
+ * array. The claim is intentionally loose — `restore` sanitizes the contents.
+ */
+function isSceneInput(value: unknown): value is SceneInput {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ "elements" in value &&
+ Array.isArray(value.elements)
+ );
+}
+
+interface ExcalidrawCanvasProps {
+ /** Raw Excalidraw scene JSON. */
+ readonly json: string;
+ /** Whether the app is in dark mode. */
+ readonly dark: boolean;
+}
+
+/**
+ * Render one Excalidraw scene read-only. Returns null if the JSON does not
+ * parse to a scene (the enclosing {@link ExcalidrawScene} shows a fallback).
+ */
+export default function ExcalidrawCanvas({ json, dark }: ExcalidrawCanvasProps) {
+ const initialData = useMemo(() => {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(json);
+ } catch {
+ return null;
+ }
+ if (!isSceneInput(parsed)) return null;
+ return restore(parsed, null, null);
+ }, [json]);
+
+ if (initialData === null) return null;
+
+ return (
+
+ );
+}
diff --git a/app/src/components/ExcalidrawScene.tsx b/app/src/components/ExcalidrawScene.tsx
new file mode 100644
index 0000000..787805e
--- /dev/null
+++ b/app/src/components/ExcalidrawScene.tsx
@@ -0,0 +1,109 @@
+/**
+ * Read-only viewer for one Excalidraw recap scene.
+ *
+ * Wraps the lazily-loaded {@link ExcalidrawCanvas} in a Suspense boundary (small
+ * skeleton) and an error boundary so a scene that fails to parse or render shows
+ * a fallback card (" · could not render") instead of crashing the
+ * Briefing. The `@excalidraw/excalidraw` dependency is code-split behind
+ * `React.lazy`, and `window.EXCALIDRAW_ASSET_PATH` is set to the self-hosted
+ * `/excalidraw/` path *before* the dynamic import resolves so fonts load
+ * on-origin (the default is the esm.sh CDN, which the Tauri CSP blocks).
+ */
+
+import { Component, Suspense, lazy, type ReactNode } from "react";
+import { Loader2 } from "lucide-react";
+import { isRenderableScene } from "@/lib/recap-scene";
+
+declare global {
+ interface Window {
+ /** Base URL Excalidraw resolves fonts/assets against; set for self-hosting. */
+ EXCALIDRAW_ASSET_PATH?: string;
+ }
+}
+
+// Set the self-hosted asset base before the Excalidraw module evaluates. The
+// assignment runs synchronously in the same tick as (and before) the dynamic
+// import, so the global is in place when the chunk's font loader reads it.
+const ExcalidrawCanvas = lazy(() => {
+ if (typeof window !== "undefined") {
+ window.EXCALIDRAW_ASSET_PATH = "/excalidraw/";
+ }
+ return import("./ExcalidrawCanvas");
+});
+
+// ---------------------------------------------------------------------------
+// Error boundary (must be a class — React has no hook equivalent)
+// ---------------------------------------------------------------------------
+
+interface BoundaryProps {
+ readonly fallback: ReactNode;
+ readonly children: ReactNode;
+}
+
+interface BoundaryState {
+ readonly failed: boolean;
+}
+
+class SceneErrorBoundary extends Component {
+ constructor(props: BoundaryProps) {
+ super(props);
+ this.state = { failed: false };
+ }
+
+ static getDerivedStateFromError(): BoundaryState {
+ return { failed: true };
+ }
+
+ override componentDidCatch(error: unknown): void {
+ console.error("Excalidraw scene failed to render", error);
+ }
+
+ override render(): ReactNode {
+ if (this.state.failed) return this.props.fallback;
+ return this.props.children;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// ExcalidrawScene
+// ---------------------------------------------------------------------------
+
+function FallbackCard({ name }: { readonly name: string }) {
+ return (
+
+
+ {/* Scenes first (wireframes before prose). */}
+ {recap.scenes.map((scene) => (
+
+
+ {scene.name}
+
+
+ {active ? (
+
+ ) : (
+
+ )}
+
+
+ ))}
+
+ {/* Then the recap prose. */}
+ {recap.mdx !== null && (
+
+
+
+ )}
+
+ )}
+
+ );
+}
diff --git a/app/src/components/ReviewWorkspace.tsx b/app/src/components/ReviewWorkspace.tsx
index 0c94b64..3236754 100644
--- a/app/src/components/ReviewWorkspace.tsx
+++ b/app/src/components/ReviewWorkspace.tsx
@@ -17,10 +17,12 @@ import type { Review } from "../bindings/Review";
import type { DiffData } from "../bindings/DiffData";
import type { DiffSide } from "../bindings/DiffSide";
import type { MirrorResult } from "../bindings/MirrorResult";
+import { BriefingTab } from "./BriefingTab";
import { DiffView } from "./DiffView";
import { CiPanel } from "./CiPanel";
import { AgentPanel } from "./AgentPanel";
import { Terminal } from "./Terminal";
+import { initialReviewTab, type ReviewTab } from "@/lib/review-tab";
import { Loader2 } from "lucide-react";
import { cn } from "@/lib/utils";
@@ -28,8 +30,8 @@ import { cn } from "@/lib/utils";
// Types
// ---------------------------------------------------------------------------
-/** The workspace tabs. */
-type WorkspaceTab = "diff" | "ci" | "agent" | "shell";
+/** The workspace tabs. Briefing leads while a review is fresh (see landing). */
+type WorkspaceTab = ReviewTab;
interface ReviewWorkspaceProps {
readonly review: Review;
@@ -51,6 +53,7 @@ interface ReviewWorkspaceProps {
// ---------------------------------------------------------------------------
const TABS: readonly { readonly key: WorkspaceTab; readonly label: string }[] = [
+ { key: "briefing", label: "Briefing" },
{ key: "diff", label: "Diff" },
{ key: "ci", label: "CI" },
{ key: "agent", label: "Agent" },
@@ -60,9 +63,12 @@ const TABS: readonly { readonly key: WorkspaceTab; readonly label: string }[] =
function WorkspaceTabBar({
active,
onSelect,
+ findingsCount,
}: {
readonly active: WorkspaceTab;
readonly onSelect: (tab: WorkspaceTab) => void;
+ /** Advisory finding count; badges the Briefing tab when positive. */
+ readonly findingsCount: number;
}) {
// Styling mirrors the `ui/Tabs` `line` variant so in-content tabs read the
// same across the app: a transparent bar with a baseline border and an
@@ -71,6 +77,7 @@ function WorkspaceTabBar({
{TABS.map((tab) => {
const isActive = active === tab.key;
+ const showBadge = tab.key === "briefing" && findingsCount > 0;
return (
);
})}
@@ -108,19 +123,44 @@ export function ReviewWorkspace({
onRequestChanges,
onMirrorComments,
}: ReviewWorkspaceProps) {
- // Land on the Agent tab when a spawned agent for this review is blocked on a
- // permission decision, so the reviewer arriving from the PermissionBanner sees
- // the Allow/Deny gate immediately rather than the diff.
- const [activeTab, setActiveTab] = useState(() =>
- useAppStore
- .getState()
- .pendingPermissions.some((p) => p.object_id === review.pr)
+ // Initial landing: a review blocked on a permission decision opens on the
+ // Agent tab (so the Allow/Deny gate is seen at once); otherwise the workspace
+ // lands on the Briefing while the review is fresh, else the Diff. The per-PR
+ // effect below re-applies this whenever the opened review changes.
+ const initialLanding = (r: Review): WorkspaceTab =>
+ useAppStore.getState().pendingPermissions.some((p) => p.object_id === r.pr)
? "agent"
- : "diff",
+ : initialReviewTab(r);
+ const [activeTab, setActiveTab] = useState(() =>
+ initialLanding(review),
);
const error = useAppStore((s) => s.error);
const clearError = useAppStore((s) => s.clearError);
const ensureReviewWorktree = useAppStore((s) => s.ensureReviewWorktree);
+ const requestDiffJump = useAppStore((s) => s.requestDiffJump);
+
+ // Re-land on the default tab when the opened review changes (the component is
+ // reused across reviews, so the mount-time initial state alone is not enough).
+ // Guarded by the PR ref so a routine review refresh does not re-land.
+ const landedPrRef = useRef(review.pr);
+ useEffect(() => {
+ if (landedPrRef.current === review.pr) return;
+ landedPrRef.current = review.pr;
+ setActiveTab(initialLanding(review));
+ // Only the PR identity should re-trigger landing; distilled_intent /
+ // findings are read from the review captured at that change.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [review.pr]);
+
+ // Bridge a Briefing finding's "Jump" into the Diff tab: publish the target to
+ // the store (DiffView consumes it) and switch to the Diff tab.
+ const handleJumpToDiff = useCallback(
+ (path: string, side: DiffSide, line: number) => {
+ requestDiffJump(review.pr, path, side, line);
+ setActiveTab("diff");
+ },
+ [requestDiffJump, review.pr],
+ );
const toggleAgentTab = useCallback(() => {
setActiveTab((prev) => (prev === "agent" ? "diff" : "agent"));
@@ -157,9 +197,10 @@ export function ReviewWorkspace({
// Track which tabs have been activated at least once so we can keep
// them mounted in the DOM (hidden via CSS) after first visit. This
// prevents Monaco reinitialisation and terminal session loss on
- // tab switch.
+ // tab switch. Diff is always mounted so its cross-tab jump consumer stays
+ // live; the initial landing tab is included so it paints without a flash.
const [mountedTabs, setMountedTabs] = useState>(
- () => new Set(["diff", "agent"]),
+ () => new Set(["diff", "agent", initialLanding(review)]),
);
useEffect(() => {
@@ -204,7 +245,11 @@ export function ReviewWorkspace({
return (
-
+
{error !== null && (
{error}
@@ -218,6 +263,20 @@ export function ReviewWorkspace({
)}
+ {mountedTabs.has("briefing") && (
+
+
+
+ )}
{mountedTabs.has("diff") && (
{
+ it("orders Critical > Warning > Info", () => {
+ expect(severityRank("Critical")).toBeGreaterThan(severityRank("Warning"));
+ expect(severityRank("Warning")).toBeGreaterThan(severityRank("Info"));
+ });
+});
+
+describe("sortFindingsBySeverity", () => {
+ it("ranks Critical first, then Warning, then Info", () => {
+ const info = makeFinding({ id: "i", severity: "Info" });
+ const critical = makeFinding({ id: "c", severity: "Critical" });
+ const warning = makeFinding({ id: "w", severity: "Warning" });
+
+ const sorted = sortFindingsBySeverity([info, warning, critical]);
+
+ expect(sorted.map((f) => f.id)).toEqual(["c", "w", "i"]);
+ });
+
+ it("is stable within a severity class and does not mutate the input", () => {
+ const a = makeFinding({ id: "a", severity: "Warning" });
+ const b = makeFinding({ id: "b", severity: "Warning" });
+ const input = [a, b];
+
+ const sorted = sortFindingsBySeverity(input);
+
+ expect(sorted.map((f) => f.id)).toEqual(["a", "b"]);
+ expect(input.map((f) => f.id)).toEqual(["a", "b"]);
+ expect(sorted).not.toBe(input);
+ });
+});
+
+describe("severityMeta", () => {
+ it("maps each severity to its short/label/dot/text", () => {
+ expect(severityMeta("Critical")).toEqual({
+ short: "CRIT",
+ label: "Critical",
+ dot: "bg-danger",
+ text: "text-danger",
+ });
+ expect(severityMeta("Warning").short).toBe("WARN");
+ expect(severityMeta("Info").dot).toBe("bg-muted-foreground");
+ });
+});
diff --git a/app/src/lib/finding-severity.ts b/app/src/lib/finding-severity.ts
new file mode 100644
index 0000000..daf1092
--- /dev/null
+++ b/app/src/lib/finding-severity.ts
@@ -0,0 +1,86 @@
+/**
+ * Shared severity ordering + presentation for advisory review findings.
+ *
+ * The diff-gate bands (`FindingsPanel`, the Monaco `FindingPin`) each carry
+ * their own inline copy of this mapping; the Briefing tab's read-only findings
+ * list and instrument row consume it from here so the severity conventions
+ * (Critical → danger, Warning → warning, Info → muted) stay identical without
+ * touching those bands. Presentation is returned as class-name descriptors,
+ * following the `finding-decorations` precedent of keeping the mapping pure and
+ * unit-testable.
+ */
+
+import type { ReviewFinding } from "../bindings/ReviewFinding";
+import type { FindingSeverity } from "../bindings/FindingSeverity";
+
+function assertNever(x: never): never {
+ throw new Error(`unreachable: ${String(x)}`);
+}
+
+/** Sort rank: Critical outranks Warning outranks Info. */
+export function severityRank(severity: FindingSeverity): number {
+ switch (severity) {
+ case "Critical":
+ return 3;
+ case "Warning":
+ return 2;
+ case "Info":
+ return 1;
+ default:
+ return assertNever(severity);
+ }
+}
+
+/**
+ * Findings sorted highest-severity first. Stable within a severity class, so
+ * the backend's ordering is preserved among peers. Returns a new array; the
+ * input is not mutated.
+ */
+export function sortFindingsBySeverity(
+ findings: readonly ReviewFinding[],
+): ReviewFinding[] {
+ return findings
+ .slice()
+ .sort((a, b) => severityRank(b.severity) - severityRank(a.severity));
+}
+
+/** Presentation for a finding severity: short label, dot, and text color. */
+export interface SeverityMeta {
+ /** Short uppercase label used in dense chips (`CRIT` / `WARN` / `INFO`). */
+ readonly short: string;
+ /** Full label used in row headers (`Critical` / `Warning` / `Info`). */
+ readonly label: string;
+ /** Tailwind background class for the status dot. */
+ readonly dot: string;
+ /** Tailwind text-color class for the label. */
+ readonly text: string;
+}
+
+/** Map a severity to its shared label/dot/text presentation. */
+export function severityMeta(severity: FindingSeverity): SeverityMeta {
+ switch (severity) {
+ case "Critical":
+ return {
+ short: "CRIT",
+ label: "Critical",
+ dot: "bg-danger",
+ text: "text-danger",
+ };
+ case "Warning":
+ return {
+ short: "WARN",
+ label: "Warning",
+ dot: "bg-warning",
+ text: "text-warning",
+ };
+ case "Info":
+ return {
+ short: "INFO",
+ label: "Info",
+ dot: "bg-muted-foreground",
+ text: "text-muted-foreground",
+ };
+ default:
+ return assertNever(severity);
+ }
+}
diff --git a/app/src/lib/recap-scene.test.ts b/app/src/lib/recap-scene.test.ts
new file mode 100644
index 0000000..95862e5
--- /dev/null
+++ b/app/src/lib/recap-scene.test.ts
@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { isRenderableScene } from "./recap-scene";
+
+describe("isRenderableScene", () => {
+ it("accepts a JSON object with an elements array", () => {
+ const json = JSON.stringify({
+ type: "excalidraw",
+ elements: [{ id: "1", type: "rectangle" }],
+ appState: {},
+ });
+ expect(isRenderableScene(json)).toBe(true);
+ });
+
+ it("accepts an empty elements array", () => {
+ expect(isRenderableScene(JSON.stringify({ elements: [] }))).toBe(true);
+ });
+
+ it("rejects a string that fails JSON.parse", () => {
+ expect(isRenderableScene("{ not valid json")).toBe(false);
+ });
+
+ it("rejects valid JSON with no elements array", () => {
+ expect(isRenderableScene(JSON.stringify({ appState: {} }))).toBe(false);
+ expect(isRenderableScene(JSON.stringify({ elements: "nope" }))).toBe(false);
+ });
+
+ it("rejects non-object JSON", () => {
+ expect(isRenderableScene(JSON.stringify(null))).toBe(false);
+ expect(isRenderableScene(JSON.stringify(42))).toBe(false);
+ expect(isRenderableScene(JSON.stringify([1, 2, 3]))).toBe(false);
+ });
+});
diff --git a/app/src/lib/recap-scene.ts b/app/src/lib/recap-scene.ts
new file mode 100644
index 0000000..c0d71ff
--- /dev/null
+++ b/app/src/lib/recap-scene.ts
@@ -0,0 +1,28 @@
+/**
+ * Pure guard for Excalidraw recap scene JSON.
+ *
+ * The recap scenes are raw JSON read from disk (external, untyped) and handed
+ * to the lazy Excalidraw viewer. This decides whether a scene string is worth
+ * mounting the viewer for — a JSON object carrying an `elements` array — so the
+ * Briefing can show a fallback card instead of crashing on malformed input. The
+ * viewer's own `restore` pass re-validates every element at render time.
+ */
+
+/**
+ * Whether a scene string parses to a renderable Excalidraw scene: a JSON object
+ * with an `elements` array. Returns false on any parse error or wrong shape.
+ */
+export function isRenderableScene(json: string): boolean {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(json);
+ } catch {
+ return false;
+ }
+ return (
+ typeof parsed === "object" &&
+ parsed !== null &&
+ "elements" in parsed &&
+ Array.isArray(parsed.elements)
+ );
+}
diff --git a/app/src/lib/recap.test.ts b/app/src/lib/recap.test.ts
new file mode 100644
index 0000000..66804f9
--- /dev/null
+++ b/app/src/lib/recap.test.ts
@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { recapStale, shortSha } from "./recap";
+
+describe("recapStale", () => {
+ it("is not stale when the recap SHA matches the head (fresh)", () => {
+ expect(recapStale("abcdef1234", "abcdef1234")).toBe(false);
+ });
+
+ it("is stale when the recap SHA differs from the head", () => {
+ expect(recapStale("abcdef1234", "999999aaaa")).toBe(true);
+ });
+
+ it("is not stale when there is no recap SHA (absent)", () => {
+ expect(recapStale(null, "abcdef1234")).toBe(false);
+ });
+});
+
+describe("shortSha", () => {
+ it("abbreviates to the leading 7 characters", () => {
+ expect(shortSha("abcdef1234567890")).toBe("abcdef1");
+ });
+
+ it("returns a short SHA unchanged", () => {
+ expect(shortSha("abc")).toBe("abc");
+ });
+
+ it("handles an empty SHA", () => {
+ expect(shortSha("")).toBe("");
+ });
+});
diff --git a/app/src/lib/recap.ts b/app/src/lib/recap.ts
new file mode 100644
index 0000000..1c8b44f
--- /dev/null
+++ b/app/src/lib/recap.ts
@@ -0,0 +1,26 @@
+/**
+ * Recap staleness + presentation helpers for the Briefing tab.
+ *
+ * The recap SHA pointer (`Review.recap_sha`, mirrored on the payload) is
+ * deliberately *not* cleared when the head moves, so staleness is derivable: a
+ * recap is stale when its SHA no longer matches the current head. An absent
+ * recap (`recapSha === null`) is simply absent — not stale — so it draws no
+ * regenerate nudge.
+ */
+
+/** The number of leading hex characters shown for an abbreviated SHA. */
+const SHORT_SHA_LEN = 7;
+
+/**
+ * Whether a recap is stale: it was generated (`recapSha !== null`) at a SHA
+ * that differs from the current head. A `null` recap SHA is not stale.
+ */
+export function recapStale(recapSha: string | null, headSha: string): boolean {
+ if (recapSha === null) return false;
+ return recapSha !== headSha;
+}
+
+/** Abbreviate a SHA to its leading {@link SHORT_SHA_LEN} characters. */
+export function shortSha(sha: string): string {
+ return sha.slice(0, SHORT_SHA_LEN);
+}
diff --git a/app/src/lib/review-tab.test.ts b/app/src/lib/review-tab.test.ts
new file mode 100644
index 0000000..096ccb8
--- /dev/null
+++ b/app/src/lib/review-tab.test.ts
@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { initialReviewTab } from "./review-tab";
+import { makeReview, makeFinding } from "../test/fixtures";
+
+describe("initialReviewTab", () => {
+ it("lands on Briefing when only a distilled intent is present", () => {
+ const review = makeReview({
+ distilled_intent: "This PR wires the widget.",
+ review_findings: [],
+ });
+ expect(initialReviewTab(review)).toBe("briefing");
+ });
+
+ it("lands on Briefing when only findings are present", () => {
+ const review = makeReview({
+ distilled_intent: null,
+ review_findings: [makeFinding()],
+ });
+ expect(initialReviewTab(review)).toBe("briefing");
+ });
+
+ it("lands on Diff when neither intent nor findings are present", () => {
+ const review = makeReview({
+ distilled_intent: null,
+ review_findings: [],
+ });
+ expect(initialReviewTab(review)).toBe("diff");
+ });
+
+ it("lands on Diff for a merged review whose annotations were cleared", () => {
+ // The backend clears intent + findings when the head moves, so a merged
+ // review typically has neither and stays on the diff — unchanged behavior.
+ const review = makeReview({
+ gate_state: "Merged",
+ distilled_intent: null,
+ review_findings: [],
+ });
+ expect(initialReviewTab(review)).toBe("diff");
+ });
+
+ it("still lands on Briefing when both intent and findings are present", () => {
+ const review = makeReview({
+ distilled_intent: "Reworks the parser.",
+ review_findings: [makeFinding(), makeFinding({ id: "finding-2" })],
+ });
+ expect(initialReviewTab(review)).toBe("briefing");
+ });
+});
diff --git a/app/src/lib/review-tab.ts b/app/src/lib/review-tab.ts
new file mode 100644
index 0000000..1031d80
--- /dev/null
+++ b/app/src/lib/review-tab.ts
@@ -0,0 +1,31 @@
+/**
+ * Review workspace tab identity + the default-landing decision.
+ *
+ * The workspace opens on the Briefing tab while a review is *fresh* — i.e. the
+ * pre-review agent's read or its findings are present for the current head. The
+ * backend clears `distilled_intent` and `review_findings` whenever the head
+ * moves, so their mere presence means they describe the current head (see the
+ * `Review.recap_sha` doc for why the recap pointer, by contrast, is not
+ * cleared). Otherwise the workspace lands on the Diff tab.
+ */
+
+import type { Review } from "../bindings/Review";
+
+/** A tab in the review workspace. Briefing leads, then the working tabs. */
+export type ReviewTab = "briefing" | "diff" | "ci" | "agent" | "shell";
+
+/**
+ * The tab to land on when a review is opened, ignoring the runtime overrides
+ * (a pending permission or a fresh dispatch, which the workspace applies on top
+ * of this decision).
+ *
+ * Lands on `"briefing"` iff the review carries pre-review context for the
+ * current head — a distilled intent or at least one finding — and on `"diff"`
+ * otherwise. Because the backend clears both when the head moves, a stale or
+ * merged review (whose annotations were cleared) lands on the diff.
+ */
+export function initialReviewTab(review: Review): ReviewTab {
+ const fresh =
+ review.distilled_intent !== null || review.review_findings.length > 0;
+ return fresh ? "briefing" : "diff";
+}
diff --git a/app/src/store.test.ts b/app/src/store.test.ts
index b06d085..463e1bb 100644
--- a/app/src/store.test.ts
+++ b/app/src/store.test.ts
@@ -5,6 +5,7 @@ import type { Skill } from "./bindings/Skill";
import type { CiCheck } from "./bindings/CiCheck";
import type { SubmitReviewResult } from "./bindings/SubmitReviewResult";
import type { EvidenceSummary } from "./bindings/EvidenceSummary";
+import type { RecapPayload } from "./bindings/RecapPayload";
import type { FilePair } from "./bindings/FilePair";
import type { TrajectorySummary } from "./bindings/TrajectorySummary";
import {
@@ -622,6 +623,58 @@ describe("preReview", () => {
});
});
+describe("fetchRecap", () => {
+ it("stores the recap payload keyed by PR on success", async () => {
+ const recap: RecapPayload = {
+ mdx: "# Recap\n\nWhat changed.",
+ scenes: [{ name: "architecture", json: "{}" }],
+ sha: "abc1234",
+ };
+ mockInvoke("get_review_recap", (args) => {
+ expect(args.pr).toBe("pr-1");
+ return recap;
+ });
+
+ const result = await useAppStore.getState().fetchRecap("pr-1");
+
+ expect(result).toEqual(recap);
+ expect(useAppStore.getState().recaps["pr-1"]).toEqual(recap);
+ expect(useAppStore.getState().error).toBeNull();
+ });
+
+ it("returns null and never sets the blocking error on failure (Invariant 1)", async () => {
+ const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+ mockInvokeReject("get_review_recap", "boom");
+
+ const result = await useAppStore.getState().fetchRecap("pr-1");
+
+ expect(result).toBeNull();
+ expect(useAppStore.getState().recaps["pr-1"]).toBeUndefined();
+ expect(useAppStore.getState().error).toBeNull();
+ spy.mockRestore();
+ });
+});
+
+describe("requestDiffJump", () => {
+ it("publishes a jump request and increments the nonce on re-request", () => {
+ useAppStore.getState().requestDiffJump("pr-1", "src/a.ts", "New", 12);
+ const first = useAppStore.getState().pendingDiffJump;
+ if (first === null) throw new Error("expected a pending jump");
+ expect(first).toMatchObject({
+ pr: "pr-1",
+ path: "src/a.ts",
+ side: "New",
+ line: 12,
+ });
+
+ // Re-requesting the identical target must bump the nonce so DiffView re-fires.
+ useAppStore.getState().requestDiffJump("pr-1", "src/a.ts", "New", 12);
+ const second = useAppStore.getState().pendingDiffJump;
+ if (second === null) throw new Error("expected a pending jump");
+ expect(second.nonce).toBe(first.nonce + 1);
+ });
+});
+
describe("fetchFilePair", () => {
it("returns the pair and memoizes by pr:path:head (B4)", async () => {
useAppStore.getState().filePairCache.clear();
diff --git a/app/src/store.ts b/app/src/store.ts
index 1894e63..f9a8a34 100644
--- a/app/src/store.ts
+++ b/app/src/store.ts
@@ -17,6 +17,7 @@ import type { AgentMode } from "./bindings/AgentMode";
import type { CiCheck } from "./bindings/CiCheck";
import type { DiffSide } from "./bindings/DiffSide";
import type { EvidenceSummary } from "./bindings/EvidenceSummary";
+import type { RecapPayload } from "./bindings/RecapPayload";
import type { FilePair } from "./bindings/FilePair";
import type { TrajectorySummary } from "./bindings/TrajectorySummary";
import type { ConversationItem } from "./bindings/ConversationItem";
@@ -71,6 +72,29 @@ export interface PendingPermission {
readonly requested_at_epoch_ms: number;
}
+/**
+ * A cross-tab request to reveal a specific line in the Diff tab's Monaco editor.
+ *
+ * The Briefing tab's findings live in a sibling tab from the diff editor, so a
+ * "Jump" there cannot call DiffView's internal reveal machinery directly.
+ * Instead it publishes one of these to the store; DiffView consumes it, keying
+ * on {@link nonce} so re-jumping to the same line re-fires. PR 5 (diff strip)
+ * and PR 7 (board preview rail) reuse this same field via
+ * {@link AppStore.requestDiffJump}.
+ */
+export interface PendingDiffJump {
+ /** PR ref the jump targets; DiffView ignores jumps for other reviews. */
+ readonly pr: string;
+ /** File path to select in the diff. */
+ readonly path: string;
+ /** Which diff side (`New` / `Old`) the line lives on. */
+ readonly side: DiffSide;
+ /** The real file line to reveal and flash. */
+ readonly line: number;
+ /** Monotonic counter so an identical target still re-triggers the reveal. */
+ readonly nonce: number;
+}
+
/**
* Navigation state discriminated union.
*
@@ -316,6 +340,41 @@ interface AppStore {
*/
preReview: (pr: string) => Promise;
+ /**
+ * The pre-review recap artifacts (intent-adjacent MDX + Excalidraw scenes)
+ * per PR, keyed by PR ref. Populated by {@link fetchRecap}; the Briefing tab
+ * reads it. An absent entry means "not yet fetched"; a fetched-but-empty
+ * recap is `{ mdx: null, scenes: [], sha: … }`.
+ */
+ readonly recaps: Readonly>;
+
+ /**
+ * Fetch the recap payload for a PR into {@link recaps} (Briefing tab).
+ * Best-effort: returns `null` and logs on failure rather than setting the
+ * blocking `error` — the recap is a glance aid and never blocks the loop
+ * (Invariant 1).
+ */
+ fetchRecap: (pr: string) => Promise;
+
+ /**
+ * A pending cross-tab jump-to-line request for the Diff tab, or null. Set by
+ * {@link requestDiffJump} (e.g. a Briefing finding's "Jump"); consumed by
+ * DiffView, which keys on the {@link PendingDiffJump.nonce}.
+ */
+ readonly pendingDiffJump: PendingDiffJump | null;
+
+ /**
+ * Publish a jump-to-line request for the Diff tab. The caller is responsible
+ * for switching the workspace to the Diff tab; DiffView performs the reveal
+ * once it observes the new request for its own review.
+ */
+ requestDiffJump: (
+ pr: string,
+ path: string,
+ side: DiffSide,
+ line: number,
+ ) => void;
+
/**
* Per `pr:path:head_sha` cache of resolved full-file pairs (B4). Populated by
* {@link fetchFilePair}; keyed on the head SHA so a force-push naturally
@@ -550,6 +609,8 @@ export const useAppStore = create((set, get) => ({
filePairCache: new Map(),
restackProgress: {},
pendingPermissions: [],
+ recaps: {},
+ pendingDiffJump: null,
fetchReviews: async () => {
set({ loading: true, error: null });
@@ -1018,6 +1079,30 @@ export const useAppStore = create((set, get) => ({
}
},
+ fetchRecap: async (pr: string): Promise => {
+ try {
+ const recap = await invoke("get_review_recap", { pr });
+ set({ recaps: { ...get().recaps, [pr]: recap } });
+ return recap;
+ } catch (e: unknown) {
+ // Non-fatal (Invariant 1): the recap is a glance aid, never a gate.
+ console.error("get_review_recap failed", e);
+ return null;
+ }
+ },
+
+ requestDiffJump: (
+ pr: string,
+ path: string,
+ side: DiffSide,
+ line: number,
+ ): void => {
+ const prev = get().pendingDiffJump;
+ set({
+ pendingDiffJump: { pr, path, side, line, nonce: (prev?.nonce ?? 0) + 1 },
+ });
+ },
+
fetchFilePair: async (
pr: string,
path: string,
diff --git a/app/vite.config.ts b/app/vite.config.ts
index f9256cd..c3876a5 100644
--- a/app/vite.config.ts
+++ b/app/vite.config.ts
@@ -15,6 +15,14 @@ export default defineConfig({
port: 5173,
strictPort: true,
},
+ build: {
+ // Excalidraw is large but strictly lazy: it is only reached via the dynamic
+ // import in ExcalidrawScene, so Vite code-splits it into its own chunk that
+ // loads on demand and never enters the main bundle. (An explicit
+ // manualChunks entry is deliberately avoided — it made Rollup hoist the
+ // chunk into the entry's static import graph.)
+ chunkSizeWarningLimit: 2000,
+ },
test: {
environment: "jsdom",
globals: true,