@colixsystems/widget-sdk 0.146.0 → 0.148.0

package/README.md

@@ -47,6 +47,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
+| **AGENTS** | `useAgent(agentRef)` | `{ send, 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:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `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) |
@@ -71,7 +72,41 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.146.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.148.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.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)
 

package/dist/contract.cjs

@@ -1172,6 +1172,47 @@ const HOOKS = [
     requiredContextSlice: ["datastore.interpret"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useAgent",
+    signature: "useAgent(agentRef)",
+    description:
+      "sc-7991 — 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, each " +
+      "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
+      "You CANNOT set the system prompt, replay an edited transcript, " +
+      "or pick a model. No API returns the prompt — but that is a guarantee " +
+      "about the WIRE, not secrecy: a model can be talked into repeating its " +
+      "own prompt, so never put credentials or hidden data in one. " +
+      "or pick a model: the server assembles every turn from the stored " +
+      "prompt plus the stored history, and `content` is the only thing that " +
+      "goes on the wire. `agentRef` is an agent id an author bound through an " +
+      "`agentRef` property — when it is missing, or the host brokers no " +
+      "agents client, `available` is false and send() rejects UNAVAILABLE; " +
+      "render a visible unbound state, NEVER a blank box. reset() drops the " +
+      "thread and clears the transcript (a 'new chat' affordance). " +
+      "Every send spends the workspace's AI CREDITS and is rate-limited per " +
+      "caller AND per workspace, so call it once per user action. " +
+      "AgentError.code distinguishes the refusals that share a status: " +
+      "AI_QUOTA_EXCEEDED (429) is the workspace's credit ceiling and will " +
+      "NOT clear on a retry — never offer 'try again' for it — where " +
+      "RATE_LIMITED (429) will; AGENT_DISABLED (409) means the author turned " +
+      "it off, so hide the affordance rather than retrying. NEVER surface a " +
+      "raw error or the workspace's billing state to an app user. " +
+      "Reads ctx.agents.",
+    returnShape: {
+      send: "(text) => Promise<{ id, role, content, created_at } | null>",
+      reset: "() => void",
+      messages: "Array<{ id, conversation_id, role, content, created_at }>",
+      sending: "boolean",
+      error: "AgentError | null",
+      available: "boolean  // false when no agent is bound, or the host brokers none",
+    },
+    requiredContextSlice: ["agents.conversations"],
+    scopes: ["ai.invoke:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -2271,6 +2312,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { params: "object", set: "function" },
   },
+  agents: {
+    description:
+      "sc-7991 — injected @colixsystems/agents-client instance. " +
+      "{ conversations(agentId) -> { create(), list(query), remove(conversationId), " +
+      "messages(conversationId) -> { list(query), send({ content }) } } }. " +
+      "Backs useAgent(). The workspace's agent owns the system prompt and the " +
+      "server owns the transcript, so `send` puts ONLY `content` on the wire — " +
+      "a prompt, a history or a model id cannot be smuggled through. " +
+      "A conversation belongs to the CALLER (the app user, or the studio user " +
+      "previewing on the canvas); another user's id is a 404, never a 403. " +
+      "Absent on a host that brokers no agents (an unbound preview), where " +
+      "useAgent() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { conversations: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -4054,6 +4110,10 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.116.0: additive (sc-7991) — `useAgent(agentRef)` + the `agents` host
+  // client + the `agentRef` propertySchema type + the `ai.invoke:*` scope. A
+  // widget can hold a conversation with one of the WORKSPACE's own AI agents.
+  // Nothing existing changes shape.
   // 1.114.0: behaviour (sc-7965) — `resolveFooterTokens` / `resolveSidebarTokens`
   //    now return a `borderWidth` CLAMPED to 1-8 instead of any finite number.
   //    The bound lived only in the export (`coerceBorderWidth(...) ?? 1`), so a
@@ -4064,7 +4124,23 @@ const CONTRACT = deepFreeze({
   //    Zero clamps up for the same reason the export already rendered 1 there —
   //    the divider's COLOUR is its switch. Every legal 1-8 value is unchanged,
   //    and only a hand-edited or pre-coercer blob can hold anything else.
-  version: "1.114.0",
+  // 1.115.0: BREAKING on the pre-1.0 channel (sc-8033) — `resolveFooterTokens`
+  //    reads `theme.footer` and NOTHING else. Every colour used to fall back to
+  //    `theme.sidebar`, so restyling the rail restyled a page's bottom
+  //    navigation bar and the two could not be dressed apart — the defect
+  //    sc-7951 set out to fix and only half did. The wire block's overloaded
+  //    `activeColor` (the FILL under "filled", the LABEL under "accent") is
+  //    retired for `tabActiveBackgroundColor` + `tabActiveTextColor`, two
+  //    independent halves; `activeTint` folds into the returned `activeColor`,
+  //    which is now the active tab's label, glyph and accent edge. The returned
+  //    `backgroundColor` and `textColor` are resolved strings rather than
+  //    raw-or-null, so neither host keeps a default of its own. `borderWidth`
+  //    admits 0 HERE alone — the strip's thickness is a Studio control offered
+  //    down to zero, and zero resolves into the existing no-divider state —
+  //    where the rail's and the header's keep sc-7965's 1-8 clamp. A backfill
+  //    (`20270123000000_sc8033_footer_tokens_uncouple`) materialised what each
+  //    workspace was inheriting, so no shipped app moved.
+  version: "1.116.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1172,6 +1172,47 @@ const HOOKS = [
     requiredContextSlice: ["datastore.interpret"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useAgent",
+    signature: "useAgent(agentRef)",
+    description:
+      "sc-7991 — 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, each " +
+      "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
+      "You CANNOT set the system prompt, replay an edited transcript, " +
+      "or pick a model. No API returns the prompt — but that is a guarantee " +
+      "about the WIRE, not secrecy: a model can be talked into repeating its " +
+      "own prompt, so never put credentials or hidden data in one. " +
+      "or pick a model: the server assembles every turn from the stored " +
+      "prompt plus the stored history, and `content` is the only thing that " +
+      "goes on the wire. `agentRef` is an agent id an author bound through an " +
+      "`agentRef` property — when it is missing, or the host brokers no " +
+      "agents client, `available` is false and send() rejects UNAVAILABLE; " +
+      "render a visible unbound state, NEVER a blank box. reset() drops the " +
+      "thread and clears the transcript (a 'new chat' affordance). " +
+      "Every send spends the workspace's AI CREDITS and is rate-limited per " +
+      "caller AND per workspace, so call it once per user action. " +
+      "AgentError.code distinguishes the refusals that share a status: " +
+      "AI_QUOTA_EXCEEDED (429) is the workspace's credit ceiling and will " +
+      "NOT clear on a retry — never offer 'try again' for it — where " +
+      "RATE_LIMITED (429) will; AGENT_DISABLED (409) means the author turned " +
+      "it off, so hide the affordance rather than retrying. NEVER surface a " +
+      "raw error or the workspace's billing state to an app user. " +
+      "Reads ctx.agents.",
+    returnShape: {
+      send: "(text) => Promise<{ id, role, content, created_at } | null>",
+      reset: "() => void",
+      messages: "Array<{ id, conversation_id, role, content, created_at }>",
+      sending: "boolean",
+      error: "AgentError | null",
+      available: "boolean  // false when no agent is bound, or the host brokers none",
+    },
+    requiredContextSlice: ["agents.conversations"],
+    scopes: ["ai.invoke:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -2267,6 +2308,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { params: "object", set: "function" },
   },
+  agents: {
+    description:
+      "sc-7991 — injected @colixsystems/agents-client instance. " +
+      "{ conversations(agentId) -> { create(), list(query), remove(conversationId), " +
+      "messages(conversationId) -> { list(query), send({ content }) } } }. " +
+      "Backs useAgent(). The workspace's agent owns the system prompt and the " +
+      "server owns the transcript, so `send` puts ONLY `content` on the wire — " +
+      "a prompt, a history or a model id cannot be smuggled through. " +
+      "A conversation belongs to the CALLER (the app user, or the studio user " +
+      "previewing on the canvas); another user's id is a 404, never a 403. " +
+      "Absent on a host that brokers no agents (an unbound preview), where " +
+      "useAgent() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { conversations: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -4050,6 +4106,10 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.116.0: additive (sc-7991) — `useAgent(agentRef)` + the `agents` host
+  // client + the `agentRef` propertySchema type + the `ai.invoke:*` scope. A
+  // widget can hold a conversation with one of the WORKSPACE's own AI agents.
+  // Nothing existing changes shape.
   // 1.114.0: behaviour (sc-7965) — `resolveFooterTokens` / `resolveSidebarTokens`
   //    now return a `borderWidth` CLAMPED to 1-8 instead of any finite number.
   //    The bound lived only in the export (`coerceBorderWidth(...) ?? 1`), so a
@@ -4060,7 +4120,23 @@ const CONTRACT = deepFreeze({
   //    Zero clamps up for the same reason the export already rendered 1 there —
   //    the divider's COLOUR is its switch. Every legal 1-8 value is unchanged,
   //    and only a hand-edited or pre-coercer blob can hold anything else.
-  version: "1.114.0",
+  // 1.115.0: BREAKING on the pre-1.0 channel (sc-8033) — `resolveFooterTokens`
+  //    reads `theme.footer` and NOTHING else. Every colour used to fall back to
+  //    `theme.sidebar`, so restyling the rail restyled a page's bottom
+  //    navigation bar and the two could not be dressed apart — the defect
+  //    sc-7951 set out to fix and only half did. The wire block's overloaded
+  //    `activeColor` (the FILL under "filled", the LABEL under "accent") is
+  //    retired for `tabActiveBackgroundColor` + `tabActiveTextColor`, two
+  //    independent halves; `activeTint` folds into the returned `activeColor`,
+  //    which is now the active tab's label, glyph and accent edge. The returned
+  //    `backgroundColor` and `textColor` are resolved strings rather than
+  //    raw-or-null, so neither host keeps a default of its own. `borderWidth`
+  //    admits 0 HERE alone — the strip's thickness is a Studio control offered
+  //    down to zero, and zero resolves into the existing no-divider state —
+  //    where the rail's and the header's keep sc-7965's 1-8 clamp. A backfill
+  //    (`20270123000000_sc8033_footer_tokens_uncouple`) materialised what each
+  //    workspace was inheriting, so no shipped app moved.
+  version: "1.116.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2694,6 +2694,196 @@ export function useInterpretDraft(tableId) {
   return { interpret, interpreting, error, result, available };
 }
 
+/**
+ * sc-7991 — structured error thrown by `useAgent().send`. Carries a stable
+ * `code` so widgets branch without parsing message strings; mirrors the shape
+ * of `TranslateError` / `NotificationError`.
+ *
+ * `code` is one of:
+ *   - "UNAVAILABLE"           — the host brokers no agents client, or no agent
+ *                               is bound (the widget should render its unbound
+ *                               state, not an error)
+ *   - "AGENT_NOT_FOUND"       — 404 (the bound agent was deleted)
+ *   - "AGENT_DISABLED"        — 409 (the author turned it off; it still exists)
+ *   - "CONVERSATION_NOT_FOUND"— 404 (a stale thread; `reset()` starts a new one)
+ *   - "INVALID_MESSAGE"       — 400 (empty, or past the length cap)
+ *   - "AI_QUOTA_EXCEEDED"     — 429 (the WORKSPACE is out of AI credit; this
+ *                               does NOT clear by retrying — say so)
+ *   - "RATE_LIMITED"          — 429 (too many turns — retry shortly)
+ *   - "AI_UNAVAILABLE"        — 503 (no AI provider configured)
+ *   - "AI_GENERATION_FAILED"  — 502 (the provider did not answer)
+ *   - "AUTH_REQUIRED"         — 401 (no signed-in app user)
+ *   - "INTERNAL"              — anything else (network, 5xx)
+ */
+export class AgentError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "AgentError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toAgentError(err) {
+  if (err instanceof AgentError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : err && typeof err.status === "number"
+        ? err.status
+        : null;
+  const bodyCode =
+    (err && err.response && err.response.data && err.response.data.code) ||
+    (err && typeof err.code === "string" ? err.code : null);
+  const bodyMessage =
+    (err && err.response && err.response.data && err.response.data.message) ||
+    (err && err.message) ||
+    "The agent could not answer";
+  let code = "INTERNAL";
+  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 429) code = "RATE_LIMITED";
+  else if (status === 400) code = "INVALID_MESSAGE";
+  else if (status === 409) code = "AGENT_DISABLED";
+  else if (status === 404) code = "AGENT_NOT_FOUND";
+  else if (status === 502) code = "AI_GENERATION_FAILED";
+  else if (status === 503) code = "AI_UNAVAILABLE";
+  return new AgentError(code, bodyMessage, { cause: err });
+}
+
+/**
+ * sc-7991 — hold a conversation with a workspace-authored AI agent.
+ * Returns `{ send, reset, messages, sending, error, available }`.
+ *
+ *   send(text) → Promise<{ role, content }>   the agent's reply
+ *
+ * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls `send`
+ * from an event handler. The first `send` opens the conversation, so an author
+ * who places the widget and never types costs the workspace nothing.
+ *
+ * `messages` is the running transcript this widget has seen, oldest first,
+ * each `{ id, role, content, created_at }` with `role` of "user" | "assistant".
+ * The SERVER owns the real transcript and the system prompt: the widget sends
+ * one message and can neither read nor set the prompt.
+ *
+ * `agentRef` is the agent id an author bound through an `agentRef` property.
+ * When it is absent, or the host brokers no agents client (an unbound canvas
+ * preview), `available` is false and `send` rejects UNAVAILABLE rather than
+ * throwing at render — the widget must render a visible unbound state, never a
+ * blank box (CLAUDE.md §8).
+ *
+ * Routes through the injected `@colixsystems/agents-client` at `ctx.agents`,
+ * so the Player and the Expo export resolve against the identical client.
+ */
+export function useAgent(agentRef) {
+  const ctx = useWidgetContextOrThrow("useAgent");
+  const available =
+    Boolean(agentRef) &&
+    Boolean(ctx.agents) &&
+    typeof ctx.agents.conversations === "function";
+
+  const clientRef = useRef(available ? ctx.agents : null);
+  clientRef.current = available ? ctx.agents : null;
+  const agentIdRef = useRef(agentRef);
+  agentIdRef.current = agentRef;
+  // The open thread, held as the in-flight PROMISE rather than the id.
+  //
+  // A ref alone only fixes the SEQUENTIAL case. `if (!id) { id = await create() }`
+  // reads the guard before the await and writes it after, so two overlapping
+  // sends — a double-tap, or a widget sending on each keystroke — both see null,
+  // both open a conversation, and both spend a paid turn. Latching the promise
+  // makes the second caller await the FIRST create instead of starting another.
+  const conversationRef = useRef(null);
+
+  const [messages, setMessages] = useState([]);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState(null);
+
+  // Set during render when the binding changes; consumed below. A setState in
+  // the render body would be a cascading re-render, so the flag is applied to
+  // the value this render returns instead.
+  const pendingResetRef = useRef(false);
+
+  // A changed binding is a different agent, so neither the open thread nor the
+  // transcript carries — leaving the messages would render agent A's
+  // conversation underneath agent B.
+  const boundRef = useRef(agentRef);
+  if (boundRef.current !== agentRef) {
+    boundRef.current = agentRef;
+    conversationRef.current = null;
+    pendingResetRef.current = true;
+  }
+
+  const reset = useCallback(() => {
+    conversationRef.current = null;
+    setMessages([]);
+    setError(null);
+  }, []);
+
+  const send = useCallback(async (text) => {
+    const client = clientRef.current;
+    const agentId = agentIdRef.current;
+    if (!client || !agentId) {
+      throw new AgentError("UNAVAILABLE", "No agent is available for this host");
+    }
+    const content = typeof text === "string" ? text.trim() : "";
+    if (!content) {
+      throw new AgentError("INVALID_MESSAGE", "A message is required");
+    }
+
+    setSending(true);
+    setError(null);
+    try {
+      const thread = client.conversations(agentId);
+      if (!conversationRef.current) {
+        // Assigned BEFORE the first await, so a concurrent send joins this one.
+        conversationRef.current = thread.create().then((created) => {
+          const id = created && created.id ? created.id : null;
+          if (!id) {
+            throw new AgentError("INTERNAL", "The conversation could not be opened");
+          }
+          return id;
+        });
+      }
+      let conversationId;
+      try {
+        conversationId = await conversationRef.current;
+      } catch (err) {
+        // A failed open must not wedge the widget on a rejected promise.
+        conversationRef.current = null;
+        throw err;
+      }
+      const turn = await thread.messages(conversationId).send({ content });
+      const userMessage = turn && turn.user_message ? turn.user_message : null;
+      const reply = turn && turn.reply ? turn.reply : null;
+      setMessages((prior) =>
+        prior.concat(userMessage ? [userMessage] : [], reply ? [reply] : []),
+      );
+      setSending(false);
+      return reply;
+    } catch (err) {
+      const e = toAgentError(err);
+      // A stale thread is recoverable on the next send rather than permanently
+      // broken: drop it so the widget opens a fresh one.
+      if (e.code === "CONVERSATION_NOT_FOUND") conversationRef.current = null;
+      setError(e);
+      setSending(false);
+      throw e;
+    }
+  }, []);
+
+  // The binding changed this render: hand back the empty transcript now rather
+  // than one frame of the previous agent's conversation.
+  let visibleMessages = messages;
+  if (pendingResetRef.current) {
+    pendingResetRef.current = false;
+    visibleMessages = [];
+    if (messages.length > 0) setMessages([]);
+  }
+
+  return { send, reset, messages: visibleMessages, sending, error, available };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/host.d.ts

@@ -173,35 +173,32 @@ export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
  */
 export function menuItemCap(menuType: string): number | null;
 
-/** The app's bottom edge — a page's own bottom navigation bar. A `null` colour
- *  means the host keeps its own default; a `null` `borderColor` means no
- *  divider is drawn at all. */
+/** The app's bottom edge — a page's own bottom navigation bar. Every colour is
+ *  resolved, so no host keeps a default of its own; a `null` `borderColor`
+ *  means no divider is drawn at all. */
 export interface FooterTokens {
-  backgroundColor: string | null;
-  textColor: string | null;
-  /** Never `null`: an unset value resolves to the brand primary here rather
-   *  than in each host, which is what lets the two active-tab fields below be
-   *  resolved here at all. */
+  backgroundColor: string;
+  textColor: string;
+  /** The active tab's label, its glyph, and — under "accent" — the edge that
+   *  marks it. One colour for all three: a mark and its label disagreeing about
+   *  which colour means "you are here" would be two marks, not one. */
   activeColor: string;
+  /** `null` when no divider is drawn, which a zero `borderWidth` also means. */
   borderColor: string | null;
   borderWidth: number | null;
   activeStyle: "filled" | "accent";
   /** Whether a tab's glyph sits beside its label or above it (sc-7951). */
   tabLayout: "inline" | "stacked";
-  /** The active tab's surface, or `null` for none. Under "filled" with nothing
-   *  named this is the active colour — what both hosts shipped. */
+  /** The active tab's surface, or `null` for none — which is what "accent"
+   *  resolves to unless the author names one. */
   activeSurface: string | null;
-  /** The active tab's label and glyph. White only under an unnamed "filled"
-   *  surface, which is the pairing both hosts hard-coded. */
-  activeTint: string;
 }
 
 /**
- * Resolves the footer strip's tokens from a whole `theme_config`. Every colour
- * falls back to the sidebar's, so a workspace that never opens the Bottom
- * navigation bar panel renders exactly as it did before the block existed.
- * `tabActiveBackgroundColor` and `tabLayout` are the strip's own and inherit
- * from nothing — a vertical rail item has neither.
+ * Resolves the footer strip's tokens from a whole `theme_config`. It reads
+ * `theme.footer` and NOTHING else (sc-8033): the colours used to fall back to
+ * the sidebar's, so restyling the rail restyled the strip and the two could not
+ * be dressed apart.
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
 

package/dist/index.d.ts

@@ -663,6 +663,8 @@ export interface WidgetContext<TProps = unknown> {
   notifications: NotificationsClient;
   /** Injected @colixsystems/identification-client; backs useIdentification. */
   identification: IdentificationClient;
+  /** sc-7991 — injected @colixsystems/agents-client backing useAgent(). */
+  agents?: { conversations(agentId: string): unknown };
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
   renderer: { renderNode(node: unknown): unknown };
   events: { emit(eventName: string, payload?: unknown): void };
@@ -1204,6 +1206,36 @@ export function useInterpretDraft(
   tableId: string | null | undefined,
 ): InterpretDraftApi;
 
+export interface AgentMessage {
+  id: string;
+  conversation_id: string;
+  /** The system prompt is NOT part of the transcript — it lives on the agent. */
+  role: "user" | "assistant";
+  content: string;
+  created_at: string;
+}
+
+export interface AgentApi {
+  /** Imperative — call from an event handler. The first send opens the thread. */
+  send(text: string): Promise<AgentMessage | null>;
+  /** Drop the open thread and clear the transcript this widget has seen. */
+  reset(): void;
+  /** Oldest first. The SERVER owns the real transcript. */
+  messages: AgentMessage[];
+  sending: boolean;
+  error: AgentError | null;
+  /** False when no agent is bound, or the host brokers no agents client. */
+  available: boolean;
+}
+
+/**
+ * sc-7991 — hold a conversation with a workspace-authored AI agent.
+ * IMPERATIVE: never fires on mount, so an unused widget costs nothing. The
+ * widget sends ONE message; the system prompt and the real transcript stay
+ * server-side and are never readable or settable from here.
+ */
+export function useAgent(agentRef: string | null | undefined): AgentApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"
@@ -1926,10 +1958,29 @@ export class DirectoryError extends Error {
 }
 
 /**
- * sc-3783 — error class thrown by `useTranslate().translate`. The `code` is a
- * stable categorisation widgets can branch on. TRANSLATION_QUOTA_EXCEEDED and
- * TRANSLATE_NOT_CONFIGURED will not clear on a retry — show the original text.
+ * sc-7991 — structured error thrown by `useAgent().send`. Branch on `code`:
+ * `AI_QUOTA_EXCEEDED` is the workspace's credit ceiling and will NOT clear on
+ * a retry, unlike `RATE_LIMITED`; `AGENT_DISABLED` means the author switched
+ * the agent off; `AI_AGENTS_DISABLED` means the feature is not released for
+ * this workspace. Never show an app user a raw code or the billing state.
  */
+export class AgentError extends Error {
+  code:
+    | "UNAVAILABLE"
+    | "AGENT_NOT_FOUND"
+    | "AGENT_DISABLED"
+    | "CONVERSATION_NOT_FOUND"
+    | "INVALID_MESSAGE"
+    | "AI_QUOTA_EXCEEDED"
+    | "RATE_LIMITED"
+    | "AI_UNAVAILABLE"
+    | "AI_GENERATION_FAILED"
+    | "AUTH_REQUIRED"
+    | "INTERNAL"
+    | (string & {});
+  constructor(code: string, message: string, opts?: { cause?: unknown });
+}
+
 export class TranslateError extends Error {
   code:
     | "UNSUPPORTED"

package/dist/index.js

@@ -28,6 +28,7 @@ export {
   NotificationError,
   DirectoryError,
   PermissionError,
+  AgentError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -35,6 +36,7 @@ export {
   useStableQuery,
   useCanWrite,
   useInterpretDraft,
+  useAgent,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,

package/dist/index.native.js

@@ -28,6 +28,7 @@ export {
   NotificationError,
   DirectoryError,
   PermissionError,
+  AgentError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -35,6 +36,7 @@ export {
   useStableQuery,
   useCanWrite,
   useInterpretDraft,
+  useAgent,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,

package/dist/linter.cjs

@@ -565,6 +565,26 @@ function _scopeRules(source, manifest) {
       });
     }
   }
+
+  // sc-7991 — every send spends the workspace's AI credits, so the manifest has
+  // to declare the capability. This gate is ADVISORY, not an authorization
+  // boundary: unlike users/groups (minted into X-Widget-Scopes and checked
+  // server-side), nothing re-checks ai.invoke at call time, so a widget that
+  // evades this regex still reaches the endpoint. What actually bounds abuse is
+  // the app-user JWT, the per-actor and per-tenant limiters and the AI quota
+  // gate. The scope's real job is DISCLOSURE — it is what the marketplace
+  // install consent screen shows.
+  if (/\buseAgent\s*\(/.test(source)) {
+    const invokes = declared.has("ai.invoke:*") || declared.has("ai.invoke");
+    if (!invokes) {
+      findings.push({
+        rule: "scope-required-for-useAgent",
+        label: "useAgent() requires `ai.invoke:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/linter.js

@@ -528,6 +528,26 @@ function _scopeRules(source, manifest) {
       });
     }
   }
+
+  // sc-7991 — every send spends the workspace's AI credits, so the manifest has
+  // to declare the capability. This gate is ADVISORY, not an authorization
+  // boundary: unlike users/groups (minted into X-Widget-Scopes and checked
+  // server-side), nothing re-checks ai.invoke at call time, so a widget that
+  // evades this regex still reaches the endpoint. What actually bounds abuse is
+  // the app-user JWT, the per-actor and per-tenant limiters and the AI quota
+  // gate. The scope's real job is DISCLOSURE — it is what the marketplace
+  // install consent screen shows.
+  if (/\buseAgent\s*\(/.test(source)) {
+    const invokes = declared.has("ai.invoke:*") || declared.has("ai.invoke");
+    if (!invokes) {
+      findings.push({
+        rule: "scope-required-for-useAgent",
+        label: "useAgent() requires `ai.invoke:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/navigation.cjs

@@ -71,78 +71,76 @@ function menuItemCap(menuType) {
 }
 
 // REQ-NAV-LOCAL: the app's BOTTOM EDGE — the tokens a page's own bottom
-// navigation bar is drawn from. Every colour falls back to the sidebar's, so a
-// workspace that never opens the panel keeps the appearance it has.
+// navigation bar is drawn from.
 //
 // sc-7753: the global quick bar these tokens were introduced for is retired;
 // the bar that reads them now is the page's own (`local_nav = BOTTOM_BAR`).
 //
-// sc-7951: three of the keys ARE that bar's own — the active-item style it
-// used to borrow from the rail for want of a control, the active tab's
-// surface, and whether the glyph sits beside the label or above it.
+// sc-8033: the block is SELF-CONTAINED — it reads `theme.footer` and nothing
+// else. Every colour used to fall back to the rail's, so restyling the sidebar
+// restyled the strip and the two could not be dressed apart; that is the defect
+// sc-7951 set out to fix and only half did. A one-off backfill materialised
+// what each workspace was inheriting, so no shipped app lost its look when the
+// chain went (migration `20260918000000_footer_tokens_uncouple`).
+//
+// The eight authorable keys are the eight controls the Design panel offers, one
+// for one: `backgroundColor`, `textColor`, `tabActiveBackgroundColor`,
+// `tabActiveTextColor`, `borderColor`, `borderWidth`, `activeStyle`,
+// `tabLayout`.
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
-  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
-  // Hex-guarded on the way out, not merely on the way in: `theme_config` is an
-  // opaque blob an operator can hand-edit, and the EXPORT already refused a
-  // malformed colour here while the Player passed it to a style object — so the
-  // guard is what stops the two hosts painting a stored junk value differently.
-  const pick = (key) => hexOrNull(footer[key]) || hexOrNull(sidebar[key]) || null;
-  const borderColor = pick("borderColor");
-  // sc-7951: the rail's style is the FALLBACK now, not the only source. Unset
-  // still follows the rail, which is what keeps every shipped app where it is.
-  const activeStyle = footer.activeStyle || sidebar.activeStyle;
-  const accent = activeStyle === "accent";
-  const activeColor = hexOr(pick("activeColor"), brandPrimary(config));
-  // Footer-only: a rail item is a full-width row with no tab surface to paint,
-  // so this inherits from nothing and unset means "no surface of its own".
-  const namedSurface = hexOrNull(footer.tabActiveBackgroundColor);
+  // Hex-guarded on read: `theme_config` is an opaque blob an operator can
+  // hand-edit, and the EXPORT already refused a malformed colour here while the
+  // Player passed it to a style object — so the guard is what stops the two
+  // hosts painting a stored junk value differently.
+  const accent = footer.activeStyle === "accent";
+  const borderColor = hexOrNull(footer.borderColor);
+  // sc-8033: the strip's thickness is authorable down to 0, where the rail's
+  // and the header's clamp up to 1 (sc-7965). The panel OFFERS zero, so zero is
+  // a choice rather than the junk value that clamp refuses — and it resolves
+  // into the existing no-divider state, so neither host needs a second way to
+  // draw nothing.
+  const borderWidth = borderColor ? footerBorderWidthOr(footer.borderWidth) : 0;
+  const divider = borderWidth > 0;
   return {
-    backgroundColor: pick("backgroundColor"),
-    textColor: pick("textColor"),
-    // Resolved here rather than by each caller, which is what lets the two
-    // active-tab fields below be resolved here too.
-    activeColor,
-    // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
-    // all — which the native strip did not honour before this, ruling a
-    // hairline across a tinted bar that had asked for none.
-    borderColor,
-    borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
+    backgroundColor: hexOr(footer.backgroundColor, DEFAULT_FOOTER_SURFACE),
+    textColor: hexOr(footer.textColor, DEFAULT_CHROME_TEXT),
+    borderColor: divider ? borderColor : null,
+    borderWidth: divider ? borderWidth : null,
     activeStyle: accent ? "accent" : "filled",
     // sc-7951: bottom tabs are the only strip tall enough to stack the two, so
     // the choice is the footer's alone.
     tabLayout: footer.tabLayout === "stacked" ? "stacked" : "inline",
-    // sc-7951: the active tab's two halves, resolved HERE so neither host
-    // re-derives the back-compat rule. "filled" with nothing named is what both
-    // hosts shipped — the active colour as the fill, the label forced white —
-    // and that pairing is the only reason a marked tab's label is not simply
-    // the active colour. Naming a surface unbundles them: the surface is the
-    // author's and the label goes back to the active colour.
-    activeSurface: namedSurface || (accent ? null : activeColor),
-    activeTint: accent || namedSurface ? activeColor : FILLED_TAB_LABEL,
+    // sc-8033: the active tab's two halves are two KEYS, resolved here so
+    // neither host re-derives them. They used to be one overloaded
+    // `activeColor` — the fill under "filled", the label under "accent" — which
+    // is why no author could set both. Only the DEFAULTS still consult the
+    // style, and they are exactly what each style shipped: a brand-primary fill
+    // under a white label, or no fill under a brand-primary label and edge.
+    activeSurface: accent
+      ? hexOrNull(footer.tabActiveBackgroundColor)
+      : hexOr(footer.tabActiveBackgroundColor, brandPrimary(config)),
+    // The active tab's label, its glyph, and — under "accent" — the edge that
+    // marks it. One colour for all three: a mark and its label disagreeing
+    // about which colour means "you are here" would be two marks, not one.
+    activeColor: hexOr(
+      footer.tabActiveTextColor,
+      accent ? brandPrimary(config) : FILLED_TAB_LABEL,
+    ),
   };
 }
 
 // REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
 // hosts.
 //
-// These return FULLY resolved values where `resolveFooterTokens` above still
-// returns raw-or-null for its SURFACE, LABEL and DIVIDER colours, and the
-// difference is deliberate. The footer's two hosts happen to agree on their
-// separately-written defaults for those three (`#ffffff` / `#475569` / no
-// line); the rail's and the bar's did not. sc-7951 resolved the footer's active
-// tab — `activeColor`, `activeSurface`, `activeTint` — because a rule that
-// pairs a surface with a label cannot live in two hosts; the three above are
-// what remains of the old shape. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
-// background in the export, and an unset `topBar.textColor` painted the brand
-// primary on web and slate-700 in the export. A default that lives in the
-// resolver cannot drift; one that lives in each host already had. The footer's
-// three remaining raw colours want this same shape next.
-//
-// Every default is what the WEB Player renders today, so the Player does not
-// move and the export converges onto it. That is the direction the footer was
-// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+// Every default here is what the WEB Player renders, so the Player does not
+// move and the export converges onto it. An unset `sidebar.backgroundColor`
+// painted #ffffff on web and the app background in the export, and an unset
+// `topBar.textColor` painted the brand primary on web and slate-700 in the
+// export. A default that lives in the resolver cannot drift; one that lives in
+// each host already had — which is why `resolveFooterTokens` above stopped
+// returning raw-or-null too (sc-8033).
 //
 // sc-6596 — the ONE exception, and it moves BOTH hosts: an unset rail or bar
 // takes the page's own colour. Converging on the Player's white left a themed
@@ -151,13 +149,16 @@ function resolveFooterTokens(theme) {
 const DEFAULT_PRIMARY_COLOR = "#3b82f6";
 // The web nav item's `text-slate-600`.
 const DEFAULT_CHROME_TEXT = "#475569";
+// The strip's own surface. Both hosts already defaulted to this separately (the
+// web `footerBg`, the compiler's `#ffffff`); sc-8033 resolved it here instead.
+const DEFAULT_FOOTER_SURFACE = "#ffffff";
 // The web mobile header's icon colour, `text-slate-700`.
 const DEFAULT_TOP_BAR_TINT = "#334155";
 // The page beneath the chrome — the web's `DEFAULT_APP_BACKGROUND_COLOR`
 // (frontend/src/utils/theme.js) and the compiler's, which are the same slate-50.
 const DEFAULT_APP_SURFACE = "#f8fafc";
-// The literal both hosts hard-coded behind an unnamed "filled" surface, before
-// resolveFooterTokens decided the pairing once (sc-7951).
+// A filled tab's label where the author names none — the literal both hosts
+// hard-coded behind an unnamed "filled" surface before the resolver decided it.
 const FILLED_TAB_LABEL = "#ffffff";
 
 // A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
@@ -377,6 +378,18 @@ function resolveTopBarTokens(theme) {
 // COLOUR is its switch, so a coloured 0px edge is a contradiction, not "off".
 const BORDER_WIDTH_MIN = 1;
 const BORDER_WIDTH_MAX = 8;
+
+// The BOTTOM strip's own range, which starts at zero. Its thickness is a
+// control the Design panel offers down to 0, so a stored zero is an author
+// saying "no line" rather than the junk value the clamp above refuses — and
+// `resolveFooterTokens` turns it back into the no-divider state both hosts
+// already draw, so the extra bound costs neither host a branch (sc-8033).
+function footerBorderWidthOr(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return BORDER_WIDTH_MIN;
+  }
+  return Math.min(Math.max(Math.round(value), 0), BORDER_WIDTH_MAX);
+}
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) {

package/dist/navigation.js

@@ -62,78 +62,76 @@ export function menuItemCap(menuType) {
 }
 
 // REQ-NAV-LOCAL: the app's BOTTOM EDGE — the tokens a page's own bottom
-// navigation bar is drawn from. Every colour falls back to the sidebar's, so a
-// workspace that never opens the panel keeps the appearance it has.
+// navigation bar is drawn from.
 //
 // sc-7753: the global quick bar these tokens were introduced for is retired;
 // the bar that reads them now is the page's own (`local_nav = BOTTOM_BAR`).
 //
-// sc-7951: three of the keys ARE that bar's own — the active-item style it
-// used to borrow from the rail for want of a control, the active tab's
-// surface, and whether the glyph sits beside the label or above it.
+// sc-8033: the block is SELF-CONTAINED — it reads `theme.footer` and nothing
+// else. Every colour used to fall back to the rail's, so restyling the sidebar
+// restyled the strip and the two could not be dressed apart; that is the defect
+// sc-7951 set out to fix and only half did. A one-off backfill materialised
+// what each workspace was inheriting, so no shipped app lost its look when the
+// chain went (migration `20260918000000_footer_tokens_uncouple`).
+//
+// The eight authorable keys are the eight controls the Design panel offers, one
+// for one: `backgroundColor`, `textColor`, `tabActiveBackgroundColor`,
+// `tabActiveTextColor`, `borderColor`, `borderWidth`, `activeStyle`,
+// `tabLayout`.
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
-  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
-  // Hex-guarded on the way out, not merely on the way in: `theme_config` is an
-  // opaque blob an operator can hand-edit, and the EXPORT already refused a
-  // malformed colour here while the Player passed it to a style object — so the
-  // guard is what stops the two hosts painting a stored junk value differently.
-  const pick = (key) => hexOrNull(footer[key]) || hexOrNull(sidebar[key]) || null;
-  const borderColor = pick("borderColor");
-  // sc-7951: the rail's style is the FALLBACK now, not the only source. Unset
-  // still follows the rail, which is what keeps every shipped app where it is.
-  const activeStyle = footer.activeStyle || sidebar.activeStyle;
-  const accent = activeStyle === "accent";
-  const activeColor = hexOr(pick("activeColor"), brandPrimary(config));
-  // Footer-only: a rail item is a full-width row with no tab surface to paint,
-  // so this inherits from nothing and unset means "no surface of its own".
-  const namedSurface = hexOrNull(footer.tabActiveBackgroundColor);
+  // Hex-guarded on read: `theme_config` is an opaque blob an operator can
+  // hand-edit, and the EXPORT already refused a malformed colour here while the
+  // Player passed it to a style object — so the guard is what stops the two
+  // hosts painting a stored junk value differently.
+  const accent = footer.activeStyle === "accent";
+  const borderColor = hexOrNull(footer.borderColor);
+  // sc-8033: the strip's thickness is authorable down to 0, where the rail's
+  // and the header's clamp up to 1 (sc-7965). The panel OFFERS zero, so zero is
+  // a choice rather than the junk value that clamp refuses — and it resolves
+  // into the existing no-divider state, so neither host needs a second way to
+  // draw nothing.
+  const borderWidth = borderColor ? footerBorderWidthOr(footer.borderWidth) : 0;
+  const divider = borderWidth > 0;
   return {
-    backgroundColor: pick("backgroundColor"),
-    textColor: pick("textColor"),
-    // Resolved here rather than by each caller, which is what lets the two
-    // active-tab fields below be resolved here too.
-    activeColor,
-    // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
-    // all — which the native strip did not honour before this, ruling a
-    // hairline across a tinted bar that had asked for none.
-    borderColor,
-    borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
+    backgroundColor: hexOr(footer.backgroundColor, DEFAULT_FOOTER_SURFACE),
+    textColor: hexOr(footer.textColor, DEFAULT_CHROME_TEXT),
+    borderColor: divider ? borderColor : null,
+    borderWidth: divider ? borderWidth : null,
     activeStyle: accent ? "accent" : "filled",
     // sc-7951: bottom tabs are the only strip tall enough to stack the two, so
     // the choice is the footer's alone.
     tabLayout: footer.tabLayout === "stacked" ? "stacked" : "inline",
-    // sc-7951: the active tab's two halves, resolved HERE so neither host
-    // re-derives the back-compat rule. "filled" with nothing named is what both
-    // hosts shipped — the active colour as the fill, the label forced white —
-    // and that pairing is the only reason a marked tab's label is not simply
-    // the active colour. Naming a surface unbundles them: the surface is the
-    // author's and the label goes back to the active colour.
-    activeSurface: namedSurface || (accent ? null : activeColor),
-    activeTint: accent || namedSurface ? activeColor : FILLED_TAB_LABEL,
+    // sc-8033: the active tab's two halves are two KEYS, resolved here so
+    // neither host re-derives them. They used to be one overloaded
+    // `activeColor` — the fill under "filled", the label under "accent" — which
+    // is why no author could set both. Only the DEFAULTS still consult the
+    // style, and they are exactly what each style shipped: a brand-primary fill
+    // under a white label, or no fill under a brand-primary label and edge.
+    activeSurface: accent
+      ? hexOrNull(footer.tabActiveBackgroundColor)
+      : hexOr(footer.tabActiveBackgroundColor, brandPrimary(config)),
+    // The active tab's label, its glyph, and — under "accent" — the edge that
+    // marks it. One colour for all three: a mark and its label disagreeing
+    // about which colour means "you are here" would be two marks, not one.
+    activeColor: hexOr(
+      footer.tabActiveTextColor,
+      accent ? brandPrimary(config) : FILLED_TAB_LABEL,
+    ),
   };
 }
 
 // REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
 // hosts.
 //
-// These return FULLY resolved values where `resolveFooterTokens` above still
-// returns raw-or-null for its SURFACE, LABEL and DIVIDER colours, and the
-// difference is deliberate. The footer's two hosts happen to agree on their
-// separately-written defaults for those three (`#ffffff` / `#475569` / no
-// line); the rail's and the bar's did not. sc-7951 resolved the footer's active
-// tab — `activeColor`, `activeSurface`, `activeTint` — because a rule that
-// pairs a surface with a label cannot live in two hosts; the three above are
-// what remains of the old shape. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
-// background in the export, and an unset `topBar.textColor` painted the brand
-// primary on web and slate-700 in the export. A default that lives in the
-// resolver cannot drift; one that lives in each host already had. The footer's
-// three remaining raw colours want this same shape next.
-//
-// Every default is what the WEB Player renders today, so the Player does not
-// move and the export converges onto it. That is the direction the footer was
-// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+// Every default here is what the WEB Player renders, so the Player does not
+// move and the export converges onto it. An unset `sidebar.backgroundColor`
+// painted #ffffff on web and the app background in the export, and an unset
+// `topBar.textColor` painted the brand primary on web and slate-700 in the
+// export. A default that lives in the resolver cannot drift; one that lives in
+// each host already had — which is why `resolveFooterTokens` above stopped
+// returning raw-or-null too (sc-8033).
 //
 // sc-6596 — the ONE exception, and it moves BOTH hosts: an unset rail or bar
 // takes the page's own colour. Converging on the Player's white left a themed
@@ -142,13 +140,16 @@ export function resolveFooterTokens(theme) {
 const DEFAULT_PRIMARY_COLOR = "#3b82f6";
 // The web nav item's `text-slate-600`.
 const DEFAULT_CHROME_TEXT = "#475569";
+// The strip's own surface. Both hosts already defaulted to this separately (the
+// web `footerBg`, the compiler's `#ffffff`); sc-8033 resolved it here instead.
+const DEFAULT_FOOTER_SURFACE = "#ffffff";
 // The web mobile header's icon colour, `text-slate-700`.
 const DEFAULT_TOP_BAR_TINT = "#334155";
 // The page beneath the chrome — the web's `DEFAULT_APP_BACKGROUND_COLOR`
 // (frontend/src/utils/theme.js) and the compiler's, which are the same slate-50.
 const DEFAULT_APP_SURFACE = "#f8fafc";
-// The literal both hosts hard-coded behind an unnamed "filled" surface, before
-// resolveFooterTokens decided the pairing once (sc-7951).
+// A filled tab's label where the author names none — the literal both hosts
+// hard-coded behind an unnamed "filled" surface before the resolver decided it.
 const FILLED_TAB_LABEL = "#ffffff";
 
 // A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
@@ -368,6 +369,18 @@ export function resolveTopBarTokens(theme) {
 // COLOUR is its switch, so a coloured 0px edge is a contradiction, not "off".
 const BORDER_WIDTH_MIN = 1;
 const BORDER_WIDTH_MAX = 8;
+
+// The BOTTOM strip's own range, which starts at zero. Its thickness is a
+// control the Design panel offers down to 0, so a stored zero is an author
+// saying "no line" rather than the junk value the clamp above refuses — and
+// `resolveFooterTokens` turns it back into the no-divider state both hosts
+// already draw, so the extra bound costs neither host a branch (sc-8033).
+function footerBorderWidthOr(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return BORDER_WIDTH_MIN;
+  }
+  return Math.min(Math.max(Math.round(value), 0), BORDER_WIDTH_MAX);
+}
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) {

package/dist/property-schema.js

@@ -23,6 +23,11 @@ const VALID_TYPES = new Set([
   // value is the raw uuid string so the tenant-copy walker can remap it
   // through `_remapJson` without per-prop hooks.
   "groupRef",
+  // sc-7991: `agentRef` is a picker for one of the workspace's AI agents,
+  // emitting a bare TenantAiAgent UUID into the page JSON. A widget reads it
+  // and calls `useAgent(agentRef)`. Bare uuid string like `groupRef`/`pageRef`,
+  // so tenant-copy remaps it through the layout walk's merged id map.
+  "agentRef",
   // REQ-WDG-PAGEREF: `pageRef` is a page picker that emits a bare AppPage
   // UUID into the page JSON. Renders a page `<select>` in the Studio
   // Properties Panel; a widget reads it and navigates via
@@ -148,6 +153,7 @@ function coerceLeaf(def, value, path, errors) {
     case "recordBinding":
     case "groupRef":
     case "pageRef":
+    case "agentRef":
     case "richText":
     case "asset":
     case "folderRef":

package/package.json

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