@colixsystems/widget-sdk 0.133.0 → 0.133.1

package/README.md

@@ -35,32 +35,32 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
-| **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). **Background watch (sc-6450)** — `startBackgroundWatch({ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs })` keeps positions arriving while the app is backgrounded; `stopBackgroundWatch()` releases it. NATIVE-ONLY and opt-in per app: gate the control on `backgroundSupported` (false on web, and in an export whose workspace did not opt in). The watch outlives the widget's mount, and its positions land in the same `latitude`/`longitude`/`accuracy` slots. |
-| **CORE** | `useSpeechToText(options?)` | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
-| **CORE** | `useCamera(options?)` | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). |
+| **CORE** | `useGeolocation(options)` (optional: options) | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). **Background watch (sc-6450)** — `startBackgroundWatch({ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs })` keeps positions arriving while the app is backgrounded; `stopBackgroundWatch()` releases it. NATIVE-ONLY and opt-in per app: gate the control on `backgroundSupported` (false on web, and in an export whose workspace did not opt in). The watch outlives the widget's mount, and its positions land in the same `latitude`/`longitude`/`accuracy` slots. |
+| **CORE** | `useSpeechToText(options)` (optional: options) | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
+| **CORE** | `useCamera(options)` (optional: options) | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
-| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
+| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
-| **DATASTORE** | `useDatastoreSubscription(table, handlers, options?)` | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
-| **DATASTORE** | `useCanWrite(tableId, options?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
+| **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
-| **FILES** | `useAssetsByTag(tag, { type? })` | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
-| **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
-| **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
-| **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
-| **DIRECTORY** | `useInvites(query?)` | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
+| **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
+| **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
+| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
+| **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
+| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
-| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId? })` | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side and saves it as a file (`application/pdf`); same server-side renderer on web + native. |
+| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: folderId) | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side and saves it as a file (`application/pdf`); same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
-| **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider?, purpose?, pollIntervalMs? })` | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. |
+| **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider, purpose, pollIntervalMs })` (optional: every key, and the whole argument) | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
 
@@ -70,7 +70,13 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.133.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.133.1` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.133.1 (contract 1.102.1)
+
+**Hook signatures no longer carry doc-style optional markers (sc-6946).** `CONTRACT.hooks[].signature` used to write optionality inline — `useFilestoreFiles({ spaceType, folderId?, q?, type? })` — but a `?` inside a destructuring pattern or object literal is a parse error, and the AI widget agent renders those signatures into its prompt verbatim. Every signature is now a call form that parses; the omittable parts moved to a new `optionalArgs` array the prompt prints beside it. The hook table above was rewritten to match (the version history below is left as each release wrote it).
+
+- **Documentation only.** No hook gained, lost, or changed an argument — `useFilestoreFiles({ spaceType })` and `useDirectory()` behave exactly as before. Only the way the contract *writes down* which arguments are optional has changed.
 
 ### What's new in 0.133.0 (contract 1.102.0)
 

package/dist/contract.cjs

@@ -793,7 +793,8 @@ const HOOKS = [
   },
   {
     name: "useAssetsByTag",
-    signature: "useAssetsByTag(tag, { type? } = {})",
+    signature: "useAssetsByTag(tag, { type })",
+    optionalArgs: ["type"],
     description:
       "List every tenant asset carrying a given tag. Backs the Gallery " +
       "widget's tag-source mode but is a general SDK primitive — any widget " +
@@ -815,7 +816,8 @@ const HOOKS = [
   },
   {
     name: "useFilestoreFiles",
-    signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
+    signature: "useFilestoreFiles({ spaceType, folderId, q, type })",
+    optionalArgs: ["folderId", "q", "type"],
     description:
       "Browse the end-user's Filestore files in a project, personal, or public " +
       "space. The hook resolves owner_id from the host context (tenant for " +
@@ -876,7 +878,8 @@ const HOOKS = [
   },
   {
     name: "useFilestoreUpload",
-    signature: "useFilestoreUpload({ spaceType, folderId?, compress? })",
+    signature: "useFilestoreUpload({ spaceType, folderId, compress })",
+    optionalArgs: ["folderId", "compress"],
     description:
       "Upload a file into the end-user's Filestore space. The widget passes " +
       "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
@@ -914,7 +917,8 @@ const HOOKS = [
   },
   {
     name: "usePdfExport",
-    signature: "usePdfExport({ spaceType, folderId? })",
+    signature: "usePdfExport({ spaceType, folderId })",
+    optionalArgs: ["folderId"],
     description:
       "Render an HTML string to a PDF server-side and SAVE it as a file in " +
       "the end-user's Filestore space. The widget passes the SPACE " +
@@ -939,7 +943,8 @@ const HOOKS = [
   },
   {
     name: "useFilestoreFolders",
-    signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
+    signature: "useFilestoreFolders({ spaceType, parentFolderId, q, enabled })",
+    optionalArgs: ["parentFolderId", "q", "enabled"],
     description:
       "Browse the end-user's Filestore folders in a project, personal, or public " +
       "space, mirroring useFilestoreFiles for subfolder navigation. The hook " +
@@ -956,7 +961,8 @@ const HOOKS = [
   },
   {
     name: "useFileSignature",
-    signature: "useFileSignature(fileId, existingSignatureId?)",
+    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() " +
@@ -1003,7 +1009,8 @@ const HOOKS = [
   },
   {
     name: "useFileRoster",
-    signature: "useFileRoster(fileId, { limit?, offset?, enabled? }?)",
+    signature: "useFileRoster(fileId, { limit, offset, enabled })",
+    optionalArgs: ["limit", "offset", "enabled"],
     description:
       "MANAGE-gated signer roster for one Filestore file: the people expected " +
       "to be able to sign it (the file's folder audience) each annotated " +
@@ -1025,7 +1032,8 @@ const HOOKS = [
   },
   {
     name: "useFolderPermissions",
-    signature: "useFolderPermissions(folderId, { enabled? }?)",
+    signature: "useFolderPermissions(folderId, { enabled })",
+    optionalArgs: ["enabled"],
     description:
       "Manage a folder's permissions (the Filestore ACL — folder-scoped). Lists " +
       "the folder's grants and exposes grant(subjectType, subjectId, permission) " +
@@ -1048,7 +1056,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreQuery",
-    signature: "useDatastoreQuery(tableId, options?)",
+    signature: "useDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
     returnShape: {
       data: "Record[]",
       loading: "boolean",
@@ -1155,7 +1164,8 @@ const HOOKS = [
   },
   {
     name: "useDirectory",
-    signature: "useDirectory(query?)",
+    signature: "useDirectory(query)",
+    optionalArgs: ["query"],
     returnShape: {
       users: "Array<{ id, name, role }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -1250,7 +1260,8 @@ const HOOKS = [
   // that only call read methods need only `users.read:*`.
   {
     name: "useUsers",
-    signature: "useUsers(query?)",
+    signature: "useUsers(query)",
+    optionalArgs: ["query"],
     description:
       "AppUser administration via the injected directory-client at " +
       "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
@@ -1292,7 +1303,8 @@ const HOOKS = [
   // affects the user's effective access.
   {
     name: "useGroups",
-    signature: "useGroups(query?)",
+    signature: "useGroups(query)",
+    optionalArgs: ["query"],
     description:
       "AppUserGroup administration via the injected directory-client at " +
       "ctx.directory.groups.{list,create,remove,addMember,removeMember,listMine}. " +
@@ -1322,7 +1334,8 @@ const HOOKS = [
   // caller's `users.write` SystemAcl capability.
   {
     name: "useInvites",
-    signature: "useInvites(query?)",
+    signature: "useInvites(query)",
+    optionalArgs: ["query"],
     description:
       "Pending AppUser invite administration via the injected " +
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
@@ -1394,7 +1407,8 @@ const HOOKS = [
   // result. Anonymous by design (no widget scope, no session). Mirror of contract.js.
   {
     name: "useIdentification",
-    signature: "useIdentification(options?)",
+    signature: "useIdentification(options)",
+    optionalArgs: ["options"],
     description:
       "Identify a visitor who is NOT signed in via the injected " +
       "identification-client at ctx.identification.{available,start,get,cancel}. " +
@@ -1478,7 +1492,8 @@ const HOOKS = [
   // ctx.datastore.myPermissions.
   {
     name: "useCanWrite",
-    signature: "useCanWrite(tableId, options?)",
+    signature: "useCanWrite(tableId, options)",
+    optionalArgs: ["options"],
     description:
       "sc-5206 — is the signed-in caller permitted to write to tableId (or, with options.recordId, to that one row)? Returns { canWrite, loading, " +
       "error, refetch }, reading the injected ctx.datastore.myPermissions(tableId, { recordId }). This is a FLOOR, not a full replacement for " +
@@ -1499,7 +1514,8 @@ const HOOKS = [
   // REQ-RT-07 — realtime table subscription.
   {
     name: "useDatastoreSubscription",
-    signature: "useDatastoreSubscription(tableId, handlers, options?)",
+    signature: "useDatastoreSubscription(tableId, handlers, options)",
+    optionalArgs: ["options"],
     description:
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
@@ -1571,7 +1587,8 @@ const HOOKS = [
   // degrades to an UNSUPPORTED error rather than throwing at render.
   {
     name: "useGeolocation",
-    signature: "useGeolocation(options?)",
+    signature: "useGeolocation(options)",
+    optionalArgs: ["options"],
     description:
       "Read the device's current position. Returns { latitude, longitude, accuracy, loading, error, getCurrentPosition }. " +
       "Capture is IMPERATIVE — call getCurrentPosition() from a user gesture (a tap); browsers and the mobile OS gate the " +
@@ -1612,7 +1629,8 @@ const HOOKS = [
   // reports supported:false rather than throwing at render.
   {
     name: "useSpeechToText",
-    signature: "useSpeechToText(options?)",
+    signature: "useSpeechToText(options)",
+    optionalArgs: ["options"],
     description:
       "Dictate into text with the device's ON-DEVICE speech recogniser. Returns { transcript, partial, listening, supported, " +
       "error, start, stop, abort, reset }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a mic button); " +
@@ -1641,7 +1659,8 @@ const HOOKS = [
   // the hook reports supported:false rather than throwing at render.
   {
     name: "useCamera",
-    signature: "useCamera(options?)",
+    signature: "useCamera(options)",
+    optionalArgs: ["options"],
     description:
       "Take a photo or choose one from the device library. Returns { asset, loading, error, supported, capture, pick, reset }. " +
       "Capture is IMPERATIVE — call capture() or pick() from a user gesture (a tap); the browser and the mobile OS gate the " +
@@ -1674,7 +1693,8 @@ const HOOKS = [
   // reports supported:false rather than throwing at render.
   {
     name: "useBarcodeScanner",
-    signature: "useBarcodeScanner(options?)",
+    signature: "useBarcodeScanner(options)",
+    optionalArgs: ["options"],
     description:
       "Read a barcode or QR code with the device camera. Returns { result, scanning, error, supported, scan, reset }. " +
       "Scanning is IMPERATIVE — call scan() from a user gesture (a tap); the browser and the mobile OS gate the camera " +
@@ -3851,7 +3871,15 @@ const CONTRACT = deepFreeze({
   //    §7: a breaking change to a shipped package needs a reason, and there is
   //    none here). Only the MANDATE to emit it is gone, from the AI widget
   //    agent prompt and the designer skill. Minor bump: nothing removed.
-  version: "1.102.0",
+  // 1.102.1: fix (sc-6946) — hook signatures carried doc-style OPTIONAL
+  //    markers (`useFilestoreFiles({ spaceType, folderId?, q?, type? })`).
+  //    A signature invites a literal copy, and a `?` inside a destructuring
+  //    pattern or object literal is a parse error — so the AI widget agent
+  //    prompt, which renders these verbatim, was itself teaching source that
+  //    fails the publish gate. Every signature is now a valid call and the
+  //    omittable parts moved to a new `optionalArgs` array the prompt prints
+  //    beside it. Documentation only; no hook changed shape or behaviour.
+  version: "1.102.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -793,7 +793,8 @@ const HOOKS = [
   },
   {
     name: "useAssetsByTag",
-    signature: "useAssetsByTag(tag, { type? } = {})",
+    signature: "useAssetsByTag(tag, { type })",
+    optionalArgs: ["type"],
     description:
       "List every tenant asset carrying a given tag. Backs the Gallery " +
       "widget's tag-source mode but is a general SDK primitive — any widget " +
@@ -815,7 +816,8 @@ const HOOKS = [
   },
   {
     name: "useFilestoreFiles",
-    signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
+    signature: "useFilestoreFiles({ spaceType, folderId, q, type })",
+    optionalArgs: ["folderId", "q", "type"],
     description:
       "Browse the end-user's Filestore files in a project, personal, or public " +
       "space. The hook resolves owner_id from the host context (tenant for " +
@@ -876,7 +878,8 @@ const HOOKS = [
   },
   {
     name: "useFilestoreUpload",
-    signature: "useFilestoreUpload({ spaceType, folderId?, compress? })",
+    signature: "useFilestoreUpload({ spaceType, folderId, compress })",
+    optionalArgs: ["folderId", "compress"],
     description:
       "Upload a file into the end-user's Filestore space. The widget passes " +
       "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
@@ -914,7 +917,8 @@ const HOOKS = [
   },
   {
     name: "usePdfExport",
-    signature: "usePdfExport({ spaceType, folderId? })",
+    signature: "usePdfExport({ spaceType, folderId })",
+    optionalArgs: ["folderId"],
     description:
       "Render an HTML string to a PDF server-side and SAVE it as a file in " +
       "the end-user's Filestore space. The widget passes the SPACE " +
@@ -939,7 +943,8 @@ const HOOKS = [
   },
   {
     name: "useFilestoreFolders",
-    signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
+    signature: "useFilestoreFolders({ spaceType, parentFolderId, q, enabled })",
+    optionalArgs: ["parentFolderId", "q", "enabled"],
     description:
       "Browse the end-user's Filestore folders in a project, personal, or public " +
       "space, mirroring useFilestoreFiles for subfolder navigation. The hook " +
@@ -956,7 +961,8 @@ const HOOKS = [
   },
   {
     name: "useFileSignature",
-    signature: "useFileSignature(fileId, existingSignatureId?)",
+    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() " +
@@ -1003,7 +1009,8 @@ const HOOKS = [
   },
   {
     name: "useFileRoster",
-    signature: "useFileRoster(fileId, { limit?, offset?, enabled? }?)",
+    signature: "useFileRoster(fileId, { limit, offset, enabled })",
+    optionalArgs: ["limit", "offset", "enabled"],
     description:
       "MANAGE-gated signer roster for one Filestore file: the people expected " +
       "to be able to sign it (the file's folder audience) each annotated " +
@@ -1025,7 +1032,8 @@ const HOOKS = [
   },
   {
     name: "useFolderPermissions",
-    signature: "useFolderPermissions(folderId, { enabled? }?)",
+    signature: "useFolderPermissions(folderId, { enabled })",
+    optionalArgs: ["enabled"],
     description:
       "Manage a folder's permissions (the Filestore ACL — folder-scoped). Lists " +
       "the folder's grants and exposes grant(subjectType, subjectId, permission) " +
@@ -1048,7 +1056,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreQuery",
-    signature: "useDatastoreQuery(tableId, options?)",
+    signature: "useDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
     returnShape: {
       data: "Record[]",
       loading: "boolean",
@@ -1155,7 +1164,8 @@ const HOOKS = [
   },
   {
     name: "useDirectory",
-    signature: "useDirectory(query?)",
+    signature: "useDirectory(query)",
+    optionalArgs: ["query"],
     returnShape: {
       users: "Array<{ id, name, role }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -1250,7 +1260,8 @@ const HOOKS = [
   // that only call read methods need only `users.read:*`.
   {
     name: "useUsers",
-    signature: "useUsers(query?)",
+    signature: "useUsers(query)",
+    optionalArgs: ["query"],
     description:
       "AppUser administration via the injected directory-client at " +
       "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
@@ -1292,7 +1303,8 @@ const HOOKS = [
   // affects the user's effective access.
   {
     name: "useGroups",
-    signature: "useGroups(query?)",
+    signature: "useGroups(query)",
+    optionalArgs: ["query"],
     description:
       "AppUserGroup administration via the injected directory-client at " +
       "ctx.directory.groups.{list,create,remove,addMember,removeMember,listMine}. " +
@@ -1322,7 +1334,8 @@ const HOOKS = [
   // caller's `users.write` SystemAcl capability.
   {
     name: "useInvites",
-    signature: "useInvites(query?)",
+    signature: "useInvites(query)",
+    optionalArgs: ["query"],
     description:
       "Pending AppUser invite administration via the injected " +
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
@@ -1394,7 +1407,8 @@ const HOOKS = [
   // result. Anonymous by design (no widget scope, no session). Mirror of contract.cjs.
   {
     name: "useIdentification",
-    signature: "useIdentification(options?)",
+    signature: "useIdentification(options)",
+    optionalArgs: ["options"],
     description:
       "Identify a visitor who is NOT signed in via the injected " +
       "identification-client at ctx.identification.{available,start,get,cancel}. " +
@@ -1478,7 +1492,8 @@ const HOOKS = [
   // ctx.datastore.myPermissions.
   {
     name: "useCanWrite",
-    signature: "useCanWrite(tableId, options?)",
+    signature: "useCanWrite(tableId, options)",
+    optionalArgs: ["options"],
     description:
       "sc-5206 — is the signed-in caller permitted to write to tableId (or, with options.recordId, to that one row)? Returns { canWrite, loading, " +
       "error, refetch }, reading the injected ctx.datastore.myPermissions(tableId, { recordId }). This is a FLOOR, not a full replacement for " +
@@ -1499,7 +1514,8 @@ const HOOKS = [
   // REQ-RT-07 — realtime table subscription.
   {
     name: "useDatastoreSubscription",
-    signature: "useDatastoreSubscription(tableId, handlers, options?)",
+    signature: "useDatastoreSubscription(tableId, handlers, options)",
+    optionalArgs: ["options"],
     description:
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
@@ -1571,7 +1587,8 @@ const HOOKS = [
   // degrades to an UNSUPPORTED error rather than throwing at render.
   {
     name: "useGeolocation",
-    signature: "useGeolocation(options?)",
+    signature: "useGeolocation(options)",
+    optionalArgs: ["options"],
     description:
       "Read the device's current position. Returns { latitude, longitude, accuracy, loading, error, getCurrentPosition }. " +
       "Capture is IMPERATIVE — call getCurrentPosition() from a user gesture (a tap); browsers and the mobile OS gate the " +
@@ -1612,7 +1629,8 @@ const HOOKS = [
   // reports supported:false rather than throwing at render.
   {
     name: "useSpeechToText",
-    signature: "useSpeechToText(options?)",
+    signature: "useSpeechToText(options)",
+    optionalArgs: ["options"],
     description:
       "Dictate into text with the device's ON-DEVICE speech recogniser. Returns { transcript, partial, listening, supported, " +
       "error, start, stop, abort, reset }. Capture is IMPERATIVE — call start() from a user gesture (a tap on a mic button); " +
@@ -1641,7 +1659,8 @@ const HOOKS = [
   // the hook reports supported:false rather than throwing at render.
   {
     name: "useCamera",
-    signature: "useCamera(options?)",
+    signature: "useCamera(options)",
+    optionalArgs: ["options"],
     description:
       "Take a photo or choose one from the device library. Returns { asset, loading, error, supported, capture, pick, reset }. " +
       "Capture is IMPERATIVE — call capture() or pick() from a user gesture (a tap); the browser and the mobile OS gate the " +
@@ -1674,7 +1693,8 @@ const HOOKS = [
   // reports supported:false rather than throwing at render.
   {
     name: "useBarcodeScanner",
-    signature: "useBarcodeScanner(options?)",
+    signature: "useBarcodeScanner(options)",
+    optionalArgs: ["options"],
     description:
       "Read a barcode or QR code with the device camera. Returns { result, scanning, error, supported, scan, reset }. " +
       "Scanning is IMPERATIVE — call scan() from a user gesture (a tap); the browser and the mobile OS gate the camera " +
@@ -3851,7 +3871,15 @@ const CONTRACT = deepFreeze({
   //    §7: a breaking change to a shipped package needs a reason, and there is
   //    none here). Only the MANDATE to emit it is gone, from the AI widget
   //    agent prompt and the designer skill. Minor bump: nothing removed.
-  version: "1.102.0",
+  // 1.102.1: fix (sc-6946) — hook signatures carried doc-style OPTIONAL
+  //    markers (`useFilestoreFiles({ spaceType, folderId?, q?, type? })`).
+  //    A signature invites a literal copy, and a `?` inside a destructuring
+  //    pattern or object literal is a parse error — so the AI widget agent
+  //    prompt, which renders these verbatim, was itself teaching source that
+  //    fails the publish gate. Every signature is now a valid call and the
+  //    omittable parts moved to a new `optionalArgs` array the prompt prints
+  //    beside it. Documentation only; no hook changed shape or behaviour.
+  version: "1.102.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -2600,6 +2600,8 @@ export function lintSource(
 export interface ContractHookEntry {
   name: string;
   signature: string;
+  /** Arguments and option keys in `signature` that may be omitted (sc-6946). */
+  optionalArgs?: string[];
   returnShape: Record<string, string>;
   requiredContextSlice: string[];
   scopes: string[] | null;

package/package.json

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