@colixsystems/widget-sdk 0.86.0 → 0.88.0

package/README.md

@@ -17,11 +17,11 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
-| **CORE** | `useTheme()` | `{ colors, elevation, spacing, radii, typography, components }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
+| **CORE** | `useTheme()` | `{ colors, elevation, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
 | **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
-| **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
+| **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. |
@@ -33,7 +33,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useSectionEmpty(isEmpty)` | `void` | `ctx.section.reportEmpty` — no scope. Declares that the widget has NO content to show, so the host drops its layout slot instead of reserving space (and its parent's `gap`) for it. Returning `null` is not enough: the host wraps every widget in an entrance element, so a widget rendering nothing still leaves an empty box the parent stack gaps around. For a CONDITIONALLY ABSENT section (a per-record child collection with no rows for this record), never to suppress a genuine empty state. Stays mounted while collapsed, so passing `false` brings it back. Authoring surfaces never collapse. No-op on a host that doesn't implement it. |
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
-| **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
+| **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
 | **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
 | **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. |
@@ -61,7 +61,71 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.86.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.88.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.88.0 (contract 1.62.0)
+
+**A refused datastore / directory / permission call now reaches the widget as its real reason (sc-4986).**
+
+- **The reason was being thrown away.** Each `@colixsystems/*-client` throws typed
+  errors carrying `.code` / `.status` / `.details` (the parsed envelope) and **no
+  `.response`** — but `toDatastoreError`, `toDirectoryError` and
+  `toPermissionError` read `err.response.*` only. Every typed client rejection
+  fell through every branch and arrived as `code: "INTERNAL"`, so a 403 the
+  workspace owner has to lift was indistinguishable from a dropped socket, and
+  `DatastoreError.fieldErrors` never populated at all. `toPaymentError` was fixed
+  for exactly this in 0.83.0; these three were not.
+- **All three mappers now read both shapes**, preferring the envelope's own
+  `message` (the canonical `{ statusCode, message, code }` field — the old code
+  read a `.error` key the envelope has never carried). The documented `code`
+  vocabularies are unchanged, so a widget already branching on
+  `code === "FORBIDDEN"` starts working rather than having to change.
+- **`DatastoreError` / `DirectoryError` / `PermissionError` gain `retryable`**
+  (and `status`). `retryable === false` for a refusal only the caller, the record
+  or the workspace can clear — 403 / 404 / 400 / 422 / 409 — and `true` for a
+  timeout, a rate limit, a 5xx or a dropped socket. Branch on it instead of
+  offering a blanket "try again". This is deliberately *not* the payments rule:
+  a 402 `DECLINED` card IS worth another attempt, so that contract differs.
+- **`fieldErrors` works again** — a 400/422 carrying
+  `errors: [{ field, code, message }]` becomes the flat `{ field: message }` map
+  the type has always advertised, so a form can mark the offending input.
+- **New soft lint rule `datastore-error-not-branched`** (severity `warning`,
+  never blocks a publish): a widget that writes with `useDatastoreMutation` but
+  never reads `retryable`, branches on `code ===`, or renders the error's own
+  `.message` is flagged, so the AI widget agent's repair loop closes the gap.
+- `CONTRACT.version` → `1.62.0`: the three hooks' `returnShape` entries now name
+  the `{ code, message, retryable }` triple. No export or signature changed —
+  additive fields on three error classes.
+
+### What's new in 0.87.0 (contract 1.61.1)
+
+**Widget toasts are actually rendered now — both hosts wire `ctx.toast` (sc-4939).**
+
+- **The host half of `useToast()` shipped.** The hook has existed since 0.15.0 and
+  the AI widget agent has always been told to confirm a write with
+  `showToast({ kind: "success", … })` — but no host ever populated the
+  `WidgetContext.toast` slot. So the web variant dispatched an
+  `appstudio:widget-toast` CustomEvent that nothing listened for, and native fell
+  through to `console.log`. Every write confirmation an app raised was invisible:
+  a user tapped Save and got nothing back. The web Player and the exported Expo
+  app now both paint a workspace-themed stack, so a confirmation you raise is a
+  confirmation the user sees.
+- **New host exports (`@colixsystems/widget-sdk/host`)** — `createToastController()`
+  (the queue, the auto-dismiss timing, newest-first stacking, injectable timers)
+  and `resolveToastTokens(theme, kind)` (the themed values a toast is painted
+  with, `error` mapping to the theme's `danger` role), plus `normalizeToastKind`
+  and `TOAST_DEFAULTS`. Both hosts drive these, so only the JSX differs and the
+  two cannot drift. This entry point is host integration, not the author API —
+  a widget author still just calls `useToast()`.
+- **No author-facing change.** No export, signature, hook or manifest field
+  moved; a widget already calling `showToast` is unchanged and simply becomes
+  visible. `CONTRACT.version` → `1.61.1` for the corrected `useToast` /
+  `widgetContextShape.toast` descriptions, which used to imply a host might not
+  render the toast at all.
+- **An authoring preview still wires nothing.** The Studio canvas leaves the slot
+  unset on purpose — a confirmation belongs to the running app, not to
+  design-time — so `showToast` is a no-op there, as `navigation` and `events`
+  already are.
 
 ### What's new in 0.86.0 (contract unchanged)
 
@@ -72,6 +136,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `CONTRACT` is unchanged (no new field), and no export changed signature.
 
+### What's new in 0.86.0 (contract 1.61.0)
+
+- **The workspace theme now reaches the elements an app is built from.** Three things that used to be unreachable are now themeable: an element inside YOUR widget, the structural card container a page is made of, and any style field whose name the platform does not know. For a widget author the practical change is that **your `styleSchema` is the contract**: every field you declare becomes a knob the workspace owner can set once for the whole app, so declare the fields that describe your widget's appearance and give them clear `label`s and `ui.group`s — those labels are what the owner reads.
+- **A field name you invented is as reachable as a canonical one.** A theme may carry values keyed by your widget's manifest id and then by your own field names, so `panelFill` is adjustable app-wide exactly like `cardBackground`. Separately, the unambiguous card names (`cardBackground`, `cardBorderColor`, `cardRadius`, `cardPadding`, `cardGradient`) bind by NAME to any widget that declares them, so naming a genuine card surface canonically opts it into the workspace's Cards controls for free.
+- **`useTheme().colors` describes the surface your widget SITS ON, not the page.** A layout container that paints its own background re-derives the surface roles for everything inside it, so reading `colors.onSurface` for your text is readable whether your widget lands on the page, in a dark hero, or in a light card nested inside that hero. Nothing to opt into.
+- **Precedence, unchanged in spirit.** Contract default → workspace palette → component scope → per-widget-type value → the app author's per-instance `props.style`. Most specific wins, and the Properties Panel is still the final word. Your widget reads `props.style` exactly as before and never learns which layer supplied a value.
+- **A colour may carry OPACITY.** `isHexColor` accepts the 8-digit `#RRGGBBAA` form alongside 3 and 6 digits, so a theme colour with an alpha reaches `useTheme()` with its transparency intact. It used to be rejected and the host dropped the key outright, which is why a translucent page background never reached the dark-surface derivation and every panel fell back to white.
+- **The colour maths ignores alpha, on purpose.** `hexChannels` reads the R/G/B pair and skips any alpha, so contrast, readable text and the derived accent tints reason about the opaque colour. None of them can composite without knowing the backdrop, which a token table does not have — so transparency lives in the VALUE your widget renders, not in the decision about whether that colour reads as light or dark.
+- **`CONTRACT.version` → `1.61.0`** (additive: `themeTokens.spacingScale` + `widgetStyles` and their bounds, `themeComponents.card.universalFields`, and the `normaliseWidgetStyles` / `deriveSurfaceTokens` host exports). No author-facing export changed signature, and a theme that sets none of it resolves exactly as before.
+
 ### What's new in 0.85.1 (contract 1.60.1)
 
 **`useWidgetEvent(name)` returns the emitter FUNCTION — the declared contract said otherwise (sc-4753).** `CONTRACT.hooks`'s entry for the hook declared `returnShape: { emit }`, so every surface derived from it — chiefly the Widget Builder Agent's hooks table — told authors the hook resolves to an object. It never did: `useWidgetEvent("slotChosen")` hands back the callable you invoke directly (`emitSlot({ courtId })`), exactly as the typings and the Developer guide have always documented. A widget written against the declared shape destructured a function, got `undefined`, and threw the moment a user interacted — a cross-widget wire that rendered perfectly and only failed on click. The declaration is now a bare callable and the publish-time render harness models the same shape, so a wrong destructure is caught instead of waved through. `CONTRACT.version` → `1.60.1`. Documentation-only correction: no export, signature, or runtime behaviour changed — a widget already calling the result is unaffected.
@@ -204,6 +278,7 @@ useEffect(() => {
 
 **The theme can restyle ONE component type — buttons, cards or text — without moving the global palette (sc-1497).** A workspace theme may now carry `themeConfig.components` (`{ button, card, text }`), and the host resolves each scope onto the `styleSchema` fields the target widgets already read. **Nothing changes for a widget author:** you keep reading `props.style` / `useWidgetStyle()`, and an author's per-instance value still wins over a theme token — the theme is the app-wide default underneath it.
 
+- **`useTheme()` gains `spacingScale`.** The app-wide spacing multiplier (default `1`) the workspace sets from Theme Settings. HOST-OWNED for layout: the host already scales every container's `padding` / `gap` / `margin` by it, so do not re-apply it to anything the host laid out. Read it only when your widget draws spacing of its own and you want that to breathe with the rest of the app — multiply your own paddings by it and leave radii and font sizes alone.
 - **`useTheme()` gains a `components` slice.** It is HOST-OWNED plumbing, not an author API: by the time your component renders, the host has already folded the matching tokens into `props.style`. Do not read `theme.components` and do not re-apply it — you would double-apply the theme and defeat the author's own styling.
 - **New host-only exports on `@colixsystems/widget-sdk/host`:** `normaliseThemeComponents(raw)` and `applyThemeComponentStyle(manifestId, theme, props)`. These are the platform-host surface (the web Player / Studio canvas and the exported Expo app), never the author API — one implementation, so the two hosts cannot diverge.
 - **`CONTRACT.themeComponents` / `CONTRACT.themeComponentShadows` / `CONTRACT.themeComponentGradient`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
@@ -583,7 +658,8 @@ The "split-implementation + vetted package list" pivot.
 
 ### What's new in 0.11.0
 
-- **`useNavigation()` is wired.** Returns the host-provided navigation surface `{ goTo, goBack, push, replace, back, currentRoute }` for internal page-to-page navigation. Missing methods degrade to no-ops on the Studio canvas preview. Additive.
+- **`useNavigation()` is wired.** Returns the host-provided navigation surface `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page-to-page navigation. Missing methods degrade to no-ops on the Studio canvas preview. Additive.
+- **`openLink(link)` follows a link whose shape you do NOT control** — a value off a datastore row, a notification's `link`, anything author- or user-supplied. It resolves the string through the host's shared resolver and then acts: an in-app page routes internally, an off-app `http(s)` URL opens outside, and anything unsafe (`javascript:`, `data:`, scheme-relative `//host`, a scheme split by a control character) is refused. Returns `true` when it acted. **Prefer it over `Linking.openURL` for untrusted values** — `Linking.openURL` performs whatever it is handed, so passing it a stored string is how a `javascript:` URL reaches the browser. Reach for `goTo(pageId)` when you already know the page, and `Linking.openURL` only for a URL your own code constructed.
 - **`usePageContext()` reads the page's DECLARED parameters.** When a page declares parameters (Page Settings → Parameters), the host resolves them ONCE before any widget renders and fetches each `record` parameter's row for the whole page. `params` holds the values coerced to their declared types (a `number` parameter is a number, not the string `useRouteParams()` returns); `records` maps each `record` parameter to its already-loaded row — read it rather than issuing the same request from every widget. A required parameter that is absent, malformed, or whose record does not resolve never reaches the widget: the host renders one page-level state instead. Both bags are empty on a page that declares nothing, so fall back to `useRouteParams()` for a page you do not control. Additive (v0.77.0).
 - **`useRouteParams()` reads the nav params.** Returns `currentRoute.params` — the bag a `goTo(pageId, params)` carried to this page. The flat accessor for master→detail: navigate with `goTo(detailPageId, { recordId: row.id })`, then read `const { recordId } = useRouteParams()`. It is an OBJECT — read a param off it, never call it. Empty object when the page was opened without params. Additive (v0.61.0).
 - **`Linking` primitive re-exported.** `Linking.openURL(url)` opens an external URL with the OS handler — web (`react-native-web`) maps to `window.open` / `location.href`; native hands off to the system. Use this for external URLs; use `useNavigation().goTo(pageId)` for internal pages.
@@ -658,7 +734,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
@@ -680,7 +756,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
-- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
+- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a `16 / 9` card cover, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
 
 **Honest ceilings:** the styling surface is React Native style objects, not full CSS. Gradients come from the `<Gradient>` primitive (not a CSS `linear-gradient` string), depth comes from `theme.elevation` (not arbitrary `box-shadow` stacks), and there are no custom CSS keyframe animations or `transition` strings, no `filter` / `backdrop-filter` / `clip-path` / `mask` / blend modes, and no opacity-faked tints (that's what `primarySoft` is for). Aim for clean, confident, professional polish within those bounds — lifted surfaces, generous corners, one accent moment.

package/dist/contract.cjs

@@ -72,6 +72,9 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   }),
   elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
+  // REQ-THEME-LOOK: multiplies every layout spacing value at render. 1 is
+  // unchanged, so a theme that never sets it renders exactly as before.
+  spacingScale: 1,
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
     fontFamily:
@@ -86,6 +89,12 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   // host so ONE channel carries them to the Player and the export. Empty by
   // default — an unconfigured theme resolves to no component overrides.
   components: Object.freeze({}),
+  // REQ-THEME-ELEMENT: the tenant's per-WIDGET-TYPE style values, keyed by
+  // manifest id. `components` above restyles a whole scope through a shared
+  // vocabulary, which only reaches a widget the vocabulary knows about; this
+  // reaches ANY widget by naming it, using that widget's OWN styleSchema field
+  // names. Empty by default.
+  widgetStyles: Object.freeze({}),
 });
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
@@ -130,6 +139,32 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   defaultAngle: 180,
 });
 
+// REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
+// NODES -- a container states its own `padding` / `gap` / `margin` -- so a plain
+// theme key could never make an existing app breathe: every node already
+// carried a value and there was no default left to change. This scales those
+// node values at RENDER time instead, on both hosts, which is why it moves a
+// page that was authored long ago. SPACING only -- never radii, font sizes or
+// minHeight -- so a look keeps its shape while its air moves, and the author’s
+// relative proportions survive: a tight table stays tighter than the card
+// beside it.
+// REQ-THEME-ELEMENT: bounds on the per-widget-type style map. `theme_config` is
+// an unbounded JSON bag that an UNAUTHENTICATED GET /tenant/config returns on
+// every cold Player start and that the compiler bakes verbatim into the native
+// export -- so a map that grows with the widget catalog needs a stated ceiling.
+// Declared here so the coercer, the Studio control and the planner prompt agree.
+const THEME_WIDGET_STYLES = Object.freeze({
+  // One entry per widget TYPE, not per instance, so this is generous.
+  maxWidgets: 200,
+  // Matches the styleSchema field cap the widget agent is held to.
+  maxFieldsPerWidget: 12,
+});
+const THEME_SPACING_SCALE = Object.freeze({
+  min: 0.5,
+  max: 2,
+  default: 1,
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -159,6 +194,23 @@ const FORM_SUBMIT_FIELDS = Object.freeze({
   gradient: "submitGradient",
 });
 
+// REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
+// ANY widget that reads them -- including a Mason-generated one, whose id can
+// never appear in a hand-maintained allowlist. That allowlist is why "make the
+// cards darker" reached the nine built-ins and nothing else.
+//
+// `shadow` is deliberately ABSENT: its name is bare and shared with the button
+// scope, so binding it by name would cross the scopes. The bare names stay on
+// the allowlist for exactly that reason -- `appstudio.image` also reads a
+// `background` field, and the button scope must not leak into it.
+const CARD_UNIVERSAL_FIELDS = Object.freeze({
+  background: "cardBackground",
+  borderColor: "cardBorderColor",
+  radius: "cardRadius",
+  padding: "cardPadding",
+  gradient: "cardGradient",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -187,6 +239,7 @@ const THEME_COMPONENTS = Object.freeze({
   }),
   card: Object.freeze({
     label: "Cards",
+    universalFields: CARD_UNIVERSAL_FIELDS,
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
@@ -243,8 +296,18 @@ const HOOKS = [
     signature: "useTheme()",
     returnShape: {
       colors:
-        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }",
+        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info } — " +
+        "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
+        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "page: a container painting its own background re-derives them for its " +
+        "subtree. Read them and your text is readable wherever the widget lands; " +
+        "there is nothing to opt into.",
       spacing: "{ xs, sm, md, lg, xl }",
+      spacingScale:
+        "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
+        "HOST-OWNED: the host already scales layout spacing by it. Read it only " +
+        "if your widget draws its own internal spacing and wants to breathe with " +
+        "the rest of the app.",
       radii: "{ sm, md, lg, pill }",
       typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
       components:
@@ -436,6 +499,7 @@ const HOOKS = [
     signature: "useNavigation()",
     returnShape: {
       goTo: "(pageId: string, params?: object) => void",
+      openLink: "(link: string) => boolean",
       goBack: "() => void",
       push: "(pageId: string, params?: object) => void",
       replace: "(pageId: string, params?: object) => void",
@@ -650,7 +714,7 @@ const HOOKS = [
       signedAt: "string | null",
       verdict: "{ valid, checks, content_status, ... } | null",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -760,9 +824,12 @@ const HOOKS = [
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
     returnShape: {
-      create: "(record) => Promise<Record>  // rejects with DatastoreError",
-      update: "(id, partial) => Promise<Record>  // rejects with DatastoreError",
-      delete: "(id) => Promise<void>  // rejects with DatastoreError",
+      create:
+        "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      update:
+        "(id, partial) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      delete:
+        "(id) => Promise<void>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
     },
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.write:*"],
@@ -878,7 +945,7 @@ const HOOKS = [
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -907,7 +974,7 @@ const HOOKS = [
     returnShape: {
       groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       create:
         "({ name }) => Promise<Group>  // rejects with DirectoryError",
@@ -946,7 +1013,7 @@ const HOOKS = [
       message: "string | null",
       loading: "boolean",
       statusLoading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -1028,7 +1095,7 @@ const HOOKS = [
       permissions:
         "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       grant:
         "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
       revoke:
@@ -1091,10 +1158,12 @@ const HOOKS = [
     description:
       "Surfaces a short auto-dismissing notification. Returns { showToast }. " +
       "showToast({ kind: 'success' | 'error' | 'info' | 'warning', message }) " +
-      "asks the host to render a workspace-themed toast. If the host hasn't " +
-      "wired a renderer, the web variant dispatches an 'appstudio:widget-toast' " +
-      "CustomEvent on window; native logs to the console. The widget never " +
-      "owns the toast UI — that's the host's responsibility.",
+      "renders a workspace-themed toast. Both shipping hosts paint it — the " +
+      "web Player and the exported Expo app — so a confirmation you raise IS " +
+      "seen by the user; use it to confirm every write. The widget never owns " +
+      "the toast UI, so never build your own banner or call Alert.alert for a " +
+      "routine save. An authoring preview (the Studio canvas) wires no " +
+      "renderer, and there the call is simply a no-op.",
     returnShape: {
       showToast: "({ kind, message }) => void",
     },
@@ -1658,9 +1727,10 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Optional host toast slot. { showToast({ kind, message }): void }. " +
       "The host populates this to render workspace-themed notifications " +
-      "from any widget that calls useToast(). When omitted the SDK falls " +
-      "back to dispatching an 'appstudio:widget-toast' CustomEvent on web " +
-      "and console.log on native.",
+      "from any widget that calls useToast(). Both rendering hosts wire it " +
+      "(the web Player and the compiler's native WidgetHost); authoring " +
+      "surfaces omit it, and the SDK then falls back to dispatching an " +
+      "'appstudio:widget-toast' CustomEvent on web and console.log on native.",
     required: false,
     fields: { showToast: "function" },
   },
@@ -2635,6 +2705,28 @@ const CONTRACT = deepFreeze({
   //    public endpoint instead, which skips the cache, the metering and the
   //    workspace's provider. Publishing the host list here keeps the linter,
   //    the Developer guide and the agent prompt reading one source.
+  // 1.52.0: additive (REQ-THEME-LOOK) -- `themeTokens.spacingScale` (default 1)
+  //    and `themeSpacingScale`, its clamp bounds. A spacing control in the
+  //    Studio could reach nothing that mattered, because layout spacing is
+  //    authored ONTO each node (`padding` / `gap` / `margin`) rather than
+  //    inherited from the theme -- so no theme key could make a built app
+  //    breathe. Both hosts now multiply a node’s resolved spacing by this scale
+  //    at render. SPACING only: radii, font sizes and minHeight are untouched,
+  //    so a look keeps its shape and the author’s proportions hold. Additive:
+  //    no export changed signature and a theme without the key resolves to 1,
+  //    rendering identically to before.
+  // 1.53.0: fix (REQ-THEME-17) -- `isHexColor` accepts the 8-digit
+  //    `#RRGGBBAA` form. The Studio has put an opacity row on every colour
+  //    field since sc-4158, so a brand colour or a page background routinely
+  //    arrives with alpha -- and this predicate rejecting it made
+  //    `themeConfigToTokens` DROP the key, so a translucent dark background
+  //    stopped reaching deriveSurfaceTokens and every panel fell back to white.
+  //    A second, alpha-aware predicate already existed beside it for gradients,
+  //    which is why the asymmetry kept being rediscovered surface by surface;
+  //    there is now one. `hexChannels` ignores the alpha pair, so contrast and
+  //    the derived tints still reason about the opaque colour while the value
+  //    keeps its transparency. Widening only: every input accepted before is
+  //    accepted now, and unchanged.
   // 1.54.0: additive (sc-4399, epic 4395) — `useContainerWidth()` +
   //    `isNarrowWidth(width)` / `NARROW_WIDTH_PX`. Built-in widgets laid
   //    themselves out at a fixed size — UserManagement's rows alone carried
@@ -2666,7 +2758,36 @@ const CONTRACT = deepFreeze({
   //    Developer guide have always said, so a widget written against the
   //    declared shape destructured a function and threw on first interaction.
   //    Declared as a bare callable now; no runtime behaviour changed.
-  version: "1.60.1",
+  // 1.61.0: additive (REQ-THEME-SURFACE / -CARD / -WIDGET / -ELEMENT) -- the
+  //    theme reaches the elements an app is built from. Four things it could
+  //    not touch before, and one mechanism each:
+  //    * `deriveSurfaceTokens` (host export) -- the surface/text/border set is
+  //      derived per PAINTED SURFACE, not once per page, so an UNSET text
+  //      colour is readable inside a coloured container. It was a hand-mirrored
+  //      copy per host; now one symmetric implementation (a light fill resolves
+  //      to the light tokens instead of returning null).
+  //    * `themeComponents.card.universalFields` -- the card scope's unambiguous
+  //      field NAMES bind to any widget that declares them, so a widget whose id
+  //      can never appear in a hand-maintained allowlist still follows "Cards".
+  //      The bare names (`background`, `textColor`, `color`, `fontSize`,
+  //      `shadow`) keep the allowlist: they mean different things per scope.
+  //      `applyThemeComponentStyle` takes an optional 4th `styleSchema` so the
+  //      name-bound fields land only on a widget that reads them.
+  //    * `themeTokens.widgetStyles` + `themeWidgetStyles` bounds +
+  //      `normaliseWidgetStyles` (host export) -- app-wide values keyed by
+  //      widget MANIFEST ID and then by that widget's OWN styleSchema field
+  //      names, so `panelFill` is as reachable as `cardBackground`: no shared
+  //      vocabulary, no allowlist, no naming requirement. Validated
+  //      structurally, because the key space is a workspace's widget catalog
+  //      rather than this contract, and bounded because `theme_config` is
+  //      unbounded, read unauthenticated on every cold Player start, and baked
+  //      verbatim into the native export.
+  //    Precedence: contract default -> palette -> `components.<scope>` ->
+  //    `widgetStyles[manifestId]` -> the author's per-instance `props.style`.
+  //    Naming one widget is strictly more specific than restyling a scope, and
+  //    the Properties Panel stays the final word. Additive throughout: a theme
+  //    that sets none of it resolves exactly as before.
+  version: "1.62.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2681,6 +2802,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeSpacingScale: THEME_SPACING_SCALE,
+  themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2720,12 +2843,31 @@ function requiredContextKeys() {
 // one source removes that drift (CLAUDE.md §3).
 // ---------------------------------------------------------------------------
 
-const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+// REQ-THEME-17 / sc-4158 — 3, 6 or 8 digits. The 8-digit form carries alpha,
+// and this predicate accepting it is load-bearing: the Studio puts an opacity
+// row on every colour field, so `primaryColor` and `backgroundColor` routinely
+// arrive as `#RRGGBBAA`. While this rejected them, `themeConfigToTokens` DROPPED
+// the key outright — a translucent page background stopped reaching
+// deriveSurfaceTokens and every panel in the app fell back to white.
+//
+// There used to be a second, alpha-aware predicate beside this one for
+// gradients, which is how the asymmetry kept being rediscovered: each new
+// alpha-carrying surface met the strict one first. There is now only this.
+const HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 
 function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+/**
+ * The R/G/B bytes, with any alpha pair IGNORED.
+ *
+ * Deliberate: everything downstream of this is luminance maths — contrast,
+ * readable text, derived tints — and none of it can composite without knowing
+ * the backdrop, which a token table does not have. Alpha survives in the VALUE
+ * (the host hands `#RRGGBBAA` straight to the renderer); it just takes no part
+ * in deciding whether a colour reads as light or dark.
+ */
 function hexChannels(hex) {
   let h = hex.slice(1);
   if (h.length === 3) {
@@ -2810,6 +2952,54 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// REQ-THEME-SURFACE: how far a derived surface travels toward white, and the
+// light-on-dark text pair a dark surface carries.
+const SURFACE_LIFT = Object.freeze({ surface: 0.1, surfaceMuted: 0.05, border: 0.18 });
+const DARK_SURFACE_TEXT = Object.freeze({
+  onSurface: "#f8fafc",
+  onSurfaceMuted: "#cbd5e1",
+});
+
+/**
+ * REQ-THEME-DARK: the coherent surface / text / border set one background wants.
+ * A dark background lifts its panels toward white and goes light-on-dark; a
+ * light one resolves to the contract's own light tokens.
+ *
+ * REQ-THEME-SURFACE: applied to the PAGE background and — because every surface
+ * a page is built from may paint its own fill — to a CONTAINER background too.
+ * That is what makes an UNSET text colour readable inside a dark card on a light
+ * page, which is in turn what lets a built app follow its theme instead of
+ * carrying a baked-in hex for every heading.
+ *
+ * Returns all five keys together, never a subset: layering a dark card's text
+ * colour over a light ancestor's surface is exactly how light-on-light happens.
+ * `null` only when the colour is unusable, letting the caller keep what it had.
+ */
+function deriveSurfaceTokens(backgroundColor) {
+  if (!isHexColor(backgroundColor)) return null;
+  // "Dark" = the background wants light text (same luminance test as the
+  // on-color contrast picker).
+  const wantsLightText =
+    readableTextColor(backgroundColor, "__dark__", "__light__") === "__light__";
+  if (!wantsLightText) {
+    const base = DEFAULT_THEME_TOKENS.colors;
+    return {
+      surface: base.surface,
+      surfaceMuted: base.surfaceMuted,
+      onSurface: base.onSurface,
+      onSurfaceMuted: base.onSurfaceMuted,
+      border: base.border,
+    };
+  }
+  return {
+    surface: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surface),
+    surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
+    onSurface: DARK_SURFACE_TEXT.onSurface,
+    onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
+  };
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -2828,9 +3018,10 @@ function gradientAngleToVector(angle) {
   };
 }
 
-// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
-// persists 8-digit component colours; the host must not drop what it accepted.
-const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+// Gradients used to need their own alpha-aware predicate because HEX_RE was not.
+// HEX_RE is now, so this is the same check by another name — kept only as a
+// local alias so the call sites below read as before.
+const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
@@ -2855,8 +3046,33 @@ function normaliseComponentGradient(raw) {
   return { from, to, angle: ((deg % 360) + 360) % 360 };
 }
 
+// REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
+// because BOTH hosts multiply node spacing by it and a disagreement here would
+// re-space an exported page against the Player. Anything absent, non-finite or
+// out of band resolves to 1 (unchanged) rather than throwing -- `theme_config`
+// is a JSON bag a workspace admin can PUT verbatim.
+function clampSpacingScale(value) {
+  // Absent means UNSET, not "as tight as possible" — Number(null) and Number("")
+  // are both 0, which would otherwise clamp an untouched theme to the minimum.
+  if (value === null || value === undefined || value === "") {
+    return THEME_SPACING_SCALE.default;
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return THEME_SPACING_SCALE.default;
+  return Math.min(Math.max(n, THEME_SPACING_SCALE.min), THEME_SPACING_SCALE.max);
+}
+
+// REQ-THEME-LOOK: apply that scale to ONE spacing value. Rounded to whole
+// pixels so a scaled gap stays on the same pixel grid as an unscaled one.
+function scaleSpacing(value, scale) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return value;
+  return Math.round(value * clampSpacingScale(scale));
+}
+
 module.exports = {
   CONTRACT,
+  clampSpacingScale,
+  scaleSpacing,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,
@@ -2864,6 +3080,7 @@ module.exports = {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveSurfaceTokens,
   gradientAngleToVector,
   normaliseComponentGradient,
   formatMoneyIn,