@colixsystems/widget-sdk 0.243.0 → 0.245.0

package/README.md

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

package/dist/contract.cjs

@@ -1205,6 +1205,8 @@ const HOOKS = [
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       scrollToSection:
         "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
+      scrollIntoView:
+        "(ref: { current }) => void — scrolls THIS page so an element inside the calling widget (the ref you attached to a View, Text or other primitive) lands just below any pinned site header; smooth unless the visitor prefers reduced motion. Use it for anchors within the widget's own content, such as a table of contents that jumps to one of its headings. Never fake page anchors with a height-capped inner ScrollView: the page itself scrolls. A ref that is not mounted is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -2062,8 +2064,8 @@ const HOOKS = [
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
       "An assistant message that used a tool also carries `activity`: what " +
-      "the agent DID — the table it read, or the table and columns it " +
-      "CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
+      "the agent DID — the table it read and the search text and filters it " +
+      "read with, or the table and columns it CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
       "row was written, and the user has no other way to notice a mistake. " +
       "A talk-only turn omits the key entirely. " +
       "You CANNOT set the system prompt, replay an edited transcript, " +
@@ -6155,7 +6157,11 @@ const CONTRACT = deepFreeze({
   //    the link that opens BankID on this device. Signing hooks document
   //    polling, the two ways to start BankID and how to read a verdict;
   //    useFileSignatures is described as the caller's own signatures.
-  version: "1.197.0",
+  // 1.198.0: additive (sc-12088) — `useNavigation().scrollIntoView(ref)`
+  //    scrolls the page to an element inside the calling widget on both hosts.
+  // 1.199.0: additive (sc-11952) — an `AgentActivity` read entry may carry
+  //    `search` and `filters`: what the agent searched for, never its rows.
+  version: "1.199.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1205,6 +1205,8 @@ const HOOKS = [
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       scrollToSection:
         "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
+      scrollIntoView:
+        "(ref: { current }) => void — scrolls THIS page so an element inside the calling widget (the ref you attached to a View, Text or other primitive) lands just below any pinned site header; smooth unless the visitor prefers reduced motion. Use it for anchors within the widget's own content, such as a table of contents that jumps to one of its headings. Never fake page anchors with a height-capped inner ScrollView: the page itself scrolls. A ref that is not mounted is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -2062,8 +2064,8 @@ const HOOKS = [
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
       "An assistant message that used a tool also carries `activity`: what " +
-      "the agent DID — the table it read, or the table and columns it " +
-      "CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
+      "the agent DID — the table it read and the search text and filters it " +
+      "read with, or the table and columns it CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
       "row was written, and the user has no other way to notice a mistake. " +
       "A talk-only turn omits the key entirely. " +
       "You CANNOT set the system prompt, replay an edited transcript, " +
@@ -6151,7 +6153,11 @@ const CONTRACT = deepFreeze({
   //    the link that opens BankID on this device. Signing hooks document
   //    polling, the two ways to start BankID and how to read a verdict;
   //    useFileSignatures is described as the caller's own signatures.
-  version: "1.197.0",
+  // 1.198.0: additive (sc-12088) — `useNavigation().scrollIntoView(ref)`
+  //    scrolls the page to an element inside the calling widget on both hosts.
+  // 1.199.0: additive (sc-11952) — an `AgentActivity` read entry may carry
+  //    `search` and `filters`: what the agent searched for, never its rows.
+  version: "1.199.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

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

package/dist/index.d.ts

@@ -850,6 +850,7 @@ export interface WidgetContext<TProps = unknown> {
     goTo(pageId: string, params?: Record<string, string>): void;
     goToStartPage(): void;
     scrollToSection(sectionId: string): void;
+    scrollIntoView(ref: { readonly current: unknown } | object | null | undefined): void;
     goBack(): void;
     push(pageId: string, params?: Record<string, unknown>): void;
     replace(pageId: string, params?: Record<string, unknown>): void;
@@ -1789,6 +1790,17 @@ export interface AgentActivity {
   table?: string;
   record_id?: string;
   fields?: string[];
+  /** A read's own search text: what the agent looked FOR, never what it found. */
+  search?: string;
+  /** A read's own filter conditions, as the agent asked for them. */
+  filters?: AgentActivityFilter[];
+}
+
+/** One condition a read filtered by; `operator` is eq, neq, gt, gte, lt, lte or contains. */
+export interface AgentActivityFilter {
+  column: string;
+  operator: string;
+  value: string;
 }
 
 export interface AgentApi {
@@ -2221,6 +2233,8 @@ export function useFitScreenInsets(): FitScreenInsets;
  * opens the signed-in user's own start page, which can differ per user.
  * `scrollToSection(sectionId)` scrolls this page to one of its sections (the
  * id comes from a `sectionRef` prop); an unknown section is a no-op.
+ * `scrollIntoView(ref)` scrolls this page to an element inside the calling
+ * widget, such as a heading its table of contents jumps to.
  * Missing methods degrade to no-ops on the Studio canvas preview where no
  * live router is mounted. For external URLs use the `Linking` primitive.
  */
@@ -2228,6 +2242,7 @@ export function useNavigation(): {
   goTo(pageId: string, params?: Record<string, unknown>): void;
   goToStartPage(): void;
   scrollToSection(sectionId: string): void;
+  scrollIntoView(ref: { readonly current: unknown } | object | null | undefined): void;
   goBack(): void;
   push(pageId: string, params?: Record<string, unknown>): void;
   replace(pageId: string, params?: Record<string, unknown>): void;

package/package.json

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

package/src/contract.js

@@ -1205,6 +1205,8 @@ const HOOKS = [
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
       scrollToSection:
         "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
+      scrollIntoView:
+        "(ref: { current }) => void — scrolls THIS page so an element inside the calling widget (the ref you attached to a View, Text or other primitive) lands just below any pinned site header; smooth unless the visitor prefers reduced motion. Use it for anchors within the widget's own content, such as a table of contents that jumps to one of its headings. Never fake page anchors with a height-capped inner ScrollView: the page itself scrolls. A ref that is not mounted is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -2062,8 +2064,8 @@ const HOOKS = [
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
       "An assistant message that used a tool also carries `activity`: what " +
-      "the agent DID — the table it read, or the table and columns it " +
-      "CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
+      "the agent DID — the table it read and the search text and filters it " +
+      "read with, or the table and columns it CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
       "row was written, and the user has no other way to notice a mistake. " +
       "A talk-only turn omits the key entirely. " +
       "You CANNOT set the system prompt, replay an edited transcript, " +
@@ -6151,7 +6153,11 @@ const CONTRACT = deepFreeze({
   //    the link that opens BankID on this device. Signing hooks document
   //    polling, the two ways to start BankID and how to read a verdict;
   //    useFileSignatures is described as the caller's own signatures.
-  version: "1.197.0",
+  // 1.198.0: additive (sc-12088) — `useNavigation().scrollIntoView(ref)`
+  //    scrolls the page to an element inside the calling widget on both hosts.
+  // 1.199.0: additive (sc-11952) — an `AgentActivity` read entry may carry
+  //    `search` and `filters`: what the agent searched for, never its rows.
+  version: "1.199.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,