Skip to content

Inbox: links inside an attached HTML page open - #2000

Merged
backnotprop merged 12 commits into
mainfrom
inbox-html-links
Oct 20, 2026
Merged

backnotprop merged 12 commits into
mainfrom
inbox-html-links

Conversation

@backnotprop

@backnotprop backnotprop commented Oct 19, 2026 •

Copy link
Copy Markdown
Owner

The bug

AttachmentPane passed HtmlViewer an onOpenLink that only opened http(s) URLs, so every relative link in an attached HTML page did nothing. Real case: a contact sheet (SHEET.html) whose links are sibling pages (A-story.html, B-cards.html, not attached) and frames/*.png (some attached, most not).

What a link does now

Links are read with annotate's own rules (resolveHtmlLinkIntent: relative to the folder of the page the link is in, root-relative to the attached page's folder, query dropped, fragment kept), then mapped in packages/inbox/htmlLinks.ts:

Target What happens
A file of the thread (attachment or captured message image, by realpath or named_path) Opens in the pane as a new history entry (browser Back returns to the page). The frame is kept, so full screen stays full screen. A typed comment asks first. A fragment is passed on once as initialFragment.
Another .html/.htm in the attached page's folder, not attached Opens read-only over the page, after the same unsaved-comment question, through the new GET /api/inbox/attachments/:id/linked-page?path=. A band shows "‹ Back to ", " is not attached, so comments are off." and Open in new tab. The fragment scrolls. The attached page stays mounted under it, hidden and inert, so Back returns to it as it was left.
A local image in that folder, not attached Opens in ImageLightbox through the attached page's asset route.
Another site Opens in a new tab, as before.
Anything else (another file type, outside the folder, hidden or dotenv name, other scheme, unreadable link) A note at the page's foot for 5 s, also read out by the pane's live region. Nothing fails silently.

Moving between linked pages. Each linked page is in the route (&linked=<path>%23<fragment>), so each is a history entry:

  • The browser's Back (and a phone's swipe back) steps back one page instead of closing the file.
  • The band's Back is the browser's Back when the entry was opened from there.
  • Escape steps back one page. In full screen this is a new rung of the Escape ladder, after the comments drawer and before Annotate. Beside the thread it is the only rung, for a key pressed inside the pane or the page.
  • A reload of a linked= address opens that page.

Around a linked page. In full screen the band floats at the top left and the page starts below it, so a heading at the very top is never covered. The pen is hidden while a linked page shows. The comments panel says "Off on ". Picking a comment card goes back to the attached page first.

The route. It has the same guards as the asset route and the attachment routes:

  • Paths must stay inside the attached page's folder, judged by realpath. After the open, the descriptor must still be the file that realpath names. On Linux this is judged by the descriptor's own path (/proc/self/fd/N). Elsewhere it is judged by the same dev and ino, read by lstat on both sides of a second realpath. O_NOFOLLOW covers only the last part of the path, so without this check a parent folder swapped for a symlink between realpath() and open() could serve a file outside the folder. A race test proves it.
  • Hidden segments and dotenv names are refused, judged both as requested and on the opened path.
  • Only .html/.htm and regular files are served. The read stops at 2 MB plus one byte, and anything over 2 MB is refused.
  • Cross-site requests get 403. GET only.
  • It is not on the device door.

Armed vs Interact (owner's ruling html-link-click). This is one rule for every HTML surface (annotate, plan review's raw HTML, the Inbox), and it lives in the shared bridge (bridge-script.ts):

  • Only a person's click follows a link (event.isTrusted, in both modes): a page's own a.click() never navigates the viewer or pushes the Inbox's history.
  • Only a link with a real destination follows. No href, "", "#" and javascript: go nowhere, so in Annotate a plain click pins them, as before (agents' mocks use <a href="#" class="btn">).
  • In Annotate a followable link shows no pin outline or label, and keeps the pointer cursor (SVG xlink:href links too), until Cmd/Ctrl is held. The outline always matches what a click will do.
  • In annotate and plan review, following a link to another document while a comment is being typed waits: the draft stays, focus returns to it, and a toast says why.
  • While armed, a plain click on a link follows it. Cmd-click (Ctrl-click off macOS) pins it for a comment, with its anchor as for any element. So does a shift-click that adds the link to an open multi-select draft.
  • A drag that selected text and ended on a link neither follows nor pins.
  • Enter on a focused link follows it.
  • Interact is unchanged.
  • Live apps keep navigating for real: the bridge leaves the plain click to the browser.
  • While armed, links show the pointer cursor instead of the crosshair.
  • The pen's tooltip says it: "links open (⌘-click one to comment on it)".

A linked sibling page takes no comments, so it always runs in Interact. No new keyboard shortcuts.

Tests

  • Bridge (srcdoc.test.ts, link navigation): an armed plain click follows; Cmd- and Ctrl-click pin with the anchor; a #fragment link scrolls on a plain click and pins on Cmd-click; a drag ending on a link neither follows nor pins; Cmd-click in Interact follows.
  • Live apps (htmlLiveProtocol.test.tsx): a plain click navigates natively, Cmd/Ctrl-click pins, a drag's trailing click never navigates.
  • Parent side (htmlLinkProtocol.test.tsx): an armed viewer hands the link to the host.
  • packages/inbox/htmlLinks.test.ts: the mapping (attachment, sibling page, image, external, refused).
  • packages/inbox/escapeLadder.test.ts: the linked rung.
  • packages/server/inbox-linked-page.test.ts: the route, every refusal, and the folder-swap race.
  • packages/inbox/htmlLinks.test.tsx: DOM test over inbox-dom-server.ts's new html-links mode, including the route entry, the panel note and Escape beside the thread. Added to the test.yml DOM list.
  • tests/e2e/inbox-html-links.spec.ts: compiled binary, real clicks in the page with no mode switch (armed), plus a Cmd/Ctrl-click that pins a link. Covers full screen in light and dark, beside the thread, and a phone. Checks browser Back and Forward, Escape, and a heading at the top below the band.
  • Typecheck passes. Related DOM and e2e suites pass (attachments, full view, message links, stepping, image viewer, open-in).

backnotprop and others added 12 commits October 19, 2026 19:09
A relative link in an attached HTML page did nothing: the pane only opened
http(s) links. Links are now read with annotate's rules (relative to the
page's folder, query dropped, fragment kept) and mapped onto the thread:

- a file of the thread opens in the pane as a new history entry, the frame kept;
- a sibling .html/.htm in the page's folder that is not attached opens
  read-only over the page (new GET /api/inbox/attachments/:id/linked-page),
  with Back, the reason comments are off, and Open in new tab;
- a local image beside it that is not attached opens in the lightbox through
  the page's asset route;
- another site opens a new tab;
- anything else shows a note saying why.

Armed (Annotate) clicks still pin the link, as in annotate; links follow in
Interact.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…h named

O_NOFOLLOW covers only the last segment, so a parent folder swapped for a
symlink between realpath() and open() let /linked-page serve a file outside the
attached page's folder (reproduced: a few reads in 20,000 under a swapping
process). Once open, the realpath must still lead to the same dev and ino, as
the message-image read checks; the hidden-file rule is judged on that path too;
the read stops at the cap plus one byte.

Co-Authored-By: Claude <noreply@anthropic.com>
…room under the band

Review follow-ups on links inside an attached HTML page:
- Each linked page is a history entry (route linked=), so the browser's Back
  and a phone's swipe back step back one page instead of closing the file;
  the band's Back is the browser's Back when it leads there.
- Escape steps back one page: a 'linked' rung of the full-screen ladder
  (after the drawer, before Annotate), and the one rung beside the thread.
- Following a page runs the same unsaved-comment question as leaving for a file.
- Full screen: the page starts below the floating band.
- The panel says comments are off on the linked page; a card picked there
  goes back to the attached page first. The fragment is cleared once used.
- e2e beside the thread, browser Back and forward, a heading at the top.
- The route comment no longer claims the folder swap was covered before the
  dev/ino check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The race test failed once in 20,000 on the Linux runners: stillSameFile could
see the real folder at its realpath and the swapped symlink at its lstat, which
then followed it to the very file the descriptor held. On Linux the
descriptor's own path (/proc/self/fd/N) now decides; elsewhere the dev and ino
are checked by lstat on both sides of the realpath. Passes 5 of 5 in a Linux
container.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…click pins it

The owner's ruling (html-link-click, 2026-10-20): one rule for every HTML
surface, in the shared bridge. While armed, a plain click on a link follows it
under the existing link model (annotate, plan review's raw HTML, the Inbox);
Cmd-click (Ctrl-click off macOS) pins it for a comment with its anchor, as
does a shift-click adding it to an open multi-select draft. A drag that
selected text and ended on a link neither follows nor pins. Interact is
unchanged. Live apps keep navigating for real: the plain click is left to the
browser. Links keep the pointer cursor while armed.

Tooltips, AGENTS.md and the marketing docs say so; bridge tests cover both
behaviours, live links, and drags; the Inbox e2e follows links with no mode
switch and pins one with Cmd/Ctrl-click.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	tests/e2e/playwright.config.ts
#	tests/helpers/inbox-dom-server.ts
…outline matches

Review follow-ups on the shared link rule:
- The bridge sends link-click only for a trusted click, in Annotate and
  Interact: a page's own a.click() never navigates the viewer or pushes the
  Inbox's history (a page clicking its own link on a timer is tested).
- A link that goes nowhere (no href, "", "#", javascript:) is not followed:
  a plain click in Annotate pins it as before (agents' mocks use
  <a href="#" class="btn">). The pointer cursor marks only followable links,
  SVG xlink:href links included.
- In Annotate a followable link shows no pin outline or label until Cmd/Ctrl
  is held (read from the key and from each pointer move), so the outline
  matches what a click will do.
- Annotate and plan review: following a link to another document while a
  comment is being typed waits, with a toast, and keeps the draft.
- AGENTS.md's stale line fixed; the Inbox's empty panel beside a linked page
  says where comments go instead of "Select text to annotate".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…llow the same rule

The owner's amendment to html-link-click: on a phone a tap on a link
follows it and a 500 ms press-and-hold pins it for a comment, in every
HTML surface (annotate, plan review's HTML, the Inbox, live apps). The
platform's own long-press is off on links while armed, Android's
contextmenu fires the hold, movement past 10 px cancels it, and the
release never follows the link. New e2e for annotate's local HTML and
live app surfaces (desktop click/Cmd-click, WebKit iPhone and Chromium
Pixel tap/hold) and phone hold/tap in the Inbox.
…the text as Cmd-click does

Review fixes for the touch rule:
- user-select: none on links only while a hold is in progress
  (data-plannotator-link-hold), so a mouse or trackpad drag across a
  link on a touchscreen laptop or iPad still quotes its words; the
  callout stays off on links while armed. The hold turns selection back
  on for the moment it pins, so it pins the link's words like Cmd-click.
- The release swallow ends at the next touch, mouse/pen press or key,
  and an unseen release is bounded at 10 s.
- The release's pointerup and touchend are stopped at the window for the
  gesture that became a hold, so a live app's own listeners never run.
…ntercancel and touchcancel

A press library (React Aria usePress, Motion whileTap, dnd-kit) saw
pointerdown and touchstart and never an end, so it kept the press open.
The bridge still stops the real release, then dispatches a pointercancel
(same pointerId, touch, primary) and a touchcancel on the original
target; its own listeners ignore them.
…ne tests

Linux WebKit exits on --use-mock-keychain; launch it with args: [] as
inbox-mobile.spec.ts does.
@backnotprop
backnotprop merged commit 2e5de98 into main Oct 20, 2026
32 checks passed
backnotprop added a commit that referenced this pull request Oct 20, 2026
…HTML page (#2019)

The Inbox's attached-page viewer passed maxAdditionalTargets={0}, so the
bridge was armed with a cap of 0 and every shift-click was dropped. It has
been that way since attachments shipped (#1759); not a regression from #2000.
Annotate never set the cap and works. The viewer's own cap (16) now applies.

Co-authored-by: Claude <noreply@anthropic.com>
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