DottaandPaperclip
cd5f930558
<!-- 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>
7.6 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Documents, attachments, and work products
People read and revise task documents, annotate specific content, open attached files, and inspect the outputs an agent hands back. The artifact library provides another route to the same work.
Feature ID: documents-artifacts.
Implementation: task documents, artifact library, document panel.
Agent access: companion.
Sub-features
documents:documents-artifacts/documents— edit versioned task documents and inspect or restore revisions.annotations:documents-artifacts/annotations— attach feedback to document content and inspect resolution state.attachments:documents-artifacts/attachments— upload, preview, and download allowed files with company access checks.work-products:documents-artifacts/work-products— link deliverables to their source task, resource, and review context.library:documents-artifacts/library— search, filter, group, and open artifact stacks.
How to get to it (user POV)
task-document
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 never silently replaced with the latest document. When a decision in one task reviews another task's document, the center pane keeps the originating conversation while the sidebar opens the document owner's exact revision. An inaccessible owner never falls back to the origin task's document.
task-output
Open an attachment, output card, or file link from a task. For direct uploads, use the task side panel's Open a new tab → Artifacts → Upload files or drop files anywhere in that panel. On mobile, open More actions → Properties first. Agent conversations do not expose this upload path.
artifact-library
Open /artifacts and its grouping, search, and media controls.
Driving it with Playwright and the Paperclip CLI
The explicit build-revise Product journey covers documents-artifacts/attachments: browser downloads of two ZIP versions, an independent content oracle, and preservation of the original. Its shared source is not proof of a pass on any deployed target.
Preconditions: follow the baseline. Use a task with a text document, a small attachment, and a generated work product. Use nonsensitive fixture files.
task-document
Automated: documents service, annotations, and revision restore cover server contracts.
Document image galleries 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 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 new revision and verify the earlier body plus matching interaction in the browser.
Manual: Edit a paragraph, save, reload, and compare revisions. Add an annotation to a specific selection and inspect it after another edit. Resolve it through the supported action. Restore a disposable revision and confirm the new current document and history agree.
task-output
Automated: attachment routes and work products cover data/access behavior; artifact arrival browser suite targets arrival. Artifact uploads drives file selection/drop, filename collisions, retry, and preservation of paused/unassigned tasks.
Manual: Upload a small Markdown file and CSV through Artifacts. Markdown becomes a versioned task document; other files become attachments. Read the document, download the CSV and compare bytes, then reload. Upload the same Markdown filename again and verify a separate suffixed document without overwriting the original. On a paused unassigned task, confirm upload does not start work or add comments. Verify agent-produced work products separately using an eligible test run. Test an inaccessible user/company and explicit missing workspace-only resources.
artifact-library
Automated: artifact page covers grouping, search requests, and pagination using mocks.
Manual: Find the task’s output through search and grouping, open its stack, page through results, and reload a direct stack link. Confirm the same file/content appears as from the task.
Gotchas
-
In Coordinator, saved plan cards use document chronology, so a plan written before its output appears first even when both writes share one native run. Authored issue-document links use the same compact sidebar-link surface and retain revision/annotation targets. Classic run embedding is unchanged. The UI does not remove or deduplicate canonical plan content.
-
A local path is not automatically an uploaded artifact accessible to another user.
-
A preview screenshot is not proof that download bytes or revision references are correct.
-
Version conflicts and stale annotations must stay visible rather than silently targeting different content.
Storybook verification
documents
Capability ID: documents-artifacts/documents.
Scope: ui Storybook: Writable/read-only document, save pending/failure/conflict, revision history/historical preview and restore confirmation. Production: Persist edited body and reload; append-only restore creates new revision; reject stale writes and inaccessible company/task. Sources: Source: IssueDocumentsSection.tsx, TaskDocumentPanel.tsx, documents.ts. Tests: IssueDocumentsSection.test.tsx, document-revisions.test.ts, documents-service.test.ts, issue-document-restore-routes.test.ts
Documentation scope: Artifacts and work products
Document/attachment/library/work-product journeys are mapped; every media preview type, storage backend, annotation conflict, and runtime-resource lifecycle variant remains separate.