@colixsystems/widget-sdk 0.179.0 → 0.180.1

package/README.md

@@ -57,7 +57,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
-| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
+| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
@@ -74,7 +74,21 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.179.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.180.1` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.180.1 (contract 1.141.0 — unchanged)
+
+**A widget built in the Studio turns on the device capability it uses.** The `react-native-nfc-manager` notes said the publisher must enable the NFC tags capability in Publish settings, and told the widget to say so from its error state. Nobody reads a widget's error state before building: a workspace whose widget imported the package shipped an Android build without the `NFC` permission, and the library — which touches the adapter on every activity pause — closed the app at each permission prompt, file picker and camera open. Publishing a widget from Mason or the widget agent now turns on every device capability its source uses (NFC tags for this package; step counting and activity data for `Pedometer` from `expo-sensors`, and only for `Pedometer`). A widget installed any other way is unchanged: its publisher still enables the capability in Publish settings. The notes now say both, and the error state says what is true on the phone — this build does not include NFC and needs a new one. No export, type or rule changed.
+
+### What's new in 0.180.0 (contract 1.141.0)
+
+**`<Button>` stays readable on a coloured section.** A section that paints its own fill (a card or band on the theme's colours, or a gradient wash) already gave its text a colour that reads there. Its buttons kept the page's paint, so an `outlined` button drew its label and border in the primary colour on a band washed in that same colour, and a `secondary` fill disappeared into it. A button there is now measured against the section by the same rule as its text: a colour that already reads is kept, and one the section makes unreadable takes the section's text colour, but only when that reads better. "The section makes it unreadable" is measured against the surface the look was designed for: a colour moves only when the section costs it at least a third of the contrast it had there, so a white or lightly tinted panel changes nothing.
+
+- `outlined`: a label under 4.5:1 and a border under 3:1 against the section are re-inked.
+- `secondary`: a fill under 3:1 against the section becomes the section's outlined button.
+- `primary` and `danger`: a fill under 3:1 turns inverse, with the section's text colour as its fill and its own colour as its label, so it still leads the quieter buttons. Where that label would not reach 4.5:1, or you set the label colour, the fill is kept and gains an edge in the section's text colour instead.
+
+A colour you pass in `fields`, `style` (`backgroundColor`, `borderColor`) or `labelStyle` (`color`), or that the app's button look sets, is never changed. A `<Card>` inside such a section becomes the surface its content reads: it re-derives `surface`, `onSurface`, `border` and the rest from its own fill, as a layout container does, and its buttons are measured against it. Inside a section `useTheme().colors.backdrop` is the fill your widget sits on and `colors.backdropBase` the surface the look was designed for; on the page itself both are absent.
 
 ### What's new in 0.179.0 (contract 1.140.0)
 
@@ -634,7 +648,7 @@ Also tightened in this release: the `publicGrant` flags are now type-checked. Th
 **NFC tags are vetted, native-only (`react-native-nfc-manager`).** A widget can now read and write NFC tags on the Expo export — NDEF over `NfcManager.requestTechnology(NfcTech.Ndef)`, plus the raw technologies a badge, asset tag or transit card uses: `NfcTech.IsoDep` on both hosts, `NfcTech.MifareClassic` on Android, `NfcTech.MifareIOS` / `FelicaIOS` / `Iso15693IOS` on iOS. (There is no `NfcTech.FeliCa` — check `index.d.ts` before naming one.) This is the last common "tap a physical thing" input the allowlist was missing; barcode and QR already had `useBarcodeScanner()`.
 
 - **Native-only, and the browser is why.** Web NFC ships in Chrome on Android alone — Safari, Firefox and every desktop browser omit it — so there is no web build to pair with. Put the import in `widget.native.jsx` and give `widget.web.jsx` a real way in: a typed code field, or the SDK's `useBarcodeScanner()` QR path. The linter's `import-platform-mismatch` enforces the split.
-- **Opt-in per workspace — and `isSupported()` cannot see that.** The export claims the iOS NFC entitlement and the Android `NFC` permission only when the publisher enables the **NFC tags** device capability in Publish settings. `isSupported()` probes the **device** (`readingAvailable` on iOS, `hasSystemFeature` on Android), not the gate: on a capable phone in an app that never asked, it returns `true` and the read then fails — Android throws a `SecurityException` from `registerTagEvent`, iOS cannot open the reader session. So wrap `start()` / `requestTechnology()` in a `try` and render a clear **error state** from the `catch` — name what is missing and say the capability has to be switched on in Publish settings. That `catch` is an error path, **not** the web build's typed-code substitute: do not give `widget.native.jsx` a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace.
+- **A per-workspace device capability — and `isSupported()` cannot see it.** The export claims the iOS NFC entitlement and the Android `NFC` permission only while the workspace's **NFC tags** device capability is on. A widget built in the Studio by Mason or the widget agent turns it on when it is published; for any other widget the publisher enables it in Publish settings. Either way it reaches a phone only with the next native build. `isSupported()` probes the **device** (`readingAvailable` on iOS, `hasSystemFeature` on Android), not the gate: on a capable phone running a build made without the capability, it returns `true` and the read then fails — Android throws a `SecurityException` from `registerTagEvent`, iOS cannot open the reader session. So wrap `start()` / `requestTechnology()` in a `try` and render a clear **error state** from the `catch` — say this build of the app does not include NFC and that it needs a new build. That `catch` is an error path, **not** the web build's typed-code substitute: do not give `widget.native.jsx` a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace.
 - **Clean up the session.** `cancelTechnologyRequest()` in your effect cleanup; an abandoned request leaves the reader sheet up on iOS.
 - **It is a write capability too.** Read with `getNdefMessage()`; write with `writeNdefMessage(bytes)`, `formatNdef(bytes)` (Android only, for a blank tag) and `transceive(bytes)` on the `IsoDep` / `NfcA` / `NfcV` handlers. One capability covers both — Android expresses read and write through the single `android.permission.NFC` — so the workspace owner who enables it is consenting to every widget in the workspace being able to rewrite the tags their users tap. Raw ISO7816 `transceive` on iOS additionally needs `select-identifiers` on the entitlement, which the export does not declare; NDEF read and write work on both hosts.
 - **`makeReadOnly()` is irreversible.** It permanently locks the tag — no later write will ever succeed, on any device, by any app. Call it only where the feature genuinely wants a one-time-programmable tag, and never as a cleanup step after writing.

package/dist/button-style.js

@@ -2,6 +2,8 @@
 // the built-in widgets (frontend `_shared/buttonStyle.js` re-exports these).
 // Platform-free, so both hosts resolve a button identically.
 
+import { INK_CONTRAST, contrastRatio, inkForBackdrop, isHexColor } from "./contract.js";
+
 export const BUTTON_PADDING_MAX = 64;
 export const BUTTON_BORDER_WIDTH_MAX = 8;
 
@@ -58,3 +60,95 @@ export function selfAlignStyle(style) {
   const alignSelf = SELF_ALIGNMENTS[style && style.align];
   return alignSelf ? { alignSelf } : null;
 }
+
+// How much of its page contrast a section must cost a colour before it moves:
+// a tint or neutral panel never does, a coloured band always does.
+const SECTION_LOSS = 1.5;
+
+/**
+ * A variant's own paint, measured against the painted section it sits on
+ * (`colors.backdrop`) by the rule that section's text follows. A colour moves
+ * only where it is unreadable there AND the section is what broke it, measured
+ * against the surface the look was designed for (`colors.backdropBase`). Only
+ * what the look painted moves; `owned` names what the maker set.
+ *
+ * A transparent button re-inks its label and border separately. A fill the
+ * section swallows is replaced: a quiet `secondary` becomes the section's
+ * outlined button, and an emphatic fill turns inverse (the section's ink as
+ * fill, its own colour as label), so it still outranks the quiet ones. Where
+ * that label would not read, or the maker chose it, the fill gains an edge.
+ *
+ * @param {string} variant
+ * @param {{container: object, ink: string}} paint
+ * @param {object} colors - the surface-aware theme colours.
+ * @param {{fill?: boolean, label?: boolean, border?: boolean}} [owned]
+ * @returns {{container: object, ink: string}} `paint` itself when nothing moves.
+ */
+export function paintOnBackdrop(variant, paint, colors, owned = {}) {
+  const { backdrop, backdropBase, onSurface: ink } = colors || {};
+  if (owned.fill || ![backdrop, backdropBase, ink].every(isHexColor)) return paint;
+  const reink = (colour, minimum) =>
+    isHexColor(colour) && brokenBySection(colour, backdrop, backdropBase, minimum)
+      ? inkForBackdrop(colour, ink, backdrop, minimum)
+      : colour;
+  const { container } = paint;
+  const fill = container.backgroundColor;
+  if (fill === "transparent") return reinkOutline(paint, reink, owned);
+  if (reink(fill, INK_CONTRAST.boundary) === fill) return paint;
+  if (!owned.label && variant === "secondary") {
+    return {
+      container: { backgroundColor: "transparent", borderWidth: 1, borderColor: ink },
+      ink,
+    };
+  }
+  if (!owned.label && contrastRatio(fill, ink) >= INK_CONTRAST.text) {
+    const edge = container.borderColor ? { borderColor: ink } : null;
+    return { container: { ...container, backgroundColor: ink, ...edge }, ink: fill };
+  }
+  if (owned.border) return paint;
+  return { container: { ...container, borderWidth: 1, borderColor: ink }, ink: paint.ink };
+}
+
+function brokenBySection(colour, backdrop, base, minimum) {
+  const here = contrastRatio(colour, backdrop);
+  return here < minimum && here * SECTION_LOSS <= contrastRatio(colour, base);
+}
+
+function reinkOutline(paint, reink, owned) {
+  const { borderColor } = paint.container;
+  const label = owned.label ? paint.ink : reink(paint.ink, INK_CONTRAST.text);
+  const border = owned.border ? borderColor : reink(borderColor, INK_CONTRAST.boundary);
+  if (label === paint.ink && border === borderColor) return paint;
+  return { container: { ...paint.container, borderColor: border }, ink: label };
+}
+
+const SIDE_BORDER_COLORS = [
+  "borderColor",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+];
+
+/**
+ * Which of a button's fill, label and border its caller set, so
+ * `paintOnBackdrop` never replaces them: the surface `fields`, and colours in
+ * the flattened container `style` and `labelStyle`.
+ */
+export function ownedButtonPaint(variant, fields, style, labelStyle) {
+  const f = fields || {};
+  const s = style || {};
+  const danger = variant === "danger";
+  return {
+    fill: Boolean(
+      f.background || f.gradient || s.backgroundColor || (danger && f.dangerBackground),
+    ),
+    label: Boolean(f.textColor || (labelStyle && labelStyle.color) || (danger && f.dangerTextColor)),
+    border: Boolean(
+      f.borderColor ||
+        f.ringColor ||
+        SIDE_BORDER_COLORS.some((key) => s[key]) ||
+        (danger && f.dangerBorderColor),
+    ),
+  };
+}

package/dist/button-view.js

@@ -8,7 +8,12 @@ import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { lucideGlyph } from "./icon.js";
 import { applyThemeComponentStyle } from "./theme-components.js";
 import { cornerRadiusOverlay, shadowStyle, gradientProps } from "./card-style.js";
-import { buttonSurfaceOverlay, buttonSurfaceTextOverlay } from "./button-style.js";
+import {
+  buttonSurfaceOverlay,
+  buttonSurfaceTextOverlay,
+  ownedButtonPaint,
+  paintOnBackdrop,
+} from "./button-style.js";
 
 export const BUTTON_VARIANTS = Object.freeze(["primary", "secondary", "outlined", "danger"]);
 
@@ -39,8 +44,8 @@ function variantPaint(variant, colors) {
 }
 
 // Precedence, weakest first: variant, danger scope, ring, then the fields.
-function containerLayers(variant, f, colors) {
-  const paint = variantPaint(variant, colors);
+function containerLayers(variant, f, colors, owned) {
+  const paint = paintOnBackdrop(variant, variantPaint(variant, colors), colors, owned);
   let ink = paint.ink;
   const layers = [paint.container];
   if (variant === "danger") {
@@ -115,7 +120,13 @@ export function makeButton(rn) {
       ? fields || {}
       : applyThemeComponentStyle(THEMED_AS, theme, { style: fields }).style || {};
     const resolvedVariant = BUTTON_VARIANTS.includes(variant) ? variant : "primary";
-    const { layers, ink } = containerLayers(resolvedVariant, f, colors);
+    const owned = ownedButtonPaint(
+      resolvedVariant,
+      f,
+      StyleSheet.flatten(style),
+      StyleSheet.flatten(labelStyle),
+    );
+    const { layers, ink } = containerLayers(resolvedVariant, f, colors, owned);
 
     const fontSize =
       typeof f.fontSize === "number" && Number.isFinite(f.fontSize)

package/dist/card-style.js

@@ -5,7 +5,7 @@
 // Every resolver emits ONLY the fields that are set, so a widget's own base
 // style keeps whatever the author left alone.
 
-import { CONTRACT, normaliseComponentGradient } from "./contract.js";
+import { CONTRACT, isHexColor, mixHex, normaliseComponentGradient } from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
 
@@ -118,6 +118,35 @@ export function gradientProps(value) {
     : null;
 }
 
+/**
+ * The colour a card's buttons are measured against: its opaque flat fill, or
+ * a gradient's midpoint, as a layout container's ink basis is read. `null`
+ * (a translucent or unknown fill) keeps the backdrop the card inherited.
+ *
+ * @param {object|Array} styles - the card's container style, as composed.
+ * @param {{colors: string[]}|null} gradient - its `gradientProps`.
+ */
+export function cardBackdrop(styles, gradient) {
+  if (gradient) {
+    const [from, to] = gradient.colors;
+    return isOpaqueHex(from) && isOpaqueHex(to) ? mixHex(from, to, 0.5) : null;
+  }
+  let fill = null;
+  for (const style of [styles].flat(Infinity)) {
+    if (style && typeof style === "object" && style.backgroundColor !== undefined) {
+      fill = style.backgroundColor;
+    }
+  }
+  return isOpaqueHex(fill) ? fill : null;
+}
+
+// The colour maths ignores alpha, so a see-through fill cannot be judged.
+function isOpaqueHex(value) {
+  if (!isHexColor(value)) return false;
+  const hex = value.slice(1);
+  return hex.length !== 8 || hex.slice(6).toLowerCase() === "ff";
+}
+
 /** The card-surface gradient (`cardGradient`). */
 export function cardGradientProps(style) {
   return gradientProps(style && style.cardGradient);

package/dist/card-view.js

@@ -6,7 +6,7 @@
 // swap lives here once rather than in each widget.
 
 import React from "react";
-import { useHostTheme } from "./hooks.js";
+import { useHostTheme, BackdropScope } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { CONTRACT } from "./contract.js";
 import {
@@ -14,6 +14,7 @@ import {
   cardSurfaceStyle,
   cardGradientProps,
   cardLayoutStyle,
+  cardBackdrop,
 } from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
 
@@ -134,12 +135,17 @@ export function makeCard(rn) {
 
     const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
     const gradient = cardGradientProps(fields);
+    const basis = cardBackdrop(
+      [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
+      gradient,
+    );
+    const scoped = React.createElement(BackdropScope, { basis }, children);
 
     if (!gradient) {
       return React.createElement(
         Container,
         { style: composeStyle([base, overlay, layout], containerStyle), ...rest },
-        children,
+        scoped,
       );
     }
 
@@ -156,7 +162,7 @@ export function makeCard(rn) {
           style: composeStyle([base, paint, layout], containerStyle),
           ...rest,
         },
-        children,
+        scoped,
       );
     }
 
@@ -179,7 +185,7 @@ export function makeCard(rn) {
           ),
           ...rest,
         },
-        children,
+        scoped,
       ),
     );
   }

package/dist/contract.cjs

@@ -2480,7 +2480,7 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3371,7 +3371,7 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "system",
     description:
-      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render a clear ERROR STATE from the catch - name what is missing and say the maker must switch 'nfc' on in Publish settings. That catch is an ERROR path, NOT the web build's typed-code substitute: do not give widget.native.jsx a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
+      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO a per-workspace device capability: the export claims the iOS NFC entitlement and the Android NFC permission only while the workspace's 'nfc' device capability is on. A widget built in the Studio by Mason or the widget agent turns it on when it is published; for any other widget the publisher enables it in Publish settings. Either way it reaches a phone only with the next native build. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone running a build made without the capability it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render a clear ERROR STATE from the catch - say this build of the app does not include NFC and that it needs a new build. That catch is an ERROR path, NOT the web build's typed-code substitute: do not give widget.native.jsx a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
   },
   {
     specifier: "decimal.js",
@@ -4764,7 +4764,10 @@ const CONTRACT = deepFreeze({
   //    (boolean, default false): the widget draws live figures about its
   //    records, so the app-builder counts it as the page's figures when it
   //    reuses it. Existing manifests omit it and read false.
-  version: "1.140.0",
+  // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
+  //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
+  //    colour that cannot be read against it by the rule its text follows.
+  version: "1.141.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5037,6 +5040,25 @@ function deriveSurfaceTokens(backgroundColor) {
   };
 }
 
+// sc-8370: WCAG 1.4.3 for text, 1.4.11 for a control's boundary.
+const INK_CONTRAST = Object.freeze({ text: 4.5, boundary: 3 });
+
+/**
+ * The measured re-ink rule every painted section applies — to its text tiers
+ * and to its buttons alike. `current` is kept while it reaches `minimum`
+ * against `backdrop`; below that, `candidate` replaces it only when it is
+ * genuinely more readable there. A backdrop with no good answer keeps what it
+ * had rather than committing to a colour that is wrong for half of it.
+ */
+function inkForBackdrop(current, candidate, backdrop, minimum) {
+  if (!isHexColor(current) || !isHexColor(candidate) || !isHexColor(backdrop)) {
+    return current;
+  }
+  const held = contrastRatio(current, backdrop);
+  if (held >= minimum) return current;
+  return contrastRatio(candidate, backdrop) > held ? candidate : current;
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -5119,6 +5141,8 @@ module.exports = {
   readableTextColor,
   deriveAccentTints,
   deriveSurfaceTokens,
+  inkForBackdrop,
+  INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,

package/dist/contract.js

@@ -2480,7 +2480,7 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3367,7 +3367,7 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "system",
     description:
-      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render a clear ERROR STATE from the catch - name what is missing and say the maker must switch 'nfc' on in Publish settings. That catch is an ERROR path, NOT the web build's typed-code substitute: do not give widget.native.jsx a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
+      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO a per-workspace device capability: the export claims the iOS NFC entitlement and the Android NFC permission only while the workspace's 'nfc' device capability is on. A widget built in the Studio by Mason or the widget agent turns it on when it is published; for any other widget the publisher enables it in Publish settings. Either way it reaches a phone only with the next native build. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone running a build made without the capability it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render a clear ERROR STATE from the catch - say this build of the app does not include NFC and that it needs a new build. That catch is an ERROR path, NOT the web build's typed-code substitute: do not give widget.native.jsx a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
   },
   {
     specifier: "decimal.js",
@@ -4760,7 +4760,10 @@ const CONTRACT = deepFreeze({
   //    (boolean, default false): the widget draws live figures about its
   //    records, so the app-builder counts it as the page's figures when it
   //    reuses it. Existing manifests omit it and read false.
-  version: "1.140.0",
+  // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
+  //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
+  //    colour that cannot be read against it by the rule its text follows.
+  version: "1.141.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5033,6 +5036,25 @@ function deriveSurfaceTokens(backgroundColor) {
   };
 }
 
+// sc-8370: WCAG 1.4.3 for text, 1.4.11 for a control's boundary.
+const INK_CONTRAST = Object.freeze({ text: 4.5, boundary: 3 });
+
+/**
+ * The measured re-ink rule every painted section applies — to its text tiers
+ * and to its buttons alike. `current` is kept while it reaches `minimum`
+ * against `backdrop`; below that, `candidate` replaces it only when it is
+ * genuinely more readable there. A backdrop with no good answer keeps what it
+ * had rather than committing to a colour that is wrong for half of it.
+ */
+function inkForBackdrop(current, candidate, backdrop, minimum) {
+  if (!isHexColor(current) || !isHexColor(candidate) || !isHexColor(backdrop)) {
+    return current;
+  }
+  const held = contrastRatio(current, backdrop);
+  if (held >= minimum) return current;
+  return contrastRatio(candidate, backdrop) > held ? candidate : current;
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -5115,6 +5137,8 @@ export {
   readableTextColor,
   deriveAccentTints,
   deriveSurfaceTokens,
+  inkForBackdrop,
+  INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,

package/dist/hooks.js

@@ -46,6 +46,7 @@ import {
   // sc-5717 — "is this key still at its declared default", shared with the
   // host codec so the hook and the encoder can never disagree about it.
   sameWidgetRouteValue,
+  deriveSurfaceTokens,
 } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
@@ -67,6 +68,27 @@ export function WidgetContextProvider({ value, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
+/**
+ * @internal — a surface painting its own fill inside a coloured section
+ * becomes the surface its content reads and its buttons are measured against
+ * (`<Card>` uses it), by the derivation a layout container applies.
+ * Outside such a section there is no backdrop and nothing changes.
+ */
+export function BackdropScope({ basis, children }) {
+  const ctx = useContext(HostWidgetContext);
+  const theme = ctx && ctx.workspace ? ctx.workspace.theme : null;
+  const colors = theme && theme.colors;
+  const scoped = Boolean(basis && colors && colors.backdrop && colors.backdrop !== basis);
+  const value = useMemo(
+    () =>
+      scoped
+        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis } } } }
+        : ctx,
+    [scoped, ctx, theme, colors, basis],
+  );
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
 // Exported for ./toast.js + future hook modules outside hooks.js. Internal
 // utility — widget code should not import this directly.
 export function useWidgetContextOrThrow(hookName) {

package/dist/host.d.ts

@@ -39,6 +39,21 @@ export type ThemeWidgetStyles = Record<string, ThemeComponentStyle>;
  */
 export function normaliseThemeComponents(raw: unknown): ThemeComponents;
 
+/** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
+export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
+
+/**
+ * The measured re-ink rule a painted section applies to its text and buttons:
+ * `current` while it reaches `minimum` against `backdrop`, else `candidate`
+ * when that reads better there, else `current`.
+ */
+export function inkForBackdrop(
+  current: string,
+  candidate: string,
+  backdrop: string,
+  minimum: number,
+): string;
+
 /**
  * REQ-THEME-ELEMENT host helper: validates a raw `themeConfig.widgetStyles` blob.
  * Structural only — the key space is the workspace's widget catalog, not the

package/dist/host.js

@@ -41,7 +41,7 @@ export {
 // surface — the page background and every container that carries its own fill.
 // Host plumbing, deliberately off the author entry point: a widget reads the
 // already-correct `useTheme().colors`, it never derives them itself.
-export { deriveSurfaceTokens } from "./contract.js";
+export { deriveSurfaceTokens, inkForBackdrop, INK_CONTRAST } from "./contract.js";
 
 // REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
 // auto-dismiss timing, and the themed values a toast is painted with. The

package/dist/index.d.ts

@@ -393,6 +393,11 @@ export interface ThemeTokens {
     onSurface: string;
     danger: string;
     [k: string]: string;
+  } & {
+    /** Inside a section painting its own fill: that fill. Absent on the page. */
+    backdrop?: string;
+    /** The surface the look was designed for, which `backdrop` is judged against. */
+    backdropBase?: string;
   };
   /** sc-3696: the shared elevation vocabulary. Spread a level into a style. */
   elevation: {

package/package.json

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