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>

maps/agent-access-map/documents-artifacts.md

@@ -16,6 +16,11 @@ for format, permission checks, evidence and maintenance.
 
 Capability ID: `documents-artifacts/documents`.
 
+Document image selection is browser presentation state. It needs no new API or
+agent permission. Agents can share `#document-<key>&image=<one-based-position>`
+links with optional `revision` and `viewer=full` parameters. Existing task,
+document, revision, and image resource read permissions still apply.
+
 Coordinator receipt reads add `GET /api/issues/{id}/documents/{key}/revisions/{revisionId}`.
 It applies the same task-read authorization as document revision history and
 queries exactly one revision under that task/document key. It does not fall back

maps/feature-map/documents-artifacts.md

@@ -26,6 +26,13 @@ Agent access: [companion](../agent-access-map/documents-artifacts.md).
 
 Open a document from the task thread or document side panel.
 
+Select an inline image to open the document's image gallery. Use the left and
+right arrow keys or the Previous and Next buttons to move through images in
+reading order. The URL retains the document and adds a one-based `image` position,
+such as `#document-report&image=2`. Share or reload that URL to open the same image.
+Revision and maximized-view parameters remain in the link. Escape, Close, or the
+backdrop closes the gallery and returns focus to the image.
+
 Coordinator decision receipts also open a pinned reviewed revision alongside
 the matching task interaction. Historical tabs retain their revision identity
 independently of the current document tab. Missing revisions are explicit and
@@ -55,6 +62,11 @@ Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use
 
 Automated: [documents service](../../server/src/__tests__/documents-service.test.ts), [annotations](../../server/src/__tests__/document-annotations-service.test.ts), and [revision restore](../../server/src/__tests__/issue-document-restore-routes.test.ts) cover server contracts.
 
+[Document image galleries](../../tests/e2e/document-image-gallery.spec.ts) checks
+desktop, mobile, and Classic document views with real uploaded images and saved
+document revisions. It covers keyboard/button navigation, image URLs and reload,
+focus return, focus containment, scroll locking, dismissal, and revision links.
+
 [Exact revision panel](../../ui/src/components/task-side-panel/TaskDocumentPanel.test.tsx)
 checks pinned content and missing-revision behavior; this component test does not
 prove end-to-end conversation scrolling. Open a resolved receipt after making a