@agent-native/core-corpus 0.217.0 → 0.219.0

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -327,6 +327,8 @@ import {
   planSuggestionDraftPersistence,
   saveUnlessSuggestionChanged,
   suggestionAmendmentIdempotencyKey,
+  suggestionProposalCreationIdempotencyKey,
+  forgetSuggestionProposalCreationIdempotencyKey,
   type DraftSuggestion,
   type SuggestionDraftSession,
   type SuggestionPersistenceEntry,
@@ -336,11 +338,13 @@ import {
 import { suggestedEditorIsolation } from "./suggestions/editor-isolation";
 import { useRememberedEditorMode } from "./suggestions/editor-mode-memory";
 import {
+  createDraftSuggestionPresentationTransition,
   createObservedSuggestionPresentationTransition,
   hydrateSuggestionPresentationTransitions,
   preciseSuggestionPresentationOperations,
   retainCommittedSuggestionPresentationTransitions,
   resolveSuggestionPresentationRange,
+  resolveSuggestionPresentationRangeInDraft,
   suggestionPresentationTransitionKey,
   type SuggestionPresentationTransition,
   type SuggestionPresentationTransitions,
@@ -635,6 +639,7 @@ export function suggestionPresentation(
   currentMarkdown: string,
   transition?: SuggestionPresentationTransition,
   observedTransition?: SuggestionPresentationTransition,
+  draftTransition?: SuggestionPresentationTransition,
 ): VisualEditorSuggestion | null {
   if (suggestion.status !== "pending") return null;
   const operation = suggestion.operations[0];
@@ -671,12 +676,22 @@ export function suggestionPresentation(
   ) {
     return null;
   }
-  const range = resolveSuggestionPresentationRange(
+  const canonicalRange = resolveSuggestionPresentationRange(
     currentMarkdown,
     operation,
     transition,
     observedTransition,
   );
+  const range =
+    canonicalRange ??
+    (draftTransition?.after === currentMarkdown
+      ? resolveSuggestionPresentationRangeInDraft(
+          draftTransition,
+          operation,
+          transition,
+          observedTransition,
+        )
+      : null);
   if (!range) return null;
   const editorMarkdown = canonicalizeNfm(currentMarkdown);
   const currentText = currentMarkdown.slice(range.from, range.to);
@@ -694,7 +709,9 @@ export function suggestionPresentation(
   return {
     id: suggestion.id,
     kind: operation.kind as VisualEditorSuggestion["kind"],
-    canonicalOperation: operation,
+    // The editor re-resolves a canonical operation on its own text, where only
+    // the draft carries this one, so the anchor places it instead.
+    canonicalOperation: canonicalRange ? operation : undefined,
     canonicalTransition: transition,
     observedTransition,
     beforeText: before.changedText,
@@ -726,6 +743,7 @@ export function suggestionPresentations(
   currentMarkdown: string,
   transition?: SuggestionPresentationTransition,
   observedTransition?: SuggestionPresentationTransition,
+  draftTransition?: SuggestionPresentationTransition,
 ): VisualEditorSuggestion[] {
   // Decided edits have no presentation; skip their full-Page diff.
   if (suggestion.status !== "pending") return [];
@@ -734,6 +752,7 @@ export function suggestionPresentations(
     currentMarkdown,
     transition,
     observedTransition,
+    draftTransition,
   );
   if (suggestion.operations.length !== 1) return original ? [original] : [];
   const saved = suggestion.operations[0]!;
@@ -746,6 +765,7 @@ export function suggestionPresentations(
       currentMarkdown,
       transition,
       observedTransition,
+      draftTransition,
     ),
   );
   return precise.every((presentation) => presentation !== null)
@@ -764,6 +784,13 @@ export function documentEditorSuggestionPresentations(args: {
   transitions: SuggestionPresentationTransitions;
   observedTransition?: SuggestionPresentationTransition;
 }): VisualEditorSuggestion[] {
+  const draftTransition =
+    args.savedSuggestions.length > 0
+      ? (createDraftSuggestionPresentationTransition(
+          args.drafts,
+          args.currentMarkdown,
+        ) ?? undefined)
+      : undefined;
   const savedPresentations: VisualEditorSuggestion[] = [];
   for (const suggestion of args.savedSuggestions) {
     if (suggestion.id === args.editingSuggestionId) continue;
@@ -773,6 +800,7 @@ export function documentEditorSuggestionPresentations(args: {
         args.currentMarkdown,
         args.transitions.get(suggestionPresentationTransitionKey(suggestion)),
         args.observedTransition,
+        draftTransition,
       ),
     );
   }
@@ -4160,6 +4188,15 @@ function PageEditorSessionBody({
         options.editGeneration ?? editorEditGenerationRef.current;
       const contentObservationEpoch =
         options.contentObservationEpoch ?? contentObservationEpochRef.current;
+      // Text another writer added while this save was in flight is theirs to
+      // save, so it holds back neither the confirmation nor the journal clear.
+      // An entry kept for it outlives this tab's edits, and the next tab to
+      // open the page replays it as a save of its own.
+      const settleConfirmedEdit = () => {
+        if (contentEditVersionRef.current !== contentEditVersion) return;
+        confirmedContentEditVersionRef.current = contentEditVersion;
+        clearConfirmedDraftJournal(editorEditGeneration);
+      };
       lastSavedContentRef.current = refreshUnchangedContentSaveWatermark({
         serverContent: documentContentRef.current,
         serverUpdatedAt: documentUpdatedAtRef.current,
@@ -4240,12 +4277,14 @@ function PageEditorSessionBody({
           { title, content },
           options,
         );
-        return {
-          contentPersisted:
-            !isDocumentUpdateConflict(attested) &&
-            !isDocumentUpdateSuperseded(attested) &&
-            !isDocumentUpdatePreservationRequired(attested),
-        };
+        const confirmed =
+          !isDocumentUpdateConflict(attested) &&
+          !isDocumentUpdateSuperseded(attested) &&
+          !isDocumentUpdatePreservationRequired(attested);
+        // The page already held this edit, as when a peer's save carried it,
+        // so the attestation settles it as a written save would.
+        if (confirmed) settleConfirmedEdit();
+        return { contentPersisted: confirmed };
       }
       if (!hasUpdates) {
         return { contentPersisted: !contentChanged };
@@ -4465,14 +4504,7 @@ function PageEditorSessionBody({
             : null,
         });
       }
-      // Text another writer added while this save was in flight is theirs to
-      // save, so it holds back neither the confirmation nor the journal clear.
-      // An entry kept for it outlives this tab's edits, and the next tab to
-      // open the page replays it as a save of its own.
-      if (contentEditVersionRef.current === contentEditVersion) {
-        confirmedContentEditVersionRef.current = contentEditVersion;
-        clearConfirmedDraftJournal(editorEditGeneration);
-      }
+      settleConfirmedEdit();
 
       if (autoSync) {
         const status = queryClient.getQueryData<DocumentSyncStatus>(
@@ -5906,6 +5938,10 @@ function PageEditorSessionBody({
             unresolved.request.idempotencyKey,
             unresolved.baseId,
           );
+          forgetSuggestionProposalCreationIdempotencyKey(
+            suggestionProposalCreationKeysRef.current,
+            unresolved.request,
+          );
           unresolvedProposalCreationRef.current = null;
         }
         const operations = suggestionDraftOperations(base, draft);
@@ -6086,29 +6122,28 @@ function PageEditorSessionBody({
         if (create.length > 0) {
           const pending = create.map(({ operation }) => operation);
           const pendingKeys = create.map(({ key }) => key);
-          const requestKey = JSON.stringify([base.id, pendingKeys]);
-          const idempotencyKey =
-            suggestionProposalCreationKeysRef.current.get(requestKey) ??
-            globalThis.crypto.randomUUID();
-          suggestionProposalCreationKeysRef.current.set(
-            requestKey,
-            idempotencyKey,
-          );
           const existingProposal = suggestionProposalsRef.current.get(base.id);
           const proposalSummary =
             existingProposal?.summary ?? t("editor.toolbar.suggestEdits");
-          const request = {
+          const fields = {
             resourceType: "document",
             resourceId: documentId,
             adapterKind: "content.document-markdown",
             baseRevision: base.baseRevision,
             summary: proposalSummary,
             proposalId: existingProposal?.id,
-            idempotencyKey,
             suggestions: pending.map((operation) => ({
               summary: proposalSummary,
               operations: [operation],
             })),
+          };
+          const idempotencyKey = suggestionProposalCreationIdempotencyKey(
+            suggestionProposalCreationKeysRef.current,
+            fields,
+          );
+          const request = {
+            ...fields,
+            idempotencyKey,
           } satisfies Parameters<
             typeof createSuggestionProposal.mutateAsync
           >[0];
@@ -6120,6 +6155,10 @@ function PageEditorSessionBody({
           };
           const created = await createSuggestionProposal.mutateAsync(request);
           recordCreated(created, pendingKeys, pending, idempotencyKey, base.id);
+          forgetSuggestionProposalCreationIdempotencyKey(
+            suggestionProposalCreationKeysRef.current,
+            request,
+          );
           unresolvedProposalCreationRef.current = null;
           pendingKeys.forEach((operationKey, index) => {
             persisted.set(operationKey, created.suggestions[index]!);
@@ -6135,7 +6174,14 @@ function PageEditorSessionBody({
           status < 500 &&
           status !== 408 &&
           status !== 429;
-        if (clientError) unresolvedProposalCreationRef.current = null;
+        const refused = clientError && unresolvedProposalCreationRef.current;
+        if (refused) {
+          forgetSuggestionProposalCreationIdempotencyKey(
+            suggestionProposalCreationKeysRef.current,
+            refused.request,
+          );
+          unresolvedProposalCreationRef.current = null;
+        }
         adoptConfirmedSuggestions();
         if (error instanceof SuggestionFormattingMappingError) {
           // The draft keeps its persistent unsupported-formatting alert.
@@ -8650,7 +8696,9 @@ function PageEditorSessionBody({
       onActivateSuggestion={activateSuggestionOrThread}
       onSelectedThreadChange={setSelectedThreadId}
       onHoveredThreadChange={setHoveredThreadId}
+      hoveredThreadId={hoveredThreadId}
       currentUserEmail={session?.email}
+      currentUserName={session?.name}
       currentUserOrgId={session?.orgId}
       canComment={canComment}
       canResolve={canEdit}

package/corpus/templates/content/app/components/editor/SuggestionText.tsx

@@ -9,8 +9,9 @@ import { Fragment, type ReactNode } from "react";
 
 function renderNode(node: SuggestionPresentationNode, key: string): ReactNode {
   if (node.type === "text") return <Fragment key={key}>{node.value}</Fragment>;
-  if (node.type === "indent")
+  if (node.type === "indent" || node.type === "block")
     return <Fragment key={key}>{node.value}</Fragment>;
+  if (node.type === "lineBreak") return <br key={key} />;
   const children = node.children.map((child, index) =>
     renderNode(child, `${key}-${index}`),
   );
@@ -42,16 +43,30 @@ export function SuggestionText({
   context?: SuggestionPresentationContext;
 }) {
   const t = useT();
-  const nodes = context
+  const presented = context
     ? suggestionTextPresentationForSource(content, context)
     : suggestionTextPresentation(content);
-  if (!nodes) {
+  if (!presented) {
     return (
       <span data-suggestion-text-unavailable="true">
         {t("editor.sourceComponent.previewUnavailable")}
       </span>
     );
   }
+  // A new paragraph's own line break would open or close the card with an
+  // empty line, so a break at either edge shows as its marker instead; the
+  // breaks between lines stay.
+  let start = 0;
+  let end = presented.length;
+  while (start < end && presented[start]!.type === "lineBreak") start += 1;
+  while (end > start && presented[end - 1]!.type === "lineBreak") end -= 1;
+  const marker = (count: number): SuggestionPresentationNode[] =>
+    count ? [{ type: "text", value: "↵".repeat(count) }] : [];
+  const nodes = [
+    ...marker(start),
+    ...presented.slice(start, end),
+    ...marker(presented.length - end),
+  ];
   return (
     <span className="whitespace-pre-wrap break-words">
       {nodes.map((node, index) => renderNode(node, String(index)))}

package/corpus/templates/content/app/components/editor/VisualEditor.tsx

@@ -1439,7 +1439,26 @@ function suggestionAnchorRange(
   const collapsedRange = collapsedDeletionTextblock();
   if (collapsedRange) return collapsedRange;
   if (sourceMatches) {
-    const exactRange = sourceRangeToPm(sourceFrom, sourceTo);
+    // An empty paragraph has no text to map, so a span that opens or closes
+    // with one maps the text beside it, or the place it starts when that's
+    // all it holds.
+    const emptyLine = "<empty-block/>";
+    let mapFrom = sourceFrom;
+    let mapTo = sourceTo;
+    for (;;) {
+      if (
+        mapTo - mapFrom > emptyLine.length &&
+        source.slice(mapTo - emptyLine.length - 1, mapTo) === `\n${emptyLine}`
+      )
+        mapTo -= emptyLine.length + 1;
+      else if (
+        mapTo - mapFrom > emptyLine.length &&
+        source.startsWith(`${emptyLine}\n`, mapFrom)
+      )
+        mapFrom += emptyLine.length + 1;
+      else break;
+    }
+    const exactRange = sourceRangeToPm(mapFrom, mapTo);
     if (exactRange) return exactRange;
   }
   const mappedSource = suggestionAnchorText(source);
@@ -1592,11 +1611,18 @@ export function suggestionHighlightSpec(
       editableText: true,
     };
   }
+  // Removed syntax with no text, such as indentation, a list marker, or an
+  // empty paragraph, is not in the document text, so it is drawn instead.
   const structuralDeletion =
     /^\n+$/.test(suggestionAnchorText(suggestion.beforeText)) ||
     (beforePresentation &&
       beforePresentation.length > 0 &&
-      beforePresentation.every((node) => node.type === "indent"));
+      beforePresentation.every(
+        (node) =>
+          node.type === "indent" ||
+          node.type === "block" ||
+          (node.type === "text" && /^↵+$/.test(node.value)),
+      ));
   return {
     suggestionId: suggestion.id,
     kind:
@@ -4743,9 +4769,17 @@ export function VisualEditor({
     const apply = (report = true) => {
       if (editor.isDestroyed) return;
       const specs = suggestions
-        .map((suggestion) =>
-          suggestionHighlightSpec(editor.state.doc, suggestion),
-        )
+        .map((suggestion) => {
+          const spec = suggestionHighlightSpec(editor.state.doc, suggestion);
+          // While suggesting, a saved suggestion's text outside the document
+          // is somewhere to type beside, not a control to focus.
+          return spec &&
+            suggesting &&
+            editable &&
+            suggestion.presentation === "canonical"
+            ? { ...spec, editableBoundary: true }
+            : spec;
+        })
         .filter((spec): spec is SuggestionHighlightSpec => spec !== null);
       if (report)
         onSuggestionAnchorsChange?.(
@@ -4771,8 +4805,10 @@ export function VisualEditor({
     };
   }, [
     activeSuggestionId,
+    editable,
     editor,
     onSuggestionAnchorsChange,
+    suggesting,
     suggestions,
     suggestionsSignature,
     showCommentIndicators,
@@ -4796,34 +4832,46 @@ export function VisualEditor({
     };
   }, [editor]);
 
+  // Callers build the readbacks inline and render again on every report, so
+  // these checks key on the readbacks' fields and report each divergent body
+  // once: keyed on the objects, each report re-runs its check until React
+  // aborts the render.
+  const acceptedReadbackId = acceptedDecisionReadback?.id ?? null;
+  const acceptedReadbackContent = acceptedDecisionReadback?.content ?? null;
   useLayoutEffect(() => {
-    if (!editor || editor.isDestroyed || !acceptedDecisionReadback) return;
+    if (
+      !editor ||
+      editor.isDestroyed ||
+      acceptedReadbackId === null ||
+      acceptedReadbackContent === null
+    )
+      return;
     const settlingSuggestion = suggestions.find(
-      (suggestion) => suggestion.id === acceptedDecisionReadback.id,
+      (suggestion) => suggestion.id === acceptedReadbackId,
     );
     if (!settlingSuggestion) return;
+    let reported: string | null = null;
     const check = () => {
       if (editor.isDestroyed) return;
       const actualContent = docToNfm(editor.getJSON() as any);
       if (
         acceptedSuggestionRendered(
           actualContent,
-          acceptedDecisionReadback.content,
+          acceptedReadbackContent,
           settlingSuggestion,
         )
       ) {
-        onAcceptedDecisionRendered?.(acceptedDecisionReadback.id);
+        onAcceptedDecisionRendered?.(acceptedReadbackId);
       } else if (
+        actualContent !== reported &&
         acceptedSuggestionReadbackOutdated(
           actualContent,
-          acceptedDecisionReadback.content,
+          acceptedReadbackContent,
           settlingSuggestion,
         )
       ) {
-        onAcceptedDecisionReadbackOutdated?.(
-          acceptedDecisionReadback.id,
-          actualContent,
-        );
+        reported = actualContent;
+        onAcceptedDecisionReadbackOutdated?.(acceptedReadbackId, actualContent);
       }
     };
     editor.on("transaction", check);
@@ -4832,27 +4880,44 @@ export function VisualEditor({
       editor.off("transaction", check);
     };
   }, [
-    acceptedDecisionReadback,
+    acceptedReadbackContent,
+    acceptedReadbackId,
     editor,
     onAcceptedDecisionRendered,
     onAcceptedDecisionReadbackOutdated,
     suggestions,
   ]);
 
+  const proposalReadbackGeneration =
+    proposalDecisionReadback?.generation ?? null;
+  const proposalReadbackContent = proposalDecisionReadback?.content ?? null;
+  const proposalReadbackBefore =
+    proposalDecisionReadback?.beforeContent ?? null;
   useLayoutEffect(() => {
-    if (!editor || editor.isDestroyed || !proposalDecisionReadback) return;
+    if (
+      !editor ||
+      editor.isDestroyed ||
+      proposalReadbackGeneration === null ||
+      proposalReadbackContent === null ||
+      proposalReadbackBefore === null
+    )
+      return;
+    let reported: string | null = null;
     const check = () => {
       if (editor.isDestroyed) return;
       const actual = canonicalizeNfm(docToNfm(editor.getJSON() as any));
-      if (actual === canonicalizeNfm(proposalDecisionReadback.content))
-        onProposalDecisionRendered?.(proposalDecisionReadback.generation);
+      if (actual === canonicalizeNfm(proposalReadbackContent))
+        onProposalDecisionRendered?.(proposalReadbackGeneration);
       else if (
-        actual !== canonicalizeNfm(proposalDecisionReadback.beforeContent)
-      )
+        actual !== reported &&
+        actual !== canonicalizeNfm(proposalReadbackBefore)
+      ) {
+        reported = actual;
         onProposalDecisionReadbackOutdated?.(
-          proposalDecisionReadback.generation,
+          proposalReadbackGeneration,
           actual,
         );
+      }
     };
     editor.on("transaction", check);
     check();
@@ -4863,7 +4928,9 @@ export function VisualEditor({
     editor,
     onProposalDecisionReadbackOutdated,
     onProposalDecisionRendered,
-    proposalDecisionReadback,
+    proposalReadbackBefore,
+    proposalReadbackContent,
+    proposalReadbackGeneration,
   ]);
 
   useEffect(() => {

package/corpus/templates/content/app/components/editor/block-field-comment-threads.ts

@@ -16,6 +16,21 @@ export function commentThreadFieldId(
   return thread.field?.fieldId ?? null;
 }
 
+/**
+ * The threads the margin shows with one tab open: that tab's and the
+ * Property threads. A page without tabs shows them all.
+ */
+export function commentRailThreads<
+  T extends Pick<CommentThread, "field" | "property">,
+>(threads: readonly T[], openFieldId: string | null): T[] {
+  if (openFieldId === null && !threads.some((thread) => thread.field)) {
+    return threads as T[];
+  }
+  return threads.filter(
+    (thread) => thread.property || commentThreadFieldId(thread) === openFieldId,
+  );
+}
+
 /** A key for a tab that a Map or a filter can hold: "" is the page body. */
 export function commentTabKey(fieldId: string | null): string {
   return fieldId ?? "";

package/corpus/templates/content/app/components/editor/block-field-comments.tsx

@@ -14,6 +14,7 @@ import {
 import type { CommentThread } from "@/hooks/use-comments";
 
 import {
+  commentRailThreads,
   commentThreadFieldId,
   openReviewCountsByField,
   type BlockFieldOpenCounts,
@@ -353,15 +354,10 @@ export function useBlockFieldComments({
   }, [scrollContainerRef, tabs, targetFieldId, targetKey, targetSettled]);
 
   const allThreads = threads ?? NO_THREADS;
-  const railThreads = useMemo(() => {
-    if (openFieldId === null && !allThreads.some((thread) => thread.field)) {
-      return allThreads as CommentThread[];
-    }
-    return allThreads.filter(
-      (thread) =>
-        thread.property || commentThreadFieldId(thread) === openFieldId,
-    );
-  }, [allThreads, openFieldId]);
+  const railThreads = useMemo(
+    () => commentRailThreads(allThreads as CommentThread[], openFieldId),
+    [allThreads, openFieldId],
+  );
 
   const pendingFieldId = pendingComment?.property
     ? undefined

package/corpus/templates/content/app/components/editor/comment-stacks.ts

@@ -0,0 +1,143 @@
+import type { CommentThread } from "@/hooks/use-comments";
+
+import {
+  commentTabKey,
+  commentThreadFieldId,
+} from "./block-field-comment-threads";
+import { inHiddenBlockFieldPanel } from "./blockFieldTabs";
+
+/** Where a thread's first highlight sits: its stack, and its document order. */
+export type CommentBlockPlacement = { key: string; order: number };
+
+/** Two or more open threads in one block, in document order. */
+export type CommentStack<T> = { key: string; threads: T[] };
+
+/**
+ * The block a highlight is in, as child indexes down from its editor: the
+ * innermost list item holding it, else the editor's top-level node. A
+ * highlight outside an editor, such as a Property's, has no block.
+ */
+export function commentBlockKey(highlight: Element): string | null {
+  const block = commentBlock(highlight);
+  return block ? blockPath(block) : null;
+}
+
+function commentBlock(highlight: Element) {
+  const editor = highlight.closest(".ProseMirror");
+  if (!editor) return null;
+  const item = highlight.closest("li");
+  if (item && editor.contains(item)) return { editor, block: item };
+  let block: Element | null = highlight;
+  while (block && block.parentElement !== editor) block = block.parentElement;
+  return block ? { editor, block } : null;
+}
+
+function blockPath({ editor, block }: { editor: Element; block: Element }) {
+  const path: number[] = [];
+  for (let node: Element = block; node !== editor; ) {
+    const parent: Element | null = node.parentElement;
+    if (!parent) return null;
+    path.unshift(Array.prototype.indexOf.call(parent.children, node));
+    node = parent;
+  }
+  return path.join(".");
+}
+
+/** Block keys repeat across Blocks field tabs, so a stack's key has both. */
+export function commentStackKey(fieldId: string | null, blockKey: string) {
+  return `${commentTabKey(fieldId)}:${blockKey}`;
+}
+
+/**
+ * Each thread's first highlight on the page, in document order. Property
+ * threads, threads not listed, and highlights in a closed tab are left out.
+ */
+export function measureCommentBlocks(
+  container: ParentNode,
+  threads: readonly CommentThread[],
+): Map<string, CommentBlockPlacement> {
+  const byId = new Map(
+    threads
+      .filter((thread) => !thread.property)
+      .map((thread) => [thread.threadId, thread]),
+  );
+  const placements = new Map<string, CommentBlockPlacement>();
+  // Highlights share blocks, and a block's path walks its siblings.
+  const paths = new Map<Element, string | null>();
+  for (const highlight of container.querySelectorAll("[data-comment-thread]")) {
+    const threadId = highlight.getAttribute("data-comment-thread");
+    const thread = threadId ? byId.get(threadId) : undefined;
+    if (!thread || placements.has(thread.threadId)) continue;
+    if (inHiddenBlockFieldPanel(highlight)) continue;
+    const found = commentBlock(highlight);
+    if (!found) continue;
+    let block = paths.get(found.block);
+    if (block === undefined) {
+      block = blockPath(found);
+      paths.set(found.block, block);
+    }
+    if (block === null) continue;
+    placements.set(thread.threadId, {
+      key: commentStackKey(commentThreadFieldId(thread), block),
+      order: placements.size,
+    });
+  }
+  return placements;
+}
+
+/** The blocks holding two or more open threads, in document order. */
+export function groupCommentStacks<
+  T extends Pick<CommentThread, "threadId" | "resolved" | "property">,
+>(
+  threads: readonly T[],
+  placements: ReadonlyMap<string, CommentBlockPlacement>,
+): CommentStack<T>[] {
+  const groups = new Map<string, T[]>();
+  for (const thread of threads) {
+    if (thread.resolved || thread.property) continue;
+    const placement = placements.get(thread.threadId);
+    if (!placement) continue;
+    const members = groups.get(placement.key) ?? [];
+    members.push(thread);
+    groups.set(placement.key, members);
+  }
+  const order = (thread: T) => placements.get(thread.threadId)?.order ?? 0;
+  return [...groups]
+    .filter(([, members]) => members.length >= 2)
+    .map(([key, members]) => ({
+      key,
+      threads: members.sort((left, right) => order(left) - order(right)),
+    }))
+    .sort((left, right) => order(left.threads[0]) - order(right.threads[0]));
+}
+
+function latestCommentTime(thread: Pick<CommentThread, "comments">) {
+  let latest = -Infinity;
+  for (const comment of thread.comments) {
+    const time = Date.parse(comment.created_at);
+    if (time > latest) latest = time;
+  }
+  return latest;
+}
+
+/**
+ * The thread a folded stack shows: the one last touched, else the one with
+ * the newest comment. Ties go to the first in document order.
+ */
+export function commentStackFront<
+  T extends Pick<CommentThread, "threadId" | "comments">,
+>(threads: readonly T[], touches: ReadonlyMap<string, number>): T {
+  let front = threads[0];
+  let frontTouch = touches.get(front.threadId) ?? -Infinity;
+  let frontTime = latestCommentTime(front);
+  for (const thread of threads.slice(1)) {
+    const touch = touches.get(thread.threadId) ?? -Infinity;
+    const time = latestCommentTime(thread);
+    if (touch > frontTouch || (touch === frontTouch && time > frontTime)) {
+      front = thread;
+      frontTouch = touch;
+      frontTime = time;
+    }
+  }
+  return front;
+}