@colixsystems/widget-sdk 0.125.0 → 0.127.0

package/README.md

@@ -70,7 +70,45 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.125.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.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**.
+
+### What's new in 0.127.0 (contract 1.99.0)
+
+**Widgets can do maths now — five pure-JS packages join the vetted import allowlist (sc-7191).** The list had 31 entries and exactly one non-UI utility (`date-fns`), so anything numeric a widget needed had to be hand-rolled in a sibling file. Two gaps in particular:
+
+- `decimal.js` — exact decimal arithmetic. The platform has payments, invoicing and VAT, and a total accumulated in IEEE-754 floats drifts from what the backend actually charged. `new Decimal(a).plus(b).toFixed(2)` does not.
+- `d3-scale` + `d3-shape` + `d3-array` — the scale, path-generator and domain maths a bespoke chart needs. `d3-shape` emits path strings you hand straight to the already-vetted `react-native-svg`'s `<Path d={…} />`, so a custom line/area/donut chart is ONE source file that renders identically in the Player and the Expo export.
+- `simple-statistics` — mean/median/quantile/regression/correlation, for summarising a datastore table without shipping a maths framework.
+
+All five are `platforms: ["web", "native"]` with no native module, so this is **full parity**, not a §8 native-only case. Each is host-shimmed in the Player and pinned in the export for the same reason `date-fns` is: an AI-agent widget is transpiled rather than bundled, so its bare import has to resolve at runtime on both hosts.
+
+`mathjs` was considered and deliberately left off — 9.4 MB unpacked with nine transitive dependencies, and a web-vetted package is bundled into the Studio.
+
+Additive: no existing entry, hook, primitive or `propertySchema` type changed shape. `CONTRACT.version` → `1.99.0`.
+
+### What's new in 0.126.0 (contract 1.98.0)
+
+**A widget can edit an image now, not just take one — new `useImageEditor()` (sc-7193).** `useCamera()` (0.121.0) let a widget capture a photo and `ctx.assets.upload` let it send one, but nothing could *change* one: no resize before upload, no crop to an aspect ratio, no straightening a sideways shot. A profile-picture widget had to upload the full-resolution original and hope the server-side normaliser did something acceptable.
+
+```js
+const { capture } = useCamera();
+const { edit } = useImageEditor();
+
+const shot = await capture();
+const small = await edit(shot.uri, [{ resize: { width: 800 } }], { format: "jpeg", compress: 0.8 });
+
+const fd = new FormData();
+fd.append("file", small.file);
+await ctx.assets.upload(fd);
+```
+
+`edit(uri, actions, options?)` applies `actions` in order and resolves the SAME normalised asset shape `useCamera()` yields, so capture → edit → upload is one code path on both hosts. Actions are `{ resize: { width?, height? } }`, `{ crop: { originX, originY, width, height } }`, `{ rotate: degrees }` and `{ flip: "horizontal" | "vertical" }`; output is `{ format: "jpeg" | "png" | "webp", compress, base64? }`.
+
+**Host-brokered, not a vetted import** — the same call `expo-image-picker` and `expo-speech-recognition` already got. Widgets reach it through the hook and never import the package, so it stays out of every widget bundle and parity is the SDK's problem rather than each author's. The web Player brokers it on a canvas *inside the host* (your widget never touches the DOM); the Expo export uses `expo-image-manipulator`.
+
+There is deliberately **no `extent` action**. It exists only on web in `expo-image-manipulator`, and a capability the Player has but the export does not is the direction CLAUDE.md §8 forbids.
+
+The `device.imageEditor` slice is OPTIONAL, so a host that brokers nothing degrades the hook to `supported: false` rather than throwing — gate your edit control on it. Additive: no existing hook, primitive, manifest field or `propertySchema` type changed. `CONTRACT.version` → `1.98.0`.
 
 ### What's new in 0.125.0 (contract 1.97.0)
 

package/dist/contract.cjs

@@ -1670,6 +1670,38 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-7193 — host-brokered image editing. Optional slice; the hook reports
+  // supported:false rather than throwing at render.
+  {
+    name: "useImageEditor",
+    signature: "useImageEditor()",
+    description:
+      "Resize, crop, rotate or flip an image. Returns { result, editing, error, supported, edit, reset }. " +
+      "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
+      "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
+      "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
+      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
+      "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
+      "{ flip: \"horizontal\" | \"vertical\" }. options: { format: \"jpeg\" | \"png\" | \"webp\" (default jpeg), " +
+      "compress: 0..1 (default 0.8, ignored for png), base64: boolean (off by default — it is expensive) }. " +
+      "Rejects with an ImageEditorError whose .code is one of UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | " +
+      "INTERNAL. There is deliberately NO `extent` action: it exists only on web, and a web-only capability is the direction " +
+      "CLAUDE.md §8 forbids. Check `supported` before rendering an edit control. Identical on web (a canvas in the host, so " +
+      "the widget never touches the DOM) and the Expo export (expo-image-manipulator).",
+    returnShape: {
+      result:
+        "{ uri, name, mimeType, width, height, size, base64?, file } | null",
+      editing: "boolean",
+      error: "ImageEditorError | null",
+      supported: "boolean  // false when the host brokers no image editor",
+      edit:
+        "(uri, actions, options?) => Promise<result | null>  // rejects with ImageEditorError",
+      reset: "() => void  // clear the result + error and release it",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -2310,10 +2342,13 @@ const WIDGET_CONTEXT_SHAPE = {
       "isBackgroundWatching() -> boolean, subscribeBackgroundPositions(cb) -> unsubscribe, " +
       "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> } }. " +
-      "Backs useGeolocation(), useSpeechToText() and useCamera(). The web Player brokers them via navigator.geolocation, " +
-      "window.SpeechRecognition and a getUserMedia camera preview; the Expo export via expo-location, expo-speech-recognition and " +
-      "expo-image-picker. " +
+      "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.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). " +
       "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). " +
@@ -2327,7 +2362,12 @@ const WIDGET_CONTEXT_SHAPE = {
       "foreground service), and a sibling widget may start or stop it — so subscribeBackgroundWatchState is how every mounted " +
       "widget stays truthful, and isBackgroundWatching() is only the synchronous first read.",
     required: false,
-    fields: { geolocation: "object", speech: "object", camera: "object" },
+    fields: {
+      geolocation: "object",
+      speech: "object",
+      camera: "object",
+      imageEditor: "object",
+    },
   },
 };
 
@@ -2637,6 +2677,41 @@ const VETTED_IMPORTS = [
     description:
       "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx and pair it with a widget.web.jsx reading window.DeviceMotionEvent (accelerationIncludingGravity / rotationRate), the browser API the same hardware exposes. Both hosts need a user gesture before readings start, and iOS Safari additionally needs an explicit DeviceMotionEvent.requestPermission() grant — so gate the reading behind a Pressable, never start it on mount.",
   },
+  {
+    specifier: "decimal.js",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Arbitrary-precision decimal arithmetic. Reach for it whenever a widget computes MONEY: JavaScript numbers are binary floats, so a price total, a VAT line or a discount accumulated in `+`/`*` drifts by fractions of a cent and disagrees with what the backend charged. `new Decimal(a).plus(b).toFixed(2)` does not. Pure JS with zero dependencies, identical on both platforms. Not for general maths — it is slower than a number and only earns its cost where exactness is the point.",
+  },
+  {
+    specifier: "d3-scale",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Maps data values to pixel positions — `scaleLinear`, `scaleTime`, `scaleBand`, `scaleOrdinal`, plus the `.ticks()` an axis is labelled from. The maths half of a custom chart; pair it with d3-shape for the path and react-native-svg to draw. Pure JS (its only deps are other d3 modules), so one implementation covers both platforms.",
+  },
+  {
+    specifier: "d3-shape",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a bespoke line/area/donut chart renders identically in the Player and the Expo export from ONE source file. Pure JS.",
+  },
+  {
+    specifier: "d3-array",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Array statistics and binning — `extent`, `min`/`max`, `bisect`, `bin`, `group`, `rollup`. Chiefly how you compute the domain d3-scale expects from a dataset. Pure JS.",
+  },
+  {
+    specifier: "simple-statistics",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Descriptive statistics and simple models — mean/median/mode, standard deviation, quantiles, linear regression, correlation. Small and pure JS, so a widget can summarise a datastore table without shipping a maths framework. For exact decimal arithmetic (money) use decimal.js instead: this operates on JS numbers.",
+  },
 ];
 
 // sc-1064: CORE React infrastructure specifiers the host RESOLVES at runtime
@@ -3667,7 +3742,33 @@ const CONTRACT = deepFreeze({
   //    tell apart. A host now branches on `menuType` alone; a stored
   //    `navigation.topBarMenuStyle` is inert rather than migrated, so a
   //    `top-bar` app that never chose `tabs` moves to the tab row.
-  version: "1.97.0",
+  // 1.98.0: additive (sc-7193) — new `useImageEditor()` hook + the optional
+  //    `device.imageEditor` host slice it reads. A widget could take a photo
+  //    (useCamera) and upload one, but not CHANGE one: no resize before
+  //    upload, no crop to an aspect ratio, no straightening a sideways shot.
+  //    Host-brokered rather than a vetted import, the same call expo-image-picker
+  //    and expo-speech-recognition already got — the package stays out of every
+  //    widget bundle and parity is the SDK's problem, not each author's. The web
+  //    Player brokers it on a host-side canvas (the widget never touches the
+  //    DOM), the Expo export via expo-image-manipulator; both implement the same
+  //    four actions and the same three output formats. `extent` is deliberately
+  //    absent — it is web-only in expo-image-manipulator, and a web-only
+  //    capability is the direction §8 forbids. The slice is OPTIONAL, so a host
+  //    that brokers nothing degrades the hook to supported:false rather than
+  //    throwing. Minor bump on the pre-1.0 channel.
+  // 1.99.0: additive (sc-7191) — the vetted import allowlist gains five PURE-JS
+  //    packages, the first non-UI maths available to a widget: `decimal.js`
+  //    (exact decimal arithmetic — the platform has payments, invoicing and
+  //    VAT, and float money math disagrees with what the backend charged),
+  //    `d3-scale` + `d3-shape` + `d3-array` (the scale/path/domain maths a
+  //    bespoke chart needs, drawn through the already-vetted react-native-svg),
+  //    and `simple-statistics`. All five are `["web", "native"]` with no native
+  //    module, so this is full parity, not a §8 native-only case. Each is
+  //    host-shimmed in widgetLoader.js and pinned in the export for the same
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1670,6 +1670,38 @@ const HOOKS = [
     requiredContextSlice: [],
     scopes: null,
   },
+  // sc-7193 — host-brokered image editing. Optional slice; the hook reports
+  // supported:false rather than throwing at render.
+  {
+    name: "useImageEditor",
+    signature: "useImageEditor()",
+    description:
+      "Resize, crop, rotate or flip an image. Returns { result, editing, error, supported, edit, reset }. " +
+      "Editing is IMPERATIVE — call edit() from an event handler, never during render. " +
+      "edit(uri, actions, options?) applies `actions` IN ORDER and resolves the SAME normalised asset shape useCamera() " +
+      "yields — { uri, name, mimeType, width, height, size, base64?, file } — so capture -> edit -> upload is ONE code path: " +
+      "append result.file to a FormData as `file` and pass it to ctx.assets.upload(fd). " +
+      "Each action entry carries exactly one of { resize: { width?, height? } } (aspect preserved when only one is given), " +
+      "{ crop: { originX, originY, width, height } }, { rotate: degrees } (positive is clockwise), or " +
+      "{ flip: \"horizontal\" | \"vertical\" }. options: { format: \"jpeg\" | \"png\" | \"webp\" (default jpeg), " +
+      "compress: 0..1 (default 0.8, ignored for png), base64: boolean (off by default — it is expensive) }. " +
+      "Rejects with an ImageEditorError whose .code is one of UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | " +
+      "INTERNAL. There is deliberately NO `extent` action: it exists only on web, and a web-only capability is the direction " +
+      "CLAUDE.md §8 forbids. Check `supported` before rendering an edit control. Identical on web (a canvas in the host, so " +
+      "the widget never touches the DOM) and the Expo export (expo-image-manipulator).",
+    returnShape: {
+      result:
+        "{ uri, name, mimeType, width, height, size, base64?, file } | null",
+      editing: "boolean",
+      error: "ImageEditorError | null",
+      supported: "boolean  // false when the host brokers no image editor",
+      edit:
+        "(uri, actions, options?) => Promise<result | null>  // rejects with ImageEditorError",
+      reset: "() => void  // clear the result + error and release it",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
 ];
 
 // REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
@@ -2310,10 +2342,13 @@ const WIDGET_CONTEXT_SHAPE = {
       "isBackgroundWatching() -> boolean, subscribeBackgroundPositions(cb) -> unsubscribe, " +
       "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> } }. " +
-      "Backs useGeolocation(), useSpeechToText() and useCamera(). The web Player brokers them via navigator.geolocation, " +
-      "window.SpeechRecognition and a getUserMedia camera preview; the Expo export via expo-location, expo-speech-recognition and " +
-      "expo-image-picker. " +
+      "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.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). " +
       "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). " +
@@ -2327,7 +2362,12 @@ const WIDGET_CONTEXT_SHAPE = {
       "foreground service), and a sibling widget may start or stop it — so subscribeBackgroundWatchState is how every mounted " +
       "widget stays truthful, and isBackgroundWatching() is only the synchronous first read.",
     required: false,
-    fields: { geolocation: "object", speech: "object", camera: "object" },
+    fields: {
+      geolocation: "object",
+      speech: "object",
+      camera: "object",
+      imageEditor: "object",
+    },
   },
 };
 
@@ -2637,6 +2677,41 @@ const VETTED_IMPORTS = [
     description:
       "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx and pair it with a widget.web.jsx reading window.DeviceMotionEvent (accelerationIncludingGravity / rotationRate), the browser API the same hardware exposes. Both hosts need a user gesture before readings start, and iOS Safari additionally needs an explicit DeviceMotionEvent.requestPermission() grant — so gate the reading behind a Pressable, never start it on mount.",
   },
+  {
+    specifier: "decimal.js",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Arbitrary-precision decimal arithmetic. Reach for it whenever a widget computes MONEY: JavaScript numbers are binary floats, so a price total, a VAT line or a discount accumulated in `+`/`*` drifts by fractions of a cent and disagrees with what the backend charged. `new Decimal(a).plus(b).toFixed(2)` does not. Pure JS with zero dependencies, identical on both platforms. Not for general maths — it is slower than a number and only earns its cost where exactness is the point.",
+  },
+  {
+    specifier: "d3-scale",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Maps data values to pixel positions — `scaleLinear`, `scaleTime`, `scaleBand`, `scaleOrdinal`, plus the `.ticks()` an axis is labelled from. The maths half of a custom chart; pair it with d3-shape for the path and react-native-svg to draw. Pure JS (its only deps are other d3 modules), so one implementation covers both platforms.",
+  },
+  {
+    specifier: "d3-shape",
+    platforms: ["web", "native"],
+    category: "drawing",
+    description:
+      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a bespoke line/area/donut chart renders identically in the Player and the Expo export from ONE source file. Pure JS.",
+  },
+  {
+    specifier: "d3-array",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Array statistics and binning — `extent`, `min`/`max`, `bisect`, `bin`, `group`, `rollup`. Chiefly how you compute the domain d3-scale expects from a dataset. Pure JS.",
+  },
+  {
+    specifier: "simple-statistics",
+    platforms: ["web", "native"],
+    category: "utility",
+    description:
+      "Descriptive statistics and simple models — mean/median/mode, standard deviation, quantiles, linear regression, correlation. Small and pure JS, so a widget can summarise a datastore table without shipping a maths framework. For exact decimal arithmetic (money) use decimal.js instead: this operates on JS numbers.",
+  },
 ];
 
 // sc-1064: CORE React infrastructure specifiers the host RESOLVES at runtime
@@ -3667,7 +3742,33 @@ const CONTRACT = deepFreeze({
   //    tell apart. A host now branches on `menuType` alone; a stored
   //    `navigation.topBarMenuStyle` is inert rather than migrated, so a
   //    `top-bar` app that never chose `tabs` moves to the tab row.
-  version: "1.97.0",
+  // 1.98.0: additive (sc-7193) — new `useImageEditor()` hook + the optional
+  //    `device.imageEditor` host slice it reads. A widget could take a photo
+  //    (useCamera) and upload one, but not CHANGE one: no resize before
+  //    upload, no crop to an aspect ratio, no straightening a sideways shot.
+  //    Host-brokered rather than a vetted import, the same call expo-image-picker
+  //    and expo-speech-recognition already got — the package stays out of every
+  //    widget bundle and parity is the SDK's problem, not each author's. The web
+  //    Player brokers it on a host-side canvas (the widget never touches the
+  //    DOM), the Expo export via expo-image-manipulator; both implement the same
+  //    four actions and the same three output formats. `extent` is deliberately
+  //    absent — it is web-only in expo-image-manipulator, and a web-only
+  //    capability is the direction §8 forbids. The slice is OPTIONAL, so a host
+  //    that brokers nothing degrades the hook to supported:false rather than
+  //    throwing. Minor bump on the pre-1.0 channel.
+  // 1.99.0: additive (sc-7191) — the vetted import allowlist gains five PURE-JS
+  //    packages, the first non-UI maths available to a widget: `decimal.js`
+  //    (exact decimal arithmetic — the platform has payments, invoicing and
+  //    VAT, and float money math disagrees with what the backend charged),
+  //    `d3-scale` + `d3-shape` + `d3-array` (the scale/path/domain maths a
+  //    bespoke chart needs, drawn through the already-vetted react-native-svg),
+  //    and `simple-statistics`. All five are `["web", "native"]` with no native
+  //    module, so this is full parity, not a §8 native-only case. Each is
+  //    host-shimmed in widgetLoader.js and pinned in the export for the same
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/dev-shims.js

@@ -117,6 +117,14 @@ const HOST_EXTERNAL_SPECIFIERS = [
   // bundle shares one RN-web (StyleSheet/context) instead of inlining a second
   // copy. On native, Metro resolves the real react-native in the export.
   "react-native",
+  // sc-7191: the vetted pure-JS maths set. Externalised for the same reason as
+  // date-fns — an AI-agent widget is transpiled, never bundled, so the host
+  // must resolve the bare import at runtime.
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
 ];
 
 /**

package/dist/hooks.js

@@ -1589,6 +1589,173 @@ export function useCamera(options) {
   return { asset, loading, error, supported, capture, pick, reset };
 }
 
+/**
+ * Structured error thrown by `useImageEditor` callbacks.
+ *
+ * `code` is one of:
+ *   - "UNSUPPORTED"     — this host brokers no image editor.
+ *   - "INVALID_ACTION"  — an action or output option the contract doesn't define.
+ *   - "DECODE_FAILED"   — the source could not be read as an image.
+ *   - "ENCODE_FAILED"   — the host could not write the requested output format.
+ *   - "INTERNAL"        — anything else.
+ */
+export class ImageEditorError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "ImageEditorError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+/** Coerce a thrown value into an ImageEditorError with a stable code. */
+function toImageEditorError(err) {
+  if (err instanceof ImageEditorError) return err;
+  const raw = err && err.code !== undefined ? err.code : null;
+  const known = [
+    "UNSUPPORTED",
+    "INVALID_ACTION",
+    "DECODE_FAILED",
+    "ENCODE_FAILED",
+  ];
+  const code = known.includes(raw) ? raw : "INTERNAL";
+  const message =
+    (err && typeof err.message === "string" && err.message) ||
+    "Image edit failed";
+  return new ImageEditorError(code, message, { cause: err });
+}
+
+/**
+ * Resize, crop, rotate or flip an image. Returns
+ *   `{ result, editing, error, supported, edit, reset }`.
+ *
+ * Editing is IMPERATIVE — call `edit()` from an event handler, never during
+ * render. It resolves the SAME normalised asset shape `useCamera()` yields, so
+ * capture → edit → upload is one code path on both hosts:
+ *
+ *     const { asset, capture } = useCamera();
+ *     const { edit } = useImageEditor();
+ *     const shot = await capture();
+ *     const small = await edit(shot.uri, [{ resize: { width: 800 } }]);
+ *     const fd = new FormData();
+ *     fd.append("file", small.file);
+ *     await ctx.assets.upload(fd);
+ *
+ * `actions` is an ordered array applied in sequence; each entry carries exactly
+ * one of:
+ *   - `{ resize: { width?, height? } }`  — aspect preserved when one is given
+ *   - `{ crop: { originX, originY, width, height } }`
+ *   - `{ rotate: degrees }`              — positive is clockwise
+ *   - `{ flip: "horizontal" | "vertical" }`
+ *
+ * `options` is `{ format: "jpeg" | "png" | "webp", compress: 0..1, base64? }`.
+ * There is deliberately NO `extent` action: it exists only on web, and a
+ * web-only capability is the direction CLAUDE.md §8 forbids.
+ *
+ * Check `supported` before rendering an edit control; a host with no broker
+ * reports false rather than throwing at render.
+ */
+export function useImageEditor() {
+  const ctx = useWidgetContextOrThrow("useImageEditor");
+  const [result, setResult] = useState(null);
+  const [editing, setEditing] = useState(false);
+  const [error, setError] = useState(null);
+
+  // `ctx` is a fresh identity every host render — hold the live client in a ref
+  // so the returned callbacks stay stable.
+  const clientRef = useRef(ctx.device && ctx.device.imageEditor);
+  clientRef.current = ctx.device && ctx.device.imageEditor;
+  // Web hands back a blob: URL per result; 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.edit === "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();
+    setResult(null);
+    setError(null);
+  }, [release]);
+
+  const edit = useCallback(
+    async (uri, actions, options) => {
+      const client = clientRef.current;
+      if (
+        !client ||
+        typeof client.edit !== "function" ||
+        (typeof client.isSupported === "function" && !client.isSupported())
+      ) {
+        const e = new ImageEditorError(
+          "UNSUPPORTED",
+          "This host does not provide image editing.",
+        );
+        setError(e);
+        throw e;
+      }
+      if (typeof uri !== "string" || uri === "") {
+        const e = new ImageEditorError(
+          "INVALID_ACTION",
+          "edit(uri, actions) needs a source uri.",
+        );
+        setError(e);
+        throw e;
+      }
+      const run = (runRef.current += 1);
+      setEditing(true);
+      setError(null);
+      try {
+        const next = await client.edit(
+          uri,
+          Array.isArray(actions) ? actions : [],
+          options || {},
+        );
+        // A reset() or a newer edit landed while this one was running — 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;
+        setResult(next);
+        return next;
+      } catch (err) {
+        const ie = toImageEditorError(err);
+        if (run === runRef.current) setError(ie);
+        throw ie;
+      } finally {
+        if (run === runRef.current) setEditing(false);
+      }
+    },
+    [release],
+  );
+
+  return { result, editing, error, supported, edit, reset };
+}
+
 /* ============================================================================
  * DATASTORE CLIENT — ctx.datastore (@colixsystems/datastore-client)
  *

package/dist/index.d.ts

@@ -1666,6 +1666,86 @@ export class CameraError extends Error {
   );
 }
 
+/** One edit step. Exactly one key per entry; the array applies in order. */
+export type ImageEditAction =
+  | { resize: { width?: number; height?: number } }
+  | { crop: { originX: number; originY: number; width: number; height: number } }
+  | { rotate: number }
+  | { flip: "horizontal" | "vertical" };
+
+/** Output settings for `useImageEditor().edit(...)`. */
+export interface ImageEditOptions {
+  /** Encoding of the result. Defaults to "jpeg". */
+  format?: "jpeg" | "png" | "webp";
+  /** 0–1 quality for the lossy formats. Defaults to 0.8. Ignored for png. */
+  compress?: number;
+  /** Also return the bytes as base64. Off by default — it is expensive. */
+  base64?: boolean;
+}
+
+/**
+ * An edited image, normalised across hosts. Structurally the same shape
+ * `useCamera()` yields, so capture → edit → upload is one code path.
+ */
+export interface EditedImage {
+  uri: string;
+  name: string;
+  mimeType: string;
+  width: number | null;
+  height: number | null;
+  size: number | null;
+  /** Present only when `base64` was requested. */
+  base64?: string;
+  /** Ready-to-upload part — a `File` on web, `{ uri, name, type }` on native. */
+  file: unknown;
+}
+
+export interface ImageEditorResult {
+  /** The most recent edit, or null before the first call / after reset. */
+  result: EditedImage | null;
+  editing: boolean;
+  error: ImageEditorError | null;
+  /** False when the host brokers no image editor. */
+  supported: boolean;
+  /** Apply `actions` in order and encode per `options`. */
+  edit(
+    uri: string,
+    actions: ImageEditAction[],
+    options?: ImageEditOptions,
+  ): Promise<EditedImage | null>;
+  /** Clear `result` and `error`, releasing the held image. */
+  reset(): void;
+}
+
+/**
+ * Resize, crop, rotate or flip an image. Imperative — call `edit()` from an
+ * event handler, never during render. The web Player brokers it on a canvas,
+ * the Expo export via `expo-image-manipulator`; both implement the same four
+ * actions and the same output formats. There is deliberately no `extent`
+ * action — it exists only on web, and a web-only capability is the direction
+ * CLAUDE.md §8 forbids. Safe to call on a host that brokers no editor:
+ * `supported` is then false, so gate the control on it.
+ */
+export function useImageEditor(): ImageEditorResult;
+
+/**
+ * Error surfaced by `useImageEditor()` — thrown by `edit()` and stored in the
+ * hook's `error` slot. `code` is a stable categorisation.
+ */
+export class ImageEditorError extends Error {
+  code:
+    | "UNSUPPORTED"
+    | "INVALID_ACTION"
+    | "DECODE_FAILED"
+    | "ENCODE_FAILED"
+    | "INTERNAL";
+  constructor(
+    code: ImageEditorError["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

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

package/dist/index.native.js

@@ -82,6 +82,8 @@ export {
   SpeechToTextError,
   useCamera,
   CameraError,
+  useImageEditor,
+  ImageEditorError,
   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.125.0",
+  "version": "0.127.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-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-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"
   },
   "engines": {
     "node": ">=18"

package/src/dev-shims.js

@@ -117,6 +117,14 @@ const HOST_EXTERNAL_SPECIFIERS = [
   // bundle shares one RN-web (StyleSheet/context) instead of inlining a second
   // copy. On native, Metro resolves the real react-native in the export.
   "react-native",
+  // sc-7191: the vetted pure-JS maths set. Externalised for the same reason as
+  // date-fns — an AI-agent widget is transpiled, never bundled, so the host
+  // must resolve the bare import at runtime.
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
 ];
 
 /**