@colixsystems/widget-sdk 0.218.0 → 0.219.1

package/README.md

@@ -32,7 +32,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. A sibling's input reads the payload, and a page action the author binds to the event (Run action, Navigate) runs with it — fired from one control, only that control runs it. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
-| **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
+| **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill a box of definite height: a widget in the section a fit-to-screen page stretches to the bottom of the screen, or one given a fixed slot height. Media-style widgets, and a chat or feed that scrolls its own content, switch to a `flex: 1` / `height: "100%"` layout and scroll inside it; others ignore it. Defaults `false`. |
 | **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. |
 | **CORE** | `isNarrowWidth(width)` | `boolean` | No context slice, no scope. True when a MEASURED width is below `NARROW_WIDTH_PX` (480) — the one threshold every widget switches at, so a page reflows together rather than raggedly. An unmeasured width (0) is NOT narrow, so nothing flashes through the narrow form on first paint. |
 | **CORE** | `widthTier(width)` | `"narrow" \| "medium" \| "wide"` | No context slice, no scope. Which of THREE layouts a measured width calls for: narrow below `NARROW_WIDTH_PX` (480), wide at or above `WIDE_WIDTH_PX` (960), medium between. `widthTier(w) === "narrow"` exactly when `isNarrowWidth(w)`; an unmeasured width (0) is "wide". |
@@ -83,7 +83,48 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.218.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.1` — 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.1
+
+**`useFill()` says when it is true today.** It described a page-grid tile with a "Fill tile height" choice, a layout that no longer exists. A host now fills a widget in two cases: the widget sits in the section a fit-to-screen page stretches to the bottom of the screen, or the widget has a fixed slot height. A chat or feed that scrolls its own content is one of the widgets that should honour it. A documentation correction; `CONTRACT.version` is unchanged.
+
+### 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
 

package/dist/contract.cjs

@@ -942,13 +942,14 @@ const HOOKS = [
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -1511,7 +1512,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 +1529,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 +1584,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 })",
@@ -3453,15 +3550,16 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },
@@ -3592,10 +3690,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 +5807,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

@@ -942,13 +942,14 @@ const HOOKS = [
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -1511,7 +1512,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 +1529,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 +1584,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 })",
@@ -3449,15 +3546,16 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },
@@ -3588,10 +3686,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 +5803,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,