[codex] Add document annotations and comments (#6733)

## Thinking Path > - Paperclip orchestrates AI-agent companies through issues, documents, runs, and durable company-scoped state. > - Issue documents are where agents and operators capture plans, handoffs, and work products. > - Before this change, document collaboration could only happen through whole-document edits and detached issue comments. > - Inline document annotations need stable anchors, revision-aware persistence, and UI affordances that do not break existing document editing. > - This pull request adds company-scoped document annotation threads, comments, anchor snapshots, API routes, and board UI. > - The benefit is that operators and agents can discuss specific document passages without losing context as documents evolve. ## What Changed - Added document annotation tables, schema exports, shared types, validators, anchor hashing, and text-anchor helpers. - Added server-side document annotation services and issue routes for listing, creating, commenting, resolving, and reopening annotation threads. - Included annotation summaries in relevant issue document reads and backup/recovery document workspace behavior. - Added React UI for inline document highlights, comment panels, mobile sheet behavior, deep-link focus, and resolved/open filtering. - Added annotation design artifacts, Storybook coverage, screenshots, and a screenshot helper script. - Rebased the branch onto current `paperclipai/paperclip` `master` and renumbered the annotation migration from `0085_old_swarm` to `0091_old_swarm`; the SQL uses `IF NOT EXISTS` guards so environments that previously applied the old migration number can safely apply the new one. - Adjusted the new annotation UI tests to use a local async flush helper because this workspace's React 19.2.4 export does not expose `React.act`. ## Verification - `pnpm run preflight:workspace-links && pnpm exec vitest run packages/shared/src/document-anchors.test.ts server/src/__tests__/document-annotation-routes.test.ts server/src/__tests__/document-annotations-service.test.ts ui/src/components/DocumentAnnotationLayer.test.tsx ui/src/components/IssueDocumentAnnotations.test.tsx ui/src/lib/document-annotation-hash.test.ts ui/src/lib/document-annotation-selection.test.ts` - Confirmed `git diff --check` passes. - Confirmed no `pnpm-lock.yaml` or `.github/workflows/*` files are included in the PR diff. ## Risks - Medium risk: this adds new persisted annotation tables and routes across db/shared/server/ui. - Migration risk is reduced by moving the branch migration to `0091_old_swarm` after upstream `0090_resource_memberships` and keeping the SQL idempotent for old `0085_old_swarm` adopters. - UI risk is mostly around text range anchoring and panel positioning across long documents, folded content, and mobile layouts; the PR includes focused unit coverage and design screenshots. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent, tool-using software engineering mode. Context window size is not exposed in this Paperclip runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-05-26 08:41:23 -05:00
parent f0ddd24d61
commit b7545823be
55 changed files with 25070 additions and 31 deletions
@@ -0,0 +1,202 @@
+import {
+  createDocumentAnchorSelector,
+  normalizeAnchorText,
+  projectMarkdownToText,
+  resolveProjectionRange,
+  type DocumentAnnotationAnchorSelector,
+  type DocumentTextProjection,
+  type DocumentTextRange,
+} from "@paperclipai/shared";
+
+export interface ContainerTextOffset {
+  /** Byte offset of the selection start within the flattened container text. */
+  startOffset: number;
+  /** Byte offset of the selection end within the flattened container text. */
+  endOffset: number;
+  /** Raw flattened text content of the container. */
+  containerText: string;
+  /** Raw text inside the selection. */
+  selectedText: string;
+}
+
+export function getContainerTextOffset(
+  container: HTMLElement,
+  range: Range,
+): ContainerTextOffset | null {
+  if (!container.contains(range.startContainer) || !container.contains(range.endContainer)) {
+    return null;
+  }
+  const preRange = document.createRange();
+  preRange.selectNodeContents(container);
+  preRange.setEnd(range.startContainer, range.startOffset);
+  const startOffset = preRange.toString().length;
+  preRange.setEnd(range.endContainer, range.endOffset);
+  const endOffset = preRange.toString().length;
+  if (endOffset <= startOffset) return null;
+  return {
+    startOffset,
+    endOffset,
+    containerText: container.textContent ?? "",
+    selectedText: range.toString(),
+  };
+}
+
+export interface SelectionAnchorResult {
+  selector: DocumentAnnotationAnchorSelector;
+  range: DocumentTextRange;
+  projection: DocumentTextProjection;
+}
+
+export function buildAnchorFromContainerSelection(input: {
+  markdown: string;
+  containerOffset: ContainerTextOffset;
+}): SelectionAnchorResult | null {
+  const projection = projectMarkdownToText(input.markdown);
+  const needle = normalizeAnchorText(input.containerOffset.selectedText);
+  if (!needle) return null;
+
+  const occurrences = findAllOccurrences(projection.text, needle);
+  if (occurrences.length === 0) return null;
+
+  const renderedTextLength = Math.max(1, normalizeAnchorText(input.containerOffset.containerText).length);
+  const renderedRatio = input.containerOffset.startOffset / renderedTextLength;
+  const projectionLength = Math.max(1, projection.text.length);
+  const expectedNormalized = Math.round(renderedRatio * projectionLength);
+
+  const best = pickClosestOccurrence(occurrences, expectedNormalized);
+  if (best == null) return null;
+
+  const normalizedStart = best;
+  const normalizedEnd = best + needle.length;
+  const range = resolveProjectionRange(projection, normalizedStart, normalizedEnd);
+  if (!range) return null;
+  if (normalizeAnchorText(range.text) !== needle) return null;
+
+  const selector = createDocumentAnchorSelector(projection, range);
+  return { selector, range, projection };
+}
+
+function findAllOccurrences(haystack: string, needle: string): number[] {
+  if (!needle) return [];
+  const out: number[] = [];
+  let cursor = haystack.indexOf(needle);
+  while (cursor !== -1) {
+    out.push(cursor);
+    cursor = haystack.indexOf(needle, cursor + 1);
+  }
+  return out;
+}
+
+function pickClosestOccurrence(occurrences: number[], expected: number): number | null {
+  if (occurrences.length === 0) return null;
+  if (occurrences.length === 1) return occurrences[0] ?? null;
+  let best = occurrences[0] ?? 0;
+  let bestDistance = Math.abs(best - expected);
+  for (const candidate of occurrences) {
+    const distance = Math.abs(candidate - expected);
+    if (distance < bestDistance) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+  return best;
+}
+
+/**
+ * Walk text nodes inside `container` and return a list of `Range`s that cover the
+ * normalized-text span `[normalizedStart, normalizedEnd)`. Each Range can be
+ * rectangle-projected to draw a highlight overlay.
+ */
+export function rangesForNormalizedSpan(input: {
+  container: HTMLElement;
+  selectedText: string;
+}): Range[] {
+  const normalizedNeedle = normalizeAnchorText(input.selectedText);
+  if (!normalizedNeedle) return [];
+  const containerText = input.container.textContent ?? "";
+  const normalizedContainerText = normalizeAnchorText(containerText);
+  const containerOccurrenceIndex = normalizedContainerText.indexOf(normalizedNeedle);
+  if (containerOccurrenceIndex === -1) return [];
+
+  // Convert from normalized container offset back to raw container offset
+  // by walking the raw text and matching whitespace squashing.
+  const rawIndex = mapNormalizedOffsetToRaw(containerText, containerOccurrenceIndex);
+  if (rawIndex < 0) return [];
+
+  const rawNeedleLength = matchRawLengthForNormalized(
+    containerText.slice(rawIndex),
+    normalizedNeedle.length,
+  );
+  if (rawNeedleLength <= 0) return [];
+
+  const rawStart = rawIndex;
+  const rawEnd = rawIndex + rawNeedleLength;
+  return buildRangesForRawSpan(input.container, rawStart, rawEnd);
+}
+
+function mapNormalizedOffsetToRaw(rawText: string, normalizedOffset: number): number {
+  let normalizedCursor = 0;
+  let lastWasWhitespace = true; // mimic trim() at start
+  for (let index = 0; index < rawText.length; index += 1) {
+    const char = rawText[index] ?? "";
+    if (/\s/.test(char)) {
+      if (!lastWasWhitespace) {
+        if (normalizedCursor === normalizedOffset) return index;
+        normalizedCursor += 1;
+        lastWasWhitespace = true;
+      }
+      continue;
+    }
+    if (normalizedCursor === normalizedOffset) return index;
+    normalizedCursor += 1;
+    lastWasWhitespace = false;
+  }
+  return -1;
+}
+
+function matchRawLengthForNormalized(rawTail: string, normalizedLength: number): number {
+  let normalizedCount = 0;
+  let lastWasWhitespace = false;
+  for (let index = 0; index < rawTail.length; index += 1) {
+    const char = rawTail[index] ?? "";
+    if (/\s/.test(char)) {
+      if (!lastWasWhitespace) {
+        normalizedCount += 1;
+        if (normalizedCount >= normalizedLength) return index;
+        lastWasWhitespace = true;
+      }
+    } else {
+      normalizedCount += 1;
+      lastWasWhitespace = false;
+      if (normalizedCount >= normalizedLength) return index + 1;
+    }
+  }
+  return rawTail.length;
+}
+
+function buildRangesForRawSpan(container: HTMLElement, rawStart: number, rawEnd: number): Range[] {
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, null);
+  const ranges: Range[] = [];
+  let cursor = 0;
+  let node: Node | null = walker.nextNode();
+  while (node) {
+    const textNode = node as Text;
+    const length = textNode.data.length;
+    const nodeStart = cursor;
+    const nodeEnd = cursor + length;
+    if (nodeEnd > rawStart && nodeStart < rawEnd) {
+      const startWithin = Math.max(0, rawStart - nodeStart);
+      const endWithin = Math.min(length, rawEnd - nodeStart);
+      if (endWithin > startWithin) {
+        const range = document.createRange();
+        range.setStart(textNode, startWithin);
+        range.setEnd(textNode, endWithin);
+        ranges.push(range);
+      }
+    }
+    cursor = nodeEnd;
+    if (cursor >= rawEnd) break;
+    node = walker.nextNode();
+  }
+  return ranges;
+}