@colixsystems/widget-sdk 0.188.0 → 0.190.0

package/README.md

@@ -53,6 +53,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **AGENTS** | `useAgent(agentRef)` | `{ send, cancel, reset, messages, sending, resuming, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). Sending is IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. On mount the hook DOES reopen the caller's most recent thread with this agent, so a refresh or a navigation keeps the conversation instead of starting a blank one; that resume only READS and spends no credit. `resuming` is true while it runs — render a loading state, not an empty thread. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance), and the new thread is the one a later mount resumes. **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
 | **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** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **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)` (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 |
@@ -75,7 +76,32 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.188.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.190.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.190.0 (contract 1.151.0)
+
+**New `useTyping(tableId, recordId)` hook: a typing indicator for one record.** It returns `{ typingUserIds, setTyping, status }`. Call `setTyping(true)` on every keystroke in your composer and `setTyping(false)` when the message is sent, the field is cleared or it loses focus. The hook throttles for you: it sends at most one signal every 3 s, and sends `false` on its own after 5 s without a keystroke. `typingUserIds` lists the other users typing in that record (never yourself); each one drops out 6 s after their last signal, so a closed tab never leaves a stale indicator. Signals carry no message content and are never stored.
+
+Key it on the record the conversation lives in (a thread or channel row), which the user must be able to read. It rides the same realtime connection as `useDatastoreSubscription`, so a widget holds one socket for both. `status` is `"connecting"`, `"live"` or `"unavailable"`; it is `"unavailable"` for an anonymous visitor, a refused subscription, a preview with no backend, and a host whose datastore client predates typing. The hook never throws, so render the indicator only when `typingUserIds` is non-empty:
+
+```jsx
+const { typingUserIds, setTyping } = useTyping(threadsTableId, threadId);
+// <TextInput onChangeText={(t) => { setDraft(t); setTyping(t.length > 0); }} onBlur={() => setTyping(false)} />
+// {typingUserIds.length > 0 && <Text>{typingUserIds.length === 1 ? "Someone is typing…" : "Several people are typing…"}</Text>}
+```
+
+Declare `datastore.read` for the table. Additive; works identically in the web Player and the native export.
+
+### What's new in 0.189.0 (contract 1.150.0)
+
+**The import check now catches two shapes that passed lint and then failed to load in the web Player.** This narrows `import-not-vetted`:
+
+- **Imports wrapped over several lines.** The check read one line at a time, so a Prettier-wrapped import of a package that is not on the vetted list was never seen. It now reads the whole file and reports the finding on the `from` line. `export { … } from "pkg"` and `export * from "pkg"` are checked too, and so are forms written without spaces (`import{a}from"pkg"`) or inside an expression (`x = require("pkg")`).
+- **Subpaths of packages the web Player provides.** The web Player supplies some packages itself and loads them by their exact name only. `CONTRACT.hostExternalSpecifiers` lists them; today they are `react` (and its JSX runtimes), `react-dom`, `react-native`, `@colixsystems/widget-sdk`, `lucide-react-native`, `react-native-svg`, `react-native-qrcode-svg`, `date-fns`, `decimal.js`, `d3-scale`, `d3-shape`, `d3-array` and `simple-statistics`. A subpath of one of them, such as `date-fns/format` or `react-native/Libraries/…`, cannot load on web. It is now `import-not-vetted` in any file that ships to web. Import from the package itself: `import { format } from "date-fns"`.
+
+A subpath of a package your bundle includes is still allowed, for example `leaflet/dist/leaflet.css`, a Leaflet marker image or `react-native-vector-icons/MaterialIcons`. A file that ships only to native (`widget.native.jsx`, or a manifest whose `supportedPlatforms` is `["native"]`) keeps every vetted subpath, because the native build resolves them.
+
+`CONTRACT.subpathImportRoots` lists the vetted packages whose subpaths load on web, and the new `subpathImportRootsFor(manifest)` export of `@colixsystems/widget-sdk/linter` returns the roots that load for a file with that manifest. `appstudio-widget lint --manifest` now checks `widget.web.jsx` and `widget.native.jsx` against the platform each one ships to, as the submission check already did.
 
 ### What's new in 0.188.0 (contract 1.149.0)
 

package/dist/cli.js

@@ -5,10 +5,15 @@
 //                                                          — REQ-WSDK-DEVKIT local dev server
 
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { argv, exit, stderr, stdout } from "node:process";
-import { lintSource, lintStyleWiring, lintEditability } from "./linter.js";
+import {
+  lintSource,
+  lintStyleWiring,
+  lintEditability,
+  narrowManifestForFile,
+} from "./linter.js";
 import { startDevServer } from "./devserver.js";
 
 function usage() {
@@ -99,9 +104,15 @@ async function runLint(rest) {
     }
   }
   const label = positionals.join(", ");
+  // Narrow per split-impl file, as the submission gate does.
   const perFile = Object.entries(files).map(([filePath, source]) => [
     filePath,
-    lintSource(source, manifest ? { manifest } : undefined),
+    lintSource(
+      source,
+      manifest
+        ? { manifest: narrowManifestForFile(manifest, basename(filePath)) }
+        : undefined,
+    ),
   ]);
   const wiring = manifest
     ? lintStyleWiring(manifest, files)

package/dist/contract.cjs

@@ -2043,6 +2043,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -3505,6 +3539,49 @@ const ALLOWED_BARE_IMPORTS = [
   ...CORE_INFRA_BARE_IMPORTS,
 ];
 
+// sc-10502: the bare specifiers the web host RESOLVES for a loaded widget
+// instead of letting its bundle inline a copy. The web-entry bundler marks
+// exactly these `external` and the Studio loader shims each by EXACT name, so
+// a subpath of one (`date-fns/format`) cannot load in the web Player.
+// `dev-shims.hostExternalSpecifiers()` returns this list; the loader's
+// module-load guard (frontend widgetLoader.js) throws if its shims drift.
+//
+// Why each entry is host-resolved, not bundled:
+//   * react + its JSX runtimes: one React instance (hooks, context).
+//   * react-dom, react-dom/client: react-leaflet portals through react-dom;
+//     a second renderer beside the host's React crashes (sc-1064).
+//   * @colixsystems/widget-sdk: the host-built SDK carries datastore, theme
+//     and navigation.
+//   * react-native, lucide-react-native, react-native-svg,
+//     react-native-qrcode-svg: share the host's react-native-web instance
+//     (sc-1265, sc-6105).
+//   * date-fns and the maths set: an agent widget is transpiled, not
+//     bundled, so the host must resolve its bare imports (sc-7191).
+const HOST_EXTERNAL_SPECIFIERS = [
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  "react-dom/client",
+  "@colixsystems/widget-sdk",
+  "lucide-react-native",
+  "react-native-svg",
+  "date-fns",
+  "react-native-qrcode-svg",
+  "react-native",
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
+];
+
+// Vetted roots whose subpaths load on web (`leaflet/dist/leaflet.css`): the
+// bundle inlines them, so no exact-name host shim stands in the way.
+const SUBPATH_IMPORT_ROOTS = ALLOWED_BARE_IMPORTS.filter(
+  (spec) => !HOST_EXTERNAL_SPECIFIERS.includes(spec),
+);
+
 // REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
 // soft warning. None of these block the lint by themselves — they prompt
 // the marketplace reviewer to spot-check, and they help authors learn the
@@ -4871,7 +4948,20 @@ const CONTRACT = deepFreeze({
   //    (error): a file importing leaflet / react-leaflet must import
   //    "leaflet/dist/leaflet.css". `leaflet-default-marker-icon` (warning)
   //    flags a react-leaflet <Marker> with no `icon`.
-  version: "1.149.0",
+  // 1.150.0: narrowing (sc-10502) — the linter scans imports across the whole
+  //    file, so a wrapped `import { … } from` (or an `export … from`) of an
+  //    unvetted package is `import-not-vetted` on its `from` line. A file
+  //    that ships to web may import a SUBPATH only of a bundled vetted
+  //    package (`subpathImportRoots`, e.g. "leaflet/dist/leaflet.css"); a
+  //    host-provided package's subpath ("date-fns/format") is flagged. A
+  //    native-only file keeps every vetted subpath (Metro resolves them).
+  //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
+  //    linter export `subpathImportRootsFor(manifest)`.
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ typingUserIds, setTyping, status }`: the other users typing in one
+  //    record, over the datastore client's single realtime socket. A host
+  //    whose client lacks `records(t).typing` reads `status: "unavailable"`.
+  version: "1.151.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4898,6 +4988,8 @@ const CONTRACT = deepFreeze({
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
+  hostExternalSpecifiers: HOST_EXTERNAL_SPECIFIERS,
+  subpathImportRoots: SUBPATH_IMPORT_ROOTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
   payloadValueTypes: PAYLOAD_VALUE_TYPES,
   chargeCurrency: CHARGE_CURRENCY,

package/dist/contract.js

@@ -2043,6 +2043,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -3501,6 +3535,49 @@ const ALLOWED_BARE_IMPORTS = [
   ...CORE_INFRA_BARE_IMPORTS,
 ];
 
+// sc-10502: the bare specifiers the web host RESOLVES for a loaded widget
+// instead of letting its bundle inline a copy. The web-entry bundler marks
+// exactly these `external` and the Studio loader shims each by EXACT name, so
+// a subpath of one (`date-fns/format`) cannot load in the web Player.
+// `dev-shims.hostExternalSpecifiers()` returns this list; the loader's
+// module-load guard (frontend widgetLoader.js) throws if its shims drift.
+//
+// Why each entry is host-resolved, not bundled:
+//   * react + its JSX runtimes: one React instance (hooks, context).
+//   * react-dom, react-dom/client: react-leaflet portals through react-dom;
+//     a second renderer beside the host's React crashes (sc-1064).
+//   * @colixsystems/widget-sdk: the host-built SDK carries datastore, theme
+//     and navigation.
+//   * react-native, lucide-react-native, react-native-svg,
+//     react-native-qrcode-svg: share the host's react-native-web instance
+//     (sc-1265, sc-6105).
+//   * date-fns and the maths set: an agent widget is transpiled, not
+//     bundled, so the host must resolve its bare imports (sc-7191).
+const HOST_EXTERNAL_SPECIFIERS = [
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  "react-dom/client",
+  "@colixsystems/widget-sdk",
+  "lucide-react-native",
+  "react-native-svg",
+  "date-fns",
+  "react-native-qrcode-svg",
+  "react-native",
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
+];
+
+// Vetted roots whose subpaths load on web (`leaflet/dist/leaflet.css`): the
+// bundle inlines them, so no exact-name host shim stands in the way.
+const SUBPATH_IMPORT_ROOTS = ALLOWED_BARE_IMPORTS.filter(
+  (spec) => !HOST_EXTERNAL_SPECIFIERS.includes(spec),
+);
+
 // REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
 // soft warning. None of these block the lint by themselves — they prompt
 // the marketplace reviewer to spot-check, and they help authors learn the
@@ -4867,7 +4944,20 @@ const CONTRACT = deepFreeze({
   //    (error): a file importing leaflet / react-leaflet must import
   //    "leaflet/dist/leaflet.css". `leaflet-default-marker-icon` (warning)
   //    flags a react-leaflet <Marker> with no `icon`.
-  version: "1.149.0",
+  // 1.150.0: narrowing (sc-10502) — the linter scans imports across the whole
+  //    file, so a wrapped `import { … } from` (or an `export … from`) of an
+  //    unvetted package is `import-not-vetted` on its `from` line. A file
+  //    that ships to web may import a SUBPATH only of a bundled vetted
+  //    package (`subpathImportRoots`, e.g. "leaflet/dist/leaflet.css"); a
+  //    host-provided package's subpath ("date-fns/format") is flagged. A
+  //    native-only file keeps every vetted subpath (Metro resolves them).
+  //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
+  //    linter export `subpathImportRootsFor(manifest)`.
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ typingUserIds, setTyping, status }`: the other users typing in one
+  //    record, over the datastore client's single realtime socket. A host
+  //    whose client lacks `records(t).typing` reads `status: "unavailable"`.
+  version: "1.151.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4894,6 +4984,8 @@ const CONTRACT = deepFreeze({
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
+  hostExternalSpecifiers: HOST_EXTERNAL_SPECIFIERS,
+  subpathImportRoots: SUBPATH_IMPORT_ROOTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
   payloadValueTypes: PAYLOAD_VALUE_TYPES,
   chargeCurrency: CHARGE_CURRENCY,

package/dist/dev-shims.js

@@ -19,6 +19,8 @@
 // runtime-enumerates the host's namespace). Imports of these packages from a
 // sibling .jsx file return `422` from the dev server with a clear message.
 
+import { CONTRACT } from "./contract.js";
+
 // React named exports the Studio re-exposes through the shim. Mirrors the
 // browser's `react` named-export surface. Adding a new hook in a React minor
 // release means appending it here.
@@ -61,81 +63,16 @@ export const REACT_NAMED_EXPORTS = [
 // React's automatic JSX runtime: jsx / jsxs / Fragment, plus the dev variant.
 export const REACT_JSX_RUNTIME_EXPORTS = ["jsx", "jsxs", "Fragment", "jsxDEV"];
 
-// REQ-WSDK-PLATFORM bundle (sc-1064): the canonical list of bare specifiers the
-// runtime web host RESOLVES for a loaded widget — i.e. the ones the Studio's
-// `widgetLoader.buildShims()` re-exports from `globalThis.__appstudioWidgetHost__`
-// rather than letting a bundle inline a second copy. The web-entry bundler
-// (`webbundle.bundleWebEntry`, used by both the publish packer and the dev
-// server) marks EXACTLY these `external`, so everything else the entry imports
-// (`react-leaflet`, `leaflet`, CSS, PNG assets, …) gets inlined.
-//
-// This is the SINGLE source of truth (CLAUDE.md §3). It MUST stay in lockstep
-// with the frontend's `widgetLoader._hostVettedModules()` + the core React/SDK
-// shims it builds. Two backstops enforce the equality: (1) this list's
-// contents are pinned by the SDK-side importable test
-// (`packages/widget-sdk/src/__tests__/host-externals.test.js`), and (2) the
-// loader's own module-load guard in `frontend/src/services/widgetLoader.js`
-// throws at import time if `hostShimmedSpecifiers()` drifts from
-// `hostExternalSpecifiers()` — the loader's shimmed set can't be asserted from
-// a Node test (it imports `react-dom` etc.), so that equality is enforced by
-// the load-time guard rather than a separate frontend test.
-//
-// Why each entry is host-resolved (NOT bundled):
-//   * `react`, `react/jsx-runtime`, `react/jsx-dev-runtime` — the widget MUST
-//     share the host's ONE React instance (hooks + context); a bundled second
-//     React breaks both.
-//   * `react-dom`, `react-dom/client` — `react-leaflet`'s Popup/Pane render
-//     through `createPortal` from `react-dom`. A bundled second react-dom
-//     paired with the host's external React is a mismatched renderer and
-//     crashes. The Studio is a React-DOM app, so it shims its own react-dom.
-//     On React 19 the two specifiers expose DIFFERENT surfaces — createPortal /
-//     flushSync / version live on `react-dom`, createRoot / hydrateRoot on
-//     `react-dom/client` — so the loader stashes + shims each from its own real
-//     host namespace (sc-1064).
-//   * `@colixsystems/widget-sdk` — the widget must route hooks through the SAME
-//     SDK instance the host built (datastore/theme/navigation live there).
-//   * `lucide-react-native`, `react-native-svg`, `date-fns`,
-//     `react-native-qrcode-svg` — vetted packages the host already bundles +
-//     shims (`_hostVettedModules`); sharing the host copy keeps icons/SVG on
-//     the host's react-native-web instance. qrcode-svg draws through
-//     react-native-svg, so externalising it keeps the QR on that same
-//     instance instead of a bundle inlining a second one (sc-6105).
-const HOST_EXTERNAL_SPECIFIERS = [
-  "react",
-  "react/jsx-runtime",
-  "react/jsx-dev-runtime",
-  "react-dom",
-  "react-dom/client",
-  "@colixsystems/widget-sdk",
-  "lucide-react-native",
-  "react-native-svg",
-  "date-fns",
-  "react-native-qrcode-svg",
-  // sc-1265: a bundled widget (and any vetted RN package it inlines, e.g.
-  // react-native-gesture-handler) imports `react-native`; the host resolves it
-  // to its OWN single react-native-web instance through a blob shim, so the
-  // bundle shares one RN-web (StyleSheet/context) instead of inlining a second
-  // copy. On native, Metro resolves the real react-native in the export.
-  "react-native",
-  // sc-7191: the vetted pure-JS maths set. Externalised for the same reason as
-  // date-fns — an AI-agent widget is transpiled, never bundled, so the host
-  // must resolve the bare import at runtime.
-  "decimal.js",
-  "d3-scale",
-  "d3-shape",
-  "d3-array",
-  "simple-statistics",
-];
-
 /**
  * The canonical "host-resolved at runtime" bare-specifier set — the externals
- * the web-entry bundler must NOT inline. Returns a fresh array each call so a
- * caller can't mutate the source of truth.
+ * the web-entry bundler must NOT inline. Sourced from
+ * `CONTRACT.hostExternalSpecifiers`, which documents each entry. Returns a
+ * fresh array each call so a caller can't mutate the source of truth.
  *
  * @returns {string[]}
  */
 export function hostExternalSpecifiers() {
-  return [...HOST_EXTERNAL_SPECIFIERS];
+  return [...CONTRACT.hostExternalSpecifiers];
 }
 
 function reactShimSrc() {

package/dist/hooks.js

@@ -3834,6 +3834,71 @@ export function useDatastoreSubscription(table, handlers, options) {
   return { status };
 }
 
+const _NO_TYPERS = Object.freeze([]);
+
+/**
+ * Who else is typing in one record; call `setTyping` per keystroke.
+ * Never throws: a client without typing reports status "unavailable".
+ *
+ * @param {string} tableId
+ * @param {string} recordId
+ * @returns {{ typingUserIds: string[], setTyping: (active: boolean) => void, status: "connecting" | "live" | "unavailable" }}
+ */
+export function useTyping(tableId, recordId) {
+  const ctx = useWidgetContextOrThrow("useTyping");
+  const [typingUserIds, setTypingUserIds] = useState(_NO_TYPERS);
+  const [status, setStatus] = useState("connecting");
+  const handleRef = useRef(null);
+  // `ctx` is a fresh identity per host render; the effect keys on the ids.
+  const recordsRef = useRef(null);
+  recordsRef.current =
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null;
+
+  useEffect(() => {
+    setTypingUserIds(_NO_TYPERS);
+    setStatus("connecting");
+    const unavailable = () => {
+      setStatus("unavailable");
+      return undefined;
+    };
+    if (!tableId || !recordId || typeof recordsRef.current !== "function") {
+      return unavailable();
+    }
+    try {
+      const ns = recordsRef.current(tableId);
+      if (!ns || typeof ns.typing !== "function") return unavailable();
+      let current = true;
+      const handle = ns.typing(recordId, {
+        onChange: (ids) => {
+          if (current) setTypingUserIds(ids);
+        },
+        onStatus: (s) => {
+          if (current) setStatus(s);
+        },
+      });
+      handleRef.current = handle;
+      return () => {
+        current = false;
+        handleRef.current = null;
+        if (handle && typeof handle.stop === "function") handle.stop();
+      };
+    } catch (_) {
+      return unavailable();
+    }
+  }, [tableId, recordId]);
+
+  const setTyping = useCallback((active) => {
+    const handle = handleRef.current;
+    if (handle && typeof handle.setTyping === "function") {
+      handle.setTyping(active === true);
+    }
+  }, []);
+
+  return { typingUserIds, setTyping, status };
+}
+
 /* ============================================================================
  * ASSETS CLIENT — ctx.assets (@colixsystems/assets-client)
  *

package/dist/index.d.ts

@@ -496,6 +496,14 @@ export interface DatastoreClient {
       ): Promise<unknown>;
       revoke(permissionId: string): Promise<void>;
     };
+    /** REQ-RT-08 — backs `useTyping`; optional, the hook degrades without it. */
+    typing?(
+      recordId: string,
+      handlers: {
+        onChange?(typingUserIds: string[]): void;
+        onStatus?(status: TypingStatus): void;
+      },
+    ): { setTyping(active: boolean): void; stop(): void };
   };
 }
 
@@ -1410,6 +1418,27 @@ export function useDatastoreSubscription(
   options?: DatastoreSubscriptionOptions,
 ): { status: DatastoreSubscriptionStatus };
 
+export type TypingStatus = "connecting" | "live" | "unavailable";
+
+/**
+ * REQ-RT-08: who else is typing in one record, and announcing your own typing,
+ * via `ctx.datastore.records(tableId).typing(recordId, ...)`. Call
+ * `setTyping(true)` on every keystroke (throttled inside; `false` is sent
+ * after 5 s idle) and `setTyping(false)` on send, clear or blur.
+ * `typingUserIds` lists the other users typing; each drops out 6 s after
+ * their last signal. Needs a signed-in user who can read the record.
+ * Re-subscribes when `tableId` or `recordId` changes. Never throws — a host
+ * whose datastore client lacks typing reports `status: "unavailable"`.
+ */
+export function useTyping(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): {
+  typingUserIds: string[];
+  setTyping(active: boolean): void;
+  status: TypingStatus;
+};
+
 /**
  * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
  * refetch }`. The `url` is an absolute URL composed against the host's API
@@ -3380,6 +3409,10 @@ export interface AiWidgetContract {
   readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
   readonly bannedApis: ReadonlyArray<ContractBannedApi>;
   readonly allowedBareImports: ReadonlyArray<string>;
+  /** Bare specifiers the web host provides by exact name; a widget bundle never inlines them. */
+  readonly hostExternalSpecifiers: ReadonlyArray<string>;
+  /** Bundled vetted package roots: the only roots whose subpaths load in the web Player. */
+  readonly subpathImportRoots: ReadonlyArray<string>;
   /** sc-4686 — the render-time fallback currency when the host supplies none. */
   readonly chargeCurrency: string;
   /** sc-4686 — how each currency is written; read by `formatMoney`, never Intl. */

package/dist/index.js

@@ -60,6 +60,7 @@ export {
   IdentificationError,
   useRecordPermissions,
   useDatastoreSubscription,
+  useTyping,
   useWidgetEvent,
   useWidgetInput,
   usePayments,

package/dist/index.native.js

@@ -60,6 +60,7 @@ export {
   IdentificationError,
   useRecordPermissions,
   useDatastoreSubscription,
+  useTyping,
   useWidgetEvent,
   useWidgetInput,
   usePayments,