[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>

ui/src/lib/document-annotation-hash.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildDocumentAnnotationHash,
+  parseDocumentAnnotationHash,
+} from "./document-annotation-hash";
+
+describe("parseDocumentAnnotationHash", () => {
+  it("returns null for non-document hashes", () => {
+    expect(parseDocumentAnnotationHash("")).toBeNull();
+    expect(parseDocumentAnnotationHash("#issue-foo")).toBeNull();
+  });
+
+  it("parses document key only", () => {
+    expect(parseDocumentAnnotationHash("#document-plan")).toEqual({
+      documentKey: "plan",
+      threadId: null,
+      commentId: null,
+    });
+  });
+
+  it("parses thread and comment targets", () => {
+    expect(
+      parseDocumentAnnotationHash("#document-plan&thread=t1&comment=c2"),
+    ).toEqual({
+      documentKey: "plan",
+      threadId: "t1",
+      commentId: "c2",
+    });
+  });
+
+  it("decodes URI-encoded keys", () => {
+    expect(parseDocumentAnnotationHash("#document-my%20notes&thread=abc")).toEqual({
+      documentKey: "my notes",
+      threadId: "abc",
+      commentId: null,
+    });
+  });
+});
+
+describe("buildDocumentAnnotationHash", () => {
+  it("builds a hash without thread or comment", () => {
+    expect(buildDocumentAnnotationHash({ documentKey: "plan", threadId: null, commentId: null })).toBe(
+      "#document-plan",
+    );
+  });
+
+  it("includes thread target", () => {
+    expect(
+      buildDocumentAnnotationHash({ documentKey: "plan", threadId: "t1", commentId: null }),
+    ).toBe("#document-plan&thread=t1");
+  });
+
+  it("includes both targets", () => {
+    expect(
+      buildDocumentAnnotationHash({ documentKey: "plan", threadId: "t1", commentId: "c2" }),
+    ).toBe("#document-plan&thread=t1&comment=c2");
+  });
+
+  it("survives a round trip", () => {
+    const target = { documentKey: "plan-2", threadId: "t-abc", commentId: "c-xyz" };
+    expect(parseDocumentAnnotationHash(buildDocumentAnnotationHash(target))).toEqual(target);
+  });
+});

ui/src/lib/document-annotation-hash.ts

@@ -0,0 +1,32 @@
+export interface DocumentAnnotationHashTarget {
+  documentKey: string;
+  threadId: string | null;
+  commentId: string | null;
+}
+
+const DOCUMENT_HASH_PREFIX = "#document-";
+
+export function parseDocumentAnnotationHash(hash: string): DocumentAnnotationHashTarget | null {
+  if (!hash.startsWith(DOCUMENT_HASH_PREFIX)) return null;
+  const stripped = hash.slice(DOCUMENT_HASH_PREFIX.length);
+  const [rawKey, ...rest] = stripped.split("&");
+  if (!rawKey) return null;
+  const documentKey = decodeURIComponent(rawKey);
+  const params = new URLSearchParams(rest.join("&"));
+  const threadId = params.get("thread");
+  const commentId = params.get("comment");
+  return {
+    documentKey,
+    threadId: threadId && threadId.length > 0 ? threadId : null,
+    commentId: commentId && commentId.length > 0 ? commentId : null,
+  };
+}
+
+export function buildDocumentAnnotationHash(target: DocumentAnnotationHashTarget): string {
+  const params = new URLSearchParams();
+  if (target.threadId) params.set("thread", target.threadId);
+  if (target.commentId) params.set("comment", target.commentId);
+  const qs = params.toString();
+  const encodedKey = encodeURIComponent(target.documentKey);
+  return qs ? `${DOCUMENT_HASH_PREFIX}${encodedKey}&${qs}` : `${DOCUMENT_HASH_PREFIX}${encodedKey}`;
+}

ui/src/lib/document-annotation-selection.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import { verifyDocumentAnchorSelector } from "@paperclipai/shared";
+import {
+  buildAnchorFromContainerSelection,
+  getContainerTextOffset,
+  rangesForNormalizedSpan,
+} from "./document-annotation-selection";
+
+const MARKDOWN = `# Plan
+
+We **should** keep the current markdown stack for the first version.
+
+- Highlight a text segment in a plan document.
+- Anchor comments without mutating markdown.
+
+## Acceptance
+
+The annotation feature is ready when the basic flow works.`;
+
+const RENDERED_HTML = `
+<div>
+  <h1>Plan</h1>
+  <p>We should keep the current markdown stack for the first version.</p>
+  <ul>
+    <li>Highlight a text segment in a plan document.</li>
+    <li>Anchor comments without mutating markdown.</li>
+  </ul>
+  <h2>Acceptance</h2>
+  <p>The annotation feature is ready when the basic flow works.</p>
+</div>
+`;
+
+function makeContainer(): HTMLElement {
+  const div = document.createElement("div");
+  div.innerHTML = RENDERED_HTML;
+  document.body.appendChild(div);
+  return div.firstElementChild as HTMLElement;
+}
+
+function selectText(container: HTMLElement, needle: string): Range {
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, null);
+  let node = walker.nextNode();
+  while (node) {
+    const data = (node as Text).data;
+    const index = data.indexOf(needle);
+    if (index !== -1) {
+      const range = document.createRange();
+      range.setStart(node, index);
+      range.setEnd(node, index + needle.length);
+      return range;
+    }
+    node = walker.nextNode();
+  }
+  throw new Error(`Could not find "${needle}" in container`);
+}
+
+describe("buildAnchorFromContainerSelection", () => {
+  it("produces a selector that verifies against the same markdown", () => {
+    const container = makeContainer();
+    const range = selectText(container, "current markdown stack");
+    const offset = getContainerTextOffset(container, range);
+    expect(offset).not.toBeNull();
+    const anchor = buildAnchorFromContainerSelection({
+      markdown: MARKDOWN,
+      containerOffset: offset!,
+    });
+    expect(anchor).not.toBeNull();
+    const verified = verifyDocumentAnchorSelector({
+      markdown: MARKDOWN,
+      selector: anchor!.selector,
+    });
+    expect(verified.ok).toBe(true);
+    expect(verified.anchor?.selectedText).toBe("current markdown stack");
+  });
+
+  it("returns null for empty selections", () => {
+    const container = makeContainer();
+    const range = document.createRange();
+    range.setStart(container, 0);
+    range.setEnd(container, 0);
+    const offset = getContainerTextOffset(container, range);
+    expect(offset).toBeNull();
+  });
+
+  it("returns null when selection is outside container", () => {
+    const container = makeContainer();
+    const outside = document.createElement("div");
+    outside.textContent = "outside";
+    document.body.appendChild(outside);
+    const range = document.createRange();
+    range.selectNodeContents(outside);
+    const offset = getContainerTextOffset(container, range);
+    expect(offset).toBeNull();
+  });
+});
+
+describe("rangesForNormalizedSpan", () => {
+  it("walks DOM text nodes to find span ranges", () => {
+    const container = makeContainer();
+    const ranges = rangesForNormalizedSpan({
+      container,
+      selectedText: "Highlight a text segment",
+    });
+    expect(ranges.length).toBeGreaterThan(0);
+    const merged = ranges.map((range) => range.toString()).join("");
+    expect(merged.replace(/\s+/g, " ")).toContain("Highlight a text segment");
+  });
+
+  it("returns an empty array if selected text is missing", () => {
+    const container = makeContainer();
+    const ranges = rangesForNormalizedSpan({
+      container,
+      selectedText: "this string does not exist in the document",
+    });
+    expect(ranges).toEqual([]);
+  });
+});

ui/src/lib/document-annotation-selection.ts

@@ -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;
+}

ui/src/lib/queryKeys.ts

@@ -63,6 +63,8 @@ export const queryKeys = {
     documents: (issueId: string) => ["issues", "documents", issueId] as const,
     document: (issueId: string, key: string) => ["issues", "document", issueId, key] as const,
     documentRevisions: (issueId: string, key: string) => ["issues", "document-revisions", issueId, key] as const,
+    documentAnnotations: (issueId: string, key: string, status: "open" | "resolved" | "all" = "all") =>
+      ["issues", "document-annotations", issueId, key, status] as const,
     activity: (issueId: string) => ["issues", "activity", issueId] as const,
     runs: (issueId: string) => ["issues", "runs", issueId] as const,
     approvals: (issueId: string) => ["issues", "approvals", issueId] as const,