fix(PLA-121): annotate line refs with externalId, not internal id

groupAnnotatedLineRefsByFile was setting keyChangeId to keyChange.id (the
internal DB id), but every other surface — view-state, the side panel's
focus state, and the detail page's k.externalId === focusedKeyChangeId
lookup — keys on externalId. The mismatch silently broke overlay clicks:
clicking an overlay box would set focus to an id no other component could
resolve, and the corresponding checkbox lookup against view.keyChangeIdSet
would always miss.

Reported by Cursor Bugbot.

Author: dastratakos

packages/web/src/lib/__tests__/line-refs-by-file.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { DIFF_SIDE } from "../diff-types";
+import { groupAnnotatedLineRefsByFile, groupLineRefsByFile } from "../line-refs-by-file";
+
+describe("groupLineRefsByFile", () => {
+	it("returns null for empty input", () => {
+		expect(groupLineRefsByFile([])).toBeNull();
+		expect(groupLineRefsByFile(null)).toBeNull();
+		expect(groupLineRefsByFile(undefined)).toBeNull();
+	});
+
+	it("groups refs by filePath, preserving input order within a file", () => {
+		const refs = [
+			{ filePath: "a.ts", side: DIFF_SIDE.ADDITIONS, startLine: 1, endLine: 1 },
+			{ filePath: "b.ts", side: DIFF_SIDE.ADDITIONS, startLine: 2, endLine: 2 },
+			{ filePath: "a.ts", side: DIFF_SIDE.ADDITIONS, startLine: 5, endLine: 6 },
+		];
+		const result = groupLineRefsByFile(refs);
+		expect(result?.get("a.ts")).toHaveLength(2);
+		expect(result?.get("a.ts")?.[0]?.startLine).toBe(1);
+		expect(result?.get("a.ts")?.[1]?.startLine).toBe(5);
+		expect(result?.get("b.ts")).toHaveLength(1);
+	});
+});
+
+describe("groupAnnotatedLineRefsByFile", () => {
+	it("annotates each line ref with the keyChange's externalId, not the internal id", () => {
+		// Regression: previously this used `keyChange.id` (internal DB id), which
+		// caused overlay clicks to set focus to a value that never matched the
+		// side-panel's externalId-keyed focus state.
+		const result = groupAnnotatedLineRefsByFile([
+			{
+				externalId: "ext-kc-1",
+				lineRefs: [
+					{ filePath: "src/foo.ts", side: DIFF_SIDE.ADDITIONS, startLine: 10, endLine: 10 },
+				],
+			},
+		]);
+		expect(result?.get("src/foo.ts")?.[0]?.keyChangeId).toBe("ext-kc-1");
+	});
+
+	it("returns null when there are no key changes", () => {
+		expect(groupAnnotatedLineRefsByFile([])).toBeNull();
+		expect(groupAnnotatedLineRefsByFile(null)).toBeNull();
+	});
+});

packages/web/src/lib/line-refs-by-file.ts

@@ -1,8 +1,13 @@
 import type { LineRef } from "@stage-cli/types/chapters";
 import type { AnnotatedLineRef } from "./diff-types";
 
+// `externalId` (not `id`) because that's what view-state, the side panel, and
+// the chapter detail page's focus state all key on. Annotating with the
+// internal DB id would silently break overlay ↔ side-panel sync: a side-panel
+// click sets focus to externalId, while an overlay click would set it to id,
+// and view-state checked-state lookups would never find the row.
 interface KeyChangeWithLineRefs {
-	id: string;
+	externalId: string;
 	lineRefs: LineRef[];
 }
 
@@ -30,7 +35,7 @@ export function groupAnnotatedLineRefsByFile(
 	return groupLineRefsByFile(
 		keyChanges.flatMap((keyChange) =>
 			keyChange.lineRefs.map(
-				(lineRef): AnnotatedLineRef => ({ ...lineRef, keyChangeId: keyChange.id }),
+				(lineRef): AnnotatedLineRef => ({ ...lineRef, keyChangeId: keyChange.externalId }),
 			),
 		),
 	);