@colixsystems/widget-sdk 0.128.0 → 0.130.0

package/README.md

@@ -70,7 +70,38 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.128.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.130.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.130.0 (contract 1.101.0)
+
+**New primitive `styleGroup(name)` — mark which element a style group paints (sc-7282).** A widget's `styleSchema` already names the element each field belongs to via `ui.group` ("Card", "Title", "Value"), and the Studio renders those as labelled fieldsets. But a group name says which *fieldset* a control sits in, not which *element on screen* it moves — so clicking a button in the Widget Builder preview could only ever open the whole schema.
+
+- **Spread it on the element each non-Basics group paints:** `<View {...styleGroup("Card")}>`. Pass the EXACT `ui.group` string; a mismatch marks an element no group owns. Mark each group ONCE, on the outermost element an author would point at — never the `"Basics"` group (it paints the whole widget) and never a child of an already-marked element. On a list that repeats a marked element per row, mark every row.
+- **One module, both hosts.** It rides the existing `dataSet` prop: `react-native-web` maps it to a `data-*` attribute, and real react-native drops it, so the marker is inert on the device rather than a second implementation. It is a marker, not a style — it changes nothing about how a widget renders.
+
+### What's new in 0.129.0 (contract 1.100.0)
+
+**Widgets can READ a barcode now — `useBarcodeScanner()` (sc-7228).** A widget could already *generate* a QR code (`react-native-qrcode-svg`) but never read one, so the whole class of apps that starts by pointing a phone at a label — inventory counts, asset check-in/out, warehouse picking, ticket scanning, scan-on-delivery — had no way in.
+
+```jsx
+import { useBarcodeScanner, BarcodeError } from "@colixsystems/widget-sdk";
+
+const { result, scanning, supported, scan, reset } = useBarcodeScanner();
+const hit = await scan();          // { value, format } | null
+```
+
+`scan()` is **imperative** — call it from a tap, because both hosts gate the camera permission prompt on a gesture. It resolves the first code decoded, resolves `null` when the user dismisses (a dismissal is NOT an error), and rejects a `BarcodeError` with `.code` of `PERMISSION_DENIED | UNSUPPORTED | INTERNAL`. `format` is a lowercase symbology name (`qr_code`, `code_128`, `ean_13`, …) and is a **hint**: the two hosts detect different sets, so never branch on it for correctness.
+
+It is deliberately **one-shot** rather than a start/stop subscription — to read several codes, call `scan()` again. There is no loop to leave running and no camera to forget to release.
+
+**Gate the button on `supported`, and always keep a manual-entry path.** `BarcodeDetector` is Chromium-only today, so the web Player reports `supported: false` in Safari and Firefox. That is a genuine browser gap, not a missing feature, so a scanner must never be the only way to enter a code:
+
+```jsx
+<TextInput value={code} onChangeText={setCode} />
+{supported ? <Pressable onPress={scan}><Text>Scan</Text></Pressable> : null}
+```
+
+**Host-brokered, not a vetted import.** Like the camera and speech-to-text, your widget never imports the native module: `expo-camera` is pinned by the Expo export only, so a widget that does not scan gains no native dependency and nothing new enters widget bundles.
 
 ### What's new in 0.128.0 (contract 1.99.0 — unchanged)
 

package/dist/contract.cjs

@@ -1670,6 +1670,38 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-7228 — host-brokered barcode / QR scanning. Optional slice; the hook
+  // reports supported:false rather than throwing at render.
+  {
+    name: "useBarcodeScanner",
+    signature: "useBarcodeScanner(options?)",
+    description:
+      "Read a barcode or QR code with the device camera. Returns { result, scanning, error, supported, scan, reset }. " +
+      "Scanning is IMPERATIVE — call scan() from a user gesture (a tap); the browser and the mobile OS gate the camera " +
+      "permission prompt on a gesture, so it NEVER opens on mount. It resolves { value, format } for the FIRST code " +
+      "decoded, or NULL when the user dismisses the scanner — dismissal is the common case and is deliberately NOT an " +
+      "error, so no try/catch is needed on the happy path. It rejects with a BarcodeError whose .code is one of " +
+      "PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `value` is the decoded text; `format` is a lowercase symbology name " +
+      "(qr_code, code_128, ean_13, …) — treat it as a hint, not a promise, because the two hosts detect different sets. " +
+      "It is deliberately ONE-SHOT rather than a start/stop subscription: to scan several codes, call scan() again. " +
+      "reset() clears the last result and error. ALWAYS check `supported` before rendering a scan button and give the " +
+      "widget a manual-entry path — the web Player reports false wherever the browser has no BarcodeDetector (Safari and " +
+      "Firefox today), which is a real browser gap, not a missing feature. options: { formats } is a HINT narrowing the " +
+      "symbologies to look for. The Expo export scans via expo-camera; the web Player via BarcodeDetector over the same " +
+      "getUserMedia preview useCamera() uses. The camera is released on every exit path, including a dismissal.",
+    returnShape: {
+      result: "{ value, format } | null",
+      scanning: "boolean",
+      error: "BarcodeError | null",
+      supported:
+        "boolean  // GATE THE BUTTON ON THIS: false where the browser has no BarcodeDetector",
+      scan:
+        "() => Promise<{ value, format } | null>  // null if dismissed; rejects with BarcodeError",
+      reset: "() => void  // clear the last result + error",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   // sc-7193 — host-brokered image editing. Optional slice; the hook reports
   // supported:false rather than throwing at render.
   {
@@ -1846,6 +1878,17 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-7282 — the element marker. A FUNCTION primitive like pressableLift: it
+  // returns props to spread, so ONE declaration marks the element on both
+  // hosts. Inert on native (react-native drops `dataSet`), so it costs the
+  // device nothing.
+  {
+    name: "styleGroup",
+    description:
+      "Marks WHICH rendered element a styleSchema `ui.group` paints. Spread it on the element: `<View {...styleGroup(\"Card\")}>`. Pass the EXACT group name from your styleSchema `ui.group` — character for character, or the click resolves to nothing. The Widget Builder preview reads it to map a clicked element back to its group and show only that group's style fields. Mark the OUTERMOST element of each non-Basics group ONCE; never mark the \"Basics\" group (it paints the whole widget) and never mark a child of an already-marked element. On a list that repeats a marked element per row, mark EVERY row. It is a marker, not a style: it changes nothing about how the widget renders.",
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-6607 — the SCREEN-level overlay. Widgets could previously only paint an
   // overlay inside their own box, so a preview or dialog was clipped by the
   // layout container the widget sits in; this is the one primitive that leaves
@@ -2343,10 +2386,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "subscribeBackgroundWatchState(cb) -> unsubscribe }, " +
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
-      "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera() and useImageEditor(). The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview and a host-side canvas; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker and expo-image-manipulator. " +
+      "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
+      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor() and useBarcodeScanner(). The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas and BarcodeDetector; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator and expo-camera. " +
       "imageEditor.edit applies resize / crop / rotate / flip in order and rejects with an ImageEditorError " +
       "(.code UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | INTERNAL). " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
@@ -2354,6 +2398,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted). " +
       "camera.capture/pick resolve a normalised { uri, name, mimeType, width, height, size, file, release? } or NULL when the " +
       "user dismisses the picker, and reject with a CameraError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). " +
+      "barcode.scan resolves { value, format } for the first code decoded or NULL when the user dismisses, and rejects with a " +
+      "BarcodeError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). Its formats hint and its format output BOTH speak " +
+      "BarcodeDetector names (qr_code, code_128, ean_13, ...) on both hosts; the Expo export maps them to expo-camera own " +
+      "vocabulary internally and DROPS a name it cannot map. isSupported() is false wherever the browser ships no " +
+      "BarcodeDetector (Safari, Firefox), so a widget must always offer manual entry beside a scan button. " +
       "sc-6450 — the geolocation background-watch members are NATIVE-ONLY and opt-in per app: the web Player and an export that " +
       "did not opt in both report isBackgroundSupported() false, and the Expo export backs it with expo-location + " +
       "expo-task-manager. subscribeBackgroundPositions and subscribeBackgroundWatchState are plain subscriptions — they start no " +
@@ -2367,6 +2416,7 @@ const WIDGET_CONTEXT_SHAPE = {
       speech: "object",
       camera: "object",
       imageEditor: "object",
+      barcode: "object",
     },
   },
 };
@@ -3768,7 +3818,30 @@ const CONTRACT = deepFreeze({
   //    reason date-fns is: an AI-agent widget is transpiled, never bundled, so
   //    its bare import must resolve at runtime on both hosts. No existing entry
   //    changed shape — minor bump on the pre-1.0 channel.
-  version: "1.99.0",
+  // 1.100.0: additive (sc-7228) — new `useBarcodeScanner()` hook + a `barcode`
+  //    member on the optional `device` host slice. Widgets could GENERATE a QR
+  //    code (react-native-qrcode-svg) but never READ one, so inventory counts,
+  //    asset check-in/out, ticket scanning and scan-on-delivery were
+  //    unbuildable. Host-brokered rather than a vetted import, the same call as
+  //    `camera` and `speech`: widgets never import the native module, so
+  //    `expo-camera` stays out of widget bundles and is pinned in the export
+  //    only. One-shot scan() modelled on useCamera().capture() rather than a
+  //    start/stop subscription — no second streaming lifecycle to keep in step.
+  //    NOT native-only: the web half is BarcodeDetector over the getUserMedia
+  //    preview useCamera already owns, so this is full parity wherever the
+  //    browser ships the API and a declared `supported:false` where it does not
+  //    (Safari, Firefox) — a genuine browser gap per CLAUDE.md §8.
+  // 1.101.0: additive (sc-7282) — a new `styleGroup(name)` primitive marking
+  //    WHICH rendered element a styleSchema `ui.group` paints, so the Widget
+  //    Builder preview can map a clicked node back to its group and show only
+  //    that group's style fields instead of the whole schema. It returns props
+  //    to spread (`<View {...styleGroup("Card")}>`) and rides the existing
+  //    `dataSet` prop: react-native-web maps it to `data-*`, real react-native
+  //    drops it, so ONE module serves both hosts and the marker is inert on the
+  //    device — no §8 native-only case and no paired implementation. Purely a
+  //    marker: it changes nothing about how a widget renders. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.101.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1670,6 +1670,38 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-7228 — host-brokered barcode / QR scanning. Optional slice; the hook
+  // reports supported:false rather than throwing at render.
+  {
+    name: "useBarcodeScanner",
+    signature: "useBarcodeScanner(options?)",
+    description:
+      "Read a barcode or QR code with the device camera. Returns { result, scanning, error, supported, scan, reset }. " +
+      "Scanning is IMPERATIVE — call scan() from a user gesture (a tap); the browser and the mobile OS gate the camera " +
+      "permission prompt on a gesture, so it NEVER opens on mount. It resolves { value, format } for the FIRST code " +
+      "decoded, or NULL when the user dismisses the scanner — dismissal is the common case and is deliberately NOT an " +
+      "error, so no try/catch is needed on the happy path. It rejects with a BarcodeError whose .code is one of " +
+      "PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `value` is the decoded text; `format` is a lowercase symbology name " +
+      "(qr_code, code_128, ean_13, …) — treat it as a hint, not a promise, because the two hosts detect different sets. " +
+      "It is deliberately ONE-SHOT rather than a start/stop subscription: to scan several codes, call scan() again. " +
+      "reset() clears the last result and error. ALWAYS check `supported` before rendering a scan button and give the " +
+      "widget a manual-entry path — the web Player reports false wherever the browser has no BarcodeDetector (Safari and " +
+      "Firefox today), which is a real browser gap, not a missing feature. options: { formats } is a HINT narrowing the " +
+      "symbologies to look for. The Expo export scans via expo-camera; the web Player via BarcodeDetector over the same " +
+      "getUserMedia preview useCamera() uses. The camera is released on every exit path, including a dismissal.",
+    returnShape: {
+      result: "{ value, format } | null",
+      scanning: "boolean",
+      error: "BarcodeError | null",
+      supported:
+        "boolean  // GATE THE BUTTON ON THIS: false where the browser has no BarcodeDetector",
+      scan:
+        "() => Promise<{ value, format } | null>  // null if dismissed; rejects with BarcodeError",
+      reset: "() => void  // clear the last result + error",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   // sc-7193 — host-brokered image editing. Optional slice; the hook reports
   // supported:false rather than throwing at render.
   {
@@ -1846,6 +1878,17 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-7282 — the element marker. A FUNCTION primitive like pressableLift: it
+  // returns props to spread, so ONE declaration marks the element on both
+  // hosts. Inert on native (react-native drops `dataSet`), so it costs the
+  // device nothing.
+  {
+    name: "styleGroup",
+    description:
+      "Marks WHICH rendered element a styleSchema `ui.group` paints. Spread it on the element: `<View {...styleGroup(\"Card\")}>`. Pass the EXACT group name from your styleSchema `ui.group` — character for character, or the click resolves to nothing. The Widget Builder preview reads it to map a clicked element back to its group and show only that group's style fields. Mark the OUTERMOST element of each non-Basics group ONCE; never mark the \"Basics\" group (it paints the whole widget) and never mark a child of an already-marked element. On a list that repeats a marked element per row, mark EVERY row. It is a marker, not a style: it changes nothing about how the widget renders.",
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-6607 — the SCREEN-level overlay. Widgets could previously only paint an
   // overlay inside their own box, so a preview or dialog was clipped by the
   // layout container the widget sits in; this is the one primitive that leaves
@@ -2343,10 +2386,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "subscribeBackgroundWatchState(cb) -> unsubscribe }, " +
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
-      "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera() and useImageEditor(). The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview and a host-side canvas; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker and expo-image-manipulator. " +
+      "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
+      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor() and useBarcodeScanner(). The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas and BarcodeDetector; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator and expo-camera. " +
       "imageEditor.edit applies resize / crop / rotate / flip in order and rejects with an ImageEditorError " +
       "(.code UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | INTERNAL). " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
@@ -2354,6 +2398,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted). " +
       "camera.capture/pick resolve a normalised { uri, name, mimeType, width, height, size, file, release? } or NULL when the " +
       "user dismisses the picker, and reject with a CameraError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). " +
+      "barcode.scan resolves { value, format } for the first code decoded or NULL when the user dismisses, and rejects with a " +
+      "BarcodeError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). Its formats hint and its format output BOTH speak " +
+      "BarcodeDetector names (qr_code, code_128, ean_13, ...) on both hosts; the Expo export maps them to expo-camera own " +
+      "vocabulary internally and DROPS a name it cannot map. isSupported() is false wherever the browser ships no " +
+      "BarcodeDetector (Safari, Firefox), so a widget must always offer manual entry beside a scan button. " +
       "sc-6450 — the geolocation background-watch members are NATIVE-ONLY and opt-in per app: the web Player and an export that " +
       "did not opt in both report isBackgroundSupported() false, and the Expo export backs it with expo-location + " +
       "expo-task-manager. subscribeBackgroundPositions and subscribeBackgroundWatchState are plain subscriptions — they start no " +
@@ -2367,6 +2416,7 @@ const WIDGET_CONTEXT_SHAPE = {
       speech: "object",
       camera: "object",
       imageEditor: "object",
+      barcode: "object",
     },
   },
 };
@@ -3768,7 +3818,30 @@ const CONTRACT = deepFreeze({
   //    reason date-fns is: an AI-agent widget is transpiled, never bundled, so
   //    its bare import must resolve at runtime on both hosts. No existing entry
   //    changed shape — minor bump on the pre-1.0 channel.
-  version: "1.99.0",
+  // 1.100.0: additive (sc-7228) — new `useBarcodeScanner()` hook + a `barcode`
+  //    member on the optional `device` host slice. Widgets could GENERATE a QR
+  //    code (react-native-qrcode-svg) but never READ one, so inventory counts,
+  //    asset check-in/out, ticket scanning and scan-on-delivery were
+  //    unbuildable. Host-brokered rather than a vetted import, the same call as
+  //    `camera` and `speech`: widgets never import the native module, so
+  //    `expo-camera` stays out of widget bundles and is pinned in the export
+  //    only. One-shot scan() modelled on useCamera().capture() rather than a
+  //    start/stop subscription — no second streaming lifecycle to keep in step.
+  //    NOT native-only: the web half is BarcodeDetector over the getUserMedia
+  //    preview useCamera already owns, so this is full parity wherever the
+  //    browser ships the API and a declared `supported:false` where it does not
+  //    (Safari, Firefox) — a genuine browser gap per CLAUDE.md §8.
+  // 1.101.0: additive (sc-7282) — a new `styleGroup(name)` primitive marking
+  //    WHICH rendered element a styleSchema `ui.group` paints, so the Widget
+  //    Builder preview can map a clicked node back to its group and show only
+  //    that group's style fields instead of the whole schema. It returns props
+  //    to spread (`<View {...styleGroup("Card")}>`) and rides the existing
+  //    `dataSet` prop: react-native-web maps it to `data-*`, real react-native
+  //    drops it, so ONE module serves both hosts and the marker is inert on the
+  //    device — no §8 native-only case and no paired implementation. Purely a
+  //    marker: it changes nothing about how a widget renders. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.101.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1589,6 +1589,163 @@ export function useCamera(options) {
   return { asset, loading, error, supported, capture, pick, reset };
 }
 
+/**
+ * The symbology names the SDK speaks on BOTH hosts — BarcodeDetector's
+ * vocabulary. Normalising here is what stops the hosts diverging on bad
+ * input: the web detector THROWS on a name outside its enum while the native
+ * scanner silently ignores one, so an unknown name would reject on web and
+ * quietly scan everything on native.
+ */
+const BARCODE_FORMATS = Object.freeze([
+  "aztec",
+  "codabar",
+  "code_128",
+  "code_39",
+  "code_93",
+  "data_matrix",
+  "ean_13",
+  "ean_8",
+  "itf",
+  "pdf417",
+  "qr_code",
+  "upc_a",
+  "upc_e",
+]);
+
+/** Drop anything the hosts cannot both honour, so neither has to guess. */
+function normaliseBarcodeOptions(options) {
+  const opts = options || {};
+  if (!Array.isArray(opts.formats)) return opts;
+  const formats = opts.formats
+    .map((name) => String(name).toLowerCase())
+    .filter((name) => BARCODE_FORMATS.includes(name));
+  return { ...opts, formats };
+}
+
+/**
+ * Structured error thrown by `useBarcodeScanner` callbacks.
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED" — the user (or OS) refused camera access.
+ *   - "UNSUPPORTED"       — this host brokers no scanner (no BarcodeDetector).
+ *   - "INTERNAL"          — anything else.
+ *
+ * A user dismissing the scanner is NOT an error — the promise resolves `null`.
+ */
+export class BarcodeError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "BarcodeError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+/** Coerce a thrown value into a BarcodeError with a stable code. */
+function toBarcodeError(err) {
+  if (err instanceof BarcodeError) return err;
+  const raw = err && err.code !== undefined ? err.code : null;
+  let code = "INTERNAL";
+  if (raw === "PERMISSION_DENIED") code = "PERMISSION_DENIED";
+  else if (raw === "UNSUPPORTED") code = "UNSUPPORTED";
+  const message =
+    (err && typeof err.message === "string" && err.message) ||
+    "Barcode scan failed";
+  return new BarcodeError(code, message, { cause: err });
+}
+
+/**
+ * Read a barcode or QR code with the device camera. Returns
+ *   `{ result, scanning, error, supported, scan, reset }`.
+ *
+ * Scanning is IMPERATIVE — call `scan()` from a user gesture. The OS and the
+ * browser gate the camera permission prompt on a gesture, so the hook never
+ * opens the camera on mount.
+ *
+ * `scan()` resolves `{ value, format }` for the first code decoded, or `null`
+ * when the user dismisses the scanner — dismissal is the most common outcome
+ * and is deliberately not an error, so widgets need no try/catch on the happy
+ * path. It rejects with a `BarcodeError` for a genuine failure.
+ *
+ * One-shot by design: to read several codes, call `scan()` again. There is no
+ * start/stop subscription to leave running.
+ *
+ * ALWAYS check `supported` before rendering a scan button, and give the widget
+ * a manual-entry path: the web Player reports false wherever the browser ships
+ * no `BarcodeDetector` (Safari and Firefox today). That is a real browser gap,
+ * so a scanner must never be the only way to enter a code.
+ */
+export function useBarcodeScanner(options) {
+  const ctx = useWidgetContextOrThrow("useBarcodeScanner");
+  const [result, setResult] = useState(null);
+  const [scanning, setScanning] = useState(false);
+  const [error, setError] = useState(null);
+  // `ctx` is a fresh identity every host render — hold the live client and
+  // options in refs so the returned callbacks stay stable.
+  const clientRef = useRef(ctx.device && ctx.device.barcode);
+  clientRef.current = ctx.device && ctx.device.barcode;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const runRef = useRef(0);
+
+  const supported = Boolean(
+    clientRef.current &&
+      typeof clientRef.current.scan === "function" &&
+      (typeof clientRef.current.isSupported !== "function" ||
+        clientRef.current.isSupported()),
+  );
+
+  // A scan open at unmount still resolves; bumping the run id discards it
+  // instead of setting state on a widget that is gone.
+  useEffect(
+    () => () => {
+      runRef.current += 1;
+    },
+    [],
+  );
+
+  const reset = useCallback(() => {
+    runRef.current += 1;
+    setResult(null);
+    setError(null);
+  }, []);
+
+  const scan = useCallback(async () => {
+    const client = clientRef.current;
+    if (
+      !client ||
+      typeof client.scan !== "function" ||
+      (typeof client.isSupported === "function" && !client.isSupported())
+    ) {
+      const e = new BarcodeError(
+        "UNSUPPORTED",
+        "This host does not provide barcode scanning.",
+      );
+      setError(e);
+      throw e;
+    }
+    const run = (runRef.current += 1);
+    setScanning(true);
+    setError(null);
+    try {
+      const next = await client.scan(normaliseBarcodeOptions(optionsRef.current));
+      // A reset(), a newer scan, or an unmount landed while this one was open.
+      if (run !== runRef.current) return null;
+      if (!next) return null;
+      setResult(next);
+      return next;
+    } catch (err) {
+      const be = toBarcodeError(err);
+      if (run === runRef.current) setError(be);
+      throw be;
+    } finally {
+      if (run === runRef.current) setScanning(false);
+    }
+  }, []);
+
+  return { result, scanning, error, supported, scan, reset };
+}
+
 /**
  * Structured error thrown by `useImageEditor` callbacks.
  *

package/dist/index.d.ts

@@ -1746,6 +1746,68 @@ export class ImageEditorError extends Error {
   );
 }
 
+/** A code decoded by `useBarcodeScanner().scan()`. */
+export interface BarcodeScan {
+  /** The decoded text. */
+  value: string;
+  /**
+   * Lowercase symbology name (`qr_code`, `code_128`, `ean_13`, …). A HINT, not
+   * a promise: the two hosts detect different sets, so never branch on it for
+   * correctness.
+   */
+  format: string;
+}
+
+/** Options for `useBarcodeScanner(...)`. */
+export interface BarcodeScannerOptions {
+  /** Narrow which symbologies to look for. A hint the host honours where it can. */
+  formats?: string[];
+}
+
+export interface BarcodeScannerResult {
+  /** The most recent scan, or null before the first call / after reset. */
+  result: BarcodeScan | null;
+  scanning: boolean;
+  error: BarcodeError | null;
+  /**
+   * False where the host brokers no scanner — notably any browser without
+   * `BarcodeDetector` (Safari, Firefox). GATE THE SCAN BUTTON ON THIS.
+   */
+  supported: boolean;
+  /** Resolves the first code decoded, or null if the user dismisses. */
+  scan(): Promise<BarcodeScan | null>;
+  /** Clear `result` and `error`. */
+  reset(): void;
+}
+
+/**
+ * Read a barcode or QR code with the device camera. Imperative — call `scan()`
+ * from a user gesture; the OS and the browser gate the camera prompt on one, so
+ * it never opens on mount. One-shot by design: to read several codes, call
+ * `scan()` again rather than leaving a subscription running.
+ *
+ * The Expo export scans via `expo-camera`; the web Player via `BarcodeDetector`
+ * over the same `getUserMedia` preview `useCamera()` uses. Where the browser
+ * ships no `BarcodeDetector` this is a genuine platform gap (CLAUDE.md §8), so
+ * `supported` is false and the widget must offer manual entry instead.
+ */
+export function useBarcodeScanner(
+  options?: BarcodeScannerOptions,
+): BarcodeScannerResult;
+
+/**
+ * Error surfaced by `useBarcodeScanner()` — thrown by `scan()` and stored in
+ * the hook's `error` slot. A dismissal is not an error; `scan()` resolves null.
+ */
+export class BarcodeError extends Error {
+  code: "PERMISSION_DENIED" | "UNSUPPORTED" | "INTERNAL";
+  constructor(
+    code: BarcodeError["code"],
+    message: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * Error class thrown by useDatastoreMutation callbacks (and surfaced by
  * useDatastoreQuery in its `error` slot). The `code` is a stable
@@ -2617,3 +2679,15 @@ export function pressableLift(state?: {
   hovered?: boolean;
   pressed?: boolean;
 }): Array<Record<string, unknown> | null>;
+
+/**
+ * sc-7282 — marks WHICH rendered element a styleSchema `ui.group` paints, so
+ * the Widget Builder preview can show only that group's style fields when the
+ * element is clicked. Spread it: `<View {...styleGroup("Card")}>`.
+ *
+ * `name` must be the EXACT `ui.group` string. A missing or blank name returns
+ * `undefined`, so spreading the result is always safe.
+ */
+export function styleGroup(
+  name: string,
+): { dataSet: Record<string, string> } | undefined;

package/dist/index.js

@@ -84,6 +84,8 @@ export {
   CameraError,
   useImageEditor,
   ImageEditorError,
+  useBarcodeScanner,
+  BarcodeError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
@@ -153,3 +155,4 @@ export {
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";
 export { pressableLift } from "./interaction.js";
+export { styleGroup } from "./style-group.js";

package/dist/index.native.js

@@ -84,6 +84,8 @@ export {
   CameraError,
   useImageEditor,
   ImageEditorError,
+  useBarcodeScanner,
+  BarcodeError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
@@ -147,3 +149,4 @@ export {
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";
 export { pressableLift } from "./interaction.native.js";
+export { styleGroup } from "./style-group.js";

package/dist/style-group.js

@@ -0,0 +1,33 @@
+// sc-7282 — marks WHICH rendered element a styleSchema `ui.group` paints, so
+// the Widget Builder preview can map a clicked node back to its group and show
+// only that group's style fields.
+//
+// ONE file, no `.native.js` twin: `react-native-web` maps `dataSet` to `data-*`
+// attributes while real react-native drops the prop, so the marker is inert on
+// the device rather than a second implementation (CLAUDE.md §3). The paired
+// modules in this package (interaction.js, overlay.js) exist because their
+// behaviour genuinely differs per host; this one's does not.
+//
+// Not a primitive wrapper either — primitives.js re-exports react-native-web
+// directly, and its header records that the hand-written paired wrappers were
+// removed on purpose.
+
+/** The `dataSet` key, surfacing in the DOM as `data-style-group`. */
+export const STYLE_GROUP_DATA_KEY = "styleGroup";
+
+/**
+ * Props marking the element a style group paints. Spread it:
+ * `<View {...styleGroup("Card")}>`.
+ *
+ * `name` must be the EXACT `ui.group` string from the widget's styleSchema — a
+ * mismatch marks an element no group owns, and the click resolves to nothing.
+ *
+ * Returns `undefined` for a missing or blank name so `{...styleGroup(x)}` stays
+ * safe when `x` is absent: spreading `undefined` is a no-op in JSX.
+ */
+export function styleGroup(name) {
+  if (typeof name !== "string") return undefined;
+  const trimmed = name.trim();
+  if (!trimmed) return undefined;
+  return { dataSet: { [STYLE_GROUP_DATA_KEY]: trimmed } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.128.0",
+  "version": "0.130.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
   },
   "engines": {
     "node": ">=18"