@colixsystems/widget-sdk 0.112.0 → 0.113.0

package/README.md

@@ -37,6 +37,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
 | **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
 | **CORE** | `useSpeechToText(options?)` | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
+| **CORE** | `useCamera(options?)` | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (file input) and the Expo export (`expo-image-picker`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
@@ -71,6 +72,25 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.112.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.113.0 (contract 1.86.0)
+
+**New `useCamera()` hook — take a photo or pick one from the device library.** A new CORE hook reading a new `camera` capability on the existing `ctx.device` slice. Returns `{ asset, loading, error, supported, capture, pick, reset }`. Capture is **imperative** — call `capture()` or `pick()` from a user gesture (a `Pressable.onPress`); the browser and the mobile OS gate the permission prompt on a gesture, so it NEVER opens on mount. `options` (`{ allowsEditing, quality }`) pass through to the host. It needs **no manifest scope** and **no `requestedScopes` entry**.
+
+**Dismissing the picker resolves `null`, not an error.** Backing out is the most common outcome, so it is deliberately not a rejection — your happy path needs no `try/catch`. A genuine failure (permission refused, no host broker) rejects with a structured `CameraError` (new named export) carrying a stable `.code` (`PERMISSION_DENIED` / `UNSUPPORTED` / `INTERNAL`).
+
+**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a `File` on web, a `{ uri, name, type }` triple on native. So the same three lines work everywhere:
+
+```js
+const fd = new FormData();
+fd.append("file", asset.file);
+await ctx.assets.upload(fd);
+```
+
+`options` (`{ allowsEditing, quality }`) are **hints**: the Expo export applies both, the web file input applies neither — so never depend on a cropped result or a capped file size. `reset()` clears the asset and releases it (on web that revokes the blob URL, which otherwise leaks for the life of the document). **Gate your camera button on `supported`** — a host that brokers no camera reports `false` rather than throwing. The web Player brokers it via a file input (`capture="environment"` opens the camera on a phone); the Expo export via `expo-image-picker`, whose config plugin declares the camera and photo-library permissions the runtime needs.
+
+Additive — one new hook, one new optional context-slice member; no existing export changed signature.
+
+
 ### What's new in 0.112.0 (contract unchanged at 1.85.0)
 
 **Two linter rules make the styling contract checkable, and `lintStyleWiring` joins the linter export (sc-6455).** Every visual value a widget writes reaches the app's owner through one of exactly two channels — a **theme token** (`useTheme()`), which is the app-wide default and follows a look change, or a **`styleSchema` field** read off `props.style`, which the Studio offers per instance in the widget editor *and* app-wide under **Design → Widget appearance**. A literal reaches neither: it outranks the theme permanently and no control on either surface can move it, so the owner finds a corner of their app they cannot restyle. Until now that rule was documentation only.

package/dist/contract.cjs

@@ -1576,6 +1576,37 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-6448 — host-brokered camera capture / photo picking. Optional slice;
+  // the hook reports supported:false rather than throwing at render.
+  {
+    name: "useCamera",
+    signature: "useCamera(options?)",
+    description:
+      "Take a photo or choose one from the device library. Returns { asset, loading, error, supported, capture, pick, reset }. " +
+      "Capture is IMPERATIVE — call capture() or pick() from a user gesture (a tap); the browser and the mobile OS gate the " +
+      "permission prompt on a gesture, so it NEVER opens on mount. Both resolve to a normalised asset " +
+      "{ uri, name, mimeType, width, height, size, file }, or NULL when the user dismisses the picker — dismissal is the " +
+      "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
+      "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
+      "upload part for the host (a File on web, { uri, name, type } on native): append it to a FormData as `file` and pass " +
+      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
+      "can — the Expo export applies both, the web file input applies neither, so never depend on a capped file size or a " +
+      "cropped result. Behaviour is otherwise identical on web (file input) and the Expo export (expo-image-picker).",
+    returnShape: {
+      asset:
+        "{ uri, name, mimeType, width, height, size, file } | null",
+      loading: "boolean",
+      error: "CameraError | null",
+      supported: "boolean  // false when the host brokers no camera",
+      capture:
+        "() => Promise<asset | null>  // null if dismissed; rejects with CameraError",
+      pick: "() => Promise<asset | null>  // null if dismissed; rejects with CameraError",
+      reset: "() => void  // clear the asset + error and release it",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -2168,14 +2199,18 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Optional host-brokered device capabilities. " +
       "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
-      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> } }. " +
-      "Backs useGeolocation() and useSpeechToText(). The web Player brokers them via navigator.geolocation and " +
-      "window.SpeechRecognition; the Expo export via expo-location and expo-speech-recognition. " +
+      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
+      "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> } }. " +
+      "Backs useGeolocation(), useSpeechToText() and useCamera(). The web Player brokers them via navigator.geolocation, " +
+      "window.SpeechRecognition and a file input; the Expo export via expo-location, expo-speech-recognition and " +
+      "expo-image-picker. " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
       "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
-      "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted).",
+      "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).",
     required: false,
-    fields: { geolocation: "object", speech: "object" },
+    fields: { geolocation: "object", speech: "object", camera: "object" },
   },
 };
 
@@ -3386,7 +3421,19 @@ const CONTRACT = deepFreeze({
   //    byte-identically. `mapSpacing` pushes each side through the responsive
   //    and theme scaling the scalar already got; `isZeroSpacing` lets each box
   //    property keep its own zero policy.
-  version: "1.85.0",
+  //
+  // 1.86.0: additive (sc-6448) — new `useCamera()` hook + a `camera` member on
+  //    the optional `device` host slice. Takes a photo or picks one from the
+  //    library, resolving a normalised asset whose `file` is already the right
+  //    upload part for the host (a File on web, `{ uri, name, type }` on
+  //    native), so one code path feeds `ctx.assets.upload`. Host-brokered
+  //    rather than a vetted import — the same reasoning as `speech`: widgets
+  //    never import the native module, so it stays out of widget bundles.
+  //    This supersedes the `expo-camera` deferral in
+  //    docs/design/req-widget-sdk-cross-platform-primitives.md, which was
+  //    about vetting a full camera surface (permissions, multi-step UX, frame
+  //    processing) as a widget import — none of which this adds.
+  version: "1.86.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1576,6 +1576,37 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-6448 — host-brokered camera capture / photo picking. Optional slice;
+  // the hook reports supported:false rather than throwing at render.
+  {
+    name: "useCamera",
+    signature: "useCamera(options?)",
+    description:
+      "Take a photo or choose one from the device library. Returns { asset, loading, error, supported, capture, pick, reset }. " +
+      "Capture is IMPERATIVE — call capture() or pick() from a user gesture (a tap); the browser and the mobile OS gate the " +
+      "permission prompt on a gesture, so it NEVER opens on mount. Both resolve to a normalised asset " +
+      "{ uri, name, mimeType, width, height, size, file }, or NULL when the user dismisses the picker — dismissal is the " +
+      "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
+      "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
+      "upload part for the host (a File on web, { uri, name, type } on native): append it to a FormData as `file` and pass " +
+      "that to ctx.assets.upload(fd) — one code path on both platforms. reset() clears the asset and releases it. Check " +
+      "`supported` before rendering a camera button. options: { allowsEditing, quality } are HINTS the host honours where it " +
+      "can — the Expo export applies both, the web file input applies neither, so never depend on a capped file size or a " +
+      "cropped result. Behaviour is otherwise identical on web (file input) and the Expo export (expo-image-picker).",
+    returnShape: {
+      asset:
+        "{ uri, name, mimeType, width, height, size, file } | null",
+      loading: "boolean",
+      error: "CameraError | null",
+      supported: "boolean  // false when the host brokers no camera",
+      capture:
+        "() => Promise<asset | null>  // null if dismissed; rejects with CameraError",
+      pick: "() => Promise<asset | null>  // null if dismissed; rejects with CameraError",
+      reset: "() => void  // clear the asset + error and release it",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -2168,14 +2199,18 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Optional host-brokered device capabilities. " +
       "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
-      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> } }. " +
-      "Backs useGeolocation() and useSpeechToText(). The web Player brokers them via navigator.geolocation and " +
-      "window.SpeechRecognition; the Expo export via expo-location and expo-speech-recognition. " +
+      "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
+      "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> } }. " +
+      "Backs useGeolocation(), useSpeechToText() and useCamera(). The web Player brokers them via navigator.geolocation, " +
+      "window.SpeechRecognition and a file input; the Expo export via expo-location, expo-speech-recognition and " +
+      "expo-image-picker. " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
       "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
-      "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted).",
+      "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).",
     required: false,
-    fields: { geolocation: "object", speech: "object" },
+    fields: { geolocation: "object", speech: "object", camera: "object" },
   },
 };
 
@@ -3386,7 +3421,19 @@ const CONTRACT = deepFreeze({
   //    byte-identically. `mapSpacing` pushes each side through the responsive
   //    and theme scaling the scalar already got; `isZeroSpacing` lets each box
   //    property keep its own zero policy.
-  version: "1.85.0",
+  //
+  // 1.86.0: additive (sc-6448) — new `useCamera()` hook + a `camera` member on
+  //    the optional `device` host slice. Takes a photo or picks one from the
+  //    library, resolving a normalised asset whose `file` is already the right
+  //    upload part for the host (a File on web, `{ uri, name, type }` on
+  //    native), so one code path feeds `ctx.assets.upload`. Host-brokered
+  //    rather than a vetted import — the same reasoning as `speech`: widgets
+  //    never import the native module, so it stays out of widget bundles.
+  //    This supersedes the `expo-camera` deferral in
+  //    docs/design/req-widget-sdk-cross-platform-primitives.md, which was
+  //    about vetting a full camera surface (permissions, multi-step UX, frame
+  //    processing) as a widget import — none of which this adds.
+  version: "1.86.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1297,6 +1297,159 @@ export function useSpeechToText(options) {
   };
 }
 
+/**
+ * Structured error thrown by `useCamera` callbacks.
+ *
+ * `code` is one of:
+ *   - "PERMISSION_DENIED" — the user (or OS) refused camera / library access.
+ *   - "UNSUPPORTED"       — this host does not broker the camera.
+ *   - "INTERNAL"          — anything else.
+ *
+ * A user dismissing the picker is NOT an error — the promise resolves `null`.
+ */
+export class CameraError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "CameraError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+/** Coerce a thrown value into a CameraError with a stable code. */
+function toCameraError(err) {
+  if (err instanceof CameraError) 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) ||
+    "Camera request failed";
+  return new CameraError(code, message, { cause: err });
+}
+
+/**
+ * Take a photo or choose one from the device library. Returns
+ *   `{ asset, loading, error, supported, capture, pick, reset }`.
+ *
+ * Capture is IMPERATIVE — call `capture()` / `pick()` from a user gesture. The
+ * OS and the browser gate the permission prompt on a gesture, so the hook never
+ * opens the camera on mount.
+ *
+ * Both resolve to a normalised asset, or `null` when the user dismisses the
+ * picker — dismissal is the most common outcome and is deliberately not an
+ * error, so widgets need no try/catch on the happy path. They reject with a
+ * `CameraError` for a genuine failure (permission refused, no host broker).
+ *
+ * The asset's `file` is already the right shape to upload on either host — a
+ * `File` on web, a `{ uri, name, type }` part on native — so one code path
+ * covers both:
+ *
+ *     const fd = new FormData();
+ *     fd.append("file", asset.file);
+ *     await ctx.assets.upload(fd);
+ *
+ * Check `supported` before rendering a camera button; a host with no broker
+ * reports false rather than throwing at render.
+ */
+export function useCamera(options) {
+  const ctx = useWidgetContextOrThrow("useCamera");
+  const [asset, setAsset] = useState(null);
+  const [loading, setLoading] = 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.camera);
+  clientRef.current = ctx.device && ctx.device.camera;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  // Web hands back a blob: URL per asset; abandoning it leaks the blob for the
+  // life of the document, so the hook owns revoking the one it replaced.
+  const releaseRef = useRef(null);
+  const runRef = useRef(0);
+
+  const supported = Boolean(
+    clientRef.current &&
+      typeof clientRef.current.capture === "function" &&
+      (typeof clientRef.current.isSupported !== "function" ||
+        clientRef.current.isSupported()),
+  );
+
+  const release = useCallback(() => {
+    const revoke = releaseRef.current;
+    releaseRef.current = null;
+    if (typeof revoke === "function") {
+      try {
+        revoke();
+      } catch {
+        /* the host already released it */
+      }
+    }
+  }, []);
+
+  useEffect(() => () => release(), [release]);
+
+  const reset = useCallback(() => {
+    runRef.current += 1;
+    release();
+    setAsset(null);
+    setError(null);
+  }, [release]);
+
+  // capture() and pick() differ only in which broker method they call, so both
+  // run through one request path — otherwise the loading/abort bookkeeping
+  // would exist twice and drift.
+  const request = useCallback(
+    async (method) => {
+      const client = clientRef.current;
+      if (
+        !client ||
+        typeof client[method] !== "function" ||
+        (typeof client.isSupported === "function" && !client.isSupported())
+      ) {
+        const e = new CameraError(
+          "UNSUPPORTED",
+          "This host does not provide camera access.",
+        );
+        setError(e);
+        throw e;
+      }
+      const run = (runRef.current += 1);
+      setLoading(true);
+      setError(null);
+      try {
+        const next = await client[method](optionsRef.current || {});
+        // A reset() or a newer request landed while this one was open — drop
+        // the result rather than clobbering what the widget now shows.
+        if (run !== runRef.current) {
+          if (next && typeof next.release === "function") next.release();
+          return null;
+        }
+        if (!next) return null;
+        release();
+        releaseRef.current =
+          typeof next.release === "function" ? next.release : null;
+        setAsset(next);
+        return next;
+      } catch (err) {
+        const ce = toCameraError(err);
+        if (run === runRef.current) setError(ce);
+        throw ce;
+      } finally {
+        if (run === runRef.current) setLoading(false);
+      }
+    },
+    [release],
+  );
+
+  const capture = useCallback(() => request("capture"), [request]);
+  const pick = useCallback(() => request("pick"), [request]);
+
+  return { asset, loading, error, supported, capture, pick, reset };
+}
+
 /* ============================================================================
  * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
  *

package/dist/index.d.ts

@@ -1538,6 +1538,75 @@ export class SpeechToTextError extends Error {
   );
 }
 
+/**
+ * Options for `useCamera(...)`. Both are HINTS the host honours where it can:
+ * the Expo export applies them, the web file input applies neither — so never
+ * depend on a cropped result or a capped file size.
+ */
+export interface CameraOptions {
+  /** Let the user crop/rotate before returning. Native only. Defaults to false. */
+  allowsEditing?: boolean;
+  /** 0–1 compression quality. Native only. Defaults to 0.8. */
+  quality?: number;
+}
+
+/** A photo taken or picked through `useCamera()`, normalised across hosts. */
+export interface CameraAsset {
+  /** Displayable source — `<Image source={{ uri }} />` / `<img src>`. */
+  uri: string;
+  /** File name, derived from the source when the host supplies none. */
+  name: string;
+  mimeType: string;
+  width: number | null;
+  height: number | null;
+  /** Bytes, when the host reports it. */
+  size: number | null;
+  /**
+   * Ready-to-upload part — a `File` on web, `{ uri, name, type }` on native.
+   * Append it to a FormData and hand that to `ctx.assets.upload(...)`.
+   */
+  file: unknown;
+}
+
+export interface CameraResult {
+  /** The most recent asset, or null before the first capture / after reset. */
+  asset: CameraAsset | null;
+  loading: boolean;
+  error: CameraError | null;
+  /** False when the host brokers no camera. */
+  supported: boolean;
+  /** Open the camera. Resolves null if the user dismisses it. */
+  capture(): Promise<CameraAsset | null>;
+  /** Open the photo library. Resolves null if the user dismisses it. */
+  pick(): Promise<CameraAsset | null>;
+  /** Clear `asset` and `error`, releasing the held asset. */
+  reset(): void;
+}
+
+/**
+ * Take a photo or choose one from the device library. Capture is imperative
+ * (call `capture()` / `pick()` from a user gesture; it never opens on mount).
+ * The same hook drives both platforms — the web Player brokers it via a file
+ * input, the Expo export via `expo-image-picker`. Dismissing the picker
+ * resolves `null` rather than rejecting; a genuine failure rejects with a
+ * `CameraError`. Safe to call on a host that brokers no camera: `supported` is
+ * then false, so gate the camera button on it.
+ */
+export function useCamera(options?: CameraOptions): CameraResult;
+
+/**
+ * Error surfaced by `useCamera()` — thrown by `capture()` / `pick()` and stored
+ * in the hook's `error` slot. `code` is a stable categorisation.
+ */
+export class CameraError extends Error {
+  code: "PERMISSION_DENIED" | "UNSUPPORTED" | "INTERNAL";
+  constructor(
+    code: CameraError["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

@@ -80,6 +80,8 @@ export {
   GeolocationError,
   useSpeechToText,
   SpeechToTextError,
+  useCamera,
+  CameraError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";

package/dist/index.native.js

@@ -80,6 +80,8 @@ export {
   GeolocationError,
   useSpeechToText,
   SpeechToTextError,
+  useCamera,
+  CameraError,
   WidgetTree,
 } from "./hooks.js";
 export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,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__/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__/toast-host.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-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.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-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__/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__/toast-host.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-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js"
   },
   "engines": {
     "node": ">=18"