fix(esign): signing UX pass (1/2)

docs/design.md

@@ -180,7 +180,8 @@ the selected range and a TanStack Charts line (3M per day, 1Y per week, All per
 grid, month labels, a dashed hover guide and a tooltip with the date, total and growth), and Telegram groups, Open
 reports and Active grants as links on its right (a row under it on mobile, numbers on one baseline, labelled "Groups" rather than "Telegram groups", and without the "To
 review" flag); then "Areas": one card per service whose whole surface leads where the rail icon does, with each section
-as a 44px button (two per row on mobile).
+as a 44px button (two per row on mobile). Reports › Open and Signatures › To sign carry the same accent count pill as the
+panel, from the shell's pending counts; nothing at zero or on a failed load.
 
 **States.** While a route loads, its `pendingComponent` renders `PageBar`, `PageContent` and the template's skeleton
 (`TableSkeleton`, `CardsSkeleton`, `RecordSkeleton`, `SettingsListSkeleton`, labelled "Loading {things}…"), so nothing
@@ -440,13 +441,22 @@ Rules that the templates above don't imply.
   their own icon. The rail and bottom nav show a dot on Reports while any report is open.
 - **Signatures**: the request page puts the PDF viewer (pdf.js, so every browser renders the same) beside the
   signers, delivery and activity cards; the signer's box is blue and draggable, other pending signers' boxes are dashed.
+  Until their first signature, the signer's card (and "Before you sign" in a batch) offers "Move to another spot", one
+  button per place when there are several ("Signature · p. 2"). It works like the composer's: the next click on any
+  page puts the box there, the viewer's toolbar says so in place of the page counter, and Esc or Cancel stops it.
+  The viewer jumps to a box without scrolling smoothly, and zooming keeps the middle of the view in place.
   Signature boxes use the light palette in both themes, because they sit on white paper. "Sign with CIE" opens the
-  PoliNetwork eSign's own page in a popup: the PIN is typed there, never in the dashboard. A person appears once
+  PoliNetwork eSign's own page in a popup: the PIN is typed there, never in the dashboard. When that window was closed
+  or PoliNetwork eSign doesn't answer, the dialog's footer primary is "Open the window again" beside "Cancel
+  signature" ("Stop here" once part of a batch is signed), and "Start PoliNetwork eSign" (outline) and "Setup guide" (ghost) sit in the body. A person appears once
   however many places they sign: their places are buttons under their name ("Signature · p. 2", "Mark · p. 1") whose
   menu switches the kind, moves or removes the place and rings its box on the page; marks have a dashed border.
   With several documents waiting, "Sign N together" opens a strip of the documents in the page bar's toolbar row: each
   is checked by opening it (a check replaces its number), can be left out, and the primary action stays "Next
   document" until all are checked, then becomes "Sign N documents" (one agent window, one PIN).
+  The requests list names whom an in-progress request waits on ("Waiting for X"); To sign has no Status column (every
+  row is the viewer's turn); `?status=` keeps the status segment across Back. The request page shows when each signer
+  whose turn it is was emailed, or why they weren't.
   Signatures › Drives (`esign:drives:manage`) has a card per drive with two rules, "Request signatures" and "Be asked
   to sign": chips for roles (people icon) and permissions (key icon), an inline picker listing both, a "Default: …"
   line while empty, and Save/Discard per drive. Unknown keys show as warning chips. On a new request, signers who may

docs/esign/TRACKER.md

@@ -133,6 +133,10 @@ Legend: ☐ todo · ◐ in progress · ☑ done
 - ☐ Create the IdP permission `esign:drives:manage` and grant it to whoever sets drive access (master admins get it).
 - ☐ Real-card check that one PIN can make several signatures in a session (`cie-mw`, `opencie`, built-in `cie`).
 - ☐ Docs: user guide (install agent, pair CIE), ops (Graph permissions, IdP permissions, env).
+- ☐ Setup step 4 (`src/features/esign/setup-page.tsx`) says the status page "should show that PoliNetwork eSign is
+  running and ready to sign", which fits both v0.3.0 ("The agent is running") and the readiness status page of the next
+  agent release ("Ready to sign" once reader, card and software check out). Once that release is out, the step can
+  quote "Ready to sign".
 
 ## Manual steps for the maintainer (cannot be automated here)
 
@@ -148,8 +152,10 @@ Legend: ☐ todo · ◐ in progress · ☑ done
 - ☐ Code signing (pipeline ready, esign PR #4; steps in esign `docs/code-signing.md`):
   - macOS: upload `~/dev/polinetwork/.signing/esign/developer-id.csr` as a Developer ID Application certificate on
     the PoliNetwork APS Apple account (team 842636PS9J), create an App Store Connect API key, run
-    `scripts/setup-macos-signing.sh secrets …`, tag a release.
-  - Windows: apply to SignPath Foundation (free for open source), then set the SIGNPATH_* variables and token.
+    `scripts/setup-macos-signing.sh secrets …`, tag a release, then drop the Open Anyway sentence from
+    AGENT_STEPS.macos in src/features/esign/setup-page.tsx.
+  - Windows: apply to SignPath Foundation (free for open source), then set the SIGNPATH_* variables and token, then
+    drop the Run anyway sentence from AGENT_STEPS.windows.
 - ☑ Backend released as @polinetwork/backend 1.7.0 (backend#73 merged); admin uses it (vendored copy removed).
 
 ## Local end-to-end
@@ -165,6 +171,12 @@ Open `http://localhost:10431/dashboard/esign/requests` (use `localhost`, not `12
 
 ## Log
 
+- 2026-10-21: UX pass (admin `feat/esign-ux-pass`, backend `fix/esign-ux`, agent `fix/sign-page-ux`; not pushed): the
+  signing dialog says how an attempt ended and notices a closed or silent eSign window, jobs and agent windows end on
+  errors a retry can't fix, plus composer, request, batch, setup and Overview polish. Admin follow-ups after the backend
+  release: the lock alert's "by HH:MM" from `signingNow.until`; `lostAccess` on the signer card and the drive-access
+  impact confirmation before saving a sign rule. Open product decisions: `~/dev/polinetwork/esign-ux-decisions-2026-10-21.html` (outside the repo).
+
 - 2026-10-17: merged backend#75 (released @polinetwork/backend 1.9.0), sign-agent#6 (released PoliNetwork eSign
   v0.2.0) and admin#105; the upload fallback warns signers with several places. Flux rolls out the new images.
 

docs/esign/contracts.md

@@ -42,6 +42,18 @@ Listens on `127.0.0.1:47321` only. Every request: `Host` must be `127.0.0.1:4732
 
 Allowed origins: `https://admin.polinetwork.org` by default, `http://localhost:*` with `--dev`, or the config file.
 
+The signing page tells its opener what happened with `postMessage({type: "pn-esign", status, detail?}, origin)`, to the
+dashboard's origin only: `status` is `completed`, `error` or `cancelled`, `detail` the agent error code, or
+`agent_unreachable` when the page can no longer reach the agent behind it. The dashboard polls `esign.jobs.statuses`
+again on every message and acts on a message itself only for `agent_unreachable`, because the agent can't report its own
+death to the backend. Only the next agent release (after v0.3.0) posts `agent_unreachable`: with v0.3.0 and older the
+dashboard doesn't learn that the agent stopped. Agents up to v0.1.x post type `pn-sign-agent`.
+
+The dashboard notices a closed agent window by reading `popup.closed` on every poll. That works only while the two
+windows keep their opener relationship, so neither the dashboard nor the agent page may send a
+`Cross-Origin-Opener-Policy` header: `same-origin` on either side cuts the link, the dashboard then reads the window as
+closed at once, and the page's `window.opener` is gone, so its messages stop too.
+
 Providers (tried in order, first with a card present; never falls back once a PIN reached a module or card —
 `token.Error.PINSent`):
 
@@ -63,7 +75,24 @@ Agent → backend (through the dashboard origin, `{origin}/api/esign/agent/…`,
 | `POST /api/esign/agent/jobs/{ticket}/fail`     | `{code, message?}`                                   | `{status}` — records cancellations / card errors for the dashboard                                                                                   |
 
 Errors: `{error: {code, message}}` with codes `ticket_invalid` (404), `job_expired` (410), `job_done` (409),
-`document_changed` (409), `certificate_invalid` (422), `signer_mismatch` (403), `signature_invalid` (422).
+`job_cancelled` (409: the message names who cancelled or declined the request, else "This signature was cancelled."),
+`job_failed` (409: the message of the error that ended the job), `document_changed` (409), `certificate_invalid` (422),
+`signer_mismatch` (403), `signature_invalid` (422).
+
+The agent, the backend and the dashboard agree on which errors are terminal. A terminal error ends the job: the backend
+moves it to `failed` with the code, whether the agent reported it through `/fail` or the backend raised it itself, and
+the agent shows it without a PIN form. Any other code, an unknown one included, leaves the job open in the backend. A
+retryable error returns to the PIN form in the same agent window. Any other per-document error ends the agent window
+while the backend keeps the job open; once the signer closes that window, the dashboard offers to open it again.
+
+- Terminal, reported by the agent: `pin_locked`, `card_untrusted`, `middleware_missing`, `not_paired`,
+  `certificate_not_found`.
+- Terminal, raised by the backend: `signer_mismatch`, `certificate_invalid`, `signature_invalid`, `document_changed`,
+  `pdf_invalid`, `job_done`, `agent_outdated`.
+- Retryable, back to the PIN form: `pin_incorrect`, `pin_invalid`, `pin_required`, `no_card`, `no_reader`,
+  `card_removed`, `card_unsupported`, `device_error`, `busy`, `backend_unreachable`.
+
+`/fail` on a job that already failed changes nothing and answers `{status: "failed"}`.
 
 ## Backend tRPC (`esign.*`)
 
@@ -80,17 +109,31 @@ browse OneDrive). Requests are visible to their signers and creator.
 - `esign.requests.create({title, documentId, signers: [{sub, role, places: [{...placement, kind}]}], ordered, output: {driveId, folderId, fileName}, email?: {to[], message?}})`.
   `kind` is `signature` (its own PDF signature) or `mark` (the first signature's mark, drawn in that signature's
   update); each signer has 1–20 places, at least one a signature, and appears once in the request.
-- `esign.requests.list({scope: "inbox"|"mine"|"all", status?})`, `esign.requests.get({id})`.
+- `esign.requests.list({scope: "inbox"|"mine"|"all", status?})` → request views. Each of a view's `signers[]` has
+  `lostAccess`: for a pending signer who may no longer sign the documents of one of the request's drives (its "sign"
+  rule changed, or the IdP took a role away), that drive's label; else null. `myTurn` is true when it is the caller's
+  turn and the caller's `lostAccess` is null (`turn` still lists every signer whose turn it is). `inbox` holds the
+  requests where `myTurn` is true, so a request the caller can no longer sign stays reachable under `mine`.
+- `esign.requests.get({id})` → `{request, events, versions, currentDocumentId, signingNow}`. `signingNow` is
+  `{sub, name, until}` while a signer has a signature open, `until` being when it expires at the latest; else null.
 - `esign.requests.cancel({id})`, `esign.requests.decline({id, reason})`, `esign.requests.retryDelivery({id})`.
 - `esign.drive.access()` (`esign:drives:manage`) → `{drives: [{id, label, request: {roles, permissions}, sign: {roles,
 permissions}, updatedBySub, updatedAt}], catalog: {roles: [{key, name}], permissions: [{key, name}]}}`;
   `esign.drive.setAccess({driveId, request, sign})`. A rule names roles and permissions, any of which grants it; an
   empty rule keeps the default (request: `esign:requests:manage`; sign: everyone who signs). `request` covers browsing
   the drive, using it in a request and seeing its requests; `sign` covers being chosen as signer and signing. Requests
   record `drives` (source and output); `esign.config().drives` and `esign.signers.list()[].drives` are filtered.
+  `esign.drive.accessImpact({driveId, sign})` (`esign:drives:manage`) → `[{id, title, signers: [name]}]`: the requests
+  in progress on that drive with pending signers who may sign under the current rule but not under the proposed `sign`
+  rule (the same empty-rule default); empty when the change strands nobody.
 - `esign.jobs.create({items: [{requestId, places?}]})` (1–10, all or none) → `[{requestId, jobId, ticket, expiresAt}]`,
   opened together in one agent window; `places` moves the caller's boxes (one position per place) before signing.
-  `esign.jobs.statuses({jobIds})`, `esign.jobs.cancel({jobIds})`.
+- `esign.jobs.statuses({jobIds})` → one entry per job:
+  `{jobId, requestId, status, errorCode, errorMessage, expiresAt, seen, signaturesLeft}`. `status` is `pending`,
+  `prepared`, `completed`, `failed` (a terminal error, its code in `errorCode`), `cancelled` or `expired`. A job
+  cancelled because its request was cancelled or declined has `errorCode` `request_cancelled` or `request_declined`,
+  and an `errorMessage` naming who did it (with the reason of a decline).
+- `esign.jobs.cancel({jobIds})`.
 
 Placement: `{page (0-based), x, y, width, height}` as fractions of the displayed page (crop box after rotation),
 origin top-left.

src/components/primitives/combobox.tsx

@@ -1,3 +1,4 @@
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete"
 import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox"
 import { ChevronDown } from "lucide-react"
 import type * as React from "react"
@@ -20,24 +21,38 @@ type ComboboxInputProps = ComboboxPrimitive.Input.Props & {
   listLabel: string
 }
 
-/** Combobox input: 36px field with a chevron trigger named after the list. */
+/**
+ * Combobox input: 36px field with a chevron trigger named after the list. The field draws the input's focus ring and
+ * anchors the list; the chevron is out of the Tab order, since the arrow keys open the list too.
+ */
 export function ComboboxInput({ listLabel, disabled = false, className, ...props }: ComboboxInputProps) {
   return (
-    <InputGroup className={cn("h-9 w-full rounded-(--pn-r-3)", fieldControl, className)}>
-      <ComboboxPrimitive.Input render={<InputGroupInput disabled={disabled} />} {...props} />
+    <ComboboxPrimitive.InputGroup
+      render={
+        <InputGroup
+          className={cn(
+            "h-9 w-full rounded-(--pn-r-3) has-[[data-slot=input-group-control]:focus-visible]:ring-(--pn-focus)/25",
+            fieldControl,
+            className
+          )}
+        />
+      }
+    >
+      <ComboboxPrimitive.Input render={<InputGroupInput disabled={disabled} data-focus-ring="none" />} {...props} />
       <InputGroupAddon align="inline-end">
         <InputGroupButton
           size="icon-sm"
           variant="ghost"
           render={<ComboboxPrimitive.Trigger />}
           disabled={disabled}
+          tabIndex={-1}
           aria-label={`Show ${listLabel}`}
           className="data-pressed:bg-transparent"
         >
           <ChevronDown aria-hidden className="pointer-events-none size-4 text-(--pn-fg-muted)" />
         </InputGroupButton>
       </InputGroupAddon>
-    </InputGroup>
+    </ComboboxPrimitive.InputGroup>
   )
 }
 
@@ -46,12 +61,12 @@ export function ComboboxContent({ className, ...props }: React.ComponentProps<ty
   return <UiComboboxContent className={cn(raisedSurface, floatingMotion, "rounded-(--pn-r-4)", className)} {...props} />
 }
 
-/** 36px, 13px item highlighted on `--pn-muted`; selected check on the right. */
+/** 36px, 13px item highlighted on `--pn-hover` (pointer or arrow keys); selected check on the right. */
 export function ComboboxItem({ className, ...props }: React.ComponentProps<typeof UiComboboxItem>) {
   return (
     <UiComboboxItem
       className={cn(
-        "min-h-9 rounded-(--pn-r-2) text-[13px] text-(--pn-fg) data-highlighted:bg-(--pn-muted) data-highlighted:text-(--pn-fg)",
+        "min-h-9 rounded-(--pn-r-2) text-[13px] text-(--pn-fg) data-highlighted:bg-(--pn-hover) data-highlighted:text-(--pn-fg)",
         className
       )}
       {...props}
@@ -64,4 +79,10 @@ export function ComboboxEmpty({ className, ...props }: React.ComponentProps<type
   return <UiComboboxEmpty className={cn("py-3 text-[13px] text-(--pn-fg-muted) empty:hidden", className)} {...props} />
 }
 
-export { Combobox, ComboboxList }
+/**
+ * `Combobox` picks one of a fixed set of items; `Autocomplete` is free text with suggestions. Both take the same
+ * input, content, list, item and empty parts.
+ */
+const Autocomplete = AutocompletePrimitive.Root
+
+export { Autocomplete, Combobox, ComboboxList }

src/components/primitives/index.ts

@@ -2,7 +2,15 @@ export { AvatarGroup, initialsOf, type AvatarPerson } from "./avatar-group"
 export { Chip } from "./chip"
 export { ChipOverflow } from "./chip-overflow"
 export { ColorSwatchSelect } from "./color-swatch-select"
-export { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from "./combobox"
+export {
+  Autocomplete,
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+} from "./combobox"
 export { ConfirmDialog, dialogFooter, dialogFooterButton, dialogPanel } from "./confirm-dialog"
 export { CountBadge } from "./count-badge"
 export { DataTable, RowActions, type DataTableColumn, type DataTableError, type TableSort } from "./data-table"

src/components/shell/index.ts

@@ -10,6 +10,7 @@ export {
   type PendingCounts,
   type Section,
   sectionFor,
+  sectionPending,
   type Service,
   serviceById,
   type ServiceId,
@@ -33,6 +34,7 @@ export {
   useInShell,
   useShellFrame,
 } from "./page-bar"
+export { PendingCount } from "./panel"
 export { ServiceGlyph } from "./service-glyph"
 export { DashboardShell, type DashboardShellProps } from "./shell"
 export { type Theme, themeToggleLabel, useTheme } from "./theme"

src/components/shell/panel.tsx

@@ -1,6 +1,7 @@
 import { Link } from "@tanstack/react-router"
 import { type KeyboardEvent, Suspense, use, useDeferredValue, useLayoutEffect, useRef } from "react"
 
+import { formatNumber } from "@/lib/format"
 import { cn } from "@/lib/utils"
 
 import {
@@ -24,14 +25,14 @@ const itemActiveClass = "bg-(--pn-nav-active) text-(--pn-fg) hover:bg-(--pn-nav-
 const itemCurrentClass =
   "before:absolute before:inset-y-2.5 before:-left-3 before:w-[3px] before:rounded-r-[3px] before:bg-(--pn-accent-solid)"
 
-/** Pending reports as a small accent pill next to Reports › Open; zero (or a failed load) renders nothing. */
-function PendingReportsCount({ count: countPromise }: { count: Promise<number | null> }) {
+/** Pending items (open reports, documents to sign) as a small accent pill; zero, loading or a failed load renders nothing. */
+export function PendingCount({ count: countPromise }: { count: Promise<number | null> }) {
   const count = use(useDeferredValue(countPromise))
   if (!count) return null
   return (
     <span className="ml-auto rounded-full bg-(--pn-accent-soft) px-1.75 font-mono text-[11px] leading-4.5 font-medium text-(--pn-accent) tabular-nums">
       <span className="sr-only">, </span>
-      {count}
+      {formatNumber(count)}
       <span className="sr-only"> pending</span>
     </span>
   )
@@ -96,7 +97,7 @@ export function SectionItems({ service, match, pending, variant = "panel" }: Sec
         />
         <span className="truncate">{section.title}</span>
         <Suspense fallback={null}>
-          <PendingReportsCount count={sectionPending(service.id, section.id, pending)} />
+          <PendingCount count={sectionPending(service.id, section.id, pending)} />
         </Suspense>
       </Link>
     )