@colixsystems/widget-sdk 0.215.0 → 0.219.0

package/README.md

@@ -83,7 +83,53 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.215.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.219.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.219.0 (contract 1.175.0)
+
+**Signing rounds — `useSigningRounds(fileIds)` and `useSigningRound(fileId)`.** A signing round is how a PDF gets signed by a fixed list of people. Each signer gets a place on the signature page, in the order they were listed; they may sign in any order. Someone who manages the file's folder prepares the document for the signers they pick, looks at the prepared document, and confirms it; from then on each signer signs once with BankID through `useFileSignature()`, and the round is complete when the last one has signed. While a round is being prepared or signed the file cannot be changed, and once it is complete its content cannot be replaced.
+
+| Hook | Returns | Use it for |
+| --- | --- | --- |
+| `useSigningRounds(fileIds)` | `{ byFileId, roundsEnabled, loading, error, refresh }` | A file list: what to show beside each file, in one request for the whole list. |
+| `useSigningRound(fileId)` | `{ round, loading, error, refresh, prepare, preparedFile, confirm, cancel, busy }` | One file: its round, and starting, confirming or cancelling it. |
+
+- `byFileId[fileId]` is `{ file_id, can_manage, can_prepare, round, locked }`. A file the user cannot see has no entry. `can_manage` says the user manages the file's folder; `can_prepare` says a round can be offered for it (a shared PDF with no round yet — preparing can still be refused once the document is read). `locked` is `"signing_round"` while the file cannot be changed and `"signed"` once its content cannot be replaced.
+- **Who sees what.** `round` is `{ id, status, signer_count, signed_count, my_place, can_sign }`. Someone who manages the folder gets it in every state (`DRAFT`, `OPEN`, `COMPLETED`), with `signed_count`. A signer gets it once it is confirmed, with their own place in `my_place` (`{ position, signed, signed_at }`) and `can_sign` while the round is open and their place is unsigned; `signed_count` is `null` for them, because a signer does not learn how many of the others have signed. Anyone else gets `round: null` and learns only `locked`.
+- **A workspace may not have signing rounds turned on.** `roundsEnabled` is then `false` (it is `null` until the first answer): offer no way to start a round. If `prepare()` is called anyway it is refused with code `SIGNING_ROUNDS_NOT_ENABLED`. Rounds that already exist keep working either way.
+- **Starting a round.** `prepare(signerIds)` takes user ids in the order their places should appear on the signature page — the people from `useFileRoster(fileId)` — and can take up to a minute. `preparedFile()` then returns `{ url, sha256, expires_at, size_bytes }`: a link, good for five minutes, to the document as the signers will see it. Show it, then call `confirm()`, which opens the round for exactly that document; called before `preparedFile()` it is refused with code `PREVIEW_REQUIRED`. `cancel()` ends a draft or an open round and unlocks the file.
+- **`can_prepare` and `roundsEnabled` answer different questions.** `can_prepare` is about the file and the user; `roundsEnabled` is about the workspace. Offer "prepare" only when both are true.
+- **One action at a time.** While `busy` is true, calling another action is refused at once with code `ACTION_IN_PROGRESS`; it is not queued. Disable your buttons on `busy`.
+- **What you see is always the current file's.** When `fileId` (or the set of ids, or the signed-in user) changes, the hooks return nothing of the previous one and `loading: true` until the new answer arrives. Ids are matched without regard to case. An answer that arrives late never overwrites a newer one.
+- **Refusals.** A refused action sets `error` and rejects with the same object: `code` and `message` come from the server (show `message` as it is), `errors` has one entry per refused signer — `{ app_user_id, message, reason, characters }`, where `reason` is `empty`, `too_long`, `unsupported_characters` or `mixed_scripts` when the signer's name cannot be shown on the signature page — and `retryAfter` is the number of seconds to wait when the server is busy. The hook's own refusals (`PREVIEW_REQUIRED`, `ACTION_IN_PROGRESS`, `NO_SIGNING_ROUND`) carry a `message` you can show the same way. When a refusal means the round is no longer what you were showing (it expired, was closed, or the document changed), the hook reads the round again by itself.
+
+```jsx
+const { byFileId, roundsEnabled } = useSigningRounds(files.map((f) => f.id));
+const { round, prepare, preparedFile, confirm, error, busy } = useSigningRound(file.id);
+
+const overview = byFileId[file.id];
+const canStart = roundsEnabled === true && overview && overview.can_prepare;
+
+async function start(signerIds) {
+  await prepare(signerIds);
+  const { url } = await preparedFile(); // show the document at `url`, then:
+  await confirm();
+}
+// error.errors.map((e) => `${e.app_user_id}: ${e.message}`)
+```
+
+**`useFileSignature` tells you more, and no longer guesses.** It also returns `hintCode` (where the order stands: `"sealing"` means the user has signed and the signature is being added to the document, so there is nothing to scan) and `nameRefusal` (`{ reason, characters }`, set when the order failed because the signer's name cannot be shown). `cancel()` now resolves to what became of the order instead of always reporting `cancelled`: when the user had already signed, `status` stays `pending` with `hintCode: "sealing"`, or is `complete` — keep polling with `refresh()`. An order that is picked up again keeps its `message`. `autoStartToken` is cleared once the user has signed or the order has ended, a late poll can no longer undo a cancel, and the order is forgotten when `fileId` changes.
+
+`index.d.ts` now declares `useFileSignature`, `useFileSignatures` and `useFileRoster`. Requires `@colixsystems/filestore-client@0.12.0`.
+
+### What's new in 0.218.0
+
+**Host helpers for the app logo's dark-bar variant.** An app can now carry a second logo for dark navigation bars, stored beside the app logo as `themeConfig.appLogoDarkAssetId` / `appLogoDarkUrl`. Two helpers on `@colixsystems/widget-sdk/host` decide which one a bar draws, and both hosts ask them, so the rail, the drawer, the app header and the site header pick the same logo in the web Player and in the exported app:
+
+- `isDarkSurface({ surface, backdrop, textColor, theme })` — `true` when the bar reads as dark. Pass the colour the bar paints as `surface`; a see-through `#RRGGBBAA` is composited over `backdrop`, or over the page in `theme`, first. A bar that paints nothing passes the `textColor` authored to sit on it instead: light text names a dark backdrop.
+- `resolveAppLogo(logo, darkSurfaceLogo, onDark)` — the logo to draw. The variant is used only beside an app logo; it never stands in for a missing one.
+
+These are host-integration helpers, not something a widget imports. Nothing changes for widget authors.
 
 ### What's new in 0.215.0 (contract 1.174.0)
 

package/dist/contract.cjs

@@ -1511,7 +1511,15 @@ const HOOKS = [
       "polls (fresh QR while pending — render with the Image primitive), " +
       "cancel() aborts, verify() returns the offline verdict. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
-      "state + verify() without re-signing. Reads " +
+      "state + verify() without re-signing. autoStartToken is set only while " +
+      "opening BankID can still help (null once the user has signed or the " +
+      "order has ended). hintCode says where the order " +
+      "stands; 'sealing' means the user has signed and the signature is being " +
+      "added to the document, so there is nothing to scan and it can no longer " +
+      "be cancelled. cancel() resolves to what became of the order, which is " +
+      "then still pending or already complete: read status after it, never " +
+      "assume 'cancelled'. nameRefusal is set when the order failed because " +
+      "the signer's name cannot be shown on the document. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -1520,12 +1528,15 @@ const HOOKS = [
       message: "string | null",
       signerName: "string | null",
       signedAt: "string | null",
+      hintCode: "string | null  // where the order stands, e.g. 'sealing'",
+      nameRefusal:
+        "{ reason: 'empty' | 'too_long' | 'unsupported_characters' | 'mixed_scripts', characters: string[] } | null",
       verdict: "{ valid, checks, content_status, signed_by_others_since, seal, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
-      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
+      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
       refresh: "() => Promise<void>",
-      cancel: "() => Promise<void>",
+      cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
     requiredContextSlice: ["filestore.signatures"],
@@ -1572,6 +1583,91 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useSigningRounds",
+    signature: "useSigningRounds(fileIds)",
+    description:
+      "What the signed-in user may know about the signing round of each file " +
+      "in a list, in one batched request. A signing round fixes a PDF and a " +
+      "list of signers: it is prepared and confirmed by someone who manages " +
+      "the file's folder, then each signer signs once with useFileSignature(), " +
+      "in any order (there are no turns; the list only orders the places on " +
+      "the signature page). byFileId maps a file id to { file_id, can_manage, " +
+      "can_prepare, round, locked }; a file the user cannot see is absent. " +
+      "round is null when there is none, and for a user who is neither a " +
+      "manager nor one of its signers; a signer sees it once it is confirmed, " +
+      "with their own place (my_place) and can_sign (the round is open and " +
+      "their place is unsigned), and signed_count is null " +
+      "for them. locked is 'signing_round' while the file cannot be changed, " +
+      "'signed' once its content cannot be replaced. roundsEnabled is false " +
+      "when the workspace cannot start signing rounds (offer no way to start " +
+      "one), and null until the first answer. can_prepare is about the file " +
+      "and the user, roundsEnabled is about the workspace: offer 'prepare' " +
+      "only when both are true. Ids are matched without regard to case. " +
+      "Refetches only when the set of ids or the signed-in user changes; " +
+      "until the new answer arrives loading is true and byFileId is empty. " +
+      "Reads ctx.filestore.signingRounds.overview.",
+    returnShape: {
+      byFileId:
+        "{ [fileId]: { file_id, can_manage: boolean, can_prepare: boolean, " +
+        "round: { id, status: 'DRAFT' | 'OPEN' | 'COMPLETED', signer_count, signed_count: number | null, " +
+        "my_place: { position, signed, signed_at } | null, can_sign: boolean } | null, " +
+        "locked: 'signing_round' | 'signed' | null } }",
+      roundsEnabled: "boolean | null",
+      loading: "boolean",
+      error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signingRounds"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useSigningRound",
+    signature: "useSigningRound(fileId)",
+    description:
+      "One file's current signing round, and the actions of someone who " +
+      "manages the file's folder. prepare(signerIds) drafts a round for those " +
+      "users, their places on the signature page in the order given (take the " +
+      "ids from useFileRoster()); it can take " +
+      "up to a minute. preparedFile() returns a five-minute link to the " +
+      "prepared document; show it to the user before confirming. confirm() " +
+      "opens the round for exactly the document preparedFile() last returned, " +
+      "and rejects with code PREVIEW_REQUIRED when it was not called first. " +
+      "cancel() ends a draft or an open round and resolves to the cancelled " +
+      "round (status 'CANCELLED'); round is then null. ONE ACTION RUNS AT A " +
+      "TIME: while busy is true any other action is refused at once with code " +
+      "ACTION_IN_PROGRESS (it is not queued), so disable your buttons on busy. " +
+      "round is the full round as the " +
+      "user may see it: a manager sees every signer's progress, a signer sees " +
+      "every signer's name and position and their own progress only, anyone " +
+      "else sees null. A refused action sets error and rejects with it: code " +
+      "and message come from the server (show message as it is), errors has " +
+      "one entry per refused signer ({ app_user_id, message, reason, " +
+      "characters }), retryAfter is the seconds to wait. The hook's own " +
+      "refusals (PREVIEW_REQUIRED, ACTION_IN_PROGRESS, NO_SIGNING_ROUND) carry " +
+      "a message that can be shown the same way. When a refusal means the " +
+      "round is no longer what was shown (it expired, was closed, or the " +
+      "document changed) the hook reads the round again by itself. Code " +
+      "SIGNING_ROUNDS_NOT_ENABLED means the workspace cannot start signing " +
+      "rounds; check roundsEnabled from useSigningRounds() before offering to " +
+      "start one. When fileId or the signed-in user changes, round is null " +
+      "and loading true until the new answer. Reads ctx.filestore.signingRounds.",
+    returnShape: {
+      round:
+        "{ id, file_id, status: 'DRAFT' | 'OPEN' | 'COMPLETED', created_at, confirmed_at, completed_at, expires_at, " +
+        "signers: { name, position, app_user_id?, signed?, signed_at?, signed_as? }[] } | null",
+      loading: "boolean",
+      error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
+      refresh: "() => Promise<void>",
+      prepare: "(signerIds: string[]) => Promise<round>  // status 'DRAFT'",
+      preparedFile: "() => Promise<{ url, sha256, expires_at, size_bytes }>",
+      confirm: "() => Promise<round>  // status 'OPEN'",
+      cancel: "() => Promise<round>  // the round it ended, status 'CANCELLED'",
+      busy: "boolean  // an action is running; another one is refused with ACTION_IN_PROGRESS",
+    },
+    requiredContextSlice: ["filestore.signingRounds"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFolderPermissions",
     signature: "useFolderPermissions(folderId, { enabled })",
@@ -3592,10 +3688,12 @@ const WIDGET_CONTEXT_SHAPE = {
       "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal / public spaces) + BankID file signing. " +
       "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), copy(id, body), remove(id), preview(id) }, " +
       "folders: { list, create, update, remove }, shares: { ... }, trash: { ... }, " +
-      "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
-      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+      "signatures: { list(fileIds), roster(fileId, query), initiate(fileId), status(id), cancel(id), verify(id) }, " +
+      "signingRounds: { overview(fileIds), list(fileId, query), get(roundId), prepare(fileId, signerIds), preparedFile(roundId), confirm(roundId, preparedSha256), cancel(roundId) }, " +
+      "objectUrl(token), fetchObject(token) }. " +
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature() + useFileSignatures() + useFileRoster() + useSigningRounds() + useSigningRound(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
-    fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object", signingRounds: "object" },
   },
   renderer: {
     description:
@@ -5707,7 +5805,12 @@ const CONTRACT = deepFreeze({
   //    binds no widget style fields: the component reads it on both hosts,
   //    which a scope now states as `sdkComponents`.
   //    Additive: an unthemed chip is the muted pill widgets drew by hand.
-  version: "1.174.0",
+  // 1.175.0: additive (sc-10410) — `useSigningRounds(fileIds)` and
+  //    `useSigningRound(fileId)` read and run PDF signing rounds through the
+  //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
+  //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
+  //    became of the order instead of always reporting "cancelled".
+  version: "1.175.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1511,7 +1511,15 @@ const HOOKS = [
       "polls (fresh QR while pending — render with the Image primitive), " +
       "cancel() aborts, verify() returns the offline verdict. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
-      "state + verify() without re-signing. Reads " +
+      "state + verify() without re-signing. autoStartToken is set only while " +
+      "opening BankID can still help (null once the user has signed or the " +
+      "order has ended). hintCode says where the order " +
+      "stands; 'sealing' means the user has signed and the signature is being " +
+      "added to the document, so there is nothing to scan and it can no longer " +
+      "be cancelled. cancel() resolves to what became of the order, which is " +
+      "then still pending or already complete: read status after it, never " +
+      "assume 'cancelled'. nameRefusal is set when the order failed because " +
+      "the signer's name cannot be shown on the document. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -1520,12 +1528,15 @@ const HOOKS = [
       message: "string | null",
       signerName: "string | null",
       signedAt: "string | null",
+      hintCode: "string | null  // where the order stands, e.g. 'sealing'",
+      nameRefusal:
+        "{ reason: 'empty' | 'too_long' | 'unsupported_characters' | 'mixed_scripts', characters: string[] } | null",
       verdict: "{ valid, checks, content_status, signed_by_others_since, seal, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
-      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
+      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
       refresh: "() => Promise<void>",
-      cancel: "() => Promise<void>",
+      cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
     requiredContextSlice: ["filestore.signatures"],
@@ -1572,6 +1583,91 @@ const HOOKS = [
     requiredContextSlice: ["filestore.signatures"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useSigningRounds",
+    signature: "useSigningRounds(fileIds)",
+    description:
+      "What the signed-in user may know about the signing round of each file " +
+      "in a list, in one batched request. A signing round fixes a PDF and a " +
+      "list of signers: it is prepared and confirmed by someone who manages " +
+      "the file's folder, then each signer signs once with useFileSignature(), " +
+      "in any order (there are no turns; the list only orders the places on " +
+      "the signature page). byFileId maps a file id to { file_id, can_manage, " +
+      "can_prepare, round, locked }; a file the user cannot see is absent. " +
+      "round is null when there is none, and for a user who is neither a " +
+      "manager nor one of its signers; a signer sees it once it is confirmed, " +
+      "with their own place (my_place) and can_sign (the round is open and " +
+      "their place is unsigned), and signed_count is null " +
+      "for them. locked is 'signing_round' while the file cannot be changed, " +
+      "'signed' once its content cannot be replaced. roundsEnabled is false " +
+      "when the workspace cannot start signing rounds (offer no way to start " +
+      "one), and null until the first answer. can_prepare is about the file " +
+      "and the user, roundsEnabled is about the workspace: offer 'prepare' " +
+      "only when both are true. Ids are matched without regard to case. " +
+      "Refetches only when the set of ids or the signed-in user changes; " +
+      "until the new answer arrives loading is true and byFileId is empty. " +
+      "Reads ctx.filestore.signingRounds.overview.",
+    returnShape: {
+      byFileId:
+        "{ [fileId]: { file_id, can_manage: boolean, can_prepare: boolean, " +
+        "round: { id, status: 'DRAFT' | 'OPEN' | 'COMPLETED', signer_count, signed_count: number | null, " +
+        "my_place: { position, signed, signed_at } | null, can_sign: boolean } | null, " +
+        "locked: 'signing_round' | 'signed' | null } }",
+      roundsEnabled: "boolean | null",
+      loading: "boolean",
+      error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
+      refresh: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signingRounds"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useSigningRound",
+    signature: "useSigningRound(fileId)",
+    description:
+      "One file's current signing round, and the actions of someone who " +
+      "manages the file's folder. prepare(signerIds) drafts a round for those " +
+      "users, their places on the signature page in the order given (take the " +
+      "ids from useFileRoster()); it can take " +
+      "up to a minute. preparedFile() returns a five-minute link to the " +
+      "prepared document; show it to the user before confirming. confirm() " +
+      "opens the round for exactly the document preparedFile() last returned, " +
+      "and rejects with code PREVIEW_REQUIRED when it was not called first. " +
+      "cancel() ends a draft or an open round and resolves to the cancelled " +
+      "round (status 'CANCELLED'); round is then null. ONE ACTION RUNS AT A " +
+      "TIME: while busy is true any other action is refused at once with code " +
+      "ACTION_IN_PROGRESS (it is not queued), so disable your buttons on busy. " +
+      "round is the full round as the " +
+      "user may see it: a manager sees every signer's progress, a signer sees " +
+      "every signer's name and position and their own progress only, anyone " +
+      "else sees null. A refused action sets error and rejects with it: code " +
+      "and message come from the server (show message as it is), errors has " +
+      "one entry per refused signer ({ app_user_id, message, reason, " +
+      "characters }), retryAfter is the seconds to wait. The hook's own " +
+      "refusals (PREVIEW_REQUIRED, ACTION_IN_PROGRESS, NO_SIGNING_ROUND) carry " +
+      "a message that can be shown the same way. When a refusal means the " +
+      "round is no longer what was shown (it expired, was closed, or the " +
+      "document changed) the hook reads the round again by itself. Code " +
+      "SIGNING_ROUNDS_NOT_ENABLED means the workspace cannot start signing " +
+      "rounds; check roundsEnabled from useSigningRounds() before offering to " +
+      "start one. When fileId or the signed-in user changes, round is null " +
+      "and loading true until the new answer. Reads ctx.filestore.signingRounds.",
+    returnShape: {
+      round:
+        "{ id, file_id, status: 'DRAFT' | 'OPEN' | 'COMPLETED', created_at, confirmed_at, completed_at, expires_at, " +
+        "signers: { name, position, app_user_id?, signed?, signed_at?, signed_as? }[] } | null",
+      loading: "boolean",
+      error: "PermissionError | null  // { code, message, retryable, errors, retryAfter }",
+      refresh: "() => Promise<void>",
+      prepare: "(signerIds: string[]) => Promise<round>  // status 'DRAFT'",
+      preparedFile: "() => Promise<{ url, sha256, expires_at, size_bytes }>",
+      confirm: "() => Promise<round>  // status 'OPEN'",
+      cancel: "() => Promise<round>  // the round it ended, status 'CANCELLED'",
+      busy: "boolean  // an action is running; another one is refused with ACTION_IN_PROGRESS",
+    },
+    requiredContextSlice: ["filestore.signingRounds"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFolderPermissions",
     signature: "useFolderPermissions(folderId, { enabled })",
@@ -3588,10 +3684,12 @@ const WIDGET_CONTEXT_SHAPE = {
       "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal / public spaces) + BankID file signing. " +
       "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(id, body), copy(id, body), remove(id), preview(id) }, " +
       "folders: { list, create, update, remove }, shares: { ... }, trash: { ... }, " +
-      "signatures: { initiate(fileId), status(id), cancel(id), verify(id) }, objectUrl(token), fetchObject(token) }. " +
-      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+      "signatures: { list(fileIds), roster(fileId, query), initiate(fileId), status(id), cancel(id), verify(id) }, " +
+      "signingRounds: { overview(fileIds), list(fileId, query), get(roundId), prepare(fileId, signerIds), preparedFile(roundId), confirm(roundId, preparedSha256), cancel(roundId) }, " +
+      "objectUrl(token), fetchObject(token) }. " +
+      "Backs useFilestoreFiles() + useFilestoreFolders() + useFilestoreCreateFolder() + useFilestoreCopy() + useFileSignature() + useFileSignatures() + useFileRoster() + useSigningRounds() + useSigningRound(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
     required: false,
-    fields: { files: "object", folders: "object", shares: "object", signatures: "object" },
+    fields: { files: "object", folders: "object", shares: "object", signatures: "object", signingRounds: "object" },
   },
   renderer: {
     description:
@@ -5703,7 +5801,12 @@ const CONTRACT = deepFreeze({
   //    binds no widget style fields: the component reads it on both hosts,
   //    which a scope now states as `sdkComponents`.
   //    Additive: an unthemed chip is the muted pill widgets drew by hand.
-  version: "1.174.0",
+  // 1.175.0: additive (sc-10410) — `useSigningRounds(fileIds)` and
+  //    `useSigningRound(fileId)` read and run PDF signing rounds through the
+  //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
+  //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
+  //    became of the order instead of always reporting "cancelled".
+  version: "1.175.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3775,7 +3775,7 @@ export class PermissionError extends Error {
   }
 }
 
-function toPermissionError(err) {
+export function toPermissionError(err) {
   // See the note in toDatastoreError — a client rejection is read from the
   // envelope below rather than matching this instanceof.
   if (err instanceof PermissionError) return err;
@@ -5172,149 +5172,6 @@ export function useFilestoreDelete() {
   return { remove, removing, error };
 }
 
-/**
- * Drive a BankID signing flow for one Filestore file. Returns
- * `{ status, qr, autoStartToken, message, signerName, signedAt, verdict,
- * loading, error, initiate, refresh, cancel, verify }`.
- *
- * `initiate()` opens a sign order against the file (the backend hashes its
- * bytes SERVER-SIDE and binds the digest into the BankID signature); `refresh()`
- * polls the order (surfacing a fresh animated-QR frame while pending — render
- * it with the `Image` primitive); `cancel()` aborts it; `verify()` re-runs the
- * offline verification and returns the verdict (`{ valid, content_status, … }`).
- * Reads `ctx.filestore.signatures.{initiate,status,cancel,verify}`. When
- * `fileId` is null/empty the hook collapses to a no-op.
- *
- * Pass `existingSignatureId` for a file that is ALREADY signed: the hook seeds
- * that order id (status `complete`) so the widget can show the signed state and
- * `verify()` it WITHOUT opening a new order — re-signing then requires an
- * explicit `initiate()`.
- */
-export function useFileSignature(fileId, existingSignatureId = null) {
-  const ctx = useWidgetContextOrThrow("useFileSignature");
-  if (!ctx.filestore || !ctx.filestore.signatures) {
-    throw new Error(
-      "useFileSignature: host did not inject a filestore client (ctx.filestore.signatures)",
-    );
-  }
-  const ready = Boolean(fileId);
-  const sigRef = useRef(ctx.filestore.signatures);
-  sigRef.current = ctx.filestore.signatures;
-  const fileIdRef = useRef(fileId);
-  fileIdRef.current = fileId;
-  // Seed the order from an already-completed signature so verify() works
-  // without initiating; initiate() (an explicit re-sign) overwrites it.
-  const orderRef = useRef(existingSignatureId || null);
-
-  const [status, setStatus] = useState(existingSignatureId ? "complete" : null);
-  const [qr, setQr] = useState(null);
-  const [autoStartToken, setAutoStartToken] = useState(null);
-  const [message, setMessage] = useState(null);
-  const [signerName, setSignerName] = useState(null);
-  const [signedAt, setSignedAt] = useState(null);
-  const [verdict, setVerdict] = useState(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-
-  const initiate = useCallback(async () => {
-    if (!fileIdRef.current) return null;
-    setLoading(true);
-    setError(null);
-    setVerdict(null);
-    try {
-      const res = await sigRef.current.initiate(fileIdRef.current);
-      orderRef.current = res && res.signature_id ? res.signature_id : null;
-      setStatus(res && res.status ? res.status : "pending");
-      setQr(res && res.qr ? res.qr : null);
-      setAutoStartToken(res && res.auto_start_token ? res.auto_start_token : null);
-      setSignerName(null);
-      setSignedAt(null);
-      setMessage(null);
-      setLoading(false);
-      return res;
-    } catch (err) {
-      setError(toPermissionError(err));
-      setLoading(false);
-      throw toPermissionError(err);
-    }
-  }, []);
-
-  const refresh = useCallback(async () => {
-    const id = orderRef.current;
-    if (!id) return;
-    try {
-      const res = await sigRef.current.status(id);
-      if (res) {
-        if (res.status != null) setStatus(res.status);
-        if (res.qr !== undefined) setQr(res.qr || null);
-        if (res.message !== undefined) setMessage(res.message || null);
-        if (res.signer_name !== undefined) setSignerName(res.signer_name || null);
-        if (res.signed_at !== undefined) setSignedAt(res.signed_at || null);
-      }
-    } catch (err) {
-      setError(toPermissionError(err));
-    }
-  }, []);
-
-  const cancel = useCallback(async () => {
-    const id = orderRef.current;
-    if (!id) return;
-    try {
-      await sigRef.current.cancel(id);
-      setStatus("cancelled");
-      setQr(null);
-    } catch (err) {
-      throw toPermissionError(err);
-    }
-  }, []);
-
-  const verify = useCallback(async () => {
-    const id = orderRef.current;
-    if (!id) return null;
-    try {
-      const v = await sigRef.current.verify(id);
-      setVerdict(v);
-      return v;
-    } catch (err) {
-      setError(toPermissionError(err));
-      throw toPermissionError(err);
-    }
-  }, []);
-
-  if (!ready) {
-    return {
-      status: null,
-      qr: null,
-      autoStartToken: null,
-      message: null,
-      signerName: null,
-      signedAt: null,
-      verdict: null,
-      loading: false,
-      error: null,
-      initiate: async () => null,
-      refresh: async () => undefined,
-      cancel: async () => undefined,
-      verify: async () => null,
-    };
-  }
-  return {
-    status,
-    qr,
-    autoStartToken,
-    message,
-    signerName,
-    signedAt,
-    verdict,
-    loading,
-    error,
-    initiate,
-    refresh,
-    cancel,
-    verify,
-  };
-}
-
 /**
  * Batch "is this file signed?" lookup for a set of file ids. Returns
  * `{ signaturesByFileId, loading, error, refetch }` where `signaturesByFileId`

package/dist/host.d.ts

@@ -397,6 +397,25 @@ export interface TopBarTokens {
  */
 export function resolveTopBarTokens(theme: unknown): TopBarTokens;
 
+/**
+ * Whether a chrome surface reads as dark. Pass the colour the bar paints
+ * (`#RRGGBBAA` is composited over `backdrop`, else over the page in `theme`),
+ * or, for a bar that paints nothing, the colour of the text authored to sit on it.
+ */
+export function isDarkSurface(input?: {
+  surface?: string | null;
+  backdrop?: string | null;
+  textColor?: string | null;
+  theme?: unknown;
+} | null): boolean;
+
+/** The logo a surface draws: the dark-surface variant only beside an app logo. */
+export function resolveAppLogo<T>(
+  logo: T | null | undefined,
+  darkSurfaceLogo: T | null | undefined,
+  onDark: boolean,
+): T | null;
+
 /** sc-8023 — the arrangeable contents of the sidebar layout's TOP STRIPE: the
  *  row across the top of the content, outside the panel and above it. */
 export type TopStripeSlot = "back" | "menu" | "brand" | "notifications";

package/dist/host.js

@@ -110,6 +110,8 @@ export {
   resolveSidebarUnfold,
   resolveLocalNavModel,
   drawsLocalNavAnywhere,
+  isDarkSurface,
+  resolveAppLogo,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal