# @colixsystems/widget-sdk Common widget interface for AppStudio. This package is **core only** — it implements the contract that every widget (built-in or third-party, web or native) speaks: a `WidgetManifest`, a `WidgetContext`, a property schema, the primitives + rendering surface, the helper hooks, events, theme/i18n, and the static linter that gates submissions. **It owns no HTTP and depends on none of the data SDK packages.** The data layer lives in **four separate domain-client packages**, each instantiated by the host and **injected into `WidgetContext`**. Widgets never import those packages — they reach the data surface only through this SDK's hooks, which read the injected client instances: | Injected at | Package | Surface (snake_case verbatim, `list` → `{ data, meta }`) | | ----------- | ------- | -------- | | `ctx.datastore` | `@colixsystems/datastore-client` | `tables.{list,get}`, `schema(tableId)`, `myPermissions(tableId, { recordId? })`, `records(tableId).{ list(query), get(id), create(values), update(id,values) [PATCH], delete(id), aggregate(spec), permissions(recordId).{ list, grant, update, revoke } }` | | `ctx.directory` | `@colixsystems/directory-client` | `me()`, `users.{list,get,invite,deactivate,reactivate}`, `groups.{list,create,remove,addMember,removeMember,listMine}`, `invites.{list,revoke,resend}` | | `ctx.assets` | `@colixsystems/assets-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useAsset()` (single asset by id) and `useAssetsByTag()` (every asset carrying a tag) resolve | | `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` | **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. **Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (20 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js). | Group | Hook (signature) | Returns | Reads / scope | | ----- | ---------------- | ------- | ------------- | | **CORE** | `useTheme()` | `{ colors, elevation, interaction, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`) and `loader`, the spinner colour for your own loading state. `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. | | **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. | | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. | | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope | | **CORE** | `useNavigation()` | `{ goTo, 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 (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) | | **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. | | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. | | **CORE** | `useWidgetRoute(initial)` | `[state, setState]` | `ctx.widgetRoute` — no scope. Where YOUR WIDGET is, persisted by the host so it survives a reload and travels in a shared link (the `w_` query key on web, the screen's route params natively): the folder a browser has opened, a wizard step, a selected tab, a list's sort and search. `useState` semantics over an object — writes MERGE, `null` clears a key back to its `initial`, and `initial` is read once. Values are scalars or flat arrays of scalars, size- and length-capped; anything else is not stored. NOT history (Back still leaves the page, on both platforms). Degrades to component state on the Studio canvas. | | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. | | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. | | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) | | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. | | **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. | | **CORE** | `isNarrowWidth(width)` | `boolean` | No context slice, no scope. True when a MEASURED width is below `NARROW_WIDTH_PX` (480) — the one threshold every widget switches at, so a page reflows together rather than raggedly. An unmeasured width (0) is NOT narrow, so nothing flashes through the narrow form on first paint. | | **CORE** | `useSectionEmpty(isEmpty)` | `void` | `ctx.section.reportEmpty` — no scope. Declares that the widget has NO content to show, so the host drops its layout slot instead of reserving space (and its parent's `gap`) for it. Returning `null` is not enough: the host wraps every widget in an entrance element, so a widget rendering nothing still leaves an empty box the parent stack gaps around. For a CONDITIONALLY ABSENT section (a per-record child collection with no rows for this record), never to suppress a genuine empty state. Stays mounted while collapsed, so passing `false` brings it back. Authoring surfaces never collapse. No-op on a host that doesn't implement it. | | **CORE** | `useScreenTitle(title)` | `void` | `ctx.screen.reportTitle` — no scope. Names the screen the widget is on, so the host paints that name in the app header beside the back control instead of the app brand. The page's own name is the default; only the widget knows the screen is really "Order #1423" rather than "Orders". The MOST RECENT call wins — with several widgets on one screen the last to report owns the title, and on unmount (or an empty title) the host falls back to the most recent surviving report and finally to the page name. Only a screen showing the back control paints a title; a root page keeps the brand. No-op on a host that doesn't implement it. | | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. | | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope | | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope | | **CORE** | `useGeolocation(options)` (optional: options) | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). **Background watch (sc-6450)** — `startBackgroundWatch({ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs })` keeps positions arriving while the app is backgrounded; `stopBackgroundWatch()` releases it. NATIVE-ONLY and opt-in per app: gate the control on `backgroundSupported` (false on web, and in an export whose workspace did not opt in). The watch outlives the widget's mount, and its positions land in the same `latitude`/`longitude`/`accuracy` slots. | | **CORE** | `useSpeechToText(options)` (optional: options) | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). | | **CORE** | `useCamera(options)` (optional: options) | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). | | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget..`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.`) 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..` 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`, `translate(str[])` → `Promise` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. | | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". | | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` | | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:` | | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:
` | | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:
`. 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:
`. 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, reset, messages, sending, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). 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. `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). **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. | | **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:
`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. | | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) | | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:
`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. | | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope | | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. | | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` | | **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) | | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) | | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). | | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) | | **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: folderId) | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side and saves it as a file (`application/pdf`); same server-side renderer on web + native. | | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). | | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. | | **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider, purpose, pollIntervalMs })` (optional: every key, and the whole argument) | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. | All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`). `ctx.recordPermissions`, `ctx.users`, and `ctx.groups` **no longer exist** — they were folded into `ctx.datastore.records(t).permissions` and `ctx.directory.{users,groups}` respectively. See the design reference for the full architecture: [`docs/architecture/widget-marketplace.md`](../../docs/architecture/widget-marketplace.md), specifically section 3.1. ## Status `v0.150.1` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**. ### What's new in 0.150.1 (contract 1.118.0 — unchanged) **A capability's fallback belongs to the web build, not to native (sc-8381).** The barcode guidance here, in the in-Studio hooks reference and in both AI agents' prompts told you to gate the scan button on `supported` **and** keep a manual-entry path — unconditionally, while the reason given was a browser-only gap. `supported` is always `true` on the Expo export, so that read shipped a redundant "or type the code" field on every phone: the exact typing the scanner exists to remove. The rule is now scoped to the host that actually fails the gate. - **Gate the substitute on the same flag that gates the button.** Where `supported` is `false` — the web Player in Safari and Firefox, which ship no `BarcodeDetector` — render the typed field instead of the scan button. Where it is `true`, the capability is the whole input. Nothing about the API changed; only the guidance did. - **A native `catch` is an error state, not a web substitute.** The `react-native-nfc-manager` notes said to render "the same fallback from the `catch` that `widget.web.jsx` uses". A workspace that has not switched the NFC device capability on in Publish settings is a **misconfiguration** the widget should name, not a reason to park a permanent manual-entry field beside the tap target. - **The web half is still required.** This narrows where a *substitute* belongs; it does not relax the parity rule. A native-only capability still ships a real way in on `widget.web.jsx` — a typed code, a QR scan, a non-sensor path — and still degrades visibly rather than rendering blank. ### What's new in 0.150.0 (contract 1.118.0) **New primitive `` — pick an emoji without leaving for the OS keyboard (sc-8104).** Typed emoji always worked: a plain `` stores and renders them on both hosts, and nothing about that changes. What was missing was an in-app way to *choose* one — for a message composer, or to react to something. ```jsx const [open, setOpen] = useState(false); const [recents, setRecents] = useState([]); setOpen(false)} onSelect={(char) => { const { value } = insertAtCaret(draft, char, selection); setDraft(value); setOpen(false); }} /> ``` It presents inside ``, so it escapes the widget's clipping box on both hosts, and ships a curated Unicode set (categories, search, recents) as plain data — no emoji dependency to vet. `onSelect` hands you the character; `recents` / `onRecentsChange` let you persist the picks wherever your widget keeps state. Pair it with `insertAtCaret(value, char, selection)` to land the emoji mid-draft instead of appending it. **Also new: a shared reaction model.** `groupReactions(rows, { typeField, userField, userId })` turns reaction rows into per-emoji pill groups — one row per (target, user, emoji), de-duplicated per user — and `readReactionEmoji(value)` maps a stored value to its emoji, ignoring anything it does not recognise. Widgets storing reactions should group through these rather than rolling their own, so pills behave identically wherever they appear. ### What's new in 0.149.0 (contract 1.117.0) **Six text roles on the theme, so every widget speaks one typographic voice (sc-8058).** See the theme section above for the roles and how to read them. ### What's new in 0.148.0 (contract 1.116.0) **New `useAgent(agentRef)` hook — a widget can talk to the WORKSPACE's own AI agent (sc-7991).** A new `agents` host client (`@colixsystems/agents-client`), a new `agentRef` propertySchema type and a new `ai.invoke:*` scope. Everything is additive; nothing existing changes shape. A workspace **agent** is a name plus a system prompt its author wrote in the Studio. This hook lets any widget hold a conversation with one, without touching HTTP and without ever holding an API key. ```js const { send, reset, messages, sending, error, available } = useAgent(props.agentId); ``` **What a widget deliberately cannot do.** You cannot set the system prompt, send your own transcript, or pick a model, and no API surface returns the prompt. The server assembles every turn from the stored prompt plus the stored history, and `content` is the only field that reaches the wire — not because the rest is filtered out, but because nothing else is ever sent. That guarantee is about the WIRE, not about secrecy: a model can be talked into repeating its own prompt, so an agent's prompt is not a secret store — never put credentials, or data the app's users may not see, in one. `messages` is the transcript this widget has seen; the real one is the server's. **Imperative, like `useInterpretDraft`.** It never fires on mount, and the FIRST `send` opens the conversation — so a widget an author places and nobody types into costs the workspace nothing. **Bind it with an `agentRef` property.** Declare `{ type: "agentRef" }` in your `propertySchema` and the Studio renders an agent picker; the value is the agent id you pass to `useAgent`. It is a bare UUID like `pageRef` / `groupRef`, so Copy Workspace carries a bound widget over to the copied workspace's own agent. **Every send spends the workspace's AI credits**, and is rate-limited per caller *and* per workspace. Branch on `AgentError.code`: `AI_QUOTA_EXCEEDED` (429) is the credit ceiling and will **not** clear on a retry — offering "try again" there is worse than useless — where `RATE_LIMITED` (429) will. `AGENT_DISABLED` (409) means the author switched the agent off, so hide the affordance rather than retrying. Never show an app user a raw error or the workspace's billing state: they have not heard of an AI credit and cannot buy one. **`available: false` is a render state, not an error.** It means no agent is bound, or this host brokers no agents client (an unbound canvas preview). Render a visible unbound state — never a blank box. The linter rejects `useAgent()` unless your manifest declares `ai.invoke:*` in `requestedScopes`. ### What's new in 0.147.0 (contract 1.115.0) **BREAKING: the bottom navigation bar is themed by `footer` alone — `resolveFooterTokens` reads no `sidebar` (sc-8033).** Every colour fell back to the rail's, so restyling the sidebar restyled a page's bottom bar and the two could not be dressed apart. That is the defect sc-7951 set out to fix and only half did: it gave the strip a Design panel, but left the panel's "Active tab style" offering a **Follow the sidebar** option and every colour still inheriting. The resolver now reads `theme.footer` and nothing else, and the Studio panel offers the strip's **eight** settings with no inherit anywhere. - **The overloaded `activeColor` is retired** for **`footer.tabActiveBackgroundColor`** and **`footer.tabActiveTextColor`**. One key meant the FILL under `"filled"` and the LABEL under `"accent"`, which is exactly why no author could set both. They are independent now, and each style's *defaults* are what it already rendered — `"filled"`: the brand primary behind a white label; `"accent"`: no surface, a brand-primary label and top edge. So all four colours stay meaningful under both styles. - **`activeTint` is gone from `FooterTokens`.** The returned **`activeColor`** is the active tab's label, glyph and accent edge — one colour for all three, because a mark and its label disagreeing about which colour means "you are here" would be two marks. - **`backgroundColor` and `textColor` are resolved strings**, not raw-or-null. Both hosts kept their own `#ffffff` / `#475569` defaults for them; a default that lives in each host is the drift §8 exists to prevent, and these had already diverged once. `borderColor` stays nullable — no line, no colour. - **`borderWidth` admits `0` here alone**, where `resolveSidebarTokens` keeps sc-7965's 1–8 clamp. The strip's thickness is a Studio control offered down to zero, so a stored zero is an author saying "no line" rather than the junk that clamp refuses; it resolves into the existing no-divider state, so neither host needed new drawing code. **No shipped app moved.** A backfill (`20270123000000_sc8033_footer_tokens_uncouple`) materialised into each workspace's `footer` block exactly what it had been inheriting, and split every stored `activeColor` onto the key that says which half it meant. Nothing is written where the old chain ended in a default the new one also ends in. ### What's new in 0.146.0 (contract 1.114.0) **The chrome divider's width is bounded in the resolver, so both hosts agree (sc-7965).** `resolveFooterTokens` and `resolveSidebarTokens` returned `borderWidth` as any finite number. Only the export bounded it — on its way into the StyleSheet — so a stored `1e9` ruled a **billion-pixel border across the published web app** and a normal one in the exported app. The clamp moved into the shared resolver, where both hosts inherit it. - **Clamped, not dropped.** A value past the end lands **on** the end (1–8), the idiom `tabRadiusOr` / `tabIndicatorOr` already use. This moves the EXPORT too for such a value: it used to *drop* out-of-range and fall back to the 1px hairline, and now renders 8px like the Player. - **Zero clamps up**, matching what the export already rendered there — the divider's COLOUR is its switch, so a coloured 0px edge is a contradiction rather than "off". - **Every legal 1–8 value is untouched**, and the write path has always refused anything else, so only a hand-edited or pre-coercer `theme_config` can hold a value this moves. The site header was already bounded by its own resolver and is unchanged. The compiler keeps its own `coerceBorderWidth` as defence in depth over a blob `PUT /tenant/config` still stores verbatim; a test pins the two bounds to each other behaviourally, since the SDK cannot import the backend coercer. ### What's new in 0.145.0 (contract 1.113.0) **The app's bottom navigation bar gets its own active-tab look — `resolveFooterTokens` gains three (sc-7951).** `theme_config.footer` already carried an `activeStyle`, but no Studio control ever wrote it, so the SIDEBAR's active-item style silently decided the bottom bar too: an author who accented the rail accented the tab bar, with no way to separate them. The bar was also under-authorable — `"filled"` *bundled* the active tab's surface with its label, pinning the surface to `activeColor` and the label to a hard-coded white, so no author could paint a surface of their own. - **`footer.activeStyle` is now the bar's**, reachable from the Design page's Bottom navigation bar panel. Unset it still falls back to `sidebar.activeStyle`, so every existing workspace renders exactly as before. - **`footer.tabActiveBackgroundColor`** — the active tab's surface. New, and it falls back to **nothing**: a vertical rail item has no tab surface, so unlike the colours this inherits from no one. - **`footer.tabLayout`** — `"inline"` (the row the bar has always drawn) or `"stacked"`, the glyph above its label. Also footer-only. `resolveFooterTokens` now returns the active tab **already decided** — `activeSurface` (hex or `null`) and `activeTint` — so neither host re-derives the back-compat pairing. `"filled"` with nothing named is still the active colour behind a white label; **naming a surface unbundles the two**, and the label goes back to `activeColor` so the author owns both halves. `activeColor` is resolved in the helper now rather than by each caller, so it is a `string` rather than raw-or-null — `FooterTokens.activeColor` narrows accordingly. The inherited colours are also hex-guarded on the way **out**, not only in: the export already refused a malformed stored value while the Player handed it to a style object. It also settles a divergence the bar carried: under `"accent"` the web Player drew a **left** border (the rail's rule on a horizontal tab) and the export drew no edge at all. Both now mark the edge **facing the page** — a bottom tab's top — reserved transparent at every tab's width so marking one cannot shift the row. A tab is also the same 6px-rounded chip on both hosts, where native used to be square. ### What's new in 0.144.0 (contract 1.112.0) **The global mobile quick bar is retired — `quickBarMaxItems` and `quickBarCap` leave the contract (sc-7753, REQ-NAV-STRUCTURE / REQ-NAV-LOCAL).** The quick bar was a second global menu bolted to the sidebar: its own per-page flag, its own five-item cap, its own strip on the app's bottom edge. Since sc-7695 a page can carry a bottom navigation bar of its own drawing a saved menu, which is the same strip with an author-chosen list behind it — so the global one was a duplicate shape. - `CONTRACT.themeMenuTypes.sidebar` is now `{ name, summary, maxItems }`. `menuItemCap` is unchanged; `quickBarCap` is **removed** — a page's bottom bar draws the menu the author composed, so there is no global number to state. - `resolveFooterTokens` stays exactly as it is. It was never the quick bar's alone: it is the BOTTOM EDGE's token set, and the page's own bottom bar reads it, so a workspace's bottom-edge colours survive the retirement untouched. - The sc-7753 backfill turns each workspace's quick-bar pages into a saved menu and points the pages that drew the strip at it BEFORE this ships, so no destination is lost. - Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.112.0`. **A widget can name the screen it is on — `useScreenTitle(title)` + the optional `ctx.screen` slice (sc-7955).** The app header now shows the PAGE title beside the back control on a sub-page, instead of repeating the app brand on every screen. The page's own name is the default, but a page is often about one record, and only the widget has it: ```js const { data: order } = useDatastoreRecord(tableId, recordId); useScreenTitle(order ? `Order #${order.reference}` : null); ``` - The header reads "Order #1423" rather than "Orders" as soon as the record lands; before it does, the blank title leaves the page name standing (only a non-empty string registers). - `reportTitle` returns a release function, so the title reverts cleanly when the widget unmounts or its title empties. - **The most recent call wins.** With two title-setting widgets on one screen the last to report owns the header; when it goes, the host falls back to the most recent surviving report, then to the page name. - Only a screen that shows the back control paints a title — a root/menu page keeps the app brand or logo untouched. - Optional slice: on the Studio canvas and the Agent Mode edit preview there is no app header, so the hook is a no-op rather than an error. ### What's new in 0.142.1 **A native file upload no longer crashes the app (sc-7906).** Making the part a `File` let the upload through, and then the app died on any real file: Expo's `fetch` builds a multipart body by reading the WHOLE file into the JS heap — `convertFormDataAsync` awaits `part.bytes()` and concatenates — so a send costs about three times the file's size on the JS thread. The native host now streams the file off disk through expo-file-system's upload task instead. ``, `useCamera()` and `useImageEditor()` are unchanged for a widget author — the picked file stays where the picker put it, so `asset.uri` still renders, and the name the user chose travels to the backend as an explicit `file_name` field. ### What's new in 0.142.0 (contract 1.110.0) **An action script can finally tell WHO started the run — `triggeredBy` joins `CONTRACT.actionScriptGlobals` (sc-7885).** The identity was already captured (the run history has recorded an `actorId` since REQ-ACTION-RUNLOG) but never reached the sandbox, so a script could do the work and not attribute it: no "X submitted this" notification back to the submitter, no audit row naming the actor. Authors worked around it by writing the user id into a record first and switching to a `record_*` trigger — plumbing in the app's data model, and not available to a plain button press at all. ```js if (triggeredBy && triggeredBy.type === "app_user") { await notifications.notifyUser(triggeredBy.id, { title: "Request received", body: "Thanks " + triggeredBy.name + ", we have started on it.", }); } ``` - The shape is `{ type, id, name, email, role }`, frozen, or **`null` when nothing initiated the run** — a `schedule` tick or a `record_*` event. `null` is the normal case for the automation triggers, so guard before reading it. - **`type` is load-bearing, not decoration.** It is `"app_user"` on an `app` button press and an `http_post` webhook, and `"studio_user"` on an operator's Run now. One id column, two directories behind it: check `type` before handing the id to `notifications.notifyUser` or a USER column, or a studio user's id will silently resolve to nobody. `role` carries the app-user vocabulary (`USER` / `INTEGRATION`) and is `null` for a studio user, whose workspace role is a different axis entirely. `email` is likewise `null` for a studio user: nothing in a script can address an operator, so shipping their real address to an installed third-party Action would be PII with no consumer. - **It grants nothing.** The script still runs as the Action's bound integration identity, exactly as before; `triggeredBy` describes the caller and does not widen the data the script can reach. Resolution is host-side and tenant-scoped, so a stale or foreign id resolves to `null` rather than leaking a row across workspaces. - Actions never render, so this has **no effect on Player ↔ export parity** (CLAUDE.md §8). - Also in this release: **`properties` was added to `CONTRACT.actionScriptGlobals`**, which the `@colixsystems/action-sdk` copy of the list had carried since 1.50.0 while this one had not — the two hand-mirrored lists had drifted. A parity test now pins them together. `CONTRACT.version` → `1.110.0`. Additive for every existing manifest and script. ### What's new in 0.141.0 (contract 1.109.0) **The app's global navigation is the sidebar alone — `top-bar` and `bottom-tabs` leave `CONTRACT.themeMenuTypes` (sc-7352, REQ-NAV-STRUCTURE).** A top bar is now a PAGE's local bar drawing a saved menu (REQ-NAV-LOCAL, sc-7103): the same tab row the `top-bar` shape used to draw, themed by the same `topBar` tokens (`resolveTopBarTokens` is unchanged), worn by one page under the sidebar. Two "top bars" competing for one word and one token set was the reason. - `normaliseNavigation` resolves a stored `top-bar` or `bottom-tabs` to `sidebar`, so a host never has to guard the value. `menuItemCap` / `quickBarCap` keep their signatures (`quickBarCap("sidebar")` is still 5). *(`quickBarCap` was removed in 0.142.0.)* - The global menu never lived in the shape (it is the pages' `show_in_menu` flags), so a workspace that stored a retired shape already draws the sidebar with the same menu. The sc-7352 backfill deletes the stored key BEFORE the shapes disappear; a bottom-tabs app's phone strip becomes the sidebar's quick bar. *(That strip was itself retired in 0.142.0.)* - Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.109.0`. ### What's new in 0.140.0 (contract 1.108.0) **Three rules make a generated widget's EDITABILITY checkable, and `lintEditability` joins the linter export (sc-7799).** The rules that already had a deterministic gate — the three basic style fields, `no-hardcoded-design`, `style-field-unread` — held every time. The ones left to prose drifted: `ui.group`, per-element coverage and author-editable copy were guidance only, so some widgets shipped a grouped Style section covering every element while others shipped the three basics and nothing else, and wording was routinely pinned in the source where no author could reach it. - **`style-group-missing`** — a `styleSchema` field with no `ui.group`, or one filed under a catch-all name (`Advanced`, `Other`, `Misc`, `Style`, `Styles`, `General`) that rebuilds the flat list grouping exists to split. The three basics belong under `"Basics"`; each per-element field under the Title Case singular name of the element it styles (`"Card"`, `"Title"`, `"Row"`). - **`style-elements-uncovered`** — a widget that renders several visual elements while its `styleSchema` carries nothing beyond `background`/`textColor`/`align`. A genuinely single-element widget is exempt by construction. - **`text-literal-unexposed`** — a string literal sitting directly in a ``: copy that reaches neither the author nor the translation pipeline. All three are `warning`, so `appstudio-widget lint` reports them and still exits 0 — the human author decides when to act. The AI widget agent publishes with no human in the loop and `_lintFindingsToPublishChecks` turns every finding into a publish check regardless of severity, so the same three **block** an agent publish and drive a repair turn, with no new severity plumbing. `lintEditability(manifest, files)` is bundle-level like `lintStyleWiring`, and needs `--manifest` for the same reason. It counts rendered elements PER FILE, though: joining `widget.web.jsx` and `widget.native.jsx` would double every tag and call a single-`` split-impl widget multi-element. ### What's new in 0.139.0 (contract 1.108.0) **An author can BIND a colour field to the workspace brand instead of freezing a hex (sc-7800).** A `type: "color"` field tracked the theme only while it was *unset*, through its `themeDefault` placeholder. The moment the author picked a colour it became a literal that outranked the theme forever, so "make this our brand colour" was inexpressible — the author had to type today's hex, and it went stale silently at the next rebrand. A colour field's value may now be a **binding** — `"theme:colors.primary"` or `"theme:colors.secondary"` — which both hosts resolve to the workspace's current colour at render. - **Nothing changes for a widget author.** You keep declaring `{ type: "color", … }` and reading the value off `props.style` / `props`. The host hands your code an ordinary colour string either way, so never branch on a binding, never parse the `theme:` prefix, and never add a "use theme colour" toggle beside a colour field — the Studio's picker already offers the choice, and a second control for it is a dead knob. - **Only the two brand tokens are bindable**, listed on `CONTRACT.themeColorTokens`. The derived and contrast-paired tokens (`onPrimary`, `primarySoft`, `primaryStrong`, `loader`) are deliberately withheld: they are the host's to compute, and binding one half of a contrast pair produces unreadable text. - **An unresolvable binding falls back to the field's `themeDefault`**, exactly as an unset field does — it never paints blank. - **Fully additive.** Every colour already stored is a literal, is untouched, and renders byte-identically. ### What's new in 0.138.0 (contract 1.107.0) **Every file upload from the Expo export works again.** Expo's `fetch` implements the WEB FormData spec, so a part must be a string or a Blob — but `useCamera`, `useImageEditor` and `` all handed back React Native's legacy `{ uri, name, type }` triple, which it rejects with `Unsupported FormDataPart implementation` before a byte leaves the device. Web was unaffected because a browser `File` **is** a Blob, so it only ever reproduced on device. All three now hand back expo-file-system's `File`, carrying the same `uri` / `name` / `type` / `size` — so no widget needs a change. **`useFilestoreUpload` keeps the filename, and `fileName` works on both hosts.** A Blob appended with no filename is stored as `blob`. The name travels as `append()`'s third argument for a real Blob, and is set ON the part otherwise — expo-file-system's `File` is **not** `instanceof Blob` at runtime (`implements Blob` is TypeScript-only), and Expo reads the name off the part. `upload(file, { fileName })` overrides it. The native producers set `type` the same way, because the `File` derives it from the cache URI and leaves it empty when that URI has no extension. ### What's new in 0.137.0 (contract 1.106.0) **A `datastoreTemplate` column marked `encrypted` is now actually encrypted in the workspace that installs you (sc-7557).** The field was documented nowhere and honoured nowhere: install built its column rows one way, the republish/upgrade migration built them another way, and neither carried the flag — so a column you declared confidential was created as an ordinary plaintext column and nothing told you or your installer. Both paths now share one projection, so the flag lands on install and on upgrade alike. ```js datastoreTemplate: { tables: [ { suffix: "Patients", columns: [ { name: "Name", dataType: "STRING", required: true }, { name: "Ssn", dataType: "STRING", required: true, encrypted: true }, ], rows: [{ Name: "Ada Lovelace", Ssn: "600101-1234" }], }, ], } ``` - **Your widget code does not change.** It reads and writes plaintext through `useDatastoreQuery` / `useDatastoreMutation` exactly as it does for any other column — the platform encrypts on write (AES-256-GCM under a per-workspace subkey) and decrypts for end users. - **Studio users see `🔒`, not the value.** That is the point of the flag: the people authoring the app cannot read what their end users store. The column also cannot be searched, filtered or sorted on — ciphertext is opaque. - **Sample `rows` are encrypted too.** They used to be written straight into the value table; a plaintext row under an encrypted column would have been read back as a corrupt envelope. - **Not valid on `RELATION`.** Its value is a foreign key the backend has to resolve, so it can never be opaque — declaring it is now a publish error, as is a non-boolean `encrypted`. - **An upgrade adds a new encrypted column, but never flips a live one.** Turning encryption on over existing plaintext (or off over existing ciphertext) would strand what is already stored, so a changed flag on a column that already exists is reported back to you rather than applied. ### What's new in 0.136.0 (contract 1.105.0) **A `datastoreTemplate` can now say WHICH AUDIENCE gets which access — not just the two anonymous ones (sc-7530).** `publicGrant` could only ever reach `everyone` and `authenticated`, because those are the two principals that need no id. Anything naming a real user group was unexpressible: a group id belongs to the workspace that installs your widget, so it could never travel in your manifest. The practical cost was that a permission model you had already set up correctly — say an admin group with full CRUD while ordinary signed-in users only read — shipped to your installers as nothing at all, and every one of them rebuilt it by hand across both the table grant and the record permissions. Templates now name their audiences symbolically and let the installer bind them: ```js datastoreTemplate: { roles: [ { key: "admin", label: "Administrators", description: "Manages orders end to end" }, ], tables: [ { suffix: "Orders", columns: [...], // the id-less audiences, unchanged publicGrant: { canRead: true, canWrite: false, canDelete: false }, // the audience that needs a real group roleGrants: [{ role: "admin", canRead: true, canWrite: true, canDelete: true }], }, ], } ``` `roles` is declared ONCE per template and referenced by every table, so three widgets over two tables ask the installing workspace **one** question per audience rather than one per grant. At install they pick one of their own groups for each role, or have one created for them under the role's label. - **`key`** is lowercase-kebab (`/^[a-z][a-z0-9-]*$/`), at most 8 roles per template. A `roleGrants` entry naming a role you did not declare is a publish error, as is granting the same role twice on one table or granting it no verb at all. - **`canDelete` is row-level only.** A table-scope grant answers "may I create a record"; only a record permission answers a question about a row. Both halves are written for you from the one declaration. - **An unbound role is an ordinary outcome, never a failed install.** If the installer skips a role, no grant is written and they are told which role is still unbound — they can bind it later from the table's permissions. - **Purely additive.** A template declaring neither `roles` nor `roleGrants` behaves exactly as it does today. Also tightened in this release: the `publicGrant` flags are now type-checked. They never were, so a stringy `canRead: "false"` read as truthy and silently opened the table to anonymous reads. If you have been passing anything but a real boolean there, publishing will now tell you. ### What's new in 0.135.0 (contract 1.104.0) **NFC tags are vetted, native-only (`react-native-nfc-manager`).** A widget can now read and write NFC tags on the Expo export — NDEF over `NfcManager.requestTechnology(NfcTech.Ndef)`, plus the raw technologies a badge, asset tag or transit card uses: `NfcTech.IsoDep` on both hosts, `NfcTech.MifareClassic` on Android, `NfcTech.MifareIOS` / `FelicaIOS` / `Iso15693IOS` on iOS. (There is no `NfcTech.FeliCa` — check `index.d.ts` before naming one.) This is the last common "tap a physical thing" input the allowlist was missing; barcode and QR already had `useBarcodeScanner()`. - **Native-only, and the browser is why.** Web NFC ships in Chrome on Android alone — Safari, Firefox and every desktop browser omit it — so there is no web build to pair with. Put the import in `widget.native.jsx` and give `widget.web.jsx` a real way in: a typed code field, or the SDK's `useBarcodeScanner()` QR path. The linter's `import-platform-mismatch` enforces the split. - **Opt-in per workspace — and `isSupported()` cannot see that.** The export claims the iOS NFC entitlement and the Android `NFC` permission only when the publisher enables the **NFC tags** device capability in Publish settings. `isSupported()` probes the **device** (`readingAvailable` on iOS, `hasSystemFeature` on Android), not the gate: on a capable phone in an app that never asked, it returns `true` and the read then fails — Android throws a `SecurityException` from `registerTagEvent`, iOS cannot open the reader session. So wrap `start()` / `requestTechnology()` in a `try` and render a clear **error state** from the `catch` — name what is missing and say the capability has to be switched on in Publish settings. That `catch` is an error path, **not** the web build's typed-code substitute: do not give `widget.native.jsx` a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. - **Clean up the session.** `cancelTechnologyRequest()` in your effect cleanup; an abandoned request leaves the reader sheet up on iOS. - **It is a write capability too.** Read with `getNdefMessage()`; write with `writeNdefMessage(bytes)`, `formatNdef(bytes)` (Android only, for a blank tag) and `transceive(bytes)` on the `IsoDep` / `NfcA` / `NfcV` handlers. One capability covers both — Android expresses read and write through the single `android.permission.NFC` — so the workspace owner who enables it is consenting to every widget in the workspace being able to rewrite the tags their users tap. Raw ISO7816 `transceive` on iOS additionally needs `select-identifiers` on the entitlement, which the export does not declare; NDEF read and write work on both hosts. - **`makeReadOnly()` is irreversible.** It permanently locks the tag — no later write will ever succeed, on any device, by any app. Call it only where the feature genuinely wants a one-time-programmable tag, and never as a cleanup step after writing. ### What's new in 0.134.2 (contract 1.103.0 — unchanged) **Defect fix: `useImageEditor()` now rejects the same inputs on both hosts, and two blob/state leaks are gone (sc-7205).** Review of the 0.126.0 hook found a real web↔native divergence and two bookkeeping bugs it had inherited from `useCamera`. `CONTRACT.version` does **not** move — the contract already promises identical validation across hosts; this makes the implementation honour it. - **An out-of-bounds crop now rejects `INVALID_ACTION` on web too.** A canvas silently padded the region outside the source with transparent — black once JPEG-encoded — and reported the padded dimensions, while both native platforms threw (and the throw was relabelled `DECODE_FAILED`). Dragging a crop past the edge is the commonest thing a crop UI produces. - **`compress` is range-checked on both hosts.** Out of range silently fell back to the browser's default quality on web and threw from `Bitmap.compress` on Android. - **`reset()` during an edit no longer wedges `editing` at `true`**, and **an edit still running at unmount now releases its blob**. Both bugs exist in `useCamera` too and are fixed there in the same change (CLAUDE.md §3). - A failed `base64` encode no longer leaks its object URL; a derived resize dimension is floored to match the native transformers; the web decode retries without CORS so it accepts the same sources native does at DECODE time (a cross-origin image whose host sends no `Access-Control-Allow-Origin` still taints the canvas and fails at encode with `ENCODE_FAILED`, where native succeeds — the browser's rule, not ours); and `isSupported()` no longer allocates a DOM node per render. The web broker also gains the test file it shipped without — the previous 16 cases all drove a *fake* broker, so none of the transform maths ever ran. ### What's new in 0.134.0 (contract 1.103.0) **Formatted content can carry links and tables (sc-7349).** `` and `` covered emphasis, headings, lists and images, but a link was not in the grammar at all — so a post that said "see the Booking page" had no way to get the reader there, and a comparison table could only be faked with spaces. ```jsx ``` - **Links: `[label](target)`.** The target is stored **verbatim** and followed through the host's `navigation.openLink`, which already decides page / external / refuse. An absolute URL leaves the app; a bare page id or slug navigates inside it; anything unfollowable (`javascript:`, a control character) is refused by that one resolver. Never pre-filter a target yourself, and never route one through `Linking.openURL` — it performs anything. A link label keeps its own emphasis, so `[**Book now**](booking)` reads bold. - **Tables: a header row, a `| --- | --- |` divider, then body rows.** `:--` / `--:` / `:-:` in a divider cell sets that column's alignment, and `\|` puts a literal pipe in a cell. Cells are equal-width columns whose text wraps, so a wide table stays inside the widget on a phone instead of scrolling sideways. - **Two new toolbar buttons.** Table inserts a skeleton with the first header cell selected. Link opens a form for the link text plus its target — and when you pass the new optional `pages` prop (`[{ id, name }]`) it offers those pages by name, the way `renderImage` is supplied for filestore images. Without `pages` the form offers only an external address, because a widget cannot know the app's pages on its own. - **`` gains `followLinks`** (default `true`). The editor's own preview passes `false`, so links render styled but inert and a tap while writing cannot navigate away from the draft. Additive — one shared view module per primitive, bound per host, so both hosts gain this together. Every string already stored keeps parsing identically: a line needs a divider row to become a table, and `![alt](src)` is still read as an image, never a link. `CONTRACT.version` → `1.103.0`. ### What's new in 0.133.1 (contract 1.102.1) **Hook signatures no longer carry doc-style optional markers (sc-6946).** `CONTRACT.hooks[].signature` used to write optionality inline — `useFilestoreFiles({ spaceType, folderId?, q?, type? })` — but a `?` inside a destructuring pattern or object literal is a parse error, and the AI widget agent renders those signatures into its prompt verbatim. Every signature is now a call form that parses; the omittable parts moved to a new `optionalArgs` array the prompt prints beside it. The hook table above was rewritten to match (the version history below is left as each release wrote it). - **Documentation only.** No hook gained, lost, or changed an argument — `useFilestoreFiles({ spaceType })` and `useDirectory()` behave exactly as before. Only the way the contract *writes down* which arguments are optional has changed. ### What's new in 0.133.0 (contract 1.102.0) **A required `tableRef` needs a `datastoreTemplate` table that answers to its NAME, not just another table in the list (sc-6965).** 0.57.0's publish gate `manifest.requiredTableRefsHaveTemplate` compared COUNTS — it passed as soon as `datastoreTemplate.tables` plus any host-supplied tables outnumbered the `required` `tableRef` props. So a widget with two required props published on any two template tables, including the case where both of them name the SAME prop and the other has nothing: the installer, which binds by name, then had no table for it and fell back to whichever one was left over — your widget wired to a table its code was never written against. The gate now runs the installer's own matcher over your template, per property: a table's `suffix` must answer to the property's name (`ordersTableId` needs suffix `Orders`), and the failure names only the properties nothing answers to, with the suffix each one wants. **What still passes unchanged:** the conventional bare `tableId`, which carries no name to match and takes the first table still free; a property marked `sharedTable: true`, which seeds nothing by design (0.106.0); and a standalone submit with no template at all, which fails exactly as it did. **What to change if you are newly rejected:** name the table after the property it is for — that is the pairing that was always going to decide the binding. Every first-party widget passes unchanged. No export, type, hook, or manifest field changed shape — a publish-gate tightening plus documentation. `CONTRACT` is unchanged (no new field). ### What's new in 0.132.0 (contract 1.102.0) **BREAKING: the top bar has no divider — `resolveTopBarTokens` drops `borderColor` and `borderWidth` (sc-7360).** The bar and its tab row are one surface; a line under the bar ruled it off from its own menu, and a line under the tabs ruled the menu off from the page it navigates. Neither host draws one any more, the Design page offers no colour or width for one, and `TopBarTokens` no longer carries the two fields. A stored `topBar.borderColor` / `borderWidth` is **inert, not migrated** — nothing reads it, and the theme coercer drops it from a saved look or a Mason `set_theme`. The rail's, footer's and site header's dividers are unchanged. - `resolveSidebarTokens` / `resolveFooterTokens` are unchanged. No `CONTRACT` change. ### What's new in 0.131.0 (contract 1.102.0) **`styleGroup(name)` is deprecated and now inert (sc-7344).** The Widget Builder preview's click-to-select mode — the primitive's only reader — has been removed, so nothing maps a clicked element back to its style group any more. Style fields are edited through the whole-widget style editor the gear button opens. - **No migration needed.** `styleGroup()` is still exported and still returns the same props, so existing `` spreads keep building and rendering exactly as before — they are simply no-ops now. It was always a marker that changed nothing about how a widget renders. - **Don't add it to new widgets.** The AI widget agent no longer emits it. ### What's new in 0.130.0 (contract 1.101.0) **~~New primitive `styleGroup(name)`~~ — superseded by 0.131.0, see above (sc-7282).** A widget's `styleSchema` already names the element each field belongs to via `ui.group` ("Card", "Title", "Value"), and the Studio renders those as labelled fieldsets. But a group name says which *fieldset* a control sits in, not which *element on screen* it moves — so clicking a button in the Widget Builder preview could only ever open the whole schema. *(Historical — the guidance below no longer applies; see 0.131.0 above.)* - **Spread it on the element each non-Basics group paints:** ``. Pass the EXACT `ui.group` string; a mismatch marks an element no group owns. Mark each group ONCE, on the outermost element an author would point at — never the `"Basics"` group (it paints the whole widget) and never a child of an already-marked element. On a list that repeats a marked element per row, mark every row. - **One module, both hosts.** It rides the existing `dataSet` prop: `react-native-web` maps it to a `data-*` attribute, and real react-native drops it, so the marker is inert on the device rather than a second implementation. It is a marker, not a style — it changes nothing about how a widget renders. ### What's new in 0.129.0 (contract 1.100.0) **Widgets can READ a barcode now — `useBarcodeScanner()` (sc-7228).** A widget could already *generate* a QR code (`react-native-qrcode-svg`) but never read one, so the whole class of apps that starts by pointing a phone at a label — inventory counts, asset check-in/out, warehouse picking, ticket scanning, scan-on-delivery — had no way in. ```jsx import { useBarcodeScanner, BarcodeError } from "@colixsystems/widget-sdk"; const { result, scanning, supported, scan, reset } = useBarcodeScanner(); const hit = await scan(); // { value, format } | null ``` `scan()` is **imperative** — call it from a tap, because both hosts gate the camera permission prompt on a gesture. It resolves the first code decoded, resolves `null` when the user dismisses (a dismissal is NOT an error), and rejects a `BarcodeError` with `.code` of `PERMISSION_DENIED | UNSUPPORTED | INTERNAL`. `format` is a lowercase symbology name (`qr_code`, `code_128`, `ean_13`, …) and is a **hint**: the two hosts detect different sets, so never branch on it for correctness. It is deliberately **one-shot** rather than a start/stop subscription — to read several codes, call `scan()` again. There is no loop to leave running and no camera to forget to release. **Gate the button on `supported`, and keep the manual-entry path for the host that fails that gate.** `BarcodeDetector` is Chromium-only today, so the web Player reports `supported: false` in Safari and Firefox — a genuine browser gap, not a missing feature, and there the scanner must not be the only way to enter a code. The Expo export always reports `true`, so do **not** mirror the typed field onto native: on the phone the scanner is the whole input, and the twin field is the typing the scan was meant to remove. Gate the substitute on the same flag that gates the button: ```jsx {supported ? Scan : } {/* On the phone there is no typed field to fall back to, so a denied camera has to say so rather than leave a button that does nothing. */} {error ? Camera access is off — turn it on in Settings to scan. : null} ``` That error line is not optional on native. `supported` is `true` there, so the scan button is the only way in — a `PERMISSION_DENIED` the widget swallows leaves the user tapping a control that silently does nothing. **Host-brokered, not a vetted import.** Like the camera and speech-to-text, your widget never imports the native module: `expo-camera` is pinned by the Expo export only, so a widget that does not scan gains no native dependency and nothing new enters widget bundles. ### What's new in 0.128.0 (contract 1.99.0 — unchanged) **New linter rule `flex-basis-percent` — a percentage `flexBasis` sizes the HEIGHT in a column (sc-7274).** A generated form carried one shared field helper, `style={{ flexGrow: 1, flexBasis: wide ? "100%" : 220 }}`, used both as a row cell (where the number is exactly right) and as a full-width field stacked in a column (where the percentage is a trap). `flex-basis` sizes the **main** axis, and a column's main axis is the **height**: each wide field was asking for its parent's entire height. It rendered correctly in the builder canvas — an auto-height ancestor leaves the percentage indefinite, so it degrades to `content` — and broke the moment the page shipped, because a Grid cell stretches its child on the web Player and made that height definite. Measured on the published page: the group was 633px tall and every wide field inside it was **also** 633px, so with `View`'s default `flex-shrink: 0` they could not shrink back and overflowed 633px and 1266px down, painting a blank band mid-form and three fields on top of the section below and the submit row. - **`flex-basis-percent` (severity `warning`, non-blocking).** A literal percentage `flexBasis` — `"100%"`, `"50%"`, and the responsive ternary `flexBasis: stacked ? "100%" : CARD_WIDE` — is flagged. Author fix: **`width: "100%"`**, which is the direction-agnostic way to say "full width": it fills the row in a column parent AND takes its own line in a wrap row, so nothing is lost by switching. Keep a **number** (`flexBasis: 220`) where you mean a wrap threshold. It is a **warning**, not an error, because in a ROW parent the percentage IS correct and an AST-free scan cannot see the parent's `flexDirection` — the offending style usually lives in a shared cell helper far from its parent. Scope is the literal inline form; a basis threaded through a variable is beyond the scan, and the designer skill's form guidance remains the first guard. Comments are not scanned, so documenting the anti-pattern is safe. ### What's new in 0.127.0 (contract 1.99.0) **Widgets can do maths now — five pure-JS packages join the vetted import allowlist (sc-7191).** The list had 31 entries and exactly one non-UI utility (`date-fns`), so anything numeric a widget needed had to be hand-rolled in a sibling file. Two gaps in particular: - `decimal.js` — exact decimal arithmetic. The platform has payments, invoicing and VAT, and a total accumulated in IEEE-754 floats drifts from what the backend actually charged. `new Decimal(a).plus(b).toFixed(2)` does not. - `d3-scale` + `d3-shape` + `d3-array` — the scale, path-generator and domain maths a bespoke chart needs. `d3-shape` emits path strings you hand straight to the already-vetted `react-native-svg`'s ``, so a custom line/area/donut chart is ONE source file that renders identically in the Player and the Expo export. - `simple-statistics` — mean/median/quantile/regression/correlation, for summarising a datastore table without shipping a maths framework. All five are `platforms: ["web", "native"]` with no native module, so this is **full parity**, not a §8 native-only case. Each is host-shimmed in the Player and pinned in the export for the same reason `date-fns` is: an AI-agent widget is transpiled rather than bundled, so its bare import has to resolve at runtime on both hosts. `mathjs` was considered and deliberately left off — 9.4 MB unpacked with nine transitive dependencies, and a web-vetted package is bundled into the Studio. Additive: no existing entry, hook, primitive or `propertySchema` type changed shape. `CONTRACT.version` → `1.99.0`. ### What's new in 0.126.0 (contract 1.98.0) **A widget can edit an image now, not just take one — new `useImageEditor()` (sc-7193).** `useCamera()` (0.121.0) let a widget capture a photo and `ctx.assets.upload` let it send one, but nothing could *change* one: no resize before upload, no crop to an aspect ratio, no straightening a sideways shot. A profile-picture widget had to upload the full-resolution original and hope the server-side normaliser did something acceptable. ```js const { capture } = useCamera(); const { edit } = useImageEditor(); const shot = await capture(); const small = await edit(shot.uri, [{ resize: { width: 800 } }], { format: "jpeg", compress: 0.8 }); const fd = new FormData(); fd.append("file", small.file); await ctx.assets.upload(fd); ``` `edit(uri, actions, options?)` applies `actions` in order and resolves the SAME normalised asset shape `useCamera()` yields, so capture → edit → upload is one code path on both hosts. Actions are `{ resize: { width?, height? } }`, `{ crop: { originX, originY, width, height } }`, `{ rotate: degrees }` and `{ flip: "horizontal" | "vertical" }`; output is `{ format: "jpeg" | "png" | "webp", compress, base64? }`. **Host-brokered, not a vetted import** — the same call `expo-image-picker` and `expo-speech-recognition` already got. Widgets reach it through the hook and never import the package, so it stays out of every widget bundle and parity is the SDK's problem rather than each author's. The web Player brokers it on a canvas *inside the host* (your widget never touches the DOM); the Expo export uses `expo-image-manipulator`. There is deliberately **no `extent` action**. It exists only on web in `expo-image-manipulator`, and a capability the Player has but the export does not is the direction CLAUDE.md §8 forbids. The `device.imageEditor` slice is OPTIONAL, so a host that brokers nothing degrades the hook to `supported: false` rather than throwing — gate your edit control on it. Additive: no existing hook, primitive, manifest field or `propertySchema` type changed. `CONTRACT.version` → `1.98.0`. ### What's new in 0.125.0 (contract 1.97.0) **A `top-bar` app no longer chooses which row carries its menu — `CONTRACT.themeTopBarMenuStyles` is REMOVED and `normaliseNavigation` returns `menuType` alone (sc-7044).** 0.120.0 gave the shape two menu rows to pick between: `links`, the row of text links beside the brand it had always drawn, and `tabs`, a dedicated tab row beneath the bar. `links` turned out to be the site-mode header's own row — literally the same `header` nav variant, sitting in the Studio beside "Show a header on site-mode pages" and its "Menu links" toggle, so an author was offered three adjacent settings that render the same thing. The tab row is the one that reads as an app's global navigation, so it is now the only one. A host branches on `menuType` alone: - `CONTRACT.themeTopBarMenuStyles` is gone, and so is the `ThemeTopBarMenuStyle` type. `ResolvedNavigation` is `{ menuType }`. - `resolveTopBarTokens` is UNCHANGED — the whole `topBar` tab vocabulary (`tabStyle`, `contentSurface`, `tabIndicatorWidth`, `tabCornerRadius`, `tabPaddingX` / `tabPaddingY`, `tabBackgroundColor`, `tabActiveBackgroundColor`) now applies to every `top-bar` app rather than only to one that opted into tabs. - A stored `navigation.topBarMenuStyle` is **inert**, not migrated. Nothing reads it, so no backfill runs; a `top-bar` app that never chose `tabs` renders the tab row from this version on. **BREAKING, host-integration surface only** — a host that destructured `topBarMenuStyle` must stop. Nothing a widget author imports moved: no hook, primitive, manifest field or `propertySchema` type changed. `CONTRACT.version` → `1.97.0`. ### What's new in 0.124.0 (contract 1.96.0) **A `filterList` condition can scope itself to the signed-in app-user (sc-6282).** `valueMode` used to be `literal` or `relativeDate`, so every filter value was a constant chosen at build time. "Show only my rows" was therefore not something a no-code author could express — it needed a custom widget reading `ctx.user` and filtering client-side, which put the scoping decision in code the server does not enforce. Two actor-scoped modes join the vocabulary: - **`currentUser`** on a `USER` column — the rows whose user column is the caller. - **`currentUserGroup`** on a `USER_GROUP` column — the rows assigned to any group the caller belongs to (live groups only; a tombstoned group surfaces nothing). Both **carry no value**. The condition sends the `me` sentinel and the backend resolves the identity from the request actor, so a tampered widget config cannot redirect the sentinel at another user, and a caller with no session matches **nothing** rather than every row. Valid with `eq` / `neq` only — any other operator is rejected as `INVALID_FILTER`, rather than quietly answering "mine". To be precise about what this is: it scopes what the widget **displays**. It is not an access-control boundary — a signed-in user can always ask for the unfiltered list, so row privacy has to come from the table's record ACL (a creator-only template). Use the two together. `eq` reads as "mine", `neq` as "not mine". In the Studio the author gets a signed-in-user checkbox on the row, offered only for the column type that can carry an identity. Additive — `literal` and `relativeDate` conditions are unchanged, and an author-supplied `value` is simply ignored by the new modes. `CONTRACT.version` → `1.96.0`. ### What's new in 0.123.0 (contract unchanged at 1.95.0) **Two new primitives, `` and `` — a widget can finally let an app user write FORMATTED text (sc-6970).** Widgets render through React Native primitives, which have no `dangerouslySetInnerHTML` on either host, so there was no path at all from a content string to bold, a heading or a list. A generated "manage content" widget that was asked for a formatting toolbar therefore drew a fake B/I/H2 bar over a plain `TextInput` whose buttons spliced literal ``/`
` tags into the value — the author read tag soup with no preview of the text a reader would get, and the reader got the tags. Content is **markdown text** now: one primitive authors it, the other renders it, and the string that travels between them is the one you store. ```jsx ``` `` is a multi-line field, a toolbar whose buttons wrap the current **selection** in markdown markers (bold, italic, code, H2, H3, bullets, numbered list — pressing one again toggles it back off), and a live `` preview of the result underneath. `previewLabel` defaults to `Preview` and `showPreview` to `true`; `minHeight` (150) and `maxHeight` (280) give the field a floor and a ceiling, so a long draft scrolls inside its box instead of growing past its card. Reach for it instead of a bare `TextInput` plus hand-rolled formatting buttons, which can only splice literal tags into the text. `` parses the subset — `**bold**`, `*italic*` / `_italic_`, `` `code` ``, `#`/`##`/`###` headings, `-`/`*` bullets, `1.` ordered items, and one-line `![alt](src "large")` images — and renders it with SDK primitives, so formatted content reads the same in the web Player and the exported Expo app. Colour, type scale and leading come from the workspace theme; never re-style them. Pass `renderImage` (`({ src, alt, size }) => node`) when images are filestore ids, because resolving one needs the scopes your own widget holds — without it only absolute `http(s)` URLs render. HTML is never interpreted: stored text that still holds markup is stripped to plain text rather than shown as tags. The grammar is exported too, for content you need to inspect rather than render: `parseMarkdown(text)` returns the block list, `markdownToPlainText(text)` a marker-free projection for a list preview, a search index or an accessibility label, `parseMarkdownImage(line)` / `formatMarkdownImage(block)` read and write the one-line image form, `stripHtmlToMarkdown(text)` normalises a legacy HTML row on read, and `MARKDOWN_IMAGE_SIZES` is the closed size list (`small` | `medium` | `large` | `full`). A widget that renders images itself through `renderImage` gets the image half of the same grammar, so it classifies a src exactly the way the parser does rather than re-deriving the rule: `isSafeMarkdownImageSrc(src)` (an `http(s)` URL or a filestore id — anything else, a `javascript:` scheme included, is refused), `isHttpImageSrc(src)` to tell a URL from a filestore id, `normaliseMarkdownImageSize(size)` and `readMarkdownAlt(raw)`. The linter gains `no-html-in-content` to catch the old shape: an HTML tag inside a **string** (`""`, `"
"`, `"

…

"`) is flagged, because no host will ever render it. Only string and template content is scanned, so your own `` / `` JSX cannot trip it. Warning-severity for a human author, blocking for the AI widget agent. Additive — two new primitives, ten new grammar exports, one new soft linter rule; no existing export changed signature. `CONTRACT.primitives` carries both entries; `CONTRACT.version` is unchanged at `1.95.0`. ### What's new in contract 1.95.0 (package unchanged at 0.122.0) **`useCamera().capture()` opens a real camera on the DESKTOP web Player.** The web broker's only camera surface was ``, and that attribute is honoured by phone browsers but **silently ignored on the desktop** — so on a laptop `capture()` opened an ordinary file dialog, indistinguishable from `pick()`. It now opens a live `getUserMedia` preview with a shutter, on every web host. Nothing a widget imports changed: same signature, same normalised asset, same `PERMISSION_DENIED | UNSUPPORTED | INTERNAL` vocabulary, and the Expo export is untouched. Three things a widget can observe: `options.quality` now reaches the encoder on web (it previously reached nothing); a phone gets the same in-page preview rather than its OS camera app, which trades the phone camera's optics for one behaviour everywhere; and a camera that cannot be opened (no device, or another app holding it) rejects `UNSUPPORTED` instead of quietly showing a file dialog. ### What's new in 0.122.0 (contract 1.94.0) **A refused filestore upload now says it is a PERMISSION problem (sc-6977).** `useFilestoreUpload` and `usePdfExport` relay whatever the destination decides, and that decision used to arrive as a bare `404 "Space not found"` no matter who asked. sc-5395 chose that masking for one good reason — an **anonymous** prober must not be able to enumerate which workspaces have opened their public space — but it applied to every caller, so a signed-in author uploading a cover image hit a dead end with nothing to act on. The refusal now splits along what the caller can already see: - **403** when the caller can READ the destination (the response body carries `code: "UPLOAD_NOT_PERMITTED"`, which the client puts on `err.details.code` — `err.code` is the client's own `"FORBIDDEN"`, so branch on `err.status`). The common case is a `public` space, which is world-readable but upload-**deny-by-default**: the workspace operator has to switch upload access on (Studio → File library → the space → upload access). Naming that discloses nothing the caller could not already see. - **404 `"Space not found"`** wherever saying more would leak: an anonymous caller, or a position hidden from this one (a restricted folder, a foreign `owner_id`, another tenant). A masked refusal carries no `code`. No hook signature moved, so nothing has to change to keep working — but a widget that branched on `404` alone should accept **both**, which is what the built-in Files widget now does. Folder creation and a folder move report the same split (`FOLDER_CREATE_NOT_PERMITTED` / `FOLDER_MOVE_NOT_PERMITTED`). ### What's new in 0.121.0 (contract 1.93.0) **An unset nav-chrome surface follows the PAGE, not a flat white — `resolveSidebarTokens` / `resolveTopBarTokens` (sc-6596).** 1.84.0 converged the two hosts' separately-written chrome defaults onto the web Player's `#ffffff`. Converging was right; the value was not. An app with a themed page and no explicit `sidebar`/`topBar` `backgroundColor` got bright white chrome beside the colour its author had picked — consistently on both hosts, and consistently wrong. Both resolvers now resolve an unset `backgroundColor` to the colour the page actually shows: the app's `backgroundColor`, or a configured `backgroundGradient`'s start colour, falling back to the app default (`#f8fafc`) when the theme names neither. A gradient counts only when BOTH its stops are flat hex, which is what the hosts' own page readers require — a half-configured gradient paints nothing, so the chrome must not adopt its start colour. Per REQ-THEME-17 the page is read at FULL STRENGTH: a stored `#RRGGBBAA` reaches the chrome as its opaque base, because an alpha on the app's bottom layer composites against the host's canvas rather than anything the author chose. This is deliberately NOT the rule an `attached` top-bar tab follows. A tab JOINED to the page refuses a translucent page rather than approximate it; chrome sitting BESIDE the page follows what the page renders. Both read one shared chain, which differs by exactly that rule. An explicitly coloured rail or bar is unaffected. An app that themed nothing moves from `#ffffff` to the `#f8fafc` its page already was. The footer strip is untouched and still floors at white — it keeps `resolveFooterTokens`' raw-or-null shape and wants this same treatment next. **Behaviour change, not additive:** no signature, field or export moved — only what a host renders for an unset chrome surface. Host-integration surface only; nothing a widget imports changed. `CONTRACT.version` → `1.93.0`. ### What's new in 0.120.0 (contract 1.92.0) **A `top-bar` app chooses which ROW its menu lives in, and how that row looks — `CONTRACT.themeTopBarMenuStyles` plus the `topBar` tab vocabulary (REQ-NAV-STRUCTURE).** The shape drew its menu as text links beside the brand, sharing the bar's one row wherever there was space. That reads as part of the header rather than as the app's global navigation. `topBarMenuStyle` now picks between `links` (that row, unchanged) and `tabs` — a dedicated tab row under the bar at every width, icon and label per page, scrolling sideways rather than dropping one. `normaliseNavigation` returns it beside `menuType`, so one resolver still answers both questions and the Player and the export cannot disagree about which row an app draws. Absent, unknown, or set on any other shape resolves to `links`. `resolveTopBarTokens` gains the vocabulary that row is painted with: - **`activeColor`** — the current page's mark: the active link's label, and an active tab's label and indicator. Its fallback chain is the FOOTER's rather than a new one: the bar's own value, else the **rail's**, else the brand. An app should not have to state the same navigation colour three times, and the rail is where an author already sets it. Unlike the footer's, this chain ends in the brand rather than in null — an active mark has no null state. - **`tabStyle`** (`underline` | `attached`) and **`contentSurface`**. `attached` makes the current tab a folder tab joined to the page. The join is made by CONSTRUCTION rather than by matching: an opaque tab cannot track a page that is not flat, so the content area takes the same surface and becomes the panel the tab sits in. `contentSurface` is that shared value — always opaque, following a gradient to its start colour, and honouring an authored active surface so moving the tab moves the page with it. - **`tabBackgroundColor`** / **`tabActiveBackgroundColor`** — a tab's own surface per state, authored or null. Null paints none and the bar shows through. - **`tabIndicatorWidth`** (0-8, default 2) — the underline under the current tab. Zero draws none, so the WIDTH is its switch: the indicator shares `activeColor` with the label and has no null colour to switch on. - **`tabCornerRadius`** (0-24) rounds the tab's TOP corners only — its feet stay square whatever the value, because a rounded foot notches the join — and **`tabPaddingX`** / **`tabPaddingY`** (0-32) replace the frozen 12/8, which remain the defaults. Every measurement is CLAMPED rather than dropped: landing on the end of the range is what an author dragging a slider means. Host-integration surface only — no author-facing hook, prop, primitive, or manifest field changed. ### What's new in 0.119.0 (contract 1.91.0) **`useGeolocation()` can now track location while the app is BACKGROUNDED (sc-6450).** The hook only ever read a position while the app was in the foreground, so the whole class of field-work apps — delivery tracking, site visits, mileage and timesheet logging — could not be built. Its result gains four members; the existing foreground API is untouched: | Member | Shape | Notes | | --- | --- | --- | | `backgroundSupported` | `boolean` | **Check this before rendering the control.** | | `backgroundWatching` | `boolean` | Whether a watch is running on this device. | | `startBackgroundWatch` | `(options?) => Promise` | `options`: `{ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs }`. | | `stopBackgroundWatch` | `() => Promise` | Releases the OS subscription. | ```jsx const { latitude, longitude, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch } = useGeolocation(); {backgroundSupported && (