@colixsystems/widget-sdk 0.241.0 → 0.244.0

package/README.md

@@ -24,7 +24,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useUser()` | `{ id, email, displayName, photoUrl, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope. `photoUrl` is the user's own profile photo as an absolute URL, or `null`. |
 | **CORE** | `useUserPhoto()` | `{ url, canEdit, upload, remove, uploading, error }` | `ctx.user` + the optional `ctx.account` — no scope. Changes the signed-in user's OWN profile photo. `canEdit` is false when nobody is signed in or the host cannot change it; `upload` / `remove` then reject. |
 | **CORE** | `useAnonymousAccount()` | `{ supported, canCreate, creating, error, create }` | The optional `ctx.account.anonymous` — no scope. Offers an account with a generated login code and password and no email. `create()` opens the app's own dialog, which confirms, creates the account, shows the pair once and signs the visitor in; the widget never receives the pair and `create()` resolves `{ created: true }`. `supported` is false where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview and for a badge counter; `canCreate` is false while someone is signed in. |
-| **CORE** | `useNavigation()` | `{ goTo, goToStartPage, scrollToSection, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either; `goToStartPage()` opens the signed-in user's own start page; `scrollToSection(id)` scrolls this page to a section picked with a `sectionRef` prop (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
+| **CORE** | `useNavigation()` | `{ goTo, goToStartPage, scrollToSection, scrollIntoView, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either; `goToStartPage()` opens the signed-in user's own start page; `scrollToSection(id)` scrolls this page to a section picked with a `sectionRef` prop; `scrollIntoView(ref)` scrolls it to an element inside your widget (a heading your table of contents jumps to) (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useFilePreview(file)` | `{ uri }` | No scope. A temporary address an `<Image>` can show for a file the person picked but has not uploaded yet (a photo in a composer). Native picks use their own uri; on the web the SDK creates and releases an object URL, which widgets may not do themselves. `uri` is null for no file. |
 | **CORE** | `usePageBadge(count)` | `{ supported }` | `ctx.navigation.setBadge` — no scope. Puts `count` on the menu entry or tab of the page the widget is on (a chat's unread messages). The host sums the page's widgets and keeps the last count after the widget leaves the screen, until it reports again; `0` clears this widget's share. `supported` is false where the host draws no page badges (the Builder canvas). |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
@@ -84,7 +84,59 @@ 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.244.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.244.0 (contract 1.198.0)
+
+**A widget can scroll its page to an element inside itself — `useNavigation().scrollIntoView(ref)`.** A long article, FAQ or handbook widget can show a table of contents whose entries jump to its own headings. The page itself scrolls, so the widget keeps its full height and never needs a scroll box of its own. Attach a ref to the element and pass the ref:
+
+```jsx
+import { useRef } from "react";
+import { useNavigation, Pressable, Text, View } from "@colixsystems/widget-sdk";
+
+export default function Handbook({ sections }) {
+  const { scrollIntoView } = useNavigation();
+  const headings = useRef({});
+  return (
+    <View>
+      {sections.map((s) => (
+        <Pressable key={s.id} onPress={() => scrollIntoView({ current: headings.current[s.id] })}>
+          <Text>{s.title}</Text>
+        </Pressable>
+      ))}
+      {sections.map((s) => (
+        <View key={s.id} ref={(el) => { headings.current[s.id] = el; }}>
+          <Text>{s.title}</Text>
+          <Text>{s.body}</Text>
+        </View>
+      ))}
+    </View>
+  );
+}
+```
+
+Both hosts use the same scroll as `scrollToSection`: smooth (instant under reduced motion), stopping with the element just below a pinned site header, on a normal page and on a Fit to screen page. A ref that is not mounted does nothing, and so does the Studio canvas. To jump to another part of the PAGE, keep using `scrollToSection` with a `sectionRef` prop. Additive.
+
+### 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)
 
@@ -2964,7 +3016,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useWidgetRoute`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goToStartPage, scrollToSection, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `goToStartPage()` opens the signed-in user's own start page (the page the app opens on for them); `scrollToSection(sectionId)` scrolls the current page to one of its sections (bind the id with a `sectionRef` prop); `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useWidgetRoute`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goToStartPage, scrollToSection, scrollIntoView, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `goToStartPage()` opens the signed-in user's own start page (the page the app opens on for them); `scrollToSection(sectionId)` scrolls the current page to one of its sections (bind the id with a `sectionRef` prop); `scrollIntoView(ref)` scrolls it to an element inside the calling widget; `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `Overlay` — the screen-level overlay (sc-6607). `<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">…</Overlay>` renders its children OUTSIDE the widget's layout box on both hosts (web portals it to the document root, native uses the OS modal), so no clipping card, `ScrollView` or neighbouring widget can cut off a document/media preview, lightbox or confirm dialog — which absolute positioning inside the widget cannot achieve on either platform. Children stay in your own React tree, so state and hooks work normally. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme. An anchored dropdown still belongs inside your own root.

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

@@ -1205,6 +1205,8 @@ const HOOKS = [
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       scrollToSection:
         "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
+      scrollIntoView:
+        "(ref: { current }) => void — scrolls THIS page so an element inside the calling widget (the ref you attached to a View, Text or other primitive) lands just below any pinned site header; smooth unless the visitor prefers reduced motion. Use it for anchors within the widget's own content, such as a table of contents that jumps to one of its headings. Never fake page anchors with a height-capped inner ScrollView: the page itself scrolls. A ref that is not mounted is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -1624,10 +1626,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 +1666,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 +1691,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 +1737,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 +1749,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 +1821,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 +2654,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 +6153,13 @@ 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.
+  // 1.198.0: additive (sc-12088) — `useNavigation().scrollIntoView(ref)`
+  //    scrolls the page to an element inside the calling widget on both hosts.
+  version: "1.198.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1205,6 +1205,8 @@ const HOOKS = [
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       scrollToSection:
         "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
+      scrollIntoView:
+        "(ref: { current }) => void — scrolls THIS page so an element inside the calling widget (the ref you attached to a View, Text or other primitive) lands just below any pinned site header; smooth unless the visitor prefers reduced motion. Use it for anchors within the widget's own content, such as a table of contents that jumps to one of its headings. Never fake page anchors with a height-capped inner ScrollView: the page itself scrolls. A ref that is not mounted is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -1624,10 +1626,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 +1666,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 +1691,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 +1737,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 +1749,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 +1821,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 +2654,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 +6149,13 @@ 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.
+  // 1.198.0: additive (sc-12088) — `useNavigation().scrollIntoView(ref)`
+  //    scrolls the page to an element inside the calling widget on both hosts.
+  version: "1.198.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -744,11 +744,14 @@ export function useContainerWidth() {
 }
 
 /**
- * Returns the host-provided navigation surface:
- *   `{ goTo, goToStartPage, goBack, push, replace, back, currentRoute }`.
+ * Returns the host-provided navigation surface: `{ goTo, goToStartPage,
+ * scrollToSection, scrollIntoView, goBack, push, replace, back, currentRoute,
+ * openLink }`.
  *
  * `goTo(pageId, params?)` navigates to an internal app page. `goToStartPage()`
  * opens the signed-in user's own start page, which can differ per user.
+ * `scrollToSection(id)` scrolls the page to one of its sections, and (sc-12088)
+ * `scrollIntoView(ref)` to an element inside the calling widget.
  * `goBack()` pops the stack. `push` / `replace` / `back` are aliases that map to
  * the platform's native navigator (react-router on web, react-navigation
  * on native). Missing methods degrade to no-ops on the Studio canvas

package/dist/index.d.ts

@@ -850,6 +850,7 @@ export interface WidgetContext<TProps = unknown> {
     goTo(pageId: string, params?: Record<string, string>): void;
     goToStartPage(): void;
     scrollToSection(sectionId: string): void;
+    scrollIntoView(ref: { readonly current: unknown } | object | null | undefined): void;
     goBack(): void;
     push(pageId: string, params?: Record<string, unknown>): void;
     replace(pageId: string, params?: Record<string, unknown>): void;
@@ -2221,6 +2222,8 @@ export function useFitScreenInsets(): FitScreenInsets;
  * opens the signed-in user's own start page, which can differ per user.
  * `scrollToSection(sectionId)` scrolls this page to one of its sections (the
  * id comes from a `sectionRef` prop); an unknown section is a no-op.
+ * `scrollIntoView(ref)` scrolls this page to an element inside the calling
+ * widget, such as a heading its table of contents jumps to.
  * Missing methods degrade to no-ops on the Studio canvas preview where no
  * live router is mounted. For external URLs use the `Linking` primitive.
  */
@@ -2228,6 +2231,7 @@ export function useNavigation(): {
   goTo(pageId: string, params?: Record<string, unknown>): void;
   goToStartPage(): void;
   scrollToSection(sectionId: string): void;
+  scrollIntoView(ref: { readonly current: unknown } | object | null | undefined): void;
   goBack(): void;
   push(pageId: string, params?: Record<string, unknown>): void;
   replace(pageId: string, params?: Record<string, unknown>): void;
@@ -5065,6 +5069,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.244.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

@@ -1205,6 +1205,8 @@ const HOOKS = [
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       scrollToSection:
         "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
+      scrollIntoView:
+        "(ref: { current }) => void — scrolls THIS page so an element inside the calling widget (the ref you attached to a View, Text or other primitive) lands just below any pinned site header; smooth unless the visitor prefers reduced motion. Use it for anchors within the widget's own content, such as a table of contents that jumps to one of its headings. Never fake page anchors with a height-capped inner ScrollView: the page itself scrolls. A ref that is not mounted is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -1624,10 +1626,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 +1666,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 +1691,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 +1737,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 +1749,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 +1821,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 +2654,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 +6149,13 @@ 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.
+  // 1.198.0: additive (sc-12088) — `useNavigation().scrollIntoView(ref)`
+  //    scrolls the page to an element inside the calling widget on both hosts.
+  version: "1.198.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,