@colixsystems/widget-sdk 0.241.0 → 0.243.0

package/README.md

@@ -84,7 +84,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.241.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.243.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.243.0 (contract 1.197.0)
+
+**`bankIdAppUrl(autoStartToken)` opens BankID on this device** (from 0.243.0). The link a signing or identification widget opens from its "Open BankID on this device" button: `Linking.openURL(bankIdAppUrl(autoStartToken))`. It is the same link the built-in Files and Identification widgets and the signing page use. For BankID on another device, show the order's `qr` with `<Image>`.
+
+`useFileSignature` does not poll by itself: while `status` is `"pending"`, call `refresh()` every 2 seconds, and render each answer's `qr`. It signs a file of any type in a shared space; outside a signing round the signature is kept beside the file, and in a round the signature is added to the PDF, which is then sealed. A `verify()` verdict reads as: `valid` (the BankID signature), `content_status` (`unchanged`, `changed` or `unavailable`), `signed_by_others_since` (later signatures in a round) and `seal.status` (`valid`, `invalid`, `certificate_revoked`, `unavailable`, or `not_applicable` for a signature kept beside the file). `useFileSignatures` is described as what it is: the signed-in user's own signatures.
+
+```jsx
+import { Button, Image, Linking, bankIdAppUrl, useFileSignature } from "@colixsystems/widget-sdk";
+
+const { status, qr, autoStartToken, initiate, refresh } = useFileSignature(fileId);
+useEffect(() => {
+  if (status !== "pending") return undefined;
+  const timer = setInterval(refresh, 2000);
+  return () => clearInterval(timer);
+}, [status, refresh]);
+// bankIdAppUrl exists from 0.243.0; a widget that must load on an older SDK
+// reads it as sdk.bankIdAppUrl from `import * as sdk` and builds the same link itself.
+// autoStartToken && <Button title="Open BankID on this device" onPress={() => Linking.openURL(bankIdAppUrl(autoStartToken))} />
+// qr && <Image source={{ uri: qr }} style={{ width: 200, height: 200 }} />
+```
 
 ### What's new in 0.241.0 (contract 1.195.0)
 

package/dist/bankid-app.js

@@ -0,0 +1,6 @@
+// The one BankID app launch link: widgets, the Player's login and the signing
+// page. Imports nothing, so every host and the exported app share it as it is.
+
+/** The URL that opens the BankID app on this device for the order of `autoStartToken`. */
+export const bankIdAppUrl = (autoStartToken) =>
+  `bankid:///?autostarttoken=${encodeURIComponent(autoStartToken)}&redirect=null`;

package/dist/contract.cjs

@@ -1624,10 +1624,30 @@ const HOOKS = [
     signature: "useFileSignature(fileId, existingSignatureId)",
     optionalArgs: ["existingSignatureId"],
     description:
-      "Drive a BankID signing flow for one Filestore file. initiate() opens a " +
-      "sign order (the backend hashes the bytes + binds the digest), refresh() " +
-      "polls (fresh QR while pending — render with the Image primitive), " +
-      "cancel() aborts, verify() returns the offline verdict. Pass " +
+      "Drive a BankID signing flow for one Filestore file of ANY type in a " +
+      "shared (project or public) space; a personal file is refused with " +
+      "NOT_SIGNABLE. Outside a signing round the signature is kept beside " +
+      "the file and the file is not changed; a PDF in an open signing round " +
+      "gets the signature added to the document itself, which is then " +
+      "sealed against changes (see useSigningRounds). initiate() opens a " +
+      "sign order (the backend hashes the bytes + binds the digest). The " +
+      "hook does NOT poll by itself: while status is 'pending' call " +
+      "refresh() every 2 seconds (a setInterval in an effect, cleared when " +
+      "status leaves 'pending' or the widget unmounts); each answer carries " +
+      "a fresh qr frame. Offer both ways to sign: BankID on THIS device is a " +
+      "button whose onPress calls Linking.openURL(bankIdAppUrl(autoStartToken)), " +
+      "shown only while autoStartToken is set; BankID on ANOTHER device is " +
+      "the qr rendered with the Image primitive, replaced by each poll's " +
+      "frame. cancel() aborts, verify() returns the offline verdict: valid " +
+      "is the BankID signature itself; content_status 'unchanged' means the " +
+      "file still holds what was signed, 'changed' that it was altered " +
+      "since, 'unavailable' that it could not be checked now; " +
+      "signed_by_others_since counts later signatures in a round's PDF; " +
+      "seal.status is 'valid' (protected against changes), 'invalid' or " +
+      "'certificate_revoked' (do not rely on the copy), 'unavailable' (try " +
+      "later) or 'not_applicable' (a signature kept beside the file). Say " +
+      "each in plain words and never show a green mark when any of them " +
+      "failed. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
       "state + verify() without re-signing. autoStartToken is set only while " +
       "opening BankID can still help (null once the user has signed or the " +
@@ -1644,19 +1664,21 @@ const HOOKS = [
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
-      qr: "string | null  // PNG data-URL of the animated BankID QR",
-      autoStartToken: "string | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR; render with <Image>, refresh() every 2 s while pending for the next frame",
+      autoStartToken: "string | null  // BankID on this device: a button calling Linking.openURL(bankIdAppUrl(autoStartToken))",
       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",
+      verdict:
+        "{ valid, checks, content_status: 'unchanged' | 'changed' | 'unavailable', signed_by_others_since: number | null, " +
+        "seal: { status: 'valid' | 'invalid' | 'certificate_revoked' | 'unavailable' | 'not_applicable', sealed_at, certificate_revoked_at, ... }, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
-      refresh: "() => Promise<void>",
+      refresh: "() => Promise<void>  // the hook never polls by itself",
       cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
@@ -1667,10 +1689,14 @@ const HOOKS = [
     name: "useFileSignatures",
     signature: "useFileSignatures(fileIds)",
     description:
-      "Batch 'is this file signed?' lookup for a set of file ids. Returns a map " +
-      "of each signed, accessible file id to its latest signature; unsigned " +
-      "files are absent. Lets a file browser mark already-signed files in one " +
-      "request. Reads ctx.filestore.signatures.list and unwraps { data, meta }.",
+      "Batch 'have I signed this file?' lookup for a set of file ids. Returns " +
+      "a map of each file the SIGNED-IN USER has signed (and can still see) " +
+      "to their own latest signature; a file only others have signed, or " +
+      "nobody has, is absent, so it never tells who else signed. Pass a " +
+      "file's signature_id to useFileSignature(fileId, signatureId) to show " +
+      "and verify it. Who has signed is useFileRoster(), for someone who " +
+      "manages the folder. Reads ctx.filestore.signatures.list and unwraps " +
+      "{ data, meta }.",
     returnShape: {
       signaturesByFileId:
         "{ [fileId]: { signature_id, signer_name, signed_at } }",
@@ -1709,8 +1735,10 @@ const HOOKS = [
     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 " +
+      "in a list, in one batched request. A signing round fixes a PDF in the " +
+      "project space and a list of signers (other file types are signed one " +
+      "person at a time with useFileSignature() and no round): 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, " +
@@ -1719,7 +1747,8 @@ const HOOKS = [
       "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, " +
+      "for them. Each signature is added to the PDF itself and the document " +
+      "is sealed against changes. 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 " +
@@ -1790,7 +1819,11 @@ const HOOKS = [
       "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 " +
+      "start one, and when it is false say that document signing is not " +
+      "turned on for this workspace and that the platform turns it on. " +
+      "Rounds take PDFs in the project space only (NOT_A_PDF otherwise). A " +
+      "signer signs their place with useFileSignature(fileId), the same " +
+      "BankID flow as any file. When fileId or the signed-in user changes, round is null " +
       "and loading true until the new answer. Reads ctx.filestore.signingRounds.",
     returnShape: {
       round:
@@ -2619,8 +2652,9 @@ const HOOKS = [
       "with the Image primitive) and the hook then POLLS to completion itself " +
       "(pollIntervalMs, default 1000; pass 0 to drive refresh() yourself); " +
       "cancel() aborts; reset() clears the flow. autoStartToken opens the " +
-      "provider app on the SAME device (bankid:///?autostarttoken=<token>" +
-      "&redirect=null). On complete, `identity` is { provider, name, given_name, " +
+      "provider app on the SAME device: Linking.openURL(bankIdAppUrl(" +
+      "autoStartToken)) opens bankid:///?autostarttoken=<token>&redirect=null. " +
+      "On complete, `identity` is { provider, name, given_name, " +
       "surname, personal_number_masked, subject_hash, identified_at } — there is " +
       "NO raw personal number by design: write personal_number_masked " +
       "(\"19900101-****\") and, if you need to trace the proof, identificationId. " +
@@ -6117,7 +6151,11 @@ const CONTRACT = deepFreeze({
   //    `{ name, email }` entries for signers without an account, and
   //    `resendLink(signerId, { email })` sends such a signer a new link.
   //    The manager's places carry id, kind, email and link.
-  version: "1.195.0",
+  // 1.197.0: additive (sc-12063) — new export `bankIdAppUrl(autoStartToken)`,
+  //    the link that opens BankID on this device. Signing hooks document
+  //    polling, the two ways to start BankID and how to read a verdict;
+  //    useFileSignatures is described as the caller's own signatures.
+  version: "1.197.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1624,10 +1624,30 @@ const HOOKS = [
     signature: "useFileSignature(fileId, existingSignatureId)",
     optionalArgs: ["existingSignatureId"],
     description:
-      "Drive a BankID signing flow for one Filestore file. initiate() opens a " +
-      "sign order (the backend hashes the bytes + binds the digest), refresh() " +
-      "polls (fresh QR while pending — render with the Image primitive), " +
-      "cancel() aborts, verify() returns the offline verdict. Pass " +
+      "Drive a BankID signing flow for one Filestore file of ANY type in a " +
+      "shared (project or public) space; a personal file is refused with " +
+      "NOT_SIGNABLE. Outside a signing round the signature is kept beside " +
+      "the file and the file is not changed; a PDF in an open signing round " +
+      "gets the signature added to the document itself, which is then " +
+      "sealed against changes (see useSigningRounds). initiate() opens a " +
+      "sign order (the backend hashes the bytes + binds the digest). The " +
+      "hook does NOT poll by itself: while status is 'pending' call " +
+      "refresh() every 2 seconds (a setInterval in an effect, cleared when " +
+      "status leaves 'pending' or the widget unmounts); each answer carries " +
+      "a fresh qr frame. Offer both ways to sign: BankID on THIS device is a " +
+      "button whose onPress calls Linking.openURL(bankIdAppUrl(autoStartToken)), " +
+      "shown only while autoStartToken is set; BankID on ANOTHER device is " +
+      "the qr rendered with the Image primitive, replaced by each poll's " +
+      "frame. cancel() aborts, verify() returns the offline verdict: valid " +
+      "is the BankID signature itself; content_status 'unchanged' means the " +
+      "file still holds what was signed, 'changed' that it was altered " +
+      "since, 'unavailable' that it could not be checked now; " +
+      "signed_by_others_since counts later signatures in a round's PDF; " +
+      "seal.status is 'valid' (protected against changes), 'invalid' or " +
+      "'certificate_revoked' (do not rely on the copy), 'unavailable' (try " +
+      "later) or 'not_applicable' (a signature kept beside the file). Say " +
+      "each in plain words and never show a green mark when any of them " +
+      "failed. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
       "state + verify() without re-signing. autoStartToken is set only while " +
       "opening BankID can still help (null once the user has signed or the " +
@@ -1644,19 +1664,21 @@ const HOOKS = [
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
-      qr: "string | null  // PNG data-URL of the animated BankID QR",
-      autoStartToken: "string | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR; render with <Image>, refresh() every 2 s while pending for the next frame",
+      autoStartToken: "string | null  // BankID on this device: a button calling Linking.openURL(bankIdAppUrl(autoStartToken))",
       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",
+      verdict:
+        "{ valid, checks, content_status: 'unchanged' | 'changed' | 'unavailable', signed_by_others_since: number | null, " +
+        "seal: { status: 'valid' | 'invalid' | 'certificate_revoked' | 'unavailable' | 'not_applicable', sealed_at, certificate_revoked_at, ... }, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
-      refresh: "() => Promise<void>",
+      refresh: "() => Promise<void>  // the hook never polls by itself",
       cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
@@ -1667,10 +1689,14 @@ const HOOKS = [
     name: "useFileSignatures",
     signature: "useFileSignatures(fileIds)",
     description:
-      "Batch 'is this file signed?' lookup for a set of file ids. Returns a map " +
-      "of each signed, accessible file id to its latest signature; unsigned " +
-      "files are absent. Lets a file browser mark already-signed files in one " +
-      "request. Reads ctx.filestore.signatures.list and unwraps { data, meta }.",
+      "Batch 'have I signed this file?' lookup for a set of file ids. Returns " +
+      "a map of each file the SIGNED-IN USER has signed (and can still see) " +
+      "to their own latest signature; a file only others have signed, or " +
+      "nobody has, is absent, so it never tells who else signed. Pass a " +
+      "file's signature_id to useFileSignature(fileId, signatureId) to show " +
+      "and verify it. Who has signed is useFileRoster(), for someone who " +
+      "manages the folder. Reads ctx.filestore.signatures.list and unwraps " +
+      "{ data, meta }.",
     returnShape: {
       signaturesByFileId:
         "{ [fileId]: { signature_id, signer_name, signed_at } }",
@@ -1709,8 +1735,10 @@ const HOOKS = [
     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 " +
+      "in a list, in one batched request. A signing round fixes a PDF in the " +
+      "project space and a list of signers (other file types are signed one " +
+      "person at a time with useFileSignature() and no round): 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, " +
@@ -1719,7 +1747,8 @@ const HOOKS = [
       "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, " +
+      "for them. Each signature is added to the PDF itself and the document " +
+      "is sealed against changes. 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 " +
@@ -1790,7 +1819,11 @@ const HOOKS = [
       "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 " +
+      "start one, and when it is false say that document signing is not " +
+      "turned on for this workspace and that the platform turns it on. " +
+      "Rounds take PDFs in the project space only (NOT_A_PDF otherwise). A " +
+      "signer signs their place with useFileSignature(fileId), the same " +
+      "BankID flow as any file. When fileId or the signed-in user changes, round is null " +
       "and loading true until the new answer. Reads ctx.filestore.signingRounds.",
     returnShape: {
       round:
@@ -2619,8 +2652,9 @@ const HOOKS = [
       "with the Image primitive) and the hook then POLLS to completion itself " +
       "(pollIntervalMs, default 1000; pass 0 to drive refresh() yourself); " +
       "cancel() aborts; reset() clears the flow. autoStartToken opens the " +
-      "provider app on the SAME device (bankid:///?autostarttoken=<token>" +
-      "&redirect=null). On complete, `identity` is { provider, name, given_name, " +
+      "provider app on the SAME device: Linking.openURL(bankIdAppUrl(" +
+      "autoStartToken)) opens bankid:///?autostarttoken=<token>&redirect=null. " +
+      "On complete, `identity` is { provider, name, given_name, " +
       "surname, personal_number_masked, subject_hash, identified_at } — there is " +
       "NO raw personal number by design: write personal_number_masked " +
       "(\"19900101-****\") and, if you need to trace the proof, identificationId. " +
@@ -6113,7 +6147,11 @@ const CONTRACT = deepFreeze({
   //    `{ name, email }` entries for signers without an account, and
   //    `resendLink(signerId, { email })` sends such a signer a new link.
   //    The manager's places carry id, kind, email and link.
-  version: "1.195.0",
+  // 1.197.0: additive (sc-12063) — new export `bankIdAppUrl(autoStartToken)`,
+  //    the link that opens BankID on this device. Signing hooks document
+  //    polling, the two ways to start BankID and how to read a verdict;
+  //    useFileSignatures is described as the caller's own signatures.
+  version: "1.197.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -5065,6 +5065,13 @@ export function useFileSignature(
   verify(): Promise<FileSignatureVerdict | null>;
 };
 
+/**
+ * The link that opens the BankID app on this device for a pending order:
+ * `Linking.openURL(bankIdAppUrl(autoStartToken))` from a button. For BankID
+ * on another device, show the order's `qr` instead.
+ */
+export function bankIdAppUrl(autoStartToken: string): string;
+
 export interface FileSignatureSummary {
   signature_id: string;
   subject_file_id: string;

package/dist/index.js

@@ -135,6 +135,7 @@ export {
 } from "./stats-hooks.js";
 // sc-11025 — one source, bound to how each platform says the app is in front.
 export { useFileSignature, useSigningRounds, useSigningRound } from "./signing-hooks.js";
+export { bankIdAppUrl } from "./bankid-app.js";
 export { useOnlineMembers, useOnlineVisibility } from "./presence.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box

package/dist/index.native.js

@@ -133,6 +133,7 @@ export {
 } from "./stats-hooks.js";
 // sc-11025 — see the note on the web mirror in ./index.js.
 export { useFileSignature, useSigningRounds, useSigningRound } from "./signing-hooks.js";
+export { bankIdAppUrl } from "./bankid-app.js";
 export { useOnlineMembers, useOnlineVisibility } from "./presence.native.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.241.0",
+  "version": "0.243.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -1624,10 +1624,30 @@ const HOOKS = [
     signature: "useFileSignature(fileId, existingSignatureId)",
     optionalArgs: ["existingSignatureId"],
     description:
-      "Drive a BankID signing flow for one Filestore file. initiate() opens a " +
-      "sign order (the backend hashes the bytes + binds the digest), refresh() " +
-      "polls (fresh QR while pending — render with the Image primitive), " +
-      "cancel() aborts, verify() returns the offline verdict. Pass " +
+      "Drive a BankID signing flow for one Filestore file of ANY type in a " +
+      "shared (project or public) space; a personal file is refused with " +
+      "NOT_SIGNABLE. Outside a signing round the signature is kept beside " +
+      "the file and the file is not changed; a PDF in an open signing round " +
+      "gets the signature added to the document itself, which is then " +
+      "sealed against changes (see useSigningRounds). initiate() opens a " +
+      "sign order (the backend hashes the bytes + binds the digest). The " +
+      "hook does NOT poll by itself: while status is 'pending' call " +
+      "refresh() every 2 seconds (a setInterval in an effect, cleared when " +
+      "status leaves 'pending' or the widget unmounts); each answer carries " +
+      "a fresh qr frame. Offer both ways to sign: BankID on THIS device is a " +
+      "button whose onPress calls Linking.openURL(bankIdAppUrl(autoStartToken)), " +
+      "shown only while autoStartToken is set; BankID on ANOTHER device is " +
+      "the qr rendered with the Image primitive, replaced by each poll's " +
+      "frame. cancel() aborts, verify() returns the offline verdict: valid " +
+      "is the BankID signature itself; content_status 'unchanged' means the " +
+      "file still holds what was signed, 'changed' that it was altered " +
+      "since, 'unavailable' that it could not be checked now; " +
+      "signed_by_others_since counts later signatures in a round's PDF; " +
+      "seal.status is 'valid' (protected against changes), 'invalid' or " +
+      "'certificate_revoked' (do not rely on the copy), 'unavailable' (try " +
+      "later) or 'not_applicable' (a signature kept beside the file). Say " +
+      "each in plain words and never show a green mark when any of them " +
+      "failed. Pass " +
       "existingSignatureId for an already-signed file to seed the complete " +
       "state + verify() without re-signing. autoStartToken is set only while " +
       "opening BankID can still help (null once the user has signed or the " +
@@ -1644,19 +1664,21 @@ const HOOKS = [
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
-      qr: "string | null  // PNG data-URL of the animated BankID QR",
-      autoStartToken: "string | null",
+      qr: "string | null  // PNG data-URL of the animated BankID QR; render with <Image>, refresh() every 2 s while pending for the next frame",
+      autoStartToken: "string | null  // BankID on this device: a button calling Linking.openURL(bankIdAppUrl(autoStartToken))",
       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",
+      verdict:
+        "{ valid, checks, content_status: 'unchanged' | 'changed' | 'unavailable', signed_by_others_since: number | null, " +
+        "seal: { status: 'valid' | 'invalid' | 'certificate_revoked' | 'unavailable' | 'not_applicable', sealed_at, certificate_revoked_at, ... }, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status, hint_code?, message? }>",
-      refresh: "() => Promise<void>",
+      refresh: "() => Promise<void>  // the hook never polls by itself",
       cancel: "() => Promise<{ status, hint_code?, message?, signer_name?, signed_at? } | undefined>",
       verify: "() => Promise<verdict>",
     },
@@ -1667,10 +1689,14 @@ const HOOKS = [
     name: "useFileSignatures",
     signature: "useFileSignatures(fileIds)",
     description:
-      "Batch 'is this file signed?' lookup for a set of file ids. Returns a map " +
-      "of each signed, accessible file id to its latest signature; unsigned " +
-      "files are absent. Lets a file browser mark already-signed files in one " +
-      "request. Reads ctx.filestore.signatures.list and unwraps { data, meta }.",
+      "Batch 'have I signed this file?' lookup for a set of file ids. Returns " +
+      "a map of each file the SIGNED-IN USER has signed (and can still see) " +
+      "to their own latest signature; a file only others have signed, or " +
+      "nobody has, is absent, so it never tells who else signed. Pass a " +
+      "file's signature_id to useFileSignature(fileId, signatureId) to show " +
+      "and verify it. Who has signed is useFileRoster(), for someone who " +
+      "manages the folder. Reads ctx.filestore.signatures.list and unwraps " +
+      "{ data, meta }.",
     returnShape: {
       signaturesByFileId:
         "{ [fileId]: { signature_id, signer_name, signed_at } }",
@@ -1709,8 +1735,10 @@ const HOOKS = [
     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 " +
+      "in a list, in one batched request. A signing round fixes a PDF in the " +
+      "project space and a list of signers (other file types are signed one " +
+      "person at a time with useFileSignature() and no round): 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, " +
@@ -1719,7 +1747,8 @@ const HOOKS = [
       "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, " +
+      "for them. Each signature is added to the PDF itself and the document " +
+      "is sealed against changes. 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 " +
@@ -1790,7 +1819,11 @@ const HOOKS = [
       "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 " +
+      "start one, and when it is false say that document signing is not " +
+      "turned on for this workspace and that the platform turns it on. " +
+      "Rounds take PDFs in the project space only (NOT_A_PDF otherwise). A " +
+      "signer signs their place with useFileSignature(fileId), the same " +
+      "BankID flow as any file. When fileId or the signed-in user changes, round is null " +
       "and loading true until the new answer. Reads ctx.filestore.signingRounds.",
     returnShape: {
       round:
@@ -2619,8 +2652,9 @@ const HOOKS = [
       "with the Image primitive) and the hook then POLLS to completion itself " +
       "(pollIntervalMs, default 1000; pass 0 to drive refresh() yourself); " +
       "cancel() aborts; reset() clears the flow. autoStartToken opens the " +
-      "provider app on the SAME device (bankid:///?autostarttoken=<token>" +
-      "&redirect=null). On complete, `identity` is { provider, name, given_name, " +
+      "provider app on the SAME device: Linking.openURL(bankIdAppUrl(" +
+      "autoStartToken)) opens bankid:///?autostarttoken=<token>&redirect=null. " +
+      "On complete, `identity` is { provider, name, given_name, " +
       "surname, personal_number_masked, subject_hash, identified_at } — there is " +
       "NO raw personal number by design: write personal_number_masked " +
       "(\"19900101-****\") and, if you need to trace the proof, identificationId. " +
@@ -6113,7 +6147,11 @@ const CONTRACT = deepFreeze({
   //    `{ name, email }` entries for signers without an account, and
   //    `resendLink(signerId, { email })` sends such a signer a new link.
   //    The manager's places carry id, kind, email and link.
-  version: "1.195.0",
+  // 1.197.0: additive (sc-12063) — new export `bankIdAppUrl(autoStartToken)`,
+  //    the link that opens BankID on this device. Signing hooks document
+  //    polling, the two ways to start BankID and how to read a verdict;
+  //    useFileSignatures is described as the caller's own signatures.
+  version: "1.197.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,