@colixsystems/widget-sdk 0.90.0 → 0.92.0

package/README.md

@@ -35,11 +35,13 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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 }` | `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`). |
+| **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** | `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. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, 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** | `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** | `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) |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
@@ -61,6 +63,30 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
+`v0.91.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.92.0 (contract 1.65.0)
+
+**New `useInterpretDraft(tableId)` hook — turn one sentence into DRAFT record values.** A new DATASTORE hook reading a new `interpret` method on the existing `ctx.datastore` slice (`@colixsystems/datastore-client` 0.13.0). Returns `{ interpret, interpreting, error, result, available }`. Call `interpret(text, { fields, timeZone })` **imperatively** from an event handler — never on mount or in a render loop — and it resolves to `{ values, unresolved }`, where `values` is keyed by column NAME (the same shape `useDatastoreMutation().create` takes) and `unresolved` names the fields the sentence did not state.
+
+**It DRAFTS and writes nothing.** Prefill your inputs from `values`, let the person review and correct them, then submit as usual. A model reading free text must never create a record on its own.
+
+Only columns a sentence can honestly produce are drafted — string, text, number, float, boolean, date, datetime and array. `FILE`, `RELATION`, `USER` and `USER_GROUP` are never guessed because they carry identifiers, and encrypted columns are skipped. Every value is coerced against its column's `data_type` and dropped when it does not fit, so a value the model got wrong is reported `unresolved` rather than written through.
+
+**Every call spends the workspace's AI credits** and is rate-limited per actor. Once the workspace runs out, the call is refused with a **generic** 429: the person filling the form is never told the workspace's billing state — they have not heard of an AI credit and cannot buy one. Never surface a raw error to them; say drafting is unavailable and keep every field editable by hand. `available` is `false` where the host brokers no interpreter (an unbound preview, or an export with no reachable backend) — hide the affordance rather than rendering a dead button.
+
+Additive — one new hook, one new client method, one new context-slice function; no existing export changed signature.
+
+### What's new in 0.91.0 (contract 1.64.0)
+
+**New `useSpeechToText()` hook — dictate into text with the device's on-device recogniser.** A new CORE hook reading a new `speech` capability on the existing `ctx.device` slice. Returns `{ transcript, partial, listening, supported, error, start, stop, abort, reset }`. Capture is **imperative** — call `start()` from a user gesture (a `Pressable.onPress`); the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` accumulates finalised speech across utterances; `partial` holds the guess the recogniser has not committed yet (empty unless `options.interimResults`). `stop()` finalises and keeps what was heard, `abort()` discards the current utterance, `reset()` clears both. `options` (`{ lang, continuous, interimResults }`) pass through to the host. Rejections surface as a structured `SpeechToTextError` (new named export) with a stable `.code` (`PERMISSION_DENIED` / `NO_SPEECH` / `LANGUAGE_UNSUPPORTED` / `NETWORK` / `ABORTED` / `UNSUPPORTED` / `INTERNAL`). It needs **no manifest scope** and **no `requestedScopes` entry**.
+
+Recognition runs **on device**: no audio is uploaded, nothing reaches our servers, and no AI credit is spent — so the hook is available to every workspace regardless of its AI data-residency policy. The web Player brokers it via the browser's `SpeechRecognition`; the Expo export via `expo-speech-recognition`, whose config plugin declares the microphone and speech permissions the runtime needs. Both hosts emit the same Web Speech error vocabulary, so one mapping serves both.
+
+**Always gate your mic affordance on `supported`.** Firefox ships no `SpeechRecognition` at all, so `supported` is `false` there and `start()` rejects with `UNSUPPORTED` — render the plain text field instead of a dead button. The `speech` capability is optional and forwarded independently of `geolocation`, so a host that brokers one still brokers the other.
+
+Additive — one new hook, one new optional device capability, one new error class; no existing export changed signature.
+
 `v0.90.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.89.0 (contract unchanged)

package/dist/contract.cjs

@@ -820,6 +820,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.schema"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useInterpretDraft",
+    signature: "useInterpretDraft(tableId)",
+    description:
+      "sc-4932 — turns ONE sentence a user typed into DRAFT values for the " +
+      "table's columns (\"walk at 11 am tomorrow\" -> { title: 'Walk', " +
+      "due_at: '...T11:00' }). IMPERATIVE: call interpret(text, { fields, " +
+      "timeZone }) from an event handler (a button press), never on mount. It " +
+      "DRAFTS and writes NOTHING — prefill your form from `values`, let the " +
+      "user review and correct it, then submit through " +
+      "useDatastoreMutation().create as usual. `values` is keyed by column " +
+      "NAME, the same shape create() takes. `unresolved` lists the fields the " +
+      "sentence did not state — leave those blank rather than guessing. Pass " +
+      "`fields` to narrow the draft to the columns you actually render, each " +
+      "optionally carrying a dropdown's closed `options` list; pass `timeZone` " +
+      "(an IANA zone) so relative times resolve correctly. Only text, number, " +
+      "boolean, date/datetime and array columns are drafted — FILE, RELATION, " +
+      "USER and USER_GROUP columns are never guessed because they carry ids. " +
+      "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 of credits the call is refused with a " +
+      "generic 429 (an app user is never told the workspace's billing state — " +
+      "they have not 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. Reads ctx.datastore.interpret.",
+    returnShape: {
+      interpret:
+        "(text, { fields?, timeZone? }) => Promise<{ values, unresolved }>",
+      interpreting: "boolean",
+      error: "DatastoreError | null",
+      result: "{ values, unresolved } | null",
+      available: "boolean  // false when the host brokers no interpreter",
+    },
+    requiredContextSlice: ["datastore.interpret"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -1194,6 +1230,35 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // Host-brokered on-device speech recognition. Optional slice; the hook
+  // reports supported:false rather than throwing at render.
+  {
+    name: "useSpeechToText",
+    signature: "useSpeechToText(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); " +
+      "the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` " +
+      "accumulates finalised speech; `partial` holds the uncommitted guess (empty unless options.interimResults). stop() " +
+      "finalises and keeps what was heard, abort() discards it, reset() clears both. Recognition runs ON DEVICE — no audio is " +
+      "uploaded and no AI credit is spent. start() rejects with a SpeechToTextError whose .code is one of PERMISSION_DENIED | " +
+      "NO_SPEECH | LANGUAGE_UNSUPPORTED | NETWORK | ABORTED | UNSUPPORTED | INTERNAL. options: { lang, continuous, " +
+      "interimResults }. Check `supported` before rendering a mic button — a browser without SpeechRecognition (Firefox) " +
+      "reports false. Identical on web (SpeechRecognition) and the Expo export (expo-speech-recognition).",
+    returnShape: {
+      transcript: "string  // finalised speech, accumulated",
+      partial: "string  // uncommitted guess; '' unless interimResults",
+      listening: "boolean",
+      supported: "boolean  // false when the host brokers no recogniser",
+      error: "SpeechToTextError | null",
+      start: "() => Promise<void>  // rejects with SpeechToTextError",
+      stop: "() => Promise<void>  // finalise, keep the transcript",
+      abort: "() => void  // cancel, discard the utterance",
+      reset: "() => void  // clear transcript + partial + error",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1608,13 +1673,13 @@ const WIDGET_CONTEXT_SHAPE = {
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
-      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "{ tables: { list(), get(idOrName), interpret(idOrName, body) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
       "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
       "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
-      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing). " +
       "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function", tables: "object" },
+    fields: { records: "function", schema: "function", tables: "object", interpret: "function" },
   },
   directory: {
     description:
@@ -1769,11 +1834,15 @@ const WIDGET_CONTEXT_SHAPE = {
   device: {
     description:
       "Optional host-brokered device capabilities. " +
-      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
-      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
-      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
+      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> } }. " +
+      "Backs useGeolocation() and useSpeechToText(). The web Player brokers them via navigator.geolocation and " +
+      "window.SpeechRecognition; the Expo export via expo-location and expo-speech-recognition. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
+      "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
+      "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted).",
     required: false,
-    fields: { geolocation: "object" },
+    fields: { geolocation: "object", speech: "object" },
   },
 };
 
@@ -2822,7 +2891,7 @@ const CONTRACT = deepFreeze({
   //    published widget keeps validating. The script's `triggerType` global
   //    now names the trigger that actually FIRED the run ('manual' and 'app'
   //    included), which is what makes a multi-trigger script able to branch.
-  version: "1.63.0",
+  version: "1.65.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -820,6 +820,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.schema"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useInterpretDraft",
+    signature: "useInterpretDraft(tableId)",
+    description:
+      "sc-4932 — turns ONE sentence a user typed into DRAFT values for the " +
+      "table's columns (\"walk at 11 am tomorrow\" -> { title: 'Walk', " +
+      "due_at: '...T11:00' }). IMPERATIVE: call interpret(text, { fields, " +
+      "timeZone }) from an event handler (a button press), never on mount. It " +
+      "DRAFTS and writes NOTHING — prefill your form from `values`, let the " +
+      "user review and correct it, then submit through " +
+      "useDatastoreMutation().create as usual. `values` is keyed by column " +
+      "NAME, the same shape create() takes. `unresolved` lists the fields the " +
+      "sentence did not state — leave those blank rather than guessing. Pass " +
+      "`fields` to narrow the draft to the columns you actually render, each " +
+      "optionally carrying a dropdown's closed `options` list; pass `timeZone` " +
+      "(an IANA zone) so relative times resolve correctly. Only text, number, " +
+      "boolean, date/datetime and array columns are drafted — FILE, RELATION, " +
+      "USER and USER_GROUP columns are never guessed because they carry ids. " +
+      "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 of credits the call is refused with a " +
+      "generic 429 (an app user is never told the workspace's billing state — " +
+      "they have not 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. Reads ctx.datastore.interpret.",
+    returnShape: {
+      interpret:
+        "(text, { fields?, timeZone? }) => Promise<{ values, unresolved }>",
+      interpreting: "boolean",
+      error: "DatastoreError | null",
+      result: "{ values, unresolved } | null",
+      available: "boolean  // false when the host brokers no interpreter",
+    },
+    requiredContextSlice: ["datastore.interpret"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -1194,6 +1230,35 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // Host-brokered on-device speech recognition. Optional slice; the hook
+  // reports supported:false rather than throwing at render.
+  {
+    name: "useSpeechToText",
+    signature: "useSpeechToText(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); " +
+      "the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` " +
+      "accumulates finalised speech; `partial` holds the uncommitted guess (empty unless options.interimResults). stop() " +
+      "finalises and keeps what was heard, abort() discards it, reset() clears both. Recognition runs ON DEVICE — no audio is " +
+      "uploaded and no AI credit is spent. start() rejects with a SpeechToTextError whose .code is one of PERMISSION_DENIED | " +
+      "NO_SPEECH | LANGUAGE_UNSUPPORTED | NETWORK | ABORTED | UNSUPPORTED | INTERNAL. options: { lang, continuous, " +
+      "interimResults }. Check `supported` before rendering a mic button — a browser without SpeechRecognition (Firefox) " +
+      "reports false. Identical on web (SpeechRecognition) and the Expo export (expo-speech-recognition).",
+    returnShape: {
+      transcript: "string  // finalised speech, accumulated",
+      partial: "string  // uncommitted guess; '' unless interimResults",
+      listening: "boolean",
+      supported: "boolean  // false when the host brokers no recogniser",
+      error: "SpeechToTextError | null",
+      start: "() => Promise<void>  // rejects with SpeechToTextError",
+      stop: "() => Promise<void>  // finalise, keep the transcript",
+      abort: "() => void  // cancel, discard the utterance",
+      reset: "() => void  // clear transcript + partial + error",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -1608,13 +1673,13 @@ const WIDGET_CONTEXT_SHAPE = {
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
-      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "{ tables: { list(), get(idOrName), interpret(idOrName, body) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
       "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
       "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
-      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing). " +
       "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function", tables: "object" },
+    fields: { records: "function", schema: "function", tables: "object", interpret: "function" },
   },
   directory: {
     description:
@@ -1769,11 +1834,15 @@ const WIDGET_CONTEXT_SHAPE = {
   device: {
     description:
       "Optional host-brokered device capabilities. " +
-      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> } }. " +
-      "Backs useGeolocation(). The web Player brokers it via navigator.geolocation; the Expo export via expo-location. " +
-      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL).",
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
+      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> } }. " +
+      "Backs useGeolocation() and useSpeechToText(). The web Player brokers them via navigator.geolocation and " +
+      "window.SpeechRecognition; the Expo export via expo-location and expo-speech-recognition. " +
+      "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
+      "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
+      "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted).",
     required: false,
-    fields: { geolocation: "object" },
+    fields: { geolocation: "object", speech: "object" },
   },
 };
 
@@ -2822,7 +2891,7 @@ const CONTRACT = deepFreeze({
   //    published widget keeps validating. The script's `triggerType` global
   //    now names the trigger that actually FIRED the run ('manual' and 'app'
   //    included), which is what makes a multi-trigger script able to branch.
-  version: "1.63.0",
+  version: "1.65.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -916,6 +916,234 @@ export function useGeolocation(options) {
   };
 }
 
+/**
+ * Error surfaced by `useSpeechToText()` (thrown by `start()` and stored in the
+ * hook's `error` slot). Carries a stable `code` so widgets branch on the error
+ * class without parsing message strings.
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED"    — the user or OS refused microphone access.
+ *   - "NO_SPEECH"            — capture ended without any speech detected.
+ *   - "LANGUAGE_UNSUPPORTED" — no recogniser exists for the requested language.
+ *   - "NETWORK"              — the recogniser needed the network and failed.
+ *   - "ABORTED"              — capture was cancelled (abort(), or a new start()).
+ *   - "UNSUPPORTED"          — this host does not broker speech recognition.
+ *   - "INTERNAL"             — anything else.
+ */
+export class SpeechToTextError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "SpeechToTextError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+// Both hosts emit the Web Speech API's error vocabulary (the Expo export's
+// recogniser mirrors it deliberately), so one map serves web and native.
+const SPEECH_ERROR_CODES = {
+  "not-allowed": "PERMISSION_DENIED",
+  "service-not-allowed": "PERMISSION_DENIED",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  "no-speech": "NO_SPEECH",
+  NO_SPEECH: "NO_SPEECH",
+  // Android's recogniser reports a silence timeout instead of "no-speech".
+  "speech-timeout": "NO_SPEECH",
+  "language-not-supported": "LANGUAGE_UNSUPPORTED",
+  LANGUAGE_UNSUPPORTED: "LANGUAGE_UNSUPPORTED",
+  network: "NETWORK",
+  NETWORK: "NETWORK",
+  aborted: "ABORTED",
+  ABORTED: "ABORTED",
+  UNSUPPORTED: "UNSUPPORTED",
+};
+
+/** Coerce a thrown/emitted value into a SpeechToTextError with a stable code. */
+function toSpeechToTextError(err) {
+  if (err instanceof SpeechToTextError) return err;
+  const raw =
+    err && err.code !== undefined && err.code !== null ? err.code : null;
+  const code = (raw !== null && SPEECH_ERROR_CODES[raw]) || "INTERNAL";
+  const message =
+    (err && typeof err.message === "string" && err.message) ||
+    "Speech recognition failed";
+  return new SpeechToTextError(code, message, { cause: err });
+}
+
+/**
+ * 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). Both the browser and the mobile OS gate the microphone prompt on a
+ * user gesture, so the hook never listens on mount.
+ *
+ * `transcript` accumulates finalised speech; `partial` holds the in-flight
+ * guess the recogniser has not committed yet (empty unless
+ * `options.interimResults`). `stop()` finalises and keeps what was heard;
+ * `abort()` discards it. `reset()` clears both back to empty.
+ *
+ * Recognition runs ON DEVICE — no audio is uploaded and no AI credit is spent.
+ * The SAME hook drives both platforms: the web Player brokers it through the
+ * browser's SpeechRecognition, the Expo export through
+ * expo-speech-recognition.
+ *
+ * Safe-by-default: on a host that does not inject `ctx.device.speech` (or a
+ * browser without SpeechRecognition), `supported` is false and `start()`
+ * rejects with `code: "UNSUPPORTED"` rather than throwing at render, so a
+ * widget can call the hook unconditionally and hide its mic button.
+ */
+export function useSpeechToText(options) {
+  const ctx = useWidgetContextOrThrow("useSpeechToText");
+  const [transcript, setTranscript] = useState("");
+  const [partial, setPartial] = useState("");
+  const [listening, setListening] = useState(false);
+  const [error, setError] = useState(null);
+
+  // `ctx` is a fresh identity every host render — hold the live client and
+  // options in refs so the returned callbacks stay stable.
+  const clientRef = useRef(ctx.device && ctx.device.speech);
+  clientRef.current = ctx.device && ctx.device.speech;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  // The live capture session, so stop/abort/unmount can reach it.
+  const sessionRef = useRef(null);
+  const runRef = useRef(0);
+
+  const supported = Boolean(
+    clientRef.current &&
+    typeof clientRef.current.start === "function" &&
+    (typeof clientRef.current.isSupported !== "function" ||
+      clientRef.current.isSupported()),
+  );
+
+  // Abandoning a mounted recogniser leaves the mic hot on both hosts, so
+  // release it when the widget unmounts.
+  useEffect(
+    () => () => {
+      runRef.current += 1;
+      const session = sessionRef.current;
+      sessionRef.current = null;
+      if (session && typeof session.abort === "function") {
+        try {
+          session.abort();
+        } catch {
+          /* the host is already tearing the session down */
+        }
+      }
+    },
+    [],
+  );
+
+  const reset = useCallback(() => {
+    setTranscript("");
+    setPartial("");
+    setError(null);
+  }, []);
+
+  const stop = useCallback(async () => {
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    setListening(false);
+    setPartial("");
+    if (session && typeof session.stop === "function") await session.stop();
+  }, []);
+
+  const abort = useCallback(() => {
+    runRef.current += 1;
+    const session = sessionRef.current;
+    sessionRef.current = null;
+    setListening(false);
+    setPartial("");
+    if (session && typeof session.abort === "function") session.abort();
+  }, []);
+
+  const start = useCallback(async () => {
+    const client = clientRef.current;
+    if (
+      !client ||
+      typeof client.start !== "function" ||
+      (typeof client.isSupported === "function" && !client.isSupported())
+    ) {
+      const e = new SpeechToTextError(
+        "UNSUPPORTED",
+        "This host does not provide speech recognition.",
+      );
+      setError(e);
+      setListening(false);
+      throw e;
+    }
+    // A second start() supersedes the first: drop the old session's events.
+    const myRun = ++runRef.current;
+    const previous = sessionRef.current;
+    sessionRef.current = null;
+    if (previous && typeof previous.abort === "function") previous.abort();
+
+    setError(null);
+    setPartial("");
+    setListening(true);
+    try {
+      const session = await client.start(optionsRef.current || {}, {
+        onResult: (result) => {
+          if (runRef.current !== myRun) return;
+          const text =
+            result && typeof result.transcript === "string"
+              ? result.transcript
+              : "";
+          if (result && result.isFinal) {
+            setPartial("");
+            // Append rather than replace: a continuous session emits one final
+            // result per utterance, not a growing whole.
+            setTranscript((prev) => (prev ? `${prev} ${text}`.trim() : text));
+          } else {
+            setPartial(text);
+          }
+        },
+        onError: (err) => {
+          if (runRef.current !== myRun) return;
+          sessionRef.current = null;
+          setError(toSpeechToTextError(err));
+          setPartial("");
+          setListening(false);
+        },
+        onEnd: () => {
+          if (runRef.current !== myRun) return;
+          sessionRef.current = null;
+          setPartial("");
+          setListening(false);
+        },
+      });
+      if (runRef.current !== myRun) {
+        // Superseded while the host was still opening the mic.
+        if (session && typeof session.abort === "function") session.abort();
+        return;
+      }
+      sessionRef.current = session || null;
+    } catch (err) {
+      const se = toSpeechToTextError(err);
+      if (runRef.current === myRun) {
+        sessionRef.current = null;
+        setError(se);
+        setListening(false);
+      }
+      throw se;
+    }
+  }, []);
+
+  return {
+    transcript,
+    partial,
+    listening,
+    supported,
+    error,
+    start,
+    stop,
+    abort,
+    reset,
+  };
+}
+
 /* ============================================================================
  * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
  *
@@ -1383,6 +1611,83 @@ export function useDatastoreSchema(tableId) {
   return { schema, loading, error, refetch };
 }
 
+/**
+ * sc-4932 — draft record values for `tableId` from one sentence the user typed.
+ * Returns `{ interpret, interpreting, error, result, available }`.
+ *
+ *   interpret(text, { fields?, timeZone? }) → Promise<{ values, unresolved }>
+ *     `values` is keyed by column NAME — the same shape
+ *     `useDatastoreMutation().create` takes — so a caller prefills its form
+ *     from it and submits through the ordinary create path. `unresolved` names
+ *     the fields the sentence did not state; they are left for the user.
+ *
+ * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls
+ * `interpret` from an event handler. `interpreting` tracks an in-flight call
+ * and `error` holds the last DatastoreError (cleared at the start of each
+ * call). `result` holds the last successful draft.
+ *
+ * This DRAFTS, it does not write: the user reviews every value before the
+ * record is created. `fields` narrows the draft to the columns the caller
+ * actually renders, each optionally carrying the closed `options` list of a
+ * dropdown. `timeZone` is an IANA zone; the server resolves "at 11 am" against
+ * it and falls back to UTC when it is absent or unknown.
+ *
+ * Routes through the injected `@colixsystems/datastore-client` at
+ * `ctx.datastore.interpret`, so the Player and the Expo export resolve against
+ * the identical client. A host that brokers no interpreter (an unbound canvas
+ * preview) reports `available: false` rather than throwing, matching how
+ * useTranslate degrades.
+ */
+export function useInterpretDraft(tableId) {
+  const ctx = useWidgetContextOrThrow("useInterpretDraft");
+  const available =
+    Boolean(ctx.datastore) && typeof ctx.datastore.interpret === "function";
+
+  const fnRef = useRef(available ? ctx.datastore.interpret : null);
+  fnRef.current = available ? ctx.datastore.interpret : null;
+  const tableIdRef = useRef(tableId);
+  tableIdRef.current = tableId;
+
+  const [interpreting, setInterpreting] = useState(false);
+  const [error, setError] = useState(null);
+  const [result, setResult] = useState(null);
+
+  const interpret = useCallback(async (text, options) => {
+    const table = tableIdRef.current;
+    if (!fnRef.current || !table) {
+      throw new DatastoreError(
+        "UNAVAILABLE",
+        "No interpreter available for this host",
+      );
+    }
+    setInterpreting(true);
+    setError(null);
+    try {
+      // snake_case verbatim on the wire (REQ-GEN-09) — the SDK does not
+      // transform, so the camelCase `timeZone` argument is mapped here, once.
+      const body = { text };
+      if (options && Array.isArray(options.fields)) body.fields = options.fields;
+      if (options && options.timeZone) body.time_zone = options.timeZone;
+      const draft = await fnRef.current(table, body);
+      const safe = {
+        values: draft && draft.values ? draft.values : {},
+        unresolved:
+          draft && Array.isArray(draft.unresolved) ? draft.unresolved : [],
+      };
+      setResult(safe);
+      setInterpreting(false);
+      return safe;
+    } catch (err) {
+      const e = toDatastoreError(err);
+      setError(e);
+      setInterpreting(false);
+      throw e;
+    }
+  }, []);
+
+  return { interpret, interpreting, error, result, available };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/index.d.ts

@@ -590,8 +590,22 @@ export interface WidgetContext<TProps = unknown> {
   toast?: {
     showToast(args: { kind?: string; message: string }): void;
   };
-  /** Optional host-brokered device capabilities; backs useGeolocation. */
+  /**
+   * Optional host-brokered device capabilities; backs useGeolocation and
+   * useSpeechToText.
+   */
   device?: {
+    speech?: {
+      isSupported?(): boolean;
+      start(
+        options: SpeechToTextOptions,
+        handlers: {
+          onResult(result: { transcript: string; isFinal: boolean }): void;
+          onError(error: unknown): void;
+          onEnd(): void;
+        },
+      ): Promise<{ stop(): void | Promise<void>; abort(): void }>;
+    };
     geolocation?: {
       getCurrentPosition(options?: GeolocationOptions): Promise<{
         latitude: number;
@@ -949,6 +963,50 @@ export function useDatastoreSchema(
   tableId: string | null | undefined,
 ): SchemaResult;
 
+/** sc-4932 — one field a draft may target, with a dropdown's closed option set. */
+export interface InterpretDraftField {
+  column: string;
+  options?: Array<string | number>;
+}
+
+/** sc-4932 — options for `useInterpretDraft().interpret`. */
+export interface InterpretDraftOptions {
+  fields?: Array<InterpretDraftField | string>;
+  /** IANA zone the server resolves relative times against. Defaults to UTC. */
+  timeZone?: string;
+}
+
+/**
+ * sc-4932 — a drafted record. `values` is keyed by column NAME (the shape
+ * `useDatastoreMutation().create` takes); `unresolved` names the fields the
+ * sentence did not state.
+ */
+export interface InterpretDraftResult {
+  values: Record<string, unknown>;
+  unresolved: string[];
+}
+
+export interface InterpretDraftApi {
+  interpret(
+    text: string,
+    options?: InterpretDraftOptions,
+  ): Promise<InterpretDraftResult>;
+  interpreting: boolean;
+  error: DatastoreError | null;
+  result: InterpretDraftResult | null;
+  /** False when the host brokers no interpreter (e.g. an unbound preview). */
+  available: boolean;
+}
+
+/**
+ * sc-4932 — draft record values for `tableId` from one sentence the user typed
+ * ("walk at 11 am tomorrow"). IMPERATIVE: never fires on mount, and DRAFTS
+ * only — the user reviews the values before the record is created.
+ */
+export function useInterpretDraft(
+  tableId: string | null | undefined,
+): InterpretDraftApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"
@@ -1267,6 +1325,68 @@ export class GeolocationError extends Error {
   );
 }
 
+/** Pass-through options for `useSpeechToText(...)`. */
+export interface SpeechToTextOptions {
+  /** BCP-47 tag, e.g. "sv-SE". Defaults to the host's UI language. */
+  lang?: string;
+  /** Keep listening across pauses instead of stopping at the first result. */
+  continuous?: boolean;
+  /** Emit uncommitted guesses to `partial` while the user is still speaking. */
+  interimResults?: boolean;
+}
+
+export interface SpeechToTextResult {
+  /** Finalised speech, accumulated across utterances in this session. */
+  transcript: string;
+  /** The uncommitted guess; `""` unless `interimResults` was requested. */
+  partial: string;
+  listening: boolean;
+  /** False when the host brokers no recogniser (e.g. Firefox). */
+  supported: boolean;
+  error: SpeechToTextError | null;
+  /** Begin listening — call from a user gesture. Rejects with SpeechToTextError. */
+  start(): Promise<void>;
+  /** Stop listening and keep what was heard. */
+  stop(): Promise<void>;
+  /** Cancel listening and discard the current utterance. */
+  abort(): void;
+  /** Clear `transcript`, `partial`, and `error`. */
+  reset(): void;
+}
+
+/**
+ * Dictate into text with the device's ON-DEVICE speech recogniser. Capture is
+ * imperative (call `start()` from a user gesture; it never listens on mount).
+ * The same hook drives both platforms — the web Player brokers it via
+ * `window.SpeechRecognition`, the Expo export via `expo-speech-recognition`.
+ * No audio is uploaded and no AI credit is spent. Safe to call on a host that
+ * brokers no recogniser: `supported` is then false and `start()` rejects with
+ * `code: "UNSUPPORTED"`, so gate the mic button on `supported`.
+ */
+export function useSpeechToText(
+  options?: SpeechToTextOptions,
+): SpeechToTextResult;
+
+/**
+ * Error surfaced by `useSpeechToText()` — thrown by `start()` and stored in the
+ * hook's `error` slot. `code` is a stable categorisation.
+ */
+export class SpeechToTextError extends Error {
+  code:
+    | "PERMISSION_DENIED"
+    | "NO_SPEECH"
+    | "LANGUAGE_UNSUPPORTED"
+    | "NETWORK"
+    | "ABORTED"
+    | "UNSUPPORTED"
+    | "INTERNAL";
+  constructor(
+    code: SpeechToTextError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable

package/dist/index.js

@@ -15,6 +15,7 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useInterpretDraft,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
@@ -56,6 +57,8 @@ export {
   useContainerWidth,
   useGeolocation,
   GeolocationError,
+  useSpeechToText,
+  SpeechToTextError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";

package/dist/index.native.js

@@ -15,6 +15,7 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useInterpretDraft,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
@@ -56,6 +57,8 @@ export {
   useContainerWidth,
   useGeolocation,
   GeolocationError,
+  useSpeechToText,
+  SpeechToTextError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.90.0",
+  "version": "0.92.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js"
   },
   "engines": {
     "node": ">=18"