feat(esign): signing UX decisions (2/2)

docs/esign/TRACKER.md

@@ -113,6 +113,8 @@ Legend: ☐ todo · ◐ in progress · ☑ done
 - ☑ Review round 1 (Sol 6.1): 15 findings (4 high), all fixed with regression tests; Postgres smoke script
   (`backend/scripts/esign-store-smoke.ts`) caught a jsonb double-encoding issue in the new queries.
 - ☑ Fallback: upload a PDF signed with the official app (verified as current version + one CIE signature).
+  Removed from the dashboard on 2026-10-21: CIE ID rewrites a PDF that has no signature yet, so it never worked for
+  the first signer. The backend's `esign.requests.uploadSigned` is no longer called and can be removed.
 - ☑ Smart placement (box under "Il Presidente"/role label), navigation badge for documents to sign.
 - ☑ Review round 2 (Sol 6.1, Personal account; its safety filter cut the final report, partial notes in
   `/tmp/esign-review-r2b/`): round-1 fixes confirmed; new findings fixed — ByteRange gap must be exactly /Contents,
@@ -127,16 +129,36 @@ Legend: ☐ todo · ◐ in progress · ☑ done
   sign its documents; default unchanged (auth#62 roles + catalog in the snapshot, auth-kit#2, backend, admin).
 - ☑ Signer picker lists every registered IdP user with `esign:sign` (filtered by the drives' sign rules), not only
   people who opened Signatures; their profile is created with the request (auth#63, backend#79, admin#113).
-- ☑ Sign it yourself: when the creator signs first (or is the only signer), the composer's "Create and sign" / "Sign
-  with CIE" creates the request and opens the agent in the same click; To sign has "Sign a document", which starts
-  with the creator as first signer (admin only).
+- ☑ Sign it yourself, inside New request: "Me" adds the creator in one click, and when the creator signs first (or is
+  the only signer) the primary, "Sign and send" / "Sign with CIE", creates the request and opens the agent in the same
+  click ("Send request" on a phone or tablet). The backend doesn't email the creator about a turn that starts as the
+  request is created. To sign's "Sign a document" and the composer's `?self=true` are gone (admin only).
+- ☑ Signature spots in New request: the labels in the PDF's text become rows to fill, each with a box near its label
+  in clear space (on the signature line when there is one, else under the label or above it), covering no text, no
+  label and no signature already on the page. Labels match whole and keep qualifiers apart, also wrapped over two
+  lines ("Vice Presidente" is never "Presidente"); several labels on a line, rotated pages, the first 40 and last 10
+  pages, and labels at the page bottom are handled. Field captions ("Presidente: Mario Rossi"), sentences ending on a
+  line of their own, labels without room to sign and labels already signed are not spots. Contracts without labels
+  keep the free picker, whose boxes share the foot of the last page in signing order (admin only, `places.ts`
+  tested).
+- ☑ Send again: New request takes `?from=<request id>` (any status, so "Duplicate" is one link) and fills in the
+  title, the signers in order with their roles, the order, the folder, the file name and the email. The PDF is the same
+  OneDrive item read again, so a corrected file saved over the original is picked up, and its spots are found again
+  (people keep the spot their role names, the others their places). An uploaded PDF, or a OneDrive file that can no
+  longer be opened (the composer says so), is the request's first version, before anyone signed, fetched and uploaded
+  again as a new document. A declined request whose PDF has the same sha256 as that version says "Same PDF as before.",
+  with "Check again" for a OneDrive file (admin only).
+- ☐ After a backend release, optional: reuse a version as a new request's document, so Send again of an uploaded PDF
+  doesn't take the bytes through the browser and opening it leaves no staged document behind.
 - ☐ 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".
+- ☑ Setup page: its inline links (the ArchWiki guide, OpenCIE) are underlined at rest with `inlineLink`, like the
+  request and batch pages.
 
 ## Manual steps for the maintainer (cannot be automated here)
 
@@ -157,6 +179,22 @@ Legend: ☐ todo · ◐ in progress · ☑ done
   - 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).
+- ☐ Before deploying Setup's "Download for macOS" / "Download for Windows" and the signing dialog's "Update
+  PoliNetwork eSign" state (agents too old to sign): make `releases/latest` carry `PoliNetwork-eSign-macos.dmg`,
+  `PoliNetwork-eSign-macos.zip` and `PoliNetwork-eSign-windows-amd64.zip`. Either publish the agent release built from
+  `feat/sign-page-decisions` (esign "publish the macOS and Windows downloads under fixed names"), tagged `vX.Y.Z` with
+  no suffix so it is not a pre-release, or, to deploy the dashboard first, upload copies of v0.3.0's
+  `PoliNetwork-eSign-v0.3.0-macos.dmg`, `-macos.zip` and `-windows-amd64.zip` under those names to the v0.3.0 release
+  and regenerate its SHA256SUMS. Then check that each name answers 200:
+  `curl -sL -o /dev/null -w '%{http_code}\n' https://github.com/PoliNetworkOrg/esign/releases/latest/download/<name>`.
+  Until then they answer 404, and these links, which open in the same tab (a real download leaves the page in place),
+  replace the dashboard, and the signing dialog with it, with GitHub's 404 page.
+- ☐ Deploy order of the decisions round (admin `feat/esign-ux-decisions`, backend `feat/esign-ux-decisions`, agent
+  `feat/sign-page-decisions`): release and deploy the backend before the dashboard. The dashboard's decline dialog
+  says "{creator} gets an email with your reason", which only the new backend sends ("Request update" emails); the
+  version gate works in any order (the backend lets an unknown User-Agent through, the old dashboard doesn't forward
+  it). The agent release (above) goes out before or with the dashboard; its `ready` and fatal messages need no
+  dashboard change to be safe, and older agents keep working through `seen`.
 
 ## Local end-to-end
 
@@ -171,11 +209,51 @@ Open `http://localhost:10431/dashboard/esign/requests` (use `localhost`, not `12
 
 ## Log
 
+- 2026-10-22: decisions round integrated (admin `feat/esign-ux-decisions`, backend `feat/esign-ux-decisions`, agent
+  `feat/sign-page-decisions`; not pushed). The 17 product decisions of the UX pass are decided and built:
+  - Admin: the signing chain below, plus New request rebuilt as a viewer and one column with the PDF's signature spots
+    as rows to fill (boxes beside a stack of labels too close for one between them), signing your own PDF inside New
+    request (`?self` and To sign's "Sign a document" gone), Send again (`?from=`), Setup per system with a direct
+    download and CIE ID pairing as the check, phones and tablets review only (no flash for an iPad, whose User-Agent is
+    a Mac's). The New request and batch hand-offs keep their dialog above the routes (`EsignSigningHost`), so the page
+    they land on loads under it: New request closes it once the new request's page has drawn the signed spot. The
+    proxy forwards the agent's User-Agent, also the pre-rename `PoliNetwork-Sign-Agent/…`.
+  - Backend: the version gate (426 `agent_outdated` when the job loads, below 0.2.0, the job failed and seen),
+    "Request update" emails to the creator (declined, completed by someone else, delivery failed, also to who can
+    retry), the signed document emailed to externals in Italian with Reply-To set to the requester.
+  - Agent: fixed asset names for the macOS and Windows downloads, CIE ID named everywhere, the version in the pages'
+    footer, `ready` and fatal messages to the dashboard, the update screen instead of the PIN form, the card before the
+    PIN (held while no card is detected, never when presence is unknown), the wrong-PIN count with a warning before the
+    last attempt and "show PIN", no text on where the PIN comes from.
+  - Kept on purpose, against the option's wording: the action card's batch link reads "Sign N together", N counting
+    this document and the others the batch opens with (at most ten, as To sign's button), because that is what one PIN
+    signs; "Sign the other N together" would undercount it.
+  - Release order: see the maintainer steps (backend before the dashboard; agent release or renamed v0.3.0 copies
+    before Setup's downloads).
+
+- 2026-10-21: decisions round, request and batch pages (admin `feat/esign-dec-signing`; not pushed): one action card
+  holds the title, the status, one sentence and the request's actions, and on desktop the right column stays put while
+  the cards under it scroll; "Move box" moved into the viewer's toolbar; phones and tablets only review; declined and
+  cancelled requests offer "Send again" (`/dashboard/esign/new?from=`, which the composer branch fills in); the upload
+  fallback is gone; the agent proxy forwards PoliNetwork eSign's User-Agent, so the backend can refuse versions too old
+  to sign. The signing dialog listens for the agent's `ready` and fatal errors (older agents through the job's `seen`),
+  says within 2.5 s when PoliNetwork eSign isn't running (Start for a browser that has run it, Install otherwise), asks
+  for an update with a direct download when the agent is too old, and hands off after signing: the page updates
+  behind it, then the agent window and the dialog close and the box dissolves into the stamp. The `ready` and fatal
+  messages need the next agent release; until then the dashboard follows `seen`. Copy kept on purpose: a missing
+  CIE ID module reads "CIE ID isn't set up on this computer" / "Follow the setup guide, then sign again.", as the
+  agent window says it, not "isn't installed" (CIE ID can be installed with its module out of reach, e.g. without
+  Rosetta); the lock line is one line ("Mario Rossi is signing right now."), so the card keeps its height; the To sign
+  and requests lists keep "Requested by {name}", the only place a row says who asks (removed from the request and
+  batch pages only).
+
 - 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).
+  impact confirmation before saving a sign rule. The open product decisions it listed
+  (`~/dev/polinetwork/esign-ux-decisions-2026-10-21.html`, outside the repo) were decided on 2026-10-21 and built in
+  the decisions round above.
 
 - 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.