Skip to content

feat(annotate): All files view in the annotations panel for folder sessions - #1533

Merged
backnotprop merged 6 commits into
mainfrom
feat/annotate-all-files-panel
Sep 15, 2026
Merged

backnotprop merged 6 commits into
mainfrom
feat/annotate-all-files-panel

Conversation

@backnotprop

@backnotprop backnotprop commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

In a folder session the annotations panel only ever showed the open file's
comments. Iterating across several documents, there was no way to see the
whole review — and a file with nothing on it showed "No annotations yet" next
to a small "+N in M other files" button whose only power was to flash those
files in the sidebar. This adds the view that answers the question directly.

The model

Scope toggle. The panel header gains This file | All files, shown only
when feedback exists outside the open document (isMultiDocumentSession in
packages/editor/App.tsx). Message multi-select keeps its own cross-message
surface and is excluded. The explicit choice persists per browser in the
plannotator-annotation-scope cookie.

Default rule (resolveInitialAnnotationScope, packages/ui/utils/annotationScope.ts):
the saved preference wins, except that a document with no feedback of its
own while other documents have some
opens on All files. That is exactly the
frustration this exists for. It is re-resolved on each document change (keyed
on the open document only, so a toggle is never yanked away mid-document),
with one exception: arriving by clicking a card in the All files list keeps
All files, because that list is where the reviewer was.

Grouping (groupAnnotationsByDocument, pure): one collapsible group per
document that actually carries feedback, the open document first and the rest
by path, labelled relative to the deepest session root the file browser knows.
Groups render the same AnnotationCard the single-document timeline renders —
quote, comment, type, images, replies, Edit and Delete are not reimplemented.

Cross-file edit/delete goes through a new updateStoredAnnotations on
useLinkedDoc, writing into the owning document's stored annotations (the
linked-doc cache, or the stashed source document); the active document is
refused outright, since its annotations are host state. The export reads the
same map, so a cross-file delete is reflected in what is submitted.

Jump (useAnnotationJump) navigates through the file browser's own
selection path — active file, doc URL and linked document stay in step — waits
for the commit that makes the target the open document, then selects it, which
is what scrolls a markdown highlight and drives the HTML viewer's marker
selection. A navigation that never commits drops the request rather than
selecting an id into whatever document is open later.

The flash affordance survives as a "Show in files" link at the foot of the
All files view; while the scope is This file the header carries a quiet
+N elsewhere. A file with no feedback offers "View all N in M other files"
in its empty state, so the reviewer is never stuck.

Undo decision

Cross-file edits and deletes are deliberately not undoable. The annotation
history stack describes the open document's surface; an entry that undid into a
document the reviewer is not looking at would restore invisible state. Mod+Z
still covers everything done in the open document, and a cross-file mutation
does not disturb that stack. Called out in AGENTS.md and the manual checklist.

Counts

The panel header shows the scoped count, but the session total the decision
control runs on (feedbackAnnotationCount) is computed from session state and
is untouched by the toggle — switching scope never changes what is submitted.

Host package

AnnotationPanel is part of the published @plannotator/ui. Every new prop
(annotationScope, onAnnotationScopeChange, documentGroups,
onSelectInDocument, onDeleteInDocument, onEditInDocument) is optional
and additive
, and the feature only turns on when the first two are supplied.
A host that passes none of them — Workspaces — renders the previous panel,
legacy +N in M other files affordance included; there is a test that pins
that. bun run --cwd packages/ui smoke:package passes.

Scope

Markdown and HTML folder sessions, plus any session whose linked documents
carry feedback. Not code review, not single-document plan review, not live-app
multi-page (which already groups its export by page). The compact/touch sheet
reuses AnnotationPanel, so it gets the same toggle in its own header bar.

Test plan

New:

  • packages/ui/utils/annotationScope.test.ts — grouping order (open document
    first, then by path), empty documents dropped, label resolution, and the
    default-scope rule including the zero-here-some-elsewhere case.
  • packages/ui/components/AnnotationPanel.allFiles.test.tsx — cards from two
    documents render grouped; Delete/click on another document's card routes to
    the per-document callbacks and never to the open document's; group collapse;
    the toggle reports the choice and mutates nothing; the empty-state escape
    hatch; and the compatibility guard for hosts that pass no new props.
  • packages/ui/hooks/useLinkedDoc.crossFile.test.tsx — the real hook + the real
    panel: deleting another document's card removes it from that document's
    store (visible through getDocAnnotations, which is what the export reads)
    and leaves the open document alone; the session total moves on a cross-file
    delete and never on a scope toggle; the store refuses the active document.
  • packages/editor/hooks/useAnnotationJump.test.tsx — navigation is requested
    with the right path, the selection lands only after the destination commits,
    a commit for a different document does not settle it, and a navigation that
    never commits leaves nothing armed.

Run: DOM_TESTS=1 bun test packages/ui packages/editor — 1639 pass, 4 fail
(the pre-existing order-dependent DocBadges open-in placement cases; they
pass in isolation on this branch and fail the same way on main).
bun run typecheck, bun run --cwd packages/ui smoke:package,
bun run --cwd apps/review build and bun run build:hook all clean.

Manually verified in a three-file folder session (two files annotated):
This file with +2 elsewhere, the grouped All files view, the auto-switch on
the unannotated file, and a jump from an other-file card landing selected and
scrolled with the scope preserved.

Deploy note

The pinned guides.show viewer build changed (packages/core/guide-viewer-manifest.ts): the scope toggle's two new Tailwind utilities moved the viewer's bundled CSS hash, so the CSS filename and its SRI are repinned. The viewer JS hash and every grammar chunk are byte-identical, so nothing from the annotations panel leaked into the read-only viewer. Budgets are unchanged and within limits (js 396.3 KB gz / 400, css 51.5 KB gz / 64). Deploys with the next release tag.

Rebased onto #1532 (HTML sibling links)

A cross-file jump that lands on an HTML document now opens it with
revealSidebar: false, exactly like a link click between HTML documents: that
surface's page owns the viewport and the header carries its own Back, so
arriving there should not pop the left sidebar either. Markdown destinations
keep the markdown convention. The rule has one spelling — documentRendersHtml,
extracted from resolveHtmlLinkIntent in
packages/ui/utils/htmlLinkNavigation.ts — which both callers ask, with a test
pinning that the helper and link resolution never disagree.

@backnotprop
backnotprop force-pushed the feat/annotate-all-files-panel branch from 54a0291 to 9d6c4d7 Compare September 15, 2026 05:51
Pure helpers behind the annotations panel's cross-file view: one group per
document that carries feedback (open document first, the rest by path,
labelled relative to the nearest session root), and the rule that decides
which scope the panel opens on — the saved preference, except that a
document with no feedback of its own while other documents have some opens
on All files.
The panel gains an optional This file | All files scope toggle and a grouped
cross-file timeline built from the same AnnotationCard the single-document
view renders. Cards belonging to another document route their select, edit
and delete to per-document callbacks; useLinkedDoc grows
updateStoredAnnotations so a host can write into a stored document's
annotations (and refuses the active one, whose annotations are host state).

Every new prop is optional: a host that passes none of them renders the
previous panel, legacy '+N in M other files' affordance included.
Wires the panel's All files view into the annotate app: the scope toggle
appears whenever feedback exists outside the open document, the scope is
re-resolved on each document change (and kept across a jump), and cross-file
edits and deletes write into the owning document's store so the export
reflects them. Clicking a card in another document navigates through the file
browser's own selection path, waits for the commit, then selects — which is
what scrolls a markdown highlight or drives the HTML viewer's marker.

Cross-file mutations are deliberately not recorded in the annotation history:
that stack describes the open document's surface.
AGENTS.md gets the model (toggle, default rule, grouping, cross-file
mutation and its undo caveat, jump, counts) under Annotation System, and
tests/UI-TESTING.md a nine-step manual checklist.
The scope toggle's two new Tailwind utilities (.min-w-[16px],
.bg-surface-1/60) moved the viewer's bundled CSS hash. Only the CSS lines
change: the viewer JS hash and every grammar chunk are byte-identical, so
nothing from the annotations panel leaked into the read-only viewer.
…n HTML

A jump from the annotations panel follows the same rule as a link click
between HTML documents: an HTML destination owns the viewport and the header
carries its own Back, so arriving there must not pop the left sidebar. The
rule now has one spelling — documentRendersHtml, extracted from
resolveHtmlLinkIntent — which both callers ask.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant