Repository navigation
feat(annotate): All files view in the annotations panel for folder sessions - #1533
Merged
Merged
Conversation
backnotprop
force-pushed
the
feat/annotate-all-files-panel
branch
from
September 15, 2026 05:51
54a0291 to
9d6c4d7
Compare
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.
backnotprop
force-pushed
the
feat/annotate-all-files-panel
branch
from
September 15, 2026 06:05
9d6c4d7 to
b0afcf6
Compare
This was referenced Sep 15, 2026
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 onlywhen feedback exists outside the open document (
isMultiDocumentSessioninpackages/editor/App.tsx). Message multi-select keeps its own cross-messagesurface and is excluded. The explicit choice persists per browser in the
plannotator-annotation-scopecookie.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 perdocument 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
AnnotationCardthe single-document timeline renders —quote, comment, type, images, replies, Edit and Delete are not reimplemented.
Cross-file edit/delete goes through a new
updateStoredAnnotationsonuseLinkedDoc, writing into the owning document's stored annotations (thelinked-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 ownselection 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+Zstill 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 andis untouched by the toggle — switching scope never changes what is submitted.
Host package
AnnotationPanelis part of the published@plannotator/ui. Every new prop(
annotationScope,onAnnotationScopeChange,documentGroups,onSelectInDocument,onDeleteInDocument,onEditInDocument) is optionaland 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 filesaffordance included; there is a test that pinsthat.
bun run --cwd packages/ui smoke:packagepasses.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 documentfirst, 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 twodocuments 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 realpanel: 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 requestedwith 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 placementcases; theypass 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 buildandbun run build:hookall 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 onthe 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: thatsurface'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
resolveHtmlLinkIntentinpackages/ui/utils/htmlLinkNavigation.ts— which both callers ask, with a testpinning that the helper and link resolution never disagree.