Add shareable image galleries to task documents (#18157)

<!-- entire-trail-link-start -->
https://entire.com/gh/paperclipai/-/trails/247/changes/paperclip/247
<!-- entire-trail-link-end -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Task documents hold plans, reports, and image evidence.
> - Task attachments already have an image gallery.
> - Inline document images had no gallery navigation or image links.
> - This change gives each document a gallery that uses the existing
modal.
> - People can review the image sequence and share a link to one image.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Image review in task documents, including the side panel and Classic
interface.

**Current behavior**

Inline document images do not open a gallery. People cannot move through
them with arrow keys or share a link to one image.

**Proposed behavior**

Select an image to open the gallery. Use arrow keys or Previous and
Next. The URL records its one-based position, for example
`#document-report&image=2`. Reloading that URL opens the selected image.
Revision links keep their exact saved content.

**Reason and benefit**

People can inspect a document's image evidence in reading order and
share the exact view.

No matching issue was found. The latest 300 open PR titles were checked
for related document gallery work.

## What Changed

- Add a document renderer that collects rendered images in reading
order, including reference-style and repeated images.
- Reuse the gallery modal with optional index-change and focus-return
controls.
- Keep the document owner in the saved tab identity when people switch
between local and other-task documents.
- Match explicit current-task document owners with local document tabs.
Keep review and viewer parameters during gallery navigation.
- Treat another Classic review receipt as a new request while image
navigation retains the selected revision.
- Make inline image controls work with a keyboard. Keep focus in the
modal and restore focus on close.
- Keep document, revision, review, and maximized-view link parameters
during image navigation.
- Fix a Classic revision-cache race found by the browser test. Recheck a
pinned revision when the saved document head changes.
- Update the feature and agent access maps. No new server API or
permission is needed.

## Verification

- Passed 119 focused tests for document galleries, the shared gallery,
document rendering, the revision panel, and hash routing.
- Passed all 3 Chromium journeys: desktop, mobile, and Classic. These
use real uploads and saved document revisions.
- The browser journeys also check explicit current-task owners, review
parameters after reopening, other-task links after tab switches, and a
second Classic review link after Return to latest.
- Browser checks cover keyboard and button navigation, wraparound,
shared-link reload, exact historical content, invalid positions, focus
return and containment, scroll locking, and Escape, Close, and backdrop
dismissal.
- UI typecheck, token gates, map checks, and diff whitespace checks
passed.
- The UI production build passed in the browser harness.
- Earlier browser runs found and then verified the Classic
revision-cache fix. A later build exited 137 while the full test suite
ran. The browser run passed after that suite stopped.
- Full repository typecheck and build could not complete because Cargo
is absent. The full repository test run did not complete within this
sandbox. These checks remain subject to CI.

## Risks

- Image positions follow document reading order. Editing an unpinned
document can change those positions. A revision link retains the saved
sequence.
- The shared modal now uses Radix Escape handling. The existing gallery
tests and nested mobile dialog journey pass.
- No schema change or migration.

## Model Used

OpenAI GPT-6 through Codex. The runtime did not expose a more specific
model ID or context window size. Used reasoning, code editing, shell
commands, and browser automation.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

tests/e2e/document-image-gallery.spec.ts

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { expect, test, type APIRequestContext } from "@playwright/test";
+
+async function json(response: Awaited<ReturnType<APIRequestContext["get"]>>) {
+  expect(response.ok(), `${response.status()}: ${await response.text()}`).toBe(true);
+  return response.json();
+}
+
+for (const mode of ["desktop", "mobile", "classic"] as const) {
+  test(`document images share a gallery and deep links (${mode})`, async ({ page, request }, testInfo) => {
+    const mobile = mode === "mobile";
+    await page.setViewportSize(mobile ? { width: 390, height: 844 } : { width: 1440, height: 1000 });
+    const settings = await json(await request.get("/api/instance/settings/experimental"));
+    try {
+      await json(await request.patch("/api/instance/settings/experimental", { data: { enableClassicTaskInterface: mode === "classic" } }));
+      const company = await json(await request.post("/api/companies", { data: { name: `Document gallery ${randomUUID()}` } }));
+      const issue = await json(await request.post(`/api/companies/${company.id}/issues`, {
+        data: { title: "Review the design document", status: "backlog" },
+      }));
+      const paths: string[] = [];
+      for (const [index, title] of ["Plan the work", "Review the result", "Share the evidence"].entries()) {
+        const encoded = await page.evaluate(({ index, title }) => {
+          const canvas = document.createElement("canvas");
+          canvas.width = 1000; canvas.height = 600;
+          const ctx = canvas.getContext("2d")!;
+          ctx.fillStyle = ["#e0e7ff", "#ccfbf1", "#fef3c7"][index]!;
+          ctx.fillRect(0, 0, 1000, 600);
+          ctx.fillStyle = "#111827";
+          ctx.font = "bold 54px sans-serif";
+          ctx.fillText(title, 65, 125);
+          ctx.font = "24px sans-serif";
+          ctx.fillText(`Design review · Step ${index + 1}`, 65, 180);
+          for (let card = 0; card < 3; card++) {
+            ctx.fillStyle = "#ffffff"; ctx.fillRect(65 + card * 295, 255, 260, 220);
+            ctx.fillStyle = ["#4f46e5", "#0f766e", "#b45309"][index]!;
+            ctx.fillRect(90 + card * 295, 285, 65, 12);
+            ctx.fillStyle = "#d1d5db";
+            ctx.fillRect(90 + card * 295, 340, 190, 10);
+            ctx.fillRect(90 + card * 295, 370, 155, 10);
+          }
+          return canvas.toDataURL("image/png").split(",")[1]!;
+        }, { index, title });
+        const attachment = await json(await request.post(`/api/companies/${company.id}/issues/${issue.id}/attachments`, {
+          multipart: { file: { name: `step-${index + 1}.png`, mimeType: "image/png", buffer: Buffer.from(encoded, "base64") } },
+        }));
+        paths.push(attachment.contentPath);
+      }
+      const saved = await json(await request.put(`/api/issues/${issue.id}/documents/design`, {
+        data: { title: "Design review", format: "markdown", body: `# Design review\n\nSelect an image to review the sequence.\n\n![Plan the work](${paths[0]})\n\n![Review the result][review]\n\n![Share the evidence](${paths[2]})\n\n[review]: ${paths[1]}` },
+      }));
+      const taskPath = `/${company.issuePrefix}/issues/${issue.identifier}`;
+      await page.goto(`${taskPath}#document-design&viewer=full`);
+      const first = page.getByRole("button", { name: "Open image: Plan the work", exact: true }).first();
+      await expect(first).toBeVisible();
+      await first.click();
+      const gallery = page.getByRole("dialog", { name: "Image gallery", exact: true });
+      await expect(gallery).toBeVisible();
+      await expect(gallery).toContainText("1 / 3");
+      await expect(page).toHaveURL(/image=1/);
+      await expect(page.locator("body")).toHaveCSS("overflow", "hidden");
+      await gallery.getByRole("img").click();
+      await expect(gallery).toBeVisible();
+      await page.keyboard.press("ArrowRight");
+      await expect(gallery).toContainText("2 / 3");
+      await expect(gallery.getByRole("img")).toHaveAttribute("src", paths[1]!);
+      await expect(page).toHaveURL(/image=2/);
+      await page.screenshot({ path: testInfo.outputPath("document-gallery.png"), fullPage: true });
+      const sharedUrl = page.url();
+      await gallery.getByRole("button", { name: "Next", exact: true }).click();
+      await expect(gallery).toContainText("3 / 3");
+      await page.keyboard.press("ArrowRight");
+      await expect(gallery).toContainText("1 / 3");
+      await gallery.getByRole("button", { name: "Previous", exact: true }).click();
+      await expect(gallery).toContainText("3 / 3");
+      await page.keyboard.press("Escape");
+      await expect(gallery).toBeHidden();
+      await expect(first).toBeFocused();
+      await expect(page).not.toHaveURL(/image=/);
+      if (mobile) await expect(page.getByTestId("mobile-task-side-panel")).toBeVisible();
+      await page.goto(sharedUrl);
+      await expect(gallery).toContainText("2 / 3");
+      await page.reload();
+      await expect(gallery).toContainText("2 / 3");
+      await gallery.getByRole("button", { name: "Close", exact: true }).focus();
+      await page.keyboard.press("Tab");
+      await expect(gallery.getByRole("button", { name: "Previous", exact: true })).toBeFocused();
+      await page.keyboard.press("Shift+Tab");
+      await expect(gallery.getByRole("button", { name: "Close", exact: true })).toBeFocused();
+      await gallery.getByRole("button", { name: "Close", exact: true }).click();
+      await expect(gallery).toBeHidden();
+      const revised = await json(await request.put(`/api/issues/${issue.id}/documents/design`, {
+        data: { title: "Design review", body: "# New revision\n\nNo images.", format: "markdown", baseRevisionId: saved.latestRevisionId },
+      }));
+      expect(revised.latestRevisionId).not.toBe(saved.latestRevisionId);
+      await page.goto(`${taskPath}#document-design&viewer=full&revision=${saved.latestRevisionId}&interaction=current-task-review&documentIssue=${issue.id}&image=3`);
+      await expect(gallery).toContainText("3 / 3");
+      await expect(gallery.getByRole("img")).toHaveAttribute("src", paths[2]!);
+      await page.screenshot({ path: testInfo.outputPath("document-gallery-revision.png"), fullPage: true });
+      await gallery.click({ position: { x: 5, y: 180 } });
+      await expect(gallery).toBeHidden();
+      await expect(page).toHaveURL(new RegExp(`revision=${saved.latestRevisionId}`));
+      await first.click();
+      await expect(gallery).toContainText("1 / 3");
+      await page.keyboard.press("ArrowRight");
+      await expect(gallery).toContainText("2 / 3");
+      await expect(page).toHaveURL(/interaction=current-task-review/);
+      await expect(page).toHaveURL(/viewer=full/);
+      await expect(page).toHaveURL(new RegExp(`documentIssue=${issue.id}`));
+      await page.reload();
+      await expect(gallery).toContainText("2 / 3");
+      await gallery.getByRole("button", { name: "Close", exact: true }).click();
+      if (mode === "classic") {
+        await page.getByRole("button", { name: "Return to latest", exact: true }).click();
+        await expect(page.getByRole("heading", { name: "New revision", exact: true })).toBeVisible();
+        await page.goto(`${taskPath}#document-design&revision=${saved.latestRevisionId}&interaction=another-review&image=1`);
+        await expect(gallery).toContainText("1 / 3");
+        await gallery.getByRole("button", { name: "Close", exact: true }).click();
+      }
+      await page.goto(`${taskPath}#document-design&image=100`);
+      await page.reload();
+      await expect(page.getByRole("heading", { name: "New revision", exact: true })).toBeVisible();
+      await expect(gallery).toBeHidden();
+      if (mode === "desktop") {
+        const owner = await json(await request.post(`/api/companies/${company.id}/issues`, { data: { title: "Document owner", status: "backlog" } }));
+        const owned = await json(await request.put(`/api/issues/${owner.id}/documents/design`, { data: { title: "Owned review", body: saved.body, format: "markdown" } }));
+        await page.goto(`${taskPath}#document-design&viewer=full&revision=${owned.latestRevisionId}&documentIssue=${owner.id}&image=2`);
+        await expect(gallery).toContainText("2 / 3");
+        await gallery.getByRole("button", { name: "Close", exact: true }).click();
+        await json(await request.put(`/api/issues/${issue.id}/documents/local-images`, { data: { title: "Local images", body: saved.body, format: "markdown" } }));
+        await page.goto(`${taskPath}#document-local-images&viewer=full`);
+        await page.getByRole("button", { name: "Open image: Plan the work", exact: true }).click();
+        await gallery.getByRole("button", { name: "Close", exact: true }).click();
+        await page.locator(`[role="tab"][data-side-panel-tab-target="document:${owner.id}:design:${owned.latestRevisionId}"]`).click();
+        await page.getByRole("button", { name: "Open image: Plan the work", exact: true }).click();
+        await expect(page).toHaveURL(new RegExp(`documentIssue=${owner.id}`));
+        await page.reload();
+        await expect(gallery).toContainText("1 / 3");
+      }
+    } finally {
+      await request.patch("/api/instance/settings/experimental", { data: { enableClassicTaskInterface: settings.enableClassicTaskInterface } });
+    }
+  });
+}