@colixsystems/widget-sdk 0.30.0 → 0.31.0

package/README.md

@@ -46,27 +46,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.30.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.31.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.30.0
-
-**New `folderRef` propertySchema type (REQ-WDG-FOLDERREF).** A Filestore folder picker that stores a bare folder UUID (or `null` = space root) and renders the Asset/Filestore `FolderSelector` in the Studio Properties Panel, scoped by a sibling space field named via `ui.spaceTypeField` (its value `"project"` / `"personal"` selects the PROJECT / PERSONAL space). Changing the space drops a now-out-of-scope selection. Filestore spaces are per-tenant end-user data and are not copied, so tenant-copy leaves the id as-is. Additive — no existing export or type changed.
-
-### What's new in 0.29.0
+### What's new in 0.31.0
 
-**New `assetList` propertySchema type + `ui.showWhen` `neq`/`in` + `ui.step` (REQ-WDG-ASSET).** `assetList` is the multi-pick form of `asset` — an ordered array of bare File UUIDs rendered with the Asset Manager `MultiFileSelector` (selection order preserved; narrow with `ui.mimeFilter`). tenant-copy remaps each id. `ui.showWhen` now accepts `{ neq }` and `{ in: [...] }` alongside `{ eq }`; `ui.step` sets the numeric input/slider step. Additive — no existing export or type changed.
+**Already-signed file state (REQ-SIGN).** So a file browser can show which files are signed (and not re-sign blindly):
+- `useFileSignatures(fileIds)` → `{ signaturesByFileId, loading, error, refetch }` — a batch "is this file signed?" lookup. `signaturesByFileId` maps each signed, accessible file id to its latest `{ signature_id, signer_name, signed_at }`; unsigned files are absent. One request, no N+1. Reads `ctx.filestore.signatures.list` (new `@colixsystems/filestore-client` **0.3.0** method).
+- `useFileSignature(fileId, existingSignatureId?)` gained an optional second arg: pass an already-signed file's signature id to seed the `complete` state and `verify()` it **without** opening a new order. Re-signing then requires an explicit `initiate()`.
 
-### What's new in 0.28.0
+`CONTRACT.version` → `1.21.0` (additive — the new arg is optional, no existing hook changed).
 
-**New `asset` propertySchema type + `ui.showWhen` (REQ-WDG-ASSET).** `asset` is a file/asset picker that stores a bare File UUID and renders the Asset Manager `FileSelector` in the Studio Properties Panel (narrow it with `ui.mimeFilter`, e.g. `"image"`). `ui.showWhen: { field, eq }` conditionally hides a field unless a sibling field equals a value (e.g. show the asset picker only when `imageSource === "asset"`). tenant-copy remaps an `asset` File UUID to the copied file. Additive — no existing export or type changed.
+### What's new in 0.30.0
 
-### What's new in 0.27.0
+**Filestore browsing + BankID file signing for widgets (REQ-FS / REQ-SIGN).** Three new hooks read a newly-injected `ctx.filestore` (the `@colixsystems/filestore-client`, now constructed by both the web and native hosts):
+- `useFilestoreFiles({ spaceType, folderId?, q?, type? })` → `{ files, loading, error, refetch }` — browses the end-user's Filestore space. The hook resolves `owner_id` from the host context (tenant for a project space, the app user for a personal space), so the widget only picks the space.
+- `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching.
+- `useFileSignature(fileId)` → `{ status, qr, signerName, verdict, initiate, refresh, cancel, verify, … }` — drives a BankID signing flow for a file (the backend hashes the bytes server-side, binds the digest into the signature, and verifies the proof offline).
 
-**New `richText` propertySchema type (REQ-WDG-RICHTEXT).** A rich-text (HTML) string edited via a Tiptap editor in the Studio Properties Panel; the widget renders the sanitised HTML. Stored as a plain string (no tenant-copy remap). Additive — no existing export or type changed.
+`CONTRACT.version` → `1.20.0` (additive — no existing hook changed).
 
-### What's new in 0.26.0
+### What's new in 0.29.0
 
-**New `pageRef` propertySchema type (REQ-WDG-PAGEREF).** A page picker: the Studio Properties Panel renders a dropdown of the app's pages and stores the chosen page's bare UUID. A widget reads the prop and navigates with `useNavigation().goTo(pageId, params)` — the cross-platform replacement for the old per-widget "navigate on press" event wiring. tenant-copy remaps the stored page id to the copied page. Additive: no existing export or type changed signature.
+**The SIGNATURE column type and its hook are retired (REQ-SIGN).** `useSignature(tableId, recordId)` and the datastore-client `sign(recordId)` namespace are **removed** — signing a single record/column was the wrong granularity. BankID signing is being rebuilt around a standalone, polymorphic **Signature subject model** (sign a file first, then whole records and policy text), where the signature is cryptographically bound to the exact bytes signed (the file's SHA-256 embedded in the BankID signature) and verified offline against the pinned `BankID Root CA v1`. New SDK hooks for that model will land as the backend ships. `CONTRACT.version` → `1.19.0` (pre-1.0 breaking removal of unreleased hooks; kept monotonic).
 
 ### What's new in 0.25.0
 
@@ -103,7 +104,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
   - **`expo-linear-gradient`** (`web`/`native`) — the cross-platform gradient.
   - **`lottie-react-native`** (`native`) + **`lottie-react`** (`web`) — Lottie animations, split-impl.
   - **`react-native-webview`** (`native`) — embedded web content (pair with an `<iframe>` on web).
-- **Parity (CLAUDE.md §3):** the compiler now pins the native-module members in the exported Expo app's `package.json` and emits the **`react-native-reanimated/plugin`** in `babel.config.js` **unconditionally** (previously only for the sidebar-drawer shell), so a baked widget that imports any of these resolves and bundles on native exactly as it renders in the web Player.
+- **Parity (widget-parity skill):** the compiler now pins the native-module members in the exported Expo app's `package.json` and emits the **`react-native-reanimated/plugin`** in `babel.config.js` **unconditionally** (previously only for the sidebar-drawer shell), so a baked widget that imports any of these resolves and bundles on native exactly as it renders in the web Player.
 - **`CONTRACT.version` → `1.13.0`** (additive: new vetted import entries only). No existing export, type, manifest field, hook, or banned-API list changed.
 
 ### What's new in 0.22.0

package/dist/contract.cjs

@@ -99,7 +99,7 @@ const HOOKS = [
       'style (flex: 1 / height: "100%"); 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 (CLAUDE.md §3), so a " +
+      "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
     returnShape: {
       "(returns)": "boolean",
@@ -155,6 +155,87 @@ const HOOKS = [
     requiredContextSlice: ["files.get"],
     scopes: null,
   },
+  {
+    name: "useFilestoreFiles",
+    signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
+    description:
+      "Browse the end-user's Filestore files in a project or personal space. " +
+      "The hook resolves owner_id from the host context (tenant for project, " +
+      "app user for personal) — the widget only chooses the space. Reads " +
+      "ctx.filestore.files.list and unwraps { data, meta } to the files array.",
+    returnShape: {
+      files: "FilestoreFile[]",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFilestoreFolders",
+    signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
+    description:
+      "Browse the end-user's Filestore folders in a project or personal space, " +
+      "mirroring useFilestoreFiles for subfolder navigation. The hook resolves " +
+      "owner_id from the host context; pass enabled:false to suspend fetching. " +
+      "Reads ctx.filestore.folders.list and unwraps { data, meta } to the array.",
+    returnShape: {
+      folders: "FilestoreFolder[]",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.folders"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFileSignature",
+    signature: "useFileSignature(fileId, 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 " +
+      "existingSignatureId for an already-signed file to seed the complete " +
+      "state + verify() without re-signing. Reads " +
+      "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",
+      message: "string | null",
+      signerName: "string | null",
+      signedAt: "string | null",
+      verdict: "{ valid, checks, content_status, ... } | null",
+      loading: "boolean",
+      error: "PermissionError | null",
+      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
+      refresh: "() => Promise<void>",
+      cancel: "() => Promise<void>",
+      verify: "() => Promise<verdict>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.write:*"],
+  },
+  {
+    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 }.",
+    returnShape: {
+      signaturesByFileId:
+        "{ [fileId]: { signature_id, signer_name, signed_at } }",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.read:*"],
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -741,6 +822,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { get: "function" },
   },
+  filestore: {
+    description:
+      "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal spaces) + BankID file signing. " +
+      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(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() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+    required: false,
+    fields: { files: "object", folders: "object", signatures: "object" },
+  },
   renderer: {
     description:
       "Host child-node renderer. { renderNode(node) -> ReactElement }. Backs WidgetTree / useChildRenderer; lets a container widget (Tabs, Card, …) render arbitrary author-authored child nodes without importing the host renderer. The closure pre-binds breakpoint + page ctx + parent so the widget passes only the child node.",
@@ -973,7 +1064,7 @@ const VETTED_IMPORTS = [
   // below runs on web AND native (directly, or via the documented platform-split
   // counterpart). Native-module packages additionally carry a pinned version in
   // the compiler's generatePackageJson so a baked marketplace widget resolves in
-  // the Expo export (CLAUDE.md §3 parity). See the `adding-vetted-packages` skill
+  // the Expo export (widget-parity skill parity). See the `adding-vetted-packages` skill
   // for the full add checklist (contract ×2, version bump, compiler pin, docs).
   {
     specifier: "react-native-reanimated",
@@ -1103,7 +1194,7 @@ const CONTRACT = deepFreeze({
   //   - `allowedBareImports` is now derived from `vettedImports` (same
   //     shape; same contents grow with each vetted addition).
   // Permissive-direction change: minor bump on the contract's own
-  // versioning (per CLAUDE.md §4, pre-1.0 minor is the breaking channel —
+  // versioning (per sdk-contract-lockstep skill, pre-1.0 minor is the breaking channel —
   // the package.json version bumps accordingly).
   //
   // 1.6.0: additive — `themeTokens.colors` gains `secondary` + `onSecondary`
@@ -1191,7 +1282,7 @@ const CONTRACT = deepFreeze({
   //    existing entry changed shape and no other contract field moved, so this
   //    is additive — minor bump on the pre-1.0 channel. The compiler pins the
   //    native-module members in the exported Expo app's package.json and now
-  //    always emits the react-native-reanimated/plugin (CLAUDE.md §3 parity).
+  //    always emits the react-native-reanimated/plugin (widget-parity skill parity).
   //
   // 1.14.0: additive (REQ-RT-07) — new `useDatastoreSubscription(tableId,
   //    handlers, options?)` hook reading ctx.datastore.records(t).subscribe.
@@ -1209,7 +1300,30 @@ const CONTRACT = deepFreeze({
   //    the widget applies them itself (the host never auto-styles). New
   //    `useWidgetStyle()` hook returns props.style. No existing field, hook,
   //    primitive, or token changed shape — minor bump on the pre-1.0 channel.
-  version: "1.15.0",
+  // 1.16.0: additive (REQ-SIGN) — new `useSignature(tableId, recordId)` hook
+  //    reading ctx.datastore.records(tableId).sign(recordId).{initiate,status,
+  //    cancel}. Drives a BankID e-signing flow (QR data-URL + autostart token +
+  //    poll). No existing hook, primitive, or field changed — minor bump on the
+  //    pre-1.0 channel.
+  // 1.18.0: REQ-SIGN — removed the record-less inline-form signing hook
+  //    `useSignatureColumn` (added in 1.17.0) and the datastore-client
+  //    `signColumn` namespace it read.
+  // 1.19.0: REQ-SIGN — removed `useSignature` (record/column-scoped signing,
+  //    added in 1.16.0) and the datastore-client `sign(recordId)` namespace.
+  //    The SIGNATURE column type is retired; signing moves to a standalone
+  //    Signature subject model (files first). Pre-1.0 breaking removal of
+  //    unreleased hooks — version kept monotonic.
+  // 1.20.0: additive (REQ-SIGN / REQ-FS) — new `useFilestoreFiles` +
+  //    `useFilestoreFolders` (browse the end-user's Filestore space) and
+  //    `useFileSignature(fileId)` (BankID file signing), all reading the
+  //    newly-injected `ctx.filestore` (@colixsystems/filestore-client). No
+  //    existing hook changed.
+  // 1.21.0: additive (REQ-SIGN) — new `useFileSignatures(fileIds)` (batch
+  //    "is this file signed?" map, reads ctx.filestore.signatures.list) and a
+  //    new optional `existingSignatureId` arg on `useFileSignature` so an
+  //    already-signed file shows its state + verify()s without re-signing.
+  //    Backwards-compatible — the added arg is optional.
+  version: "1.21.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -99,7 +99,7 @@ const HOOKS = [
       'style (flex: 1 / height: "100%"); 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 (CLAUDE.md §3), so a " +
+      "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
     returnShape: {
       "(returns)": "boolean",
@@ -155,6 +155,87 @@ const HOOKS = [
     requiredContextSlice: ["files.get"],
     scopes: null,
   },
+  {
+    name: "useFilestoreFiles",
+    signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
+    description:
+      "Browse the end-user's Filestore files in a project or personal space. " +
+      "The hook resolves owner_id from the host context (tenant for project, " +
+      "app user for personal) — the widget only chooses the space. Reads " +
+      "ctx.filestore.files.list and unwraps { data, meta } to the files array.",
+    returnShape: {
+      files: "FilestoreFile[]",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFilestoreFolders",
+    signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
+    description:
+      "Browse the end-user's Filestore folders in a project or personal space, " +
+      "mirroring useFilestoreFiles for subfolder navigation. The hook resolves " +
+      "owner_id from the host context; pass enabled:false to suspend fetching. " +
+      "Reads ctx.filestore.folders.list and unwraps { data, meta } to the array.",
+    returnShape: {
+      folders: "FilestoreFolder[]",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.folders"],
+    scopes: ["files.read:*"],
+  },
+  {
+    name: "useFileSignature",
+    signature: "useFileSignature(fileId, 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 " +
+      "existingSignatureId for an already-signed file to seed the complete " +
+      "state + verify() without re-signing. Reads " +
+      "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",
+      message: "string | null",
+      signerName: "string | null",
+      signedAt: "string | null",
+      verdict: "{ valid, checks, content_status, ... } | null",
+      loading: "boolean",
+      error: "PermissionError | null",
+      initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
+      refresh: "() => Promise<void>",
+      cancel: "() => Promise<void>",
+      verify: "() => Promise<verdict>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.write:*"],
+  },
+  {
+    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 }.",
+    returnShape: {
+      signaturesByFileId:
+        "{ [fileId]: { signature_id, signer_name, signed_at } }",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.signatures"],
+    scopes: ["files.read:*"],
+  },
   {
     name: "useDatastoreQuery",
     signature: "useDatastoreQuery(tableId, options?)",
@@ -741,6 +822,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { get: "function" },
   },
+  filestore: {
+    description:
+      "Injected @colixsystems/filestore-client instance — the end-user file archive (project / personal spaces) + BankID file signing. " +
+      "{ files: { list(query) -> Promise<{ data, meta }>, get(id), upload(formData), update(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() + useFileSignature(). Optional — a host without an end-user filestore omits it and those hooks throw a clear error.",
+    required: false,
+    fields: { files: "object", folders: "object", signatures: "object" },
+  },
   renderer: {
     description:
       "Host child-node renderer. { renderNode(node) -> ReactElement }. Backs WidgetTree / useChildRenderer; lets a container widget (Tabs, Card, …) render arbitrary author-authored child nodes without importing the host renderer. The closure pre-binds breakpoint + page ctx + parent so the widget passes only the child node.",
@@ -973,7 +1064,7 @@ const VETTED_IMPORTS = [
   // below runs on web AND native (directly, or via the documented platform-split
   // counterpart). Native-module packages additionally carry a pinned version in
   // the compiler's generatePackageJson so a baked marketplace widget resolves in
-  // the Expo export (CLAUDE.md §3 parity). See the `adding-vetted-packages` skill
+  // the Expo export (widget-parity skill parity). See the `adding-vetted-packages` skill
   // for the full add checklist (contract ×2, version bump, compiler pin, docs).
   {
     specifier: "react-native-reanimated",
@@ -1103,7 +1194,7 @@ const CONTRACT = deepFreeze({
   //   - `allowedBareImports` is now derived from `vettedImports` (same
   //     shape; same contents grow with each vetted addition).
   // Permissive-direction change: minor bump on the contract's own
-  // versioning (per CLAUDE.md §4, pre-1.0 minor is the breaking channel —
+  // versioning (per sdk-contract-lockstep skill, pre-1.0 minor is the breaking channel —
   // the package.json version bumps accordingly).
   //
   // 1.6.0: additive — `themeTokens.colors` gains `secondary` + `onSecondary`
@@ -1191,7 +1282,7 @@ const CONTRACT = deepFreeze({
   //    existing entry changed shape and no other contract field moved, so this
   //    is additive — minor bump on the pre-1.0 channel. The compiler pins the
   //    native-module members in the exported Expo app's package.json and now
-  //    always emits the react-native-reanimated/plugin (CLAUDE.md §3 parity).
+  //    always emits the react-native-reanimated/plugin (widget-parity skill parity).
   //
   // 1.14.0: additive (REQ-RT-07) — new `useDatastoreSubscription(tableId,
   //    handlers, options?)` hook reading ctx.datastore.records(t).subscribe.
@@ -1209,7 +1300,30 @@ const CONTRACT = deepFreeze({
   //    the widget applies them itself (the host never auto-styles). New
   //    `useWidgetStyle()` hook returns props.style. No existing field, hook,
   //    primitive, or token changed shape — minor bump on the pre-1.0 channel.
-  version: "1.15.0",
+  // 1.16.0: additive (REQ-SIGN) — new `useSignature(tableId, recordId)` hook
+  //    reading ctx.datastore.records(tableId).sign(recordId).{initiate,status,
+  //    cancel}. Drives a BankID e-signing flow (QR data-URL + autostart token +
+  //    poll). No existing hook, primitive, or field changed — minor bump on the
+  //    pre-1.0 channel.
+  // 1.18.0: REQ-SIGN — removed the record-less inline-form signing hook
+  //    `useSignatureColumn` (added in 1.17.0) and the datastore-client
+  //    `signColumn` namespace it read.
+  // 1.19.0: REQ-SIGN — removed `useSignature` (record/column-scoped signing,
+  //    added in 1.16.0) and the datastore-client `sign(recordId)` namespace.
+  //    The SIGNATURE column type is retired; signing moves to a standalone
+  //    Signature subject model (files first). Pre-1.0 breaking removal of
+  //    unreleased hooks — version kept monotonic.
+  // 1.20.0: additive (REQ-SIGN / REQ-FS) — new `useFilestoreFiles` +
+  //    `useFilestoreFolders` (browse the end-user's Filestore space) and
+  //    `useFileSignature(fileId)` (BankID file signing), all reading the
+  //    newly-injected `ctx.filestore` (@colixsystems/filestore-client). No
+  //    existing hook changed.
+  // 1.21.0: additive (REQ-SIGN) — new `useFileSignatures(fileIds)` (batch
+  //    "is this file signed?" map, reads ctx.filestore.signatures.list) and a
+  //    new optional `existingSignatureId` arg on `useFileSignature` so an
+  //    already-signed file shows its state + verify()s without re-signing.
+  //    Backwards-compatible — the added arg is optional.
+  version: "1.21.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -132,7 +132,7 @@ export function useUser() {
  * opted the widget into filling, so calling it is always safe.
  *
  * The SAME value is injected by the web Player host and the native export
- * host (CLAUDE.md §3), so a widget's fill behaviour is identical on both
+ * host (widget-parity skill), so a widget's fill behaviour is identical on both
  * platforms — there is one source file and one `fill` flag driving it.
  */
 export function useFill() {
@@ -961,7 +961,7 @@ export function useRecordPermissions(tableId, recordId) {
  * expose `subscribe` (an older host, or a runtime with no WebSocket), the hook
  * resolves to `{ status: "fallback" }` WITHOUT throwing, so a widget that
  * subscribes degrades to polling on both the web Player and the native export
- * rather than crashing at render (CLAUDE.md §11).
+ * rather than crashing at render (widget-parity skill).
  *
  * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
  * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
@@ -1106,6 +1106,403 @@ export function useFile(fileId) {
   return { url, file, loading, error, refetch };
 }
 
+/* ============================================================================
+ * FILESTORE CLIENT — ctx.filestore (@colixsystems/filestore-client)
+ *
+ * The end-user file archive (project / personal spaces) + BankID file signing.
+ * Covers: useFilestoreFiles, useFileSignature.
+ * ==========================================================================*/
+
+// Resolve the owner_id a filestore query needs from the host context: a PROJECT
+// space is owned by the tenant (ctx.workspace.id); a PERSONAL space is owned by
+// the signed-in app user (ctx.user.id). The widget only chooses the space.
+function _filestoreOwnerId(ctx, spaceType) {
+  const space = String(spaceType || "project").toUpperCase();
+  if (space === "PERSONAL") return (ctx.user && ctx.user.id) || null;
+  return (ctx.workspace && ctx.workspace.id) || null;
+}
+
+/**
+ * Browse the end-user's Filestore files. Returns { files, loading, error,
+ * refetch }. The widget passes only the SPACE (`{ spaceType, folderId, q,
+ * type }`); the hook resolves owner_id from the host context (tenant for
+ * project, app user for personal) and calls
+ * `ctx.filestore.files.list({ space_type, owner_id, folder_id, q, type })`,
+ * unwrapping the `{ data, meta }` envelope to the files array. When the owner
+ * can't be resolved (no signed-in user for a personal space) it collapses to an
+ * empty result without a network round-trip.
+ */
+export function useFilestoreFiles(options) {
+  const ctx = useWidgetContextOrThrow("useFilestoreFiles");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.list !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreFiles: host did not inject a filestore client (ctx.filestore.files.list)",
+    );
+  }
+  const { spaceType = "project", folderId = null, q, type } = options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [files, setFiles] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+  const argsRef = useRef({});
+  argsRef.current = { spaceType, ownerId, folderId, q, type };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { spaceType: sp, ownerId: oid, folderId: fid, q: qq, type: tt } = argsRef.current;
+    if (!oid) {
+      setLoading(false);
+      setError(null);
+      setFiles([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await filesRef.current.list({
+        space_type: String(sp || "project").toUpperCase(),
+        owner_id: oid,
+        folder_id: fid || undefined,
+        q: qq || undefined,
+        type: tt || undefined,
+      });
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      if (runRef.current !== myRun) return;
+      setFiles(rows);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  const key = `${spaceType}|${ownerId}|${folderId}|${q || ""}|${type || ""}`;
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { files, loading, error, refetch };
+}
+
+/**
+ * Browse the end-user's Filestore folders. Returns { folders, loading, error,
+ * refetch }. Mirrors useFilestoreFiles for subfolder navigation: the widget
+ * passes only the SPACE (`{ spaceType, parentFolderId, q, enabled }`); the hook
+ * resolves owner_id from the host context and calls
+ * `ctx.filestore.folders.list({ space_type, owner_id, parent_folder_id, q })`,
+ * unwrapping the `{ data, meta }` envelope. Pass `enabled: false` to suspend
+ * fetching (e.g. when the widget hides subfolders) or when the owner can't be
+ * resolved — the hook then resolves to an empty list without a network call.
+ */
+export function useFilestoreFolders(options) {
+  const ctx = useWidgetContextOrThrow("useFilestoreFolders");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.folders ||
+    typeof ctx.filestore.folders.list !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreFolders: host did not inject a filestore client (ctx.filestore.folders.list)",
+    );
+  }
+  const {
+    spaceType = "project",
+    parentFolderId = null,
+    q,
+    enabled = true,
+  } = options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [folders, setFolders] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const foldersApiRef = useRef(ctx.filestore.folders);
+  foldersApiRef.current = ctx.filestore.folders;
+  const argsRef = useRef({});
+  argsRef.current = { spaceType, ownerId, parentFolderId, q, enabled };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const {
+      spaceType: sp,
+      ownerId: oid,
+      parentFolderId: pid,
+      q: qq,
+      enabled: en,
+    } = argsRef.current;
+    if (!en || !oid) {
+      setLoading(false);
+      setError(null);
+      setFolders([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await foldersApiRef.current.list({
+        space_type: String(sp || "project").toUpperCase(),
+        owner_id: oid,
+        parent_folder_id: pid || undefined,
+        q: qq || undefined,
+      });
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      if (runRef.current !== myRun) return;
+      setFolders(rows);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  const key = `${enabled ? 1 : 0}|${spaceType}|${ownerId}|${parentFolderId}|${q || ""}`;
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { folders, loading, error, refetch };
+}
+
+/**
+ * Drive a BankID signing flow for one Filestore file. Returns
+ * `{ status, qr, autoStartToken, message, signerName, signedAt, verdict,
+ * loading, error, initiate, refresh, cancel, verify }`.
+ *
+ * `initiate()` opens a sign order against the file (the backend hashes its
+ * bytes SERVER-SIDE and binds the digest into the BankID signature); `refresh()`
+ * polls the order (surfacing a fresh animated-QR frame while pending — render
+ * it with the `Image` primitive); `cancel()` aborts it; `verify()` re-runs the
+ * offline verification and returns the verdict (`{ valid, content_status, … }`).
+ * Reads `ctx.filestore.signatures.{initiate,status,cancel,verify}`. When
+ * `fileId` is null/empty the hook collapses to a no-op.
+ *
+ * Pass `existingSignatureId` for a file that is ALREADY signed: the hook seeds
+ * that order id (status `complete`) so the widget can show the signed state and
+ * `verify()` it WITHOUT opening a new order — re-signing then requires an
+ * explicit `initiate()`.
+ */
+export function useFileSignature(fileId, existingSignatureId = null) {
+  const ctx = useWidgetContextOrThrow("useFileSignature");
+  if (!ctx.filestore || !ctx.filestore.signatures) {
+    throw new Error(
+      "useFileSignature: host did not inject a filestore client (ctx.filestore.signatures)",
+    );
+  }
+  const ready = Boolean(fileId);
+  const sigRef = useRef(ctx.filestore.signatures);
+  sigRef.current = ctx.filestore.signatures;
+  const fileIdRef = useRef(fileId);
+  fileIdRef.current = fileId;
+  // Seed the order from an already-completed signature so verify() works
+  // without initiating; initiate() (an explicit re-sign) overwrites it.
+  const orderRef = useRef(existingSignatureId || null);
+
+  const [status, setStatus] = useState(existingSignatureId ? "complete" : null);
+  const [qr, setQr] = useState(null);
+  const [autoStartToken, setAutoStartToken] = useState(null);
+  const [message, setMessage] = useState(null);
+  const [signerName, setSignerName] = useState(null);
+  const [signedAt, setSignedAt] = useState(null);
+  const [verdict, setVerdict] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const initiate = useCallback(async () => {
+    if (!fileIdRef.current) return null;
+    setLoading(true);
+    setError(null);
+    setVerdict(null);
+    try {
+      const res = await sigRef.current.initiate(fileIdRef.current);
+      orderRef.current = res && res.signature_id ? res.signature_id : null;
+      setStatus(res && res.status ? res.status : "pending");
+      setQr(res && res.qr ? res.qr : null);
+      setAutoStartToken(res && res.auto_start_token ? res.auto_start_token : null);
+      setSignerName(null);
+      setSignedAt(null);
+      setMessage(null);
+      setLoading(false);
+      return res;
+    } catch (err) {
+      setError(toPermissionError(err));
+      setLoading(false);
+      throw toPermissionError(err);
+    }
+  }, []);
+
+  const refresh = useCallback(async () => {
+    const id = orderRef.current;
+    if (!id) return;
+    try {
+      const res = await sigRef.current.status(id);
+      if (res) {
+        if (res.status != null) setStatus(res.status);
+        if (res.qr !== undefined) setQr(res.qr || null);
+        if (res.message !== undefined) setMessage(res.message || null);
+        if (res.signer_name !== undefined) setSignerName(res.signer_name || null);
+        if (res.signed_at !== undefined) setSignedAt(res.signed_at || null);
+      }
+    } catch (err) {
+      setError(toPermissionError(err));
+    }
+  }, []);
+
+  const cancel = useCallback(async () => {
+    const id = orderRef.current;
+    if (!id) return;
+    try {
+      await sigRef.current.cancel(id);
+      setStatus("cancelled");
+      setQr(null);
+    } catch (err) {
+      throw toPermissionError(err);
+    }
+  }, []);
+
+  const verify = useCallback(async () => {
+    const id = orderRef.current;
+    if (!id) return null;
+    try {
+      const v = await sigRef.current.verify(id);
+      setVerdict(v);
+      return v;
+    } catch (err) {
+      setError(toPermissionError(err));
+      throw toPermissionError(err);
+    }
+  }, []);
+
+  if (!ready) {
+    return {
+      status: null,
+      qr: null,
+      autoStartToken: null,
+      message: null,
+      signerName: null,
+      signedAt: null,
+      verdict: null,
+      loading: false,
+      error: null,
+      initiate: async () => null,
+      refresh: async () => undefined,
+      cancel: async () => undefined,
+      verify: async () => null,
+    };
+  }
+  return {
+    status,
+    qr,
+    autoStartToken,
+    message,
+    signerName,
+    signedAt,
+    verdict,
+    loading,
+    error,
+    initiate,
+    refresh,
+    cancel,
+    verify,
+  };
+}
+
+/**
+ * Batch "is this file signed?" lookup for a set of file ids. Returns
+ * `{ signaturesByFileId, loading, error, refetch }` where `signaturesByFileId`
+ * maps each signed, accessible file id to its latest signature
+ * (`{ signature_id, signer_name, signed_at }`); unsigned files are simply
+ * absent. Lets a file browser mark already-signed files in one request (no
+ * N+1). Reads `ctx.filestore.signatures.list(fileIds)` and unwraps the
+ * `{ data, meta }` envelope. An empty/falsy id list resolves to an empty map
+ * without a network round-trip.
+ */
+export function useFileSignatures(fileIds) {
+  const ctx = useWidgetContextOrThrow("useFileSignatures");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.signatures ||
+    typeof ctx.filestore.signatures.list !== "function"
+  ) {
+    throw new Error(
+      "useFileSignatures: host did not inject a filestore client (ctx.filestore.signatures.list)",
+    );
+  }
+  const ids = Array.isArray(fileIds) ? fileIds.filter(Boolean) : [];
+  const key = ids.slice().sort().join(",");
+
+  const [signaturesByFileId, setSignaturesByFileId] = useState({});
+  const [loading, setLoading] = useState(ids.length > 0);
+  const [error, setError] = useState(null);
+
+  const sigRef = useRef(ctx.filestore.signatures);
+  sigRef.current = ctx.filestore.signatures;
+  const keyRef = useRef(key);
+  keyRef.current = key;
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const currentIds = keyRef.current ? keyRef.current.split(",") : [];
+    if (currentIds.length === 0) {
+      setLoading(false);
+      setError(null);
+      setSignaturesByFileId({});
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await sigRef.current.list(currentIds);
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      if (runRef.current !== myRun) return;
+      const map = {};
+      for (const row of rows) {
+        if (row && row.subject_file_id) map[row.subject_file_id] = row;
+      }
+      setSignaturesByFileId(map);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  return { signaturesByFileId, loading, error, refetch };
+}
+
 /* ============================================================================
  * DIRECTORY CLIENT — ctx.directory (@colixsystems/directory-client)
  *

package/dist/index.js

@@ -15,6 +15,10 @@ export {
   useDatastoreRecord,
   useDatastoreSchema,
   useFile,
+  useFilestoreFiles,
+  useFilestoreFolders,
+  useFileSignature,
+  useFileSignatures,
   useDatastoreMutation,
   useDirectory,
   useUsers,

package/dist/index.native.js

@@ -15,6 +15,10 @@ export {
   useDatastoreRecord,
   useDatastoreSchema,
   useFile,
+  useFilestoreFiles,
+  useFilestoreFolders,
+  useFileSignature,
+  useFileSignatures,
   useDatastoreMutation,
   useDirectory,
   useUsers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",