PT-4193: Add secondary notification action, position, and dismissible

[rolfheij-sil]

What

Adds four additive, backward-compatible optional fields to PlatformNotification so an extension can raise a two-button, specifically-placed, must-answer toast:

• secondaryClickCommandLabel / secondaryClickCommand — a second action, mapped to Sonner's cancel slot alongside the existing action. Both send the notification id as the command's single argument (no new args plumbing — the model still carries no command args).
• position — a per-toast placement (NotificationPosition, e.g. 'top-center'), passed straight through to Sonner; undefined keeps the Toaster's default.
• dismissible — passed through to Sonner; set false (with duration: 0) for a toast the user must answer via an action button rather than swipe/drag away.

Wired through notification.service-host.ts (the existing action block gains a parallel cancel block; position and dismissible go straight into toastOptions) and the OpenRPC schema; papi.d.ts regenerated via npm run build:types.

Why

This is the reusable platform capability the scheduled Send/Receive consent toast (PT-4193, extension side) needs: a persistent top-center prompt with "Send/Receive now" / "Postpone" buttons the user must answer. dismissible: false matters — Sonner 1.7.4 defaults to swipe-to-dismiss, which for a toast an extension awaits a decision on would otherwise let an accidental drag strand the waiting code.

Decision record: PT-4158 UX meeting 2026-07-15 (Q1 = option B); PT-4193 ticket comment 27495.

Back-compat

All four fields are optional. When omitted, cancel, position, and dismissible are undefined, so existing single-action / default-placement toasts are unchanged (Sonner treats explicit undefined as absent). No private code — this is public scaffolding; the private consent gate lives in the extension.

Tests

notification.service-host.test.ts +4 cases: cancel built from the secondary fields; position forwarded; dismissible forwarded; all three undefined by default. npx vitest run src/renderer/services/notification.service-host.test.ts → 9/9. Targeted eslint clean; typecheck:core adds nothing over the pre-existing baseline (one unrelated missing-buildInfo.json error).

Review fix (PT-4193): the dismissible: false cancel-slot trap

Review flagged a BLOCKER, verified against the Sonner 1.7.4 source (node_modules/sonner/dist/index.mjs): Sonner computes V = toast.dismissible !== false and gates the cancel-slot (our secondaryClickCommand) button's onClick on V, but does not gate the action button the same way:

// cancel button: onClick: r => { tt(t.cancel) && V && ((t.cancel.onClick)?.(r), $()) }        // gated on V
// action button:  onClick: r => { tt(t.action) && ((t.action.onClick)?.(r), !r.defaultPrevented && $()) } // NOT gated

So dismissible: false combined with a secondaryClickCommand produced a dead secondary button — no command fires, no dismiss happens, silently. The consuming consent toast (extension PR #183) uses exactly that combination, and this PR's own original JSDoc on dismissible recommended it ("set to false … combine with duration: 0" for an awaited decision) — i.e. the doc was steering callers straight at the trap. Sonner has only one ungated button slot (action), so a toast with two working buttons must keep dismissible: true.

Fix — swipe-dismiss becomes a first-class exit:

• Added dismissClickCommand?: keyof CommandHandlers to PlatformNotification: a parameterless-besides-the-notification-id command invoked when the user dismisses the toast (swipe/drag past Sonner's threshold, or a close button if one is ever enabled). Mapped in notification.service-host.ts to Sonner's onDismiss option, with a .catch → logger.warn so a rejected command handler can't become an unhandled rejection.
• Verified against the Sonner source which paths call onDismiss: only the swipe-release handler (onPointerUp, gated on the same dismissible flag) and the close-button onClick (also gated, and disabled by default since this app doesn't pass closeButton to <Toaster />) call it. Programmatic dismissal (INotificationService.dismiss() → toast.dismiss(id)) marks the toast delete: true, which only triggers the internal removal animation — it does not call onDismiss. Auto-close when duration elapses calls a different callback (onAutoClose), also not onDismiss. This is documented on the new field so consumers awaiting a decision know a programmatic dismiss() call will not trigger it.
• Rewrote the dismissible JSDoc: removed the "combine with duration: 0" recommendation that steered callers into the trap; added a warning that dismissible: false also disables the secondary/cancel button (and the close button), so it's only safe on a notification with no secondary action. Points callers at dismissClickCommand + dismissible: true for the "must answer" case instead.
• Same-review hardening: added a matching .catch → logger.warn on the secondary button's sendCommand call (it previously had none, unlike the primary path's now-consistent handling); constrained the OpenRPC schema's position property with an enum of the six NotificationPosition values (was a bare type: 'string').
• Regenerated papi.d.ts; the diff touches only the notification.service-model module.

Tests: extended notification.service-host.test.ts from 9 to 13 cases — added the onDismiss mapping, both new .catch-swallows-rejection-and-logs paths (secondary click, dismiss click), and broadened the back-compat case to also assert onDismiss: undefined. Also added notification-display.test.tsx (1 test) — the one test in this suite that renders the real <Toaster /> with real Sonner (every other case here mocks sonner wholesale, which is exactly why this blocker shipped undetected): it sends a toast with a secondary command and dismissible left at its default true, clicks the actual rendered cancel-slot DOM button, and asserts the secondary command was sent — pinning the real Sonner button-gating contract instead of just the shape we hand it. 14/14 green across both files; targeted eslint clean; typecheck:core still adds nothing over the pre-existing baseline.

Contract note for the consumer: extension PR #183 will drop dismissible: false and set dismissClickCommand to a "postpone" command, keeping dismissible: true.

Follow-up fix (PT-4193, 938749040d7): a live E2E screenshot showed a two-button toast (action + cancel, both long labels) with the message text crushed to a ~1-character-wide sliver — Sonner's default layout puts icon/content/cancel/action in one un-wrapped flex row, and two non-shrinking buttons squeeze the content column to nothing. Fixed with CSS only, scoped via :has() so single-button/plain toasts are unaffected: notification-display.tsx now wires the Toaster's toastOptions.classNames (verified against Sonner 1.7.4's index.d.ts) onto toast/content/actionButton/cancelButton, and the new notification-display.scss grows the content row to fill the toast and forces the two buttons onto their own row beneath it (via the standard flex-wrap "empty flex-basis: 100% item" line-break technique), right-aligned and RTL-safe for free via Sonner's existing auto-margin CSS. Extended notification-display.test.tsx from 1 to 4 cases pinning the DOM shape the stylesheet rule depends on (two-button toasts get all three class hooks under one shared flex-container ancestor with both buttons still working; single-button/plain toasts don't). 17/17 across the notification suite, 979/979 full core suite; targeted eslint + stylelint clean; typecheck:core and papi.d.ts unchanged.

Follow-up fix (PT-4193, 5a4b763af4e): live E2E testing of Send/Receive surfaced an orphaned "Syncing (0%)" toast that never went away — a sync abort's dismiss(notificationId) clears the toast-id mapping, but an in-flight, fire-and-forget progress send() for that same id can land just after, find no mapping, and resurrect a brand-new toast that nothing then dismisses. Fixed with a short (5s) grace window: dismiss() now remembers each notificationId briefly after dismissing it, and send() drops an update-style send (an explicit, existing notificationId) that falls within that window instead of creating a new toast, logging a debug line. Brand-new notifications (no id passed) are never affected, and legitimately reusing an id after the window elapses still works normally; entries are pruned lazily on send()/dismiss() — no timers. Extended notification.service-host.test.ts with 3 cases (drop-on-race + debug log, post-grace-window reuse via fake timers, id-less send unaffected) — 20/20 green across the notification suite; targeted eslint clean; typecheck:core and papi.d.ts unchanged.

Rebase note (2026-07-16): rebased onto main after #2555 merged. No conflicts — the papi.d.ts auto-merge (both sides had regenerated it) was verified by re-running npm run build:types post-rebase: zero drift, so the committed file is exactly the machine-generated output. Notification suites 20/20, targeted eslint + stylelint clean. New tip: 43d761546d7.

🤖 Generated with Claude Code

---

Fix round — 2026-07-17 (response to lyonsil's review)

All 30 findings addressed at tip 1e2a99c (three commits):

• a0cd67c — grace window deleted (findings 1, 5, 6, 7, 8, 16, 18, 22, 29; moots 24, 30). dismiss() is a true no-op when absent again; send() has no silent-drop path.
• 14dc10b — toast CSS reworked + keyboard reach (findings 2, 3, 4, 15, 23, 26): inert ::after/flex-wrap/block-size:0 overrides removed; deterministic two-row layout scoped to two-button toasts; hover bridge untouched; Alt+T now focus-cycles across every position list. Known residual: Escape still targets only Sonner's last list (cosmetic — Escape doesn't dismiss; the top-center group holds a single toast). Say the word if Escape parity is wanted as a follow-up.
• 1e2a99c — service hardening (findings 9, 10, 11, 12, 13, 14, 17, 19, 20, 21, 25, 27, 28): update-merge keeps omitted fields (documented: no unset-on-update), onAutoClose wired, dismissible:false no longer silently kills the dismiss command, shared removal-command helper with .catch by construction, parallel localization, namespaced auto-ids, !== undefined id checks, derived position values.
• 579bbfd — round-4 E2E finding F3: the break-lock toast (long warning + single wide "Break lock and retry" action button, no cancel) still rendered text and button crammed side-by-side — the two-row reflow only engaged when BOTH buttons were present; the :has() rule now matches either button class so any buttoned toast reflows (lone buttons stay right-aligned via a pair-only margin override), +1 real-Sonner render test pinning the single-action DOM shape.
• 0a566bf — press-collapse fix (credit: Sebastian's triage): holding any mouse button down on a buttoned toast collapsed it to a one-character sliver until release — Sonner sets data-swiping="true" on pointerdown before any movement, and the button-row ::before break was gated out of that state while flex-wrap/flex-basis: 0 stayed active. The break is now unconditional with an explicit position: static, out-winning Sonner's zero-specificity :where() swipe/removal ::before styles, so the two-row layout is stable through press, swipe, and removal (the ::after hover-bridge stays untouched); +1 real-Sonner render test pinning that a plain press (either button) enters the swiping state with the layout hooks intact.

Merge pairing: this PR and paratext-10-studio#163 should land in the same release window — the producer-side _syncGeneration guard (reworked on #163's branch) is now the protection for the S/R dismiss race. paratext-bible-internal-extensions#186 must not merge before this PR (its consent/lock toasts depend on position/dismissible/secondary-action fields).

Pending manual verification (needs a real browser; jsdom can't model Sonner's focus-trap): Alt+T cycling with a top-center consent toast + bottom-right toast present; the break-lock fast re-send flow (now un-broken by the window deletion).

---

This change is

[lyonsil]

Deep review of the notification changes. 30 findings, filed inline and numbered by severity. Claims about Sonner are verified against the real 1.7.4 source; CSS claims are measured in a real browser against Sonner's actual self-injected stylesheet and DOM; behavioral claims are backed by probe tests. Where I checked a suspicion and it turned out wrong, I've said so in the comment rather than leaving it implied.

Headline: paratext-10-studio#163 already fixes the race this PR's grace window was written for

It fixes it at the producer, with the right primitive - an Interlocked _syncGeneration bumped before dismiss, re-checked before the queued send, with a dedicated NUnit test, labeled PT-4211 (the same bug).

And PT10's progress toast passes no NotificationId, while the drop path is gated on notificationId !== undefined - so the window can never fire for the producer it exists to protect. It fires for nobody it was built for, while silently breaking the "Break lock and retry" flow in paranext/paratext-bible-internal-extensions#186. Keeping both would also let this window mask a future regression in _syncGeneration, whose test only pins the increment, not the skip.

Recommendation: delete the grace window. Findings 5, 6, 7, 8, 16, 18, 22 and 29 all evaporate with it.

Also live

• The ::after line-break in the new stylesheet is inert (3). Sonner already owns that pseudo-element with position: absolute. Deleting the entire block produces byte-identical geometry in Chromium; position: static fixes it.
• flex-wrap: wrap introduces an orphaned icon row (4) for #186's real message strings - so the layout fix doesn't fix, and regresses.
• Per-toast position breaks Alt+T and Escape (2). Sonner renders one <ol> per position sharing a single ref; the consent toast alone creates two, for its whole Infinity lifetime.
• An update-send that omits an optional field clobbers it (9) - dismissible: false -> true, top-center -> bottom-right, cancel button gone.

Cross-PR coordination

#186's ConsentNotification intersection type makes its dependency on this PR look soft when it is hard. If #186 ships first, these fields are silently ignored: Postpone never renders, swipe fires nothing, requestConsent's promise never settles, and isConsentPending stays true - auto-sync dies silently for the session. #186 should not merge ahead of this PR, and a runtime capability check would be safer than the type-level intersection.

Credit where due: #186's comments show the team already found and worked around the dismissible: false trap in development, which is exactly why finding 11 matters for the next caller.

Notes

• Five comments are anchored to the nearest line inside a diff hunk because their real target is an unchanged context line; each names its true line.
• Findings tagged [pre-existing] aren't regressions from this PR - raised because the PR touches or re-exposes them, and several become trivial to fix alongside these changes.

This review and all of its inline comments were AI-generated with my guidance.

[rolfheij-sil]

🤖 Claude: All 30 findings addressed; tip 1e2a99c. Summary:

• Grace window deleted (a0cd67c): findings 5, 6, 7, 8, 16, 18, 22, 29 evaporate with it; 24 and 30 are moot once it's gone. On finding 1 specifically — we agree with deletion and did it — but the "can never fire for its producer" premise is off: the fire-and-forget UPDATE sends carry the minted NotificationId (verified in the current studio main patch ~L2031 and Adjusted Network Object and Data Provider Types #163 ~L3280), and dropping those id-bearing updates was the window's actual mechanism. Deletion stands on the other legs (ran before the awaits, wrong primitive, broke #186 flows), with Adjusted Network Object and Data Provider Types #163's atomic producer-side _syncGeneration guard as the right fix. Details inline on finding 1.
• CSS override replaced, not patched (14dc10b): a deterministic two-row :has(.cancel):has(.action) layout, the line break moved to ::before so Sonner's ::after hover bridge is untouched, explicit right-alignment, and the Sonner-1.7.4 DOM dependency named in a comment (findings 3, 4, 15, 23, 26).
• Position kept (UX-specified top-center) with keyboard reachability fixed at the source — Alt+T focus-cycling across lists; a separate Toaster per position was empirically disproven since Sonner renders every toast in every Toaster (finding 2).
• Service host hardened (1e2a99c): merge-over-stored-state (9/14), onAutoClose wired (10), the dismissible: false footgun closed (11), a shared command helper with .catch by construction (12/25), map cleanup on all removal paths (13), Promise.all localization (17/27), namespaced string auto-ids (19), the falsy-0/'' fix (20), logger mocks (21), and a derived position enum (28).
• Two honest residuals: Escape still targets only Sonner's single shared list, so it collapses an expanded stack on the last-mounted list only (cosmetic — it collapses rather than dismisses; follow-up on request); and the merge semantics have no unset-on-update (documented in TSDoc — omitting a field keeps it, and JSON-RPC drops undefined, so a field can't be cleared on update).
• Merge coordination: this PR pairs with studio Adjusted Network Object and Data Provider Types #163 in the same release window, and #186 should not merge ahead of this PR — both recorded in the PR bodies.
• Verification: the passing vitest suites cover the service-host and keyboard-registration logic, and a live build this morning confirmed the three things jsdom can't exercise — Alt+T cycles focus between the top-center consent toast and the bottom-right toasts; long messages wrap into the two-row layout with the icon staying beside the message (not orphaned); and #186's "Break lock and retry" re-send now renders a toast normally with the grace window gone. The one residual left unverified is Escape scope (it collapses only the last-mounted list). Requesting re-review.

[Sebastian-ubs]

Since this PR is what introduces the notification secondary/cancel button as a platform capability, it should also settle its default look rather than leaving it as Sonner's built-in styling.

Proposal: .notification-toast-cancel-button in notification-display.scss should render as the shadcn secondary variant (from lib/platform-bible-react/src/components/shadcn-ui/button.tsx — tw:bg-secondary tw:text-secondary-foreground tw:hover:bg-secondary/80 …). Semantically this matches shadcn's action = default / cancel = secondary convention, and it means every current and future two-button platform notification (S/R consent toast in #186, and anything downstream) gets a consistent look without each caller re-deciding.

One thing to watch when you add the rules: Sonner 1.7.4 emits data-cancel defaults at zero specificity via :where() — the new rules will likely need at least .notification-toast .notification-toast-cancel-button to win reliably (same pattern you already use on the ::before overrides).

[lyonsil]

Verified review of the notification changes (correctness plus a few cleanup/convention notes) - findings are inline. The only one I'd treat as a blocker is the first (the prod-only CSS specificity tie): it breaks the two-button toast alignment in packaged builds while looking fine in dev. The rest are lower severity.

(AI-assisted, with my guidance)

[lyonsil]

@lyonsil reviewed 8 files and all commit messages, and resolved 30 discussions.
Reviewable status: all files reviewed, 10 unresolved discussions (waiting on rolfheij-sil).

[lyonsil]

@Sebastian-ubs Implemented in 9c3be33 - .notification-toast-cancel-button now renders as the shadcn secondary variant (var(--secondary) / var(--secondary-foreground), color-mix 80% hover), with three notes from implementation:

• Specificity had to go higher than suggested. The cancel button also carries data-button, so Sonner 1.7.4's base [data-sonner-toast][data-styled='true'] [data-button] rule (0,3,0) - the reason both buttons currently render identically dark - would beat .notification-toast .notification-toast-cancel-button (0,2,0). The rule uses the same &:has() pattern as the layout overrides to sit at (0,4,0), order-independent of stylesheet injection.
• Which button gets which look is deterministic and now documented in the model TSDoc: clickCommand always renders as the emphasized primary button (Sonner's action slot), secondaryClickCommand always as the muted secondary one (Sonner's cancel slot) - styling follows the field, never ordering.
• Dark mode surfaced a gap while verifying this: the Toaster was hardcoded to Sonner's light theme, so in a dark-themed app the token-driven secondary button flipped to dark colors on a still-white toast and the hierarchy collapsed. Fixed in 4db3519 by subscribing the Toaster to the theme service's CurrentTheme (same pattern as user-profile-popover) - toasts and both buttons now follow the app theme, verified live in both themes including flipping the theme with a toast already open.

Light/dark screenshots of the new rendering to follow.

(AI-assisted, with my guidance)

[lyonsil]

@lyonsil reviewed 10 files and all commit messages, and resolved 10 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved.

[lyonsil]