@colixsystems/widget-sdk 0.97.0 → 0.99.0

package/README.md

@@ -6,7 +6,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 | Injected at | Package | Surface (snake_case verbatim, `list` → `{ data, meta }`) |
 | ----------- | ------- | -------- |
-| `ctx.datastore` | `@colixsystems/datastore-client` | `tables.{list,get}`, `schema(tableId)`, `records(tableId).{ list(query), get(id), create(values), update(id,values) [PATCH], delete(id), aggregate(spec), permissions(recordId).{ list, grant, update, revoke } }` |
+| `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)` |
@@ -38,12 +38,15 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useSpeechToText(options?)` | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
+| **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
+| **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
+| **DATASTORE** | `useCanWrite(tableId, options?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "is this caller signed in AND permitted", reading the same table-ACL answer the write endpoint enforces. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type? })` | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
@@ -64,10 +67,50 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.91.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.95.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.97.0 (contract 1.69.0)
+### What's new in 0.95.0 (contract 1.68.0)
+
+**One number for the quick bar's cap — `quickBarMaxItems` + `quickBarCap`.** The sidebar's secondary mobile quick bar caps at five, and that five lived in two places: a named constant in the web chrome and a bare literal in the compiler. Nothing stopped them drifting, and no Studio surface could state the number at all.
+
+`CONTRACT.themeMenuTypes.*.quickBarMaxItems` now carries it (5 on `sidebar`, `null` on the two shapes that draw no quick bar), read through the new `quickBarCap(menuType)` host export.
+
+The distinction from `menuItemCap` is the point and is worth keeping straight: **`quickBarCap` may drop a page** — the rail and the drawer still list every menu page, so the bar is a shortcut. **`menuItemCap` may not** — where the chrome IS the menu (`bottom-tabs`), the surplus moves behind a More sheet instead.
+
+Host-integration surface only. `CONTRACT.version` → `1.68.0`.
+
+### What's new in 0.94.0 (contract 1.67.0)
+
+**The footer strip is themeable — `resolveFooterTokens` (REQ-NAV-STRUCTURE).** The bottom strip's surface was hard-coded white on both hosts and its items read the SIDEBAR's tokens. That is fine while the strip is the sidebar's secondary quick bar, and untenable once it IS the menu: the `bottom-tabs` shape hides the sidebar panel, so those tokens have nowhere to be set.
+
+A `theme_config.footer` block now carries `backgroundColor`, `textColor`, `activeColor` and the opt-in divider `borderColor` + `borderWidth`. **Every field falls back to the sidebar's**, so a workspace that never touches it renders exactly as before and only an explicit value moves anything.
+
+`resolveFooterTokens(theme)` (from `@colixsystems/widget-sdk/host`) is the one resolver both hosts read it with. It also settles two divergences the strip carried: the native bar ruled a permanent `#e2e8f0` hairline the theme could not reach — REQ-THEME-LOOK's rule is that the divider's **colour** is its switch — and it tinted the active tab's *label* where the web painted a filled pill, so `activeStyle: "filled"` meant two different things per host.
+
+Host-integration surface only: no author-facing hook, prop, primitive, or manifest field changed. `CONTRACT.version` → `1.67.0`.
+
+### What's new in 0.93.0 (contract 1.66.0)
+
+**An app picks the SHAPE its navigation takes — `CONTRACT.themeMenuTypes` (REQ-NAV-STRUCTURE).** Until now the chrome was always a sidebar: a persistent left rail on desktop, a hamburger drawer plus an optional bottom quick bar on mobile. That is the right default for an admin tool and the wrong one for a phone-first app or a site, and there was no way to say so. `CONTRACT.themeMenuTypes` publishes the closed catalogue — `sidebar`, `top-bar`, `bottom-tabs` — each entry carrying `{ name, summary, maxItems }`.
+
+`maxItems` caps how many menu pages the chrome draws at once, and its meaning differs per type deliberately: the sidebar's mobile quick bar is a **secondary** curated bar whose cap may drop a page (the rail still lists every one), while a `bottom-tabs` strip **is** the menu, so its cap must never drop one — the surplus moves behind a More sheet instead.
+
+**New host exports (`@colixsystems/widget-sdk/host`)** — `normaliseNavigation(navigation)` resolves a stored `theme_config.navigation` block to the `{ menuType }` a host switches its chrome on, and `menuItemCap(menuType)` states that shape's cap. One implementation for both hosts, so a menu type cannot mean one thing in the web Player and another in the exported Expo app. An absent or unknown value resolves to `sidebar`, so every app authored before menu types existed renders and compiles byte-identically.
+
+Host-integration surface only: no author-facing hook, prop, primitive, or manifest field changed. `CONTRACT.version` → `1.66.0`.
+
+### What's new in 0.98.0 (contract 1.70.0)
+
+**Three new hooks close the biggest gaps in the write-gating and query-authoring surface (sc-5206).**
 
+- **`useBoundColumns(tableId, shape, props)`** — resolve author-bound column NAMES from a widget's own props, built on `useDatastoreSchema`. Falls back name → case-insensitive name → first unclaimed column matching `dataType`, so `record[props.titleField]` reading `undefined` after a tenant renames a column is no longer a widget's problem: read `record[bound.titleField]` (via `const { columns: bound } = useBoundColumns(tableId, shape, props)`) and it keeps resolving.
+- **`useStableQuery(buildQuery)`** — the same content-diffed stable-reference trick `useDatastoreQuery` already applies to its own `query` argument, generalised into a reusable hook: `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` and its easy-to-get-wrong deps array. Reads no `ctx` — safe outside a `WidgetContextProvider`.
+- **`useCanWrite(tableId, options?)`** — a write-permission FLOOR reading a new `ctx.datastore.myPermissions` client method. `{ canWrite, loading, error, refetch }`; pass `{ recordId }` for a per-row check. Not a replacement for a MORE SPECIFIC domain rule (still hand-check "only the assigned user" in addition), and not a replacement for `useUser()` when the UI needs to tell "not signed in" apart from "signed in but forbidden".
+
+The SDK linter gained two matching soft-warning rules: `raw-useMemo-into-datastore-query` (a `useDatastoreQuery` argument built from a raw `useMemo` when the file hasn't reached for `useStableQuery`) and `hand-rolled-write-gate` (a write gated on `useUser().groupIds`/`.roles` when the file hasn't reached for `useCanWrite`). Both are steering nudges (`severity: "warning"`), never publish-blocking.
+
+- **`CONTRACT.version` → `1.70.0`** (additive: three new hooks + the new `datastore.myPermissions` context field + two linter rules). No existing export changed signature.
+### What's new in 0.97.0 (contract 1.69.0)
 **`CONTRACT.themeComponents` gains five scopes: `accent`, `destructive`, `muted`, `popover`, `ring` (sc-5392).** The vocabulary shipped with exactly `button`/`card`/`text` (sc-1497), so a shadcn/Tailwind app import's `--accent`, `--destructive`, `--muted`, `--popover` and `--ring` custom properties had no `themeConfig` home and were reported "no theme home" on every import. Each new scope binds to real `styleSchema` fields on the built-ins that already had a matching surface — `accent` (a highlight/tag surface: `background`/`borderColor`/`radius`) to the Label widget's own fields, `destructive` (a themed danger/delete action: `background`/`textColor`/`borderColor`) to a new "Danger" Button variant, `muted` (a subtle/secondary surface: `background`/`textColor`/`borderColor`/`radius`) to Form Input's and Form Builder's pre-existing input fields, `popover` (a dropdown/menu surface: `background`/`textColor`/`borderColor`) to the same two widgets' choice-field option list, and `ring` (the app-wide focus-visible outline: `color`/`width`) to a new emphasis border on Button. **This is HOST-ONLY plumbing, exactly like the three scopes before it** — `useTheme()`'s documented `components` slice is unchanged, no widget-authoring hook or `propertySchema` type moved, and no scope declares `universalFields`, so a third-party or AI-generated widget's contract is unaffected; the Developer guide and `DEFAULT_SYSTEM_PROMPT` need no update because neither ever documented this internal vocabulary. Fully additive: a theme with no `components` key, or one using only `button`/`card`/`text`, resolves exactly as before.
 - **`CONTRACT.version` → `1.69.0`** (additive: five new `themeComponents` scopes + their target-field bindings). No existing scope, token, or export changed shape.
 
@@ -1002,6 +1045,60 @@ The manifest declares the matching scope:
 
 The server-side gate is `canGrant` on the target record — Studio owners pass automatically; an APP_USER holds `canGrant` as the record's creator or via a delegated grant. A caller without `canGrant` receives `PermissionError { code: "FORBIDDEN" }`. The hook collapses to a stable no-op when `tableId` or `recordId` is null/empty — so a widget can render its picker first, then bind to the picked record without conditional hook tricks.
 
+## Resolving bound columns, a stable query, and a write-permission floor
+
+`useBoundColumns`, `useStableQuery`, and `useCanWrite` (sc-5206) target the three most common ways a widget goes wrong against a table it doesn't fully control: a renamed column reading `undefined`, a query argument that refetches in a loop, and a write control offered to someone the table forbids.
+
+```js
+import {
+  Text,
+  View,
+  Pressable,
+  useBoundColumns,
+  useStableQuery,
+  useDatastoreQuery,
+  useCanWrite,
+  useUser,
+} from "@colixsystems/widget-sdk";
+
+export default function OpenTasks({ tableId, titleField, statusField }) {
+  // Resolves to the CURRENT column names even if the author's binding is
+  // stale (a column renamed after install), instead of reading `undefined`.
+  const { columns: bound, loading: schemaLoading } = useBoundColumns(
+    tableId,
+    { titleField: { dataType: "STRING" }, statusField: { dataType: "STRING" } },
+    { titleField, statusField },
+  );
+
+  // A binding is undefined until the schema resolves, so hold the query back
+  // rather than filtering on an undefined column name.
+  const ready = Boolean(bound.statusField);
+  // A stable query argument with no useMemo deps array to get wrong.
+  const query = useStableQuery(() => ({
+    filter: ready ? { [bound.statusField]: "eq:open" } : {},
+    sort: { field: "created_at", dir: "desc" },
+  }));
+  const { data, loading } = useDatastoreQuery(ready ? tableId : null, query);
+
+  const user = useUser();
+  const { canWrite } = useCanWrite(tableId);
+
+  if (schemaLoading || loading) return <Text>Loading…</Text>;
+  return (
+    <View>
+      {data.map((row) => <Text key={row.id}>{row[bound.titleField]}</Text>)}
+      {!user.id ? (
+        <Text>Sign in to add a task</Text>
+      ) : canWrite ? (
+        <Pressable onPress={() => {/* … */}}><Text>Add task</Text></Pressable>
+      ) : null /* signed in but not permitted — no control, not a disabled one */}
+    </View>
+  );
+}
+```
+
+`useCanWrite` answers "is this table's ACL open to me" — it is a FLOOR, not the whole rule. A widget whose own logic is more specific ("only the assignee may edit this row") still hand-checks that in addition, typically with `options.recordId` passed to a second `useCanWrite` call or a plain `user.id === record[assigneeField]` comparison.
+
 ## Cross-platform widgets (single-file vs split)
 
 Every widget runs in **both** the web Player and the exported native (Expo) app.

package/dist/contract.cjs

@@ -159,6 +159,42 @@ const THEME_WIDGET_STYLES = Object.freeze({
   // Matches the styleSchema field cap the widget agent is held to.
   maxFieldsPerWidget: 12,
 });
+// REQ-NAV-STRUCTURE: the SHAPE an app's navigation takes. One catalogue, four
+// consumers -- the Studio's Navigation page, Mason's set_theme coercion, the web
+// PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
+// author without every host actually drawing it.
+//
+// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
+// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
+// curated bar, so its own cap may drop a page -- the rail still lists every one.
+// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
+// moves behind a "More" sheet instead.
+const THEME_MENU_TYPES = Object.freeze({
+  sidebar: Object.freeze({
+    name: "Sidebar",
+    summary:
+      "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
+    maxItems: null,
+    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
+    // the rail and the drawer still list every one -- the opposite of
+    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
+    quickBarMaxItems: 5,
+  }),
+  "top-bar": Object.freeze({
+    name: "Top bar",
+    summary:
+      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+    maxItems: null,
+    quickBarMaxItems: null,
+  }),
+  "bottom-tabs": Object.freeze({
+    name: "Bottom tabs",
+    summary:
+      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
+    maxItems: 4,
+    quickBarMaxItems: null,
+  }),
+});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -474,6 +510,23 @@ const HOOKS = [
     requiredContextSlice: ["i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useStableQuery",
+    signature: "useStableQuery(buildQuery)",
+    description:
+      "sc-5206 — keep whatever buildQuery() returns at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so it can " +
+      "be passed straight into useDatastoreQuery's second argument (useDatastoreQuery(tableId, useStableQuery(() => ({...})))) instead of a hand-rolled " +
+      "useMemo with an easy-to-get-wrong deps array. This generalises the same trick useDatastoreQuery already applies internally to its own query " +
+      "argument. buildQuery is a ZERO-ARG function called every render; pure React state — no ctx, no host required, safe outside a " +
+      "WidgetContextProvider. Never throws: a buildQuery that itself throws degrades to a stable undefined, and a result JSON.stringify can't diff " +
+      "(e.g. a circular structure) degrades to \"always a new reference\".",
+    returnShape: {
+      "(returns)":
+        "T | undefined  // the hook returns buildQuery()'s result directly, not a wrapper object",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useUser",
     signature: "useUser()",
@@ -924,6 +977,29 @@ const HOOKS = [
     requiredContextSlice: ["datastore.schema"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useBoundColumns",
+    signature: "useBoundColumns(tableId, shape, props)",
+    description:
+      "sc-5206 — resolve author-bound column NAMES from a widget's own props, built on useDatastoreSchema. shape is " +
+      "{ [propKey]: { dataType?, optional? } }; props is the widget's own props carrying author-bound column names (e.g. props.titleField === " +
+      "'Title'). Resolution order per key: (1) an exact name match on props[key], (2) a case-insensitive name match, (3) the first column whose " +
+      "data_type matches shape[key].dataType that no EARLIER key in this call already claimed, (4) unresolved. Unresolved NEVER throws — the key " +
+      "reads undefined, so a column an author renamed after install still resolves instead of crashing the widget. Returns { columns, resolved, " +
+      "missing, loading, error }: columns holds the resolved column NAME — a drop-in replacement for record[props.titleField] -> " +
+      "record[columns.titleField]; resolved holds the full Column object (snake_case verbatim, as useDatastoreSchema returns it) so a caller can " +
+      "inspect resolved.<key>.data_type; missing lists every key whose spec is not optional:true and did not resolve. Falsy tableId collapses to " +
+      "{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null } without a network round-trip.",
+    returnShape: {
+      columns: "{ [propKey]: string | undefined }",
+      resolved: "{ [propKey]: Column | undefined }",
+      missing: "string[]  // required (non-optional) keys that did not resolve",
+      loading: "boolean",
+      error: "DatastoreError | null",
+    },
+    requiredContextSlice: ["datastore.schema"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useInterpretDraft",
     signature: "useInterpretDraft(tableId)",
@@ -1295,6 +1371,28 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
+  // sc-5206 — table/record write-permission floor, reading the injected
+  // ctx.datastore.myPermissions.
+  {
+    name: "useCanWrite",
+    signature: "useCanWrite(tableId, options?)",
+    description:
+      "sc-5206 — is the signed-in caller permitted to write to tableId (or, with options.recordId, to that one row)? Returns { canWrite, loading, " +
+      "error, refetch }, reading the injected ctx.datastore.myPermissions(tableId, { recordId }). This is a FLOOR, not a full replacement for " +
+      "domain-specific write rules: a widget whose 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 to useCanWrite (user.id === record[assigneeField]). It only answers 'signed in AND permitted' — it does " +
+      "NOT distinguish 'not signed in' from 'signed in but forbidden' (both resolve canWrite:false); pair it with useUser() when the UI needs to " +
+      "tell those apart. myPermissions is a newer client method: a host that has not injected it is NOT a hard error — this hook collapses to " +
+      "{ canWrite: false, loading: false, error: null, refetch: async () => undefined } rather than throwing. Same collapse when tableId is falsy.",
+    returnShape: {
+      canWrite: "boolean",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.myPermissions"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-RT-07 — realtime table subscription.
   {
     name: "useDatastoreSubscription",
@@ -1826,13 +1924,19 @@ const WIDGET_CONTEXT_SHAPE = {
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
-      "{ tables: { list(), get(idOrName), interpret(idOrName, body) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "{ tables: { list(), get(idOrName), interpret(idOrName, body), myPermissions(idOrName, { recordId? }) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
       "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
       "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
-      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing). " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema() and useBoundColumns(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing); `myPermissions` backs useCanWrite() (sc-5206 — the caller's effective table/record write permission). " +
       "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function", tables: "object", interpret: "function" },
+    fields: {
+      records: "function",
+      schema: "function",
+      tables: "object",
+      interpret: "function",
+      myPermissions: "function",
+    },
   },
   directory: {
     description:
@@ -3065,7 +3169,37 @@ const CONTRACT = deepFreeze({
   //    shadcn/Tailwind import's matching custom properties have a themeConfig
   //    home instead of being reported lost. Host-only plumbing: no scope
   //    declares `universalFields`, so a third-party manifest is unaffected.
-  version: "1.69.0",
+  // 1.70.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes`, the closed
+  //    catalogue of navigation shapes an app can take (`sidebar`, `top-bar`,
+  //    `bottom-tabs`) with the per-type item cap. Read from `theme_config`
+  //    as `navigation.menuType`; absent or unknown resolves to `sidebar`, so
+  //    every app that exists today renders and compiles byte-identically.
+  //    Resolved through the new `normaliseNavigation` host export rather than
+  //    a literal per host.
+  // 1.71.0: additive (REQ-NAV-STRUCTURE) -- `resolveFooterTokens` (host
+  //    export). The footer strip's surface was hard-coded white on BOTH hosts
+  //    and its items read the SIDEBAR's tokens, which stops being tenable the
+  //    moment the strip IS the menu (`bottom-tabs` hides the sidebar panel, so
+  //    those tokens have nowhere to be set). A `theme_config.footer` block now
+  //    carries its own, every field falling back to the sidebar's so an
+  //    untouched workspace is unchanged.
+  // 1.72.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes.*.quickBarMaxItems`
+  //    and the `quickBarCap` host export. The sidebar's secondary quick bar
+  //    capped at five in TWO places -- a named constant on web and a bare `5`
+  //    literal in the compiler -- so the number could drift between the hosts
+  //    and no Studio surface could state it at all.
+  // 1.73.0: additive (sc-5206) — three new hooks: `useBoundColumns(tableId,
+  //    shape, props)` resolves author-bound column NAMES by name -> case-
+  //    insensitive name -> dataType fallback, so a renamed column still
+  //    resolves instead of the widget reading `record[props.titleField]`
+  //    directly and getting `undefined`; `useStableQuery(buildQuery)`
+  //    generalises `useDatastoreQuery`'s own content-diffed stable-reference
+  //    trick so a widget stops hand-rolling `useMemo` with a wrong deps
+  //    array; `useCanWrite(tableId, { recordId? })` reads a new
+  //    `ctx.datastore.myPermissions` client method as a write-permission
+  //    FLOOR, replacing the previous prompt-only "read useUser().groupIds /
+  //    .roles" guidance. No existing export changed signature.
+  version: "1.73.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3081,6 +3215,7 @@ const CONTRACT = deepFreeze({
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
+  themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/contract.js

@@ -159,6 +159,42 @@ const THEME_WIDGET_STYLES = Object.freeze({
   // Matches the styleSchema field cap the widget agent is held to.
   maxFieldsPerWidget: 12,
 });
+// REQ-NAV-STRUCTURE: the SHAPE an app's navigation takes. One catalogue, four
+// consumers -- the Studio's Navigation page, Mason's set_theme coercion, the web
+// PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
+// author without every host actually drawing it.
+//
+// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
+// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
+// curated bar, so its own cap may drop a page -- the rail still lists every one.
+// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
+// moves behind a "More" sheet instead.
+const THEME_MENU_TYPES = Object.freeze({
+  sidebar: Object.freeze({
+    name: "Sidebar",
+    summary:
+      "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
+    maxItems: null,
+    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
+    // the rail and the drawer still list every one -- the opposite of
+    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
+    quickBarMaxItems: 5,
+  }),
+  "top-bar": Object.freeze({
+    name: "Top bar",
+    summary:
+      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+    maxItems: null,
+    quickBarMaxItems: null,
+  }),
+  "bottom-tabs": Object.freeze({
+    name: "Bottom tabs",
+    summary:
+      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
+    maxItems: 4,
+    quickBarMaxItems: null,
+  }),
+});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -474,6 +510,23 @@ const HOOKS = [
     requiredContextSlice: ["i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useStableQuery",
+    signature: "useStableQuery(buildQuery)",
+    description:
+      "sc-5206 — keep whatever buildQuery() returns at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so it can " +
+      "be passed straight into useDatastoreQuery's second argument (useDatastoreQuery(tableId, useStableQuery(() => ({...})))) instead of a hand-rolled " +
+      "useMemo with an easy-to-get-wrong deps array. This generalises the same trick useDatastoreQuery already applies internally to its own query " +
+      "argument. buildQuery is a ZERO-ARG function called every render; pure React state — no ctx, no host required, safe outside a " +
+      "WidgetContextProvider. Never throws: a buildQuery that itself throws degrades to a stable undefined, and a result JSON.stringify can't diff " +
+      "(e.g. a circular structure) degrades to \"always a new reference\".",
+    returnShape: {
+      "(returns)":
+        "T | undefined  // the hook returns buildQuery()'s result directly, not a wrapper object",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useUser",
     signature: "useUser()",
@@ -924,6 +977,29 @@ const HOOKS = [
     requiredContextSlice: ["datastore.schema"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useBoundColumns",
+    signature: "useBoundColumns(tableId, shape, props)",
+    description:
+      "sc-5206 — resolve author-bound column NAMES from a widget's own props, built on useDatastoreSchema. shape is " +
+      "{ [propKey]: { dataType?, optional? } }; props is the widget's own props carrying author-bound column names (e.g. props.titleField === " +
+      "'Title'). Resolution order per key: (1) an exact name match on props[key], (2) a case-insensitive name match, (3) the first column whose " +
+      "data_type matches shape[key].dataType that no EARLIER key in this call already claimed, (4) unresolved. Unresolved NEVER throws — the key " +
+      "reads undefined, so a column an author renamed after install still resolves instead of crashing the widget. Returns { columns, resolved, " +
+      "missing, loading, error }: columns holds the resolved column NAME — a drop-in replacement for record[props.titleField] -> " +
+      "record[columns.titleField]; resolved holds the full Column object (snake_case verbatim, as useDatastoreSchema returns it) so a caller can " +
+      "inspect resolved.<key>.data_type; missing lists every key whose spec is not optional:true and did not resolve. Falsy tableId collapses to " +
+      "{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null } without a network round-trip.",
+    returnShape: {
+      columns: "{ [propKey]: string | undefined }",
+      resolved: "{ [propKey]: Column | undefined }",
+      missing: "string[]  // required (non-optional) keys that did not resolve",
+      loading: "boolean",
+      error: "DatastoreError | null",
+    },
+    requiredContextSlice: ["datastore.schema"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useInterpretDraft",
     signature: "useInterpretDraft(tableId)",
@@ -1295,6 +1371,28 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
+  // sc-5206 — table/record write-permission floor, reading the injected
+  // ctx.datastore.myPermissions.
+  {
+    name: "useCanWrite",
+    signature: "useCanWrite(tableId, options?)",
+    description:
+      "sc-5206 — is the signed-in caller permitted to write to tableId (or, with options.recordId, to that one row)? Returns { canWrite, loading, " +
+      "error, refetch }, reading the injected ctx.datastore.myPermissions(tableId, { recordId }). This is a FLOOR, not a full replacement for " +
+      "domain-specific write rules: a widget whose 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 to useCanWrite (user.id === record[assigneeField]). It only answers 'signed in AND permitted' — it does " +
+      "NOT distinguish 'not signed in' from 'signed in but forbidden' (both resolve canWrite:false); pair it with useUser() when the UI needs to " +
+      "tell those apart. myPermissions is a newer client method: a host that has not injected it is NOT a hard error — this hook collapses to " +
+      "{ canWrite: false, loading: false, error: null, refetch: async () => undefined } rather than throwing. Same collapse when tableId is falsy.",
+    returnShape: {
+      canWrite: "boolean",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.myPermissions"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-RT-07 — realtime table subscription.
   {
     name: "useDatastoreSubscription",
@@ -1826,13 +1924,19 @@ const WIDGET_CONTEXT_SHAPE = {
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
-      "{ tables: { list(), get(idOrName), interpret(idOrName, body) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "{ tables: { list(), get(idOrName), interpret(idOrName, body), myPermissions(idOrName, { recordId? }) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
       "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
       "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
-      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing). " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema() and useBoundColumns(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing); `myPermissions` backs useCanWrite() (sc-5206 — the caller's effective table/record write permission). " +
       "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function", tables: "object", interpret: "function" },
+    fields: {
+      records: "function",
+      schema: "function",
+      tables: "object",
+      interpret: "function",
+      myPermissions: "function",
+    },
   },
   directory: {
     description:
@@ -3065,7 +3169,37 @@ const CONTRACT = deepFreeze({
   //    shadcn/Tailwind import's matching custom properties have a themeConfig
   //    home instead of being reported lost. Host-only plumbing: no scope
   //    declares `universalFields`, so a third-party manifest is unaffected.
-  version: "1.69.0",
+  // 1.70.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes`, the closed
+  //    catalogue of navigation shapes an app can take (`sidebar`, `top-bar`,
+  //    `bottom-tabs`) with the per-type item cap. Read from `theme_config`
+  //    as `navigation.menuType`; absent or unknown resolves to `sidebar`, so
+  //    every app that exists today renders and compiles byte-identically.
+  //    Resolved through the new `normaliseNavigation` host export rather than
+  //    a literal per host.
+  // 1.71.0: additive (REQ-NAV-STRUCTURE) -- `resolveFooterTokens` (host
+  //    export). The footer strip's surface was hard-coded white on BOTH hosts
+  //    and its items read the SIDEBAR's tokens, which stops being tenable the
+  //    moment the strip IS the menu (`bottom-tabs` hides the sidebar panel, so
+  //    those tokens have nowhere to be set). A `theme_config.footer` block now
+  //    carries its own, every field falling back to the sidebar's so an
+  //    untouched workspace is unchanged.
+  // 1.72.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes.*.quickBarMaxItems`
+  //    and the `quickBarCap` host export. The sidebar's secondary quick bar
+  //    capped at five in TWO places -- a named constant on web and a bare `5`
+  //    literal in the compiler -- so the number could drift between the hosts
+  //    and no Studio surface could state it at all.
+  // 1.73.0: additive (sc-5206) — three new hooks: `useBoundColumns(tableId,
+  //    shape, props)` resolves author-bound column NAMES by name -> case-
+  //    insensitive name -> dataType fallback, so a renamed column still
+  //    resolves instead of the widget reading `record[props.titleField]`
+  //    directly and getting `undefined`; `useStableQuery(buildQuery)`
+  //    generalises `useDatastoreQuery`'s own content-diffed stable-reference
+  //    trick so a widget stops hand-rolling `useMemo` with a wrong deps
+  //    array; `useCanWrite(tableId, { recordId? })` reads a new
+  //    `ctx.datastore.myPermissions` client method as a write-permission
+  //    FLOOR, replacing the previous prompt-only "read useUser().groupIds /
+  //    .roles" guidance. No existing export changed signature.
+  version: "1.73.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3081,6 +3215,7 @@ const CONTRACT = deepFreeze({
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
+  themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,