PT-4711/4712/4714: Fix three per-pane content zoom defects

[rolfheij-sil]

Fixes three defects found by hands-on testing of per-pane content zoom.

A newly opened tab no longer flashes at the wrong size (PT-4714)

A tab whose view scales its own content used to open unscaled, then jump to the Settings default about a second later. The platform could not know, before the view's content mounted, whether that view scales itself — so it waited, and applied the whole-frame fallback only when the wait expired.

The platform now remembers, per view type, whether that type scales its own content, in a hidden setting. A view type that has scaled itself before is recognised on its next open and never gets the whole-frame fallback at all; every other view gets the fallback immediately, on the first frame, with no wait. The first-ever open of a view type nobody has opened before is the one case that still has to guess, and it guesses the way that is right for most views.

The record only ever gains entries in one direction — see Open question for review below.

The zoom chords follow the pane you clicked (PT-4711)

Clicking a footnote moves the caret into the footnote pane, but the view answers that click by moving the caret back to the main text. Ctrl+= / Ctrl+- / Ctrl+0 followed the caret, so they zoomed the main text instead of the footnote the user had just clicked.

The chords now distinguish a focus change the user made from one the view made in response, and stay on the pane the user chose. Ctrl+wheel was already correct — it follows the pointer.

Pop-ups drawn by the platform follow the pane's zoom (PT-4712)

The marker menu, context menus and the command palette are drawn by the platform outside the web view, so they stayed at interface scale inside a zoomed pane — small menus against large text.

Anchored pop-ups now draw at the scale of the pane that opened them. Centred surfaces that belong to the window rather than to a pane — modal dialogs, the window-wide command palette — deliberately do not, and a test now pins that.

Why the zoom sits on an inner wrapper

Radix requires a pop-up's arrow to be a descendant of its content element, and positions the arrow by writing an inline pixel offset on it. Putting the zoom on the content element therefore made the browser scale that offset a second time, landing the arrow well away from its trigger — and, where the true offset was small, collapsing it onto the content's own corner.

The zoom and all the sizing now sit on a wrapper inside the content element, with the arrow left outside that wrapper as a direct child of the content, which is what Radix requires. The pop-up still grows, because CSS zoom on a child still grows its parent's layout box, and the arrow's offset is now read at face value.

That wrapper has to take over width, flex layout and padding together. The shared PopoverContent supplies all three, and the pop-up's content renderers return fragments, so their children were direct flex items of it — taking only the padding inward silently resizes and respaces the pop-up at every scale, including 100%. PopoverContent keeps width: 'auto' so its fixed-width class cannot reassert itself over the wrapper.

Open questions for review

The per-type record only ever gains "scales its own content". It never moves back, and a pane of such a type that scales nothing in its current state — a placeholder shown before a project resolves — stays at 100% while every other pane sits at the user's default, indefinitely.

This is reachable during ordinary startup: the Scripture editor's resource panels mark their zoom area only once content resolves, behind several earlier returns that mark nothing, and in Simple mode those panels mount in Column 3 before a project does.

This is deliberate and was decided rather than overlooked: wait forever is the only wait that never flashes, and any bounded wait trades a guaranteed no-flash for a bounded stale-at-100% window. The no-flash side was chosen. It is written up here so a reviewer can weigh it, not because it is unresolved.

Pop-ups are not bounded by their own pane. No overlay ties Radix's collision boundary to the requesting pane, so a platform-drawn pop-up collision-avoids against the window and can paint slightly outside the pane that opened it. This predates content zoom and reproduces at 100%; it is called out because zoom makes it easier to notice.

Hidden views

Nothing here is geometry-driven sync across views, so there is no hidden-tab catch-up to design. The zoom push writes CSS custom properties, the grace timer's expiry does a liveness probe, and the scale read is an inline-style read — all of which work correctly in a display: none pane. Pop-ups are drawn on demand from the visible pane.

Verification

• typecheck, lint, format:check clean; core suite 5,636 passed; workspace suites green.
• E2E tests/isolated/notes-content-zoom/ 2/2. E2E tests/isolated/scripture-editor/ 11/13 — all six content-zoom tests pass, including the clicked-footnote chord case. The two failures (formatted-default-simple-mode, paragraph-style-trigger-column-floor) fail identically on this branch's base, verified by a control run; both are blocked by the first-run onboarding tour covering the toolbar in simple mode.
• Every new test was proven to bite by breaking the code it covers. The arrow regression check fails by 65.8px at 150% and 209.9px at 200% against a 2px tolerance when the fix is reverted, and passes at 100% where the zoom style is inert.

---

AI-assisted — session 1

🤖 Generated with Claude Code

https://claude.ai/code/session_01GyKxUPr99ahZUQZgSBuBBG

---

This change is 

Coordination with #2842

#2842 (the editor's context menu following its zoom area) positions its menu by writing a position, reading back where the element actually landed, and correcting by the difference — so it does not predict an offset and is robust to which ancestor carries the zoom. This PR changes exactly that: the zoom moves from the Radix content element onto an inner wrapper.

That should be absorbed, but it has only been measured against the current arrangement, not this one. So: whichever of #2841 and #2842 merges second re-measures the footnote editor pop-up — a right-click inside the pop-up at 200% must put the menu at the pointer, checked by comparing the menu's rect against the click point, not by assuming the rebase was clean.

Worth knowing for that measurement: a transform on an ancestor re-parents the containing block of a position: fixed descendant, and Radix's popper wrapper carries one. Nothing in this PR places a fixed-positioned element inside a pop-up — the popover's virtual anchor is a sibling outside the popper wrapper, and the arrow is positioned with left/top rather than fixed — but that is the shape to check for if either side adds one.

---

Code Review Summary

Branch: pt-4711-content-zoom-defects

Base: origin/pt-4584-notes-content-zoom (stacked — PR #2825, which is itself stacked on #2821)

Date: 2026-09-19

Review model: Claude Opus 5 (1M context)

Files changed: 28

Overview

Three defects found by hands-on testing of per-pane content zoom, fixed together because they share
the same machinery.

PT-4711 — the zoom chords (Ctrl+=/-/0) followed the caret. Clicking a footnote moves the caret
into the footnote pane, but the view answers that click by moving the caret back to the main text,
so the chords zoomed the text the user had just navigated away from. The in-iframe bootstrap now
distinguishes a focus change the user made from one the view made in response, and keeps the
chords on the pane the user chose. Ctrl+wheel was already correct — it follows the pointer.

PT-4714 — a newly opened tab whose view scales its own content showed unscaled for about a
second, then jumped to the Settings default, because the platform waited out a grace period to
learn whether the view would scale itself. The platform now remembers that answer per web view
type in a hidden setting, so a type it has seen before is recognised before the pane's HTML is
built and never gets the whole-frame fallback at all; every other view gets the fallback on the
first frame with no wait.

PT-4712 — platform-drawn pop-ups stayed at interface scale inside a zoomed pane. They now draw
at the requesting pane's scale. This work introduced a regression and then fixed it: Radix requires
a pop-up's arrow to be a descendant of its content element and positions it by writing an inline
pixel offset, so CSS zoom on that element made the browser scale the offset a second time. Fixed
by moving the zoom and all sizing onto a wrapper inside the content element, leaving the arrow
outside it.

API Changes

• papi-shared-types (feeds SettingTypes, visible through @papi/core/@papi/frontend's
  settings.get/set/subscribe generics): new hidden setting key
  platform.webViewContentZoomTypesWithAreas: { [webViewType: string]: boolean }, tagged
  @experimental. Additive, non-breaking. Source and regenerated papi.d.ts agree.
• No declare module '@papi/core', '@papi/backend', '@papi/frontend' or '@papi/frontend/react'
  block has a changed line.
• Non-@papi/ renderer modules that happen to be in the declaration bundle gained additive,
  @experimental-tagged exports: contentZoomOverlayStyle (new file); parseIframeZoom and
  getWebViewIframeZoom in overlay-coordinates (the latter replaces a module-private
  getIframeZoom that was never exported, so a new export rather than a breaking rename); a new
  optional contentScale?: number on the context menu's props.
• lib/platform-bible-react/, lib/platform-bible-utils/ and extension .d.ts contracts are
  untouched.

Findings

Critical — Must address before merge

None.

Important — Should address before merge

None. All four analysis passes (API/correctness, style/architecture, coverage/compliance, UX)
returned zero Critical and zero Important findings.

Minor — Consider

• The settings validator's null branch had no test reaching it — undefined is rejected
  a line earlier by the typeof !== 'object' arm, and typeof null is 'object', so only
  null exercises that guard. (fixed during review: added validate(null, …) with a comment
  saying why that input specifically is the one that reaches it)
• translateCoordinates looked the same iframe up twice — it held an iframe reference and
  then called getWebViewIframeZoom(webViewId), which re-queried the DOM for the same element.
  (fixed during review: parses the zoom from the element already in hand)
• The memory and type-record settings pairs (readMemory/readTypesWithAreas,
  enqueueMemoryTransaction/enqueueTypesWithAreasTransaction) are near-identical and could
  collapse into one generic implementation. (Author: leave it. The pairs are small, already
  documented, and each half is independently tested; a generic helper parameterised by setting
  key and cache accessors would be harder to read than the duplication it removes.)
• The popover and command palette compute their zoom size cap with near-identical logic that
  could move into the existing shared overlay-content-zoom.util.ts. (Author: leave it —
  same reasoning as above.)
• platform.webViewContentZoomTypesWithAreas is typed { [webViewType: string]: boolean }
  while the record only ever gains true entries, so the invariant is enforced by prose rather
  than by the type. (Left as boolean deliberately: the one-way behaviour is a decision that
  may be revisited — see Interview Notes — and narrowing a published type would have to be
  undone if it is. No behavioural difference either way. A reviewer who disagrees should say so.)

Template Propagation

Shared Regions Modified

None — no #region shared with <url> markers in any changed file.

Extension Config Changes

None — no files under extensions/ were changed.

Positive Observations

• Every new test was proven capable of failing by breaking the code it covers, with the failure
  text recorded. The arrow regression check fails by 65.8px at 150% and 209.9px at 200% against a
  2px tolerance when the fix is reverted, and passes at 100% where the zoom style is inert — the
  100% pass is the control showing the test is not simply always red.
• No toEqual(new DOMRect(...)) anywhere in the diff — that comparison examines nothing, because
  DOMRect keeps its values on the prototype.
• The arrow e2e check asserts a per-factor precondition that its trigger sits well away from the
  pop-up's own edge, so a collapsed arrow fails by construction rather than by luck.
• OverlayHost is deliberately the only module that imports the content-zoom service, keeping the
  service — including its test-only seams — off the extension-facing declaration bundle.
• parseIframeZoom was extracted so the two iframe-zoom readers cannot drift apart; the existing
  '150%' test case is exactly the divergence that would otherwise be possible.
• Documentation moved with the code: the decision log, Component-Builder-Patterns.md and
  Extension-Development-Guide.md were all updated in the same change.
• An independent sweep for backward-facing comments came back clean; the only ticket references in
  the diff are the decision log's own sanctioned **Source:** lines.

Interview Notes

Stated purpose: fix three defects found by hands-on testing, bundled in one PR stacked on #2825.

The one-way record — decided, not overlooked. The per-type record moves from "unknown" to
"scales its own content" and never back. A pane of such a type that scales nothing in its current
state (a placeholder before a project resolves) therefore sits at 100% while everything around it
is at the user's default, indefinitely. This is reachable during ordinary Simple-mode startup: the
Scripture editor's resource panels mark their zoom area only once content resolves, behind several
earlier returns that mark nothing, and in Simple mode those panels mount in Column 3 before a
project does. The author was given both options — leave it (never flashes, but an empty panel can
sit at the wrong scale) or give up waiting after a bounded time (no stuck panels, but the flash
returns) — and chose to leave it: "leave it. no flash is good."

Two pre-existing e2e failures, not caused by this branch.
formatted-default-simple-mode.spec.ts and paragraph-style-trigger-column-floor.spec.ts fail on
this branch, and fail identically on the branch's base — verified by a control run at
2672ef451d6, same command and machine. Both are blocked by the first-run onboarding tour covering
the toolbar in simple mode; both failing specs run in simple mode and neither dismisses the tour,
while every passing content-zoom spec runs in power mode. Author's decision: leave for now, no
ticket.

Verified by hand in the Windows dev app. The author ran all three fixes live on this branch
(git-win checkout, npm start) on 2026-09-19 and confirmed each: no flash on a newly opened tab,
the chords following a clicked footnote, and the marker menu drawing at the pane's scale with its
arrow on the trigger. Headless e2e had already covered the same three; this was the confirmation
pass, which is what the Windows dev app is for.

One thing still not verified in the running app. No in-app pane currently opens OverlayPopover
from a zoomed area, so that half of the arrow and sizing fix was checked in Storybook rather than
live — the hands-on pass could not reach it either. Its near-identical sibling, the command palette,
is covered by a passing e2e test. Called out rather than glossed, because the two were fixed
together and only one was exercised for real.

A regression this branch introduced and caught. The first version of the pop-up fix moved the
padding onto the new inner wrapper but left the width and flex spacing behind on the shared
component, silently resizing and respacing the popover at every scale including 100%. The visual
check that was supposed to catch it compared the new code at 100% against the new code at 200%, so
a change present at both scales was invisible to it — the control that was missing was new-vs-old.
Found by automated per-commit review, verified in the code, and fixed.

In-Review Quality Check

Two Minor findings were fixed during the review (the validator null case and the duplicate iframe
lookup). Targeted suites re-run after those changes: overlay-coordinates.test.ts and
core-settings-info.data.test.ts, 54 tests, all passing. Confirmed getWebViewIframeZoom is still
consumed by overlay-host.component.tsx and so was not orphaned by the change.

Full gates on the preceding commit: typecheck (4/4 projects), lint and format:check all clean;
core suite 5,636 passed / 15 skipped; workspace suites green; e2e
tests/isolated/notes-content-zoom/ 2/2; e2e tests/isolated/scripture-editor/ 11/13 with the two
failures proven pre-existing as described above. All roborev per-commit reviews for this branch were
triaged and closed with evidence, and audited closed=true.

Suggested Review Focus

• The one-way record. The consequence is a pane stuck at 100% until it marks an area. The
  trade was decided deliberately in favour of never flashing — worth a second opinion, since it
  is a look-and-feel judgement rather than a correctness one.
• OverlayPopover's half of the pop-up fix is the only part not exercised in the running
  app, for want of an in-app caller from a zoomed pane.
• Coordination with PT-4713: The editor's context menu follows the pane's zoom #2842. That PR positions its menu by reading back where the element
  landed and correcting; this PR changes which ancestor carries the zoom. Whichever merges
  second must re-measure the footnote editor pop-up rather than assume a clean rebase.
• Pop-ups are not bounded by their own pane — no overlay ties Radix's collision boundary to
  the requesting pane, so a pop-up can paint slightly outside it. Pre-existing, reproduces at
  100%, untouched here; flagged because zoom makes it easier to notice.