@colixsystems/widget-sdk 0.127.0 → 0.129.0

package/README.md

@@ -70,7 +70,37 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.127.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.129.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.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)
+
+**New linter rule `flex-basis-percent` — a percentage `flexBasis` sizes the HEIGHT in a column (sc-7274).** A generated form carried one shared field helper, `style={{ flexGrow: 1, flexBasis: wide ? "100%" : 220 }}`, used both as a row cell (where the number is exactly right) and as a full-width field stacked in a column (where the percentage is a trap). `flex-basis` sizes the **main** axis, and a column's main axis is the **height**: each wide field was asking for its parent's entire height. It rendered correctly in the builder canvas — an auto-height ancestor leaves the percentage indefinite, so it degrades to `content` — and broke the moment the page shipped, because a Grid cell stretches its child on the web Player and made that height definite. Measured on the published page: the group was 633px tall and every wide field inside it was **also** 633px, so with `View`'s default `flex-shrink: 0` they could not shrink back and overflowed 633px and 1266px down, painting a blank band mid-form and three fields on top of the section below and the submit row.
+
+- **`flex-basis-percent` (severity `warning`, non-blocking).** A literal percentage `flexBasis` — `"100%"`, `"50%"`, and the responsive ternary `flexBasis: stacked ? "100%" : CARD_WIDE` — is flagged. Author fix: **`width: "100%"`**, which is the direction-agnostic way to say "full width": it fills the row in a column parent AND takes its own line in a wrap row, so nothing is lost by switching. Keep a **number** (`flexBasis: 220`) where you mean a wrap threshold. It is a **warning**, not an error, because in a ROW parent the percentage IS correct and an AST-free scan cannot see the parent's `flexDirection` — the offending style usually lives in a shared cell helper far from its parent. Scope is the literal inline form; a basis threaded through a variable is beyond the scan, and the designer skill's form guidance remains the first guard. Comments are not scanned, so documenting the anti-pattern is safe.
 
 ### What's new in 0.127.0 (contract 1.99.0)
 
@@ -1336,7 +1366,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
 - **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces above ~720px measured width** (`flexDirection: width >= 720 ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget.
-- **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them.
+- **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **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).
@@ -1598,6 +1628,8 @@ Two rules keep a widget's look reachable from the Studio (sc-6455). `no-hardcode
 
 Pass `--manifest` to enable `style-field-unread` — it needs the manifest, and it needs every source at once so a split-impl widget's per-host field reads are seen together.
 
+`flex-basis-percent` flags a literal percentage `flexBasis` (sc-7274) — `"100%"`, `"50%"`, or the ternary a responsive cell writes. `flex-basis` sizes the MAIN axis, so in a column parent it asks for the parent's HEIGHT: under an ancestor that makes that height definite (a Grid cell stretches its child on the web Player) the child fills the container and, since a `View` never shrinks, overflows over everything below it. Say full-width with `width: "100%"` — correct in a column AND in a wrap row — and keep a NUMBER for a wrap threshold. A warning, because the percentage is right in a row and a text scan cannot see the parent.
+
 `no-html-in-content` flags an HTML tag inside a **string** (sc-6970) — `"<strong>"`, `"<br>"`, `"<p>…</p>"`. There is no HTML renderer on either host, so the tag reaches the reader as literal text; author formatted text with `<MarkdownInput>` and render it with `<RichText>` instead. Only string and template content is scanned, so your own `<View>` / `<Text>` JSX can never trip it. A warning for a human author, blocking for the AI widget agent.
 
 ## Local dev loop (`appstudio-widget dev`)

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.
   {
@@ -2343,10 +2375,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 +2387,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 +2405,7 @@ const WIDGET_CONTEXT_SHAPE = {
       speech: "object",
       camera: "object",
       imageEditor: "object",
+      barcode: "object",
     },
   },
 };
@@ -3768,7 +3807,20 @@ 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.
+  version: "1.100.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.
   {
@@ -2343,10 +2375,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 +2387,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 +2405,7 @@ const WIDGET_CONTEXT_SHAPE = {
       speech: "object",
       camera: "object",
       imageEditor: "object",
+      barcode: "object",
     },
   },
 };
@@ -3768,7 +3807,20 @@ 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.
+  version: "1.100.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

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";

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";

package/dist/linter.cjs

@@ -1201,6 +1201,37 @@ function _imagePercentHeightRules(source) {
   return findings;
 }
 
+// sc-7274 — a percentage `flexBasis` sizes the MAIN axis, which in a column is
+// the HEIGHT: under a definite-height parent (a Grid cell stretches its child
+// on the web Player) the child fills the container and, with `flex-shrink: 0`,
+// overflows over the content below. `width: "100%"` is the direction-agnostic
+// replacement. Mirror of linter.js (see there for the full rationale).
+const _FLEX_BASIS_PERCENT_RE =
+  /\bflexBasis\s*:[^,}\n]*?(["'])\s*(\d+(?:\.\d+)?)\s*%\s*\1/g;
+
+function _flexBasisPercentRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  _FLEX_BASIS_PERCENT_RE.lastIndex = 0;
+  let hit;
+  while ((hit = _FLEX_BASIS_PERCENT_RE.exec(code))) {
+    const line = code.slice(0, hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "flex-basis-percent",
+      severity: "warning",
+      label:
+        `flexBasis "${hit[2]}%" sizes the MAIN axis — in a column that is the ` +
+        `HEIGHT, so under a definite-height parent it fills the container and ` +
+        `overflows below. Use width: "100%"; a NUMBER (flexBasis: 220) is a ` +
+        `wrap threshold.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding, so cells sized
 // from it overflow the content box and the last one wraps into an empty column.
 // Mirror of linter.js (see there for the full rationale).
@@ -1491,6 +1522,9 @@ function lintSource(source, options) {
   findings.push(..._lucideIconRules(source));
   findings.push(..._selfContainedReferenceRules(source));
   findings.push(..._imagePercentHeightRules(source));
+  // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
+  // column it claims the parent's whole height and overflows.
+  findings.push(..._flexBasisPercentRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/linter.js

@@ -1226,6 +1226,61 @@ function _imagePercentHeightRules(source) {
   return findings;
 }
 
+// sc-7274 — a percentage `flexBasis` sizes the MAIN axis, and in a column that
+// is the HEIGHT.
+//
+// `flexBasis: "100%"` written to mean "full width" is only that in a ROW. In a
+// column parent it asks for the parent's whole HEIGHT, and the moment an
+// ancestor makes that height definite — a Grid cell stretches its child on the
+// web Player — every such sibling becomes as tall as the container. `View`
+// defaults to `flex-shrink: 0`, so they cannot shrink back: they overflow
+// hundreds of pixels down over whatever follows. That shipped a customer form
+// with a blank band mid-layout and three fields painted across the submit row,
+// visible only once published (the builder canvas leaves the height auto,
+// where the percentage degrades to `content` and the form looks right).
+//
+// `width: "100%"` is the direction-agnostic replacement — it fills the row in a
+// column parent AND takes its own line in a wrap row — so a percentage basis is
+// never the only way to say it.
+//
+// `severity: "warning"`, like `image-percent-height`: in a row parent the value
+// IS correct, and an AST-free scan cannot see the parent's `flexDirection`
+// (the style usually lives in a shared field/cell helper). A warning still
+// drives an AI-agent repair turn, which is the point of the rule.
+//
+// Scope is the literal inline form, including the ternary a responsive cell
+// writes (`flexBasis: stacked ? "100%" : CARD`). A basis threaded through a
+// variable stays beyond the scan; the designer skill remains the first guard.
+const _FLEX_BASIS_PERCENT_RE =
+  /\bflexBasis\s*:[^,}\n]*?(["'])\s*(\d+(?:\.\d+)?)\s*%\s*\1/g;
+
+function _flexBasisPercentRules(source) {
+  const findings = [];
+  // Comments blanked, strings kept: the value under test IS a string literal,
+  // so this rule's own documentation must not flag itself.
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  _FLEX_BASIS_PERCENT_RE.lastIndex = 0;
+  let hit;
+  while ((hit = _FLEX_BASIS_PERCENT_RE.exec(code))) {
+    const line = code.slice(0, hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "flex-basis-percent",
+      severity: "warning",
+      // Kept under FINDING_LABEL_BUDGET: the repair turn truncates the whole
+      // message at 300 chars, which would otherwise eat the fix and the line.
+      label:
+        `flexBasis "${hit[2]}%" sizes the MAIN axis — in a column that is the ` +
+        `HEIGHT, so under a definite-height parent it fills the container and ` +
+        `overflows below. Use width: "100%"; a NUMBER (flexBasis: 220) is a ` +
+        `wrap threshold.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding.
 //
 // `onLayout` reports the frame width, and padding sits inside that frame. A
@@ -1543,6 +1598,9 @@ export function lintSource(source, options) {
   findings.push(..._selfContainedReferenceRules(source));
   // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
   findings.push(..._imagePercentHeightRules(source));
+  // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
+  // column it claims the parent's whole height and overflows.
+  findings.push(..._flexBasisPercentRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.127.0",
+  "version": "0.129.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-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"
   },
   "engines": {
     "node": ">=18"