@colixsystems/widget-sdk 0.124.0 → 0.126.0

package/README.md

@@ -70,7 +70,43 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.124.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.126.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.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)
+
+**A `top-bar` app no longer chooses which row carries its menu — `CONTRACT.themeTopBarMenuStyles` is REMOVED and `normaliseNavigation` returns `menuType` alone (sc-7044).** 0.120.0 gave the shape two menu rows to pick between: `links`, the row of text links beside the brand it had always drawn, and `tabs`, a dedicated tab row beneath the bar. `links` turned out to be the site-mode header's own row — literally the same `header` nav variant, sitting in the Studio beside "Show a header on site-mode pages" and its "Menu links" toggle, so an author was offered three adjacent settings that render the same thing. The tab row is the one that reads as an app's global navigation, so it is now the only one.
+
+A host branches on `menuType` alone:
+
+- `CONTRACT.themeTopBarMenuStyles` is gone, and so is the `ThemeTopBarMenuStyle` type. `ResolvedNavigation` is `{ menuType }`.
+- `resolveTopBarTokens` is UNCHANGED — the whole `topBar` tab vocabulary (`tabStyle`, `contentSurface`, `tabIndicatorWidth`, `tabCornerRadius`, `tabPaddingX` / `tabPaddingY`, `tabBackgroundColor`, `tabActiveBackgroundColor`) now applies to every `top-bar` app rather than only to one that opted into tabs.
+- A stored `navigation.topBarMenuStyle` is **inert**, not migrated. Nothing reads it, so no backfill runs; a `top-bar` app that never chose `tabs` renders the tab row from this version on.
+
+**BREAKING, host-integration surface only** — a host that destructured `topBarMenuStyle` must stop. Nothing a widget author imports moved: no hook, primitive, manifest field or `propertySchema` type changed. `CONTRACT.version` → `1.97.0`.
 
 ### What's new in 0.124.0 (contract 1.96.0)
 

package/dist/contract.cjs

@@ -216,7 +216,7 @@ const THEME_MENU_TYPES = Object.freeze({
   "top-bar": Object.freeze({
     name: "Top bar",
     summary:
-      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+      "A tab row beneath the app header at every width -- icon and label per page, scrolling sideways when it runs out of room. No rail at any width.",
     maxItems: null,
     quickBarMaxItems: null,
   }),
@@ -228,18 +228,6 @@ const THEME_MENU_TYPES = Object.freeze({
     quickBarMaxItems: null,
   }),
 });
-const THEME_TOP_BAR_MENU_STYLES = Object.freeze({
-  links: Object.freeze({
-    name: "Links",
-    summary:
-      "Text links beside the brand, dropping to their own row only when a phone leaves them no space.",
-  }),
-  tabs: Object.freeze({
-    name: "Tabs",
-    summary:
-      "A dedicated tab row under the bar at every width -- icon and label per page, marked by the brand, scrolling sideways when it runs out of room.",
-  }),
-});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -1682,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
@@ -2322,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). " +
@@ -2339,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",
+    },
   },
 };
 
@@ -3671,7 +3699,29 @@ const CONTRACT = deepFreeze({
   //    privacy remains the record ACL's job. Existing `literal` and
   //    `relativeDate` conditions are untouched -- minor bump on the pre-1.0
   //    channel.
-  version: "1.96.0",
+  // 1.97.0: BREAKING (sc-7044) -- `themeTopBarMenuStyles` is REMOVED and
+  //    `normaliseNavigation` no longer returns `topBarMenuStyle`. A `top-bar`
+  //    app has ONE menu shape: the tab row beneath the bar. The `links` style
+  //    drew the menu on the same row-of-text-links the site-mode header draws,
+  //    so the Studio offered three adjacent settings that an author could not
+  //    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.
+  // 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.
+  version: "1.98.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3688,7 +3738,6 @@ const CONTRACT = deepFreeze({
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
-  themeTopBarMenuStyles: THEME_TOP_BAR_MENU_STYLES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/contract.js

@@ -216,7 +216,7 @@ const THEME_MENU_TYPES = Object.freeze({
   "top-bar": Object.freeze({
     name: "Top bar",
     summary:
-      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+      "A tab row beneath the app header at every width -- icon and label per page, scrolling sideways when it runs out of room. No rail at any width.",
     maxItems: null,
     quickBarMaxItems: null,
   }),
@@ -228,18 +228,6 @@ const THEME_MENU_TYPES = Object.freeze({
     quickBarMaxItems: null,
   }),
 });
-const THEME_TOP_BAR_MENU_STYLES = Object.freeze({
-  links: Object.freeze({
-    name: "Links",
-    summary:
-      "Text links beside the brand, dropping to their own row only when a phone leaves them no space.",
-  }),
-  tabs: Object.freeze({
-    name: "Tabs",
-    summary:
-      "A dedicated tab row under the bar at every width -- icon and label per page, marked by the brand, scrolling sideways when it runs out of room.",
-  }),
-});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -1682,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
@@ -2322,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). " +
@@ -2339,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",
+    },
   },
 };
 
@@ -3671,7 +3699,29 @@ const CONTRACT = deepFreeze({
   //    privacy remains the record ACL's job. Existing `literal` and
   //    `relativeDate` conditions are untouched -- minor bump on the pre-1.0
   //    channel.
-  version: "1.96.0",
+  // 1.97.0: BREAKING (sc-7044) -- `themeTopBarMenuStyles` is REMOVED and
+  //    `normaliseNavigation` no longer returns `topBarMenuStyle`. A `top-bar`
+  //    app has ONE menu shape: the tab row beneath the bar. The `links` style
+  //    drew the menu on the same row-of-text-links the site-mode header draws,
+  //    so the Studio offered three adjacent settings that an author could not
+  //    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.
+  // 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.
+  version: "1.98.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3688,7 +3738,6 @@ const CONTRACT = deepFreeze({
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
-  themeTopBarMenuStyles: THEME_TOP_BAR_MENU_STYLES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

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/host.d.ts

@@ -155,14 +155,8 @@ export function createToastController(
 
 export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
 
-// How a `top-bar` app draws its menu — closed by
-// `CONTRACT.themeTopBarMenuStyles`. Meaningless on the other two shapes, where
-// the resolver always reports "links".
-export type ThemeTopBarMenuStyle = "links" | "tabs";
-
 export interface ResolvedNavigation {
   menuType: ThemeMenuType;
-  topBarMenuStyle: ThemeTopBarMenuStyle;
 }
 
 /**

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/dist/navigation.cjs

@@ -30,9 +30,6 @@ const { CONTRACT, isHexColor } = require("./contract.cjs");
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
-// Today's row of text links, so an app that never made the choice draws exactly
-// what it drew before it existed.
-const DEFAULT_TOP_BAR_MENU_STYLE = "links";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -45,8 +42,7 @@ function isPlainObject(value) {
  * yields the default sidebar rather than something a host has to guard against.
  *
  * @param {unknown} navigation — the raw `theme_config.navigation` value.
- * @returns {{ menuType: string, topBarMenuStyle: string }} the resolved
- *   navigation structure.
+ * @returns {{ menuType: string }} the resolved navigation structure.
  */
 function normaliseNavigation(navigation) {
   const block = isPlainObject(navigation) ? navigation : {};
@@ -55,16 +51,11 @@ function normaliseNavigation(navigation) {
     typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
       ? raw
       : DEFAULT_MENU_TYPE;
-  const rawStyle = block.topBarMenuStyle;
-  // Resolved to `links` for every shape but `top-bar`, so a host reading it can
-  // never act on a value the app's own chrome has no row to draw.
-  const topBarMenuStyle =
-    menuType === "top-bar" &&
-    typeof rawStyle === "string" &&
-    Object.hasOwn(CONTRACT.themeTopBarMenuStyles, rawStyle)
-      ? rawStyle
-      : DEFAULT_TOP_BAR_MENU_STYLE;
-  return { menuType, topBarMenuStyle };
+  // sc-7044: the SHAPE is the whole answer. A `top-bar` app used to also choose
+  // which row carried its menu, and the `links` option drew the site header's
+  // own row of text links — a second way to say the same thing. The tab row is
+  // the only shape now, so a stored `topBarMenuStyle` is read by nobody.
+  return { menuType };
 }
 
 /**
@@ -339,8 +330,8 @@ function resolveTopBarTokens(theme) {
     // `underline` keeps the tab in the bar's surface and marks it with an
     // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
     // surface and sits over the row's divider, so the tab and the page beneath
-    // read as one plane. Meaningless under the `links` style, which draws no
-    // tabs — a host reads it only where it has tabs to draw.
+    // read as one plane. Meaningless on a shape that draws no tab row — a host
+    // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
     // The surface an `attached` tab AND its content panel share. One value for
     // both, so the join cannot come apart: whatever the current tab is painted,
@@ -369,8 +360,8 @@ function resolveTopBarTokens(theme) {
     tabPaddingX: tabSpaceOr(topBar.tabPaddingX, DEFAULT_TAB_PADDING_X),
     tabPaddingY: tabSpaceOr(topBar.tabPaddingY, DEFAULT_TAB_PADDING_Y),
     // A tab's own surface, authored or nothing. Null means the tab paints none
-    // and the bar shows through it, which is what both styles did before the
-    // keys existed — so an app that never set them is unchanged.
+    // and the bar shows through it, which is what the row did before the keys
+    // existed — so an app that never set them is unchanged.
     tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
     // Only meaningful where the style draws no panel: under `attached` the
     // active surface IS `contentSurface` above. Null under `underline` leaves

package/dist/navigation.js

@@ -21,9 +21,6 @@ import { CONTRACT, isHexColor } from "./contract.js";
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
-// Today's row of text links, so an app that never made the choice draws exactly
-// what it drew before it existed.
-const DEFAULT_TOP_BAR_MENU_STYLE = "links";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -36,8 +33,7 @@ function isPlainObject(value) {
  * yields the default sidebar rather than something a host has to guard against.
  *
  * @param {unknown} navigation — the raw `theme_config.navigation` value.
- * @returns {{ menuType: string, topBarMenuStyle: string }} the resolved
- *   navigation structure.
+ * @returns {{ menuType: string }} the resolved navigation structure.
  */
 export function normaliseNavigation(navigation) {
   const block = isPlainObject(navigation) ? navigation : {};
@@ -46,16 +42,11 @@ export function normaliseNavigation(navigation) {
     typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
       ? raw
       : DEFAULT_MENU_TYPE;
-  const rawStyle = block.topBarMenuStyle;
-  // Resolved to `links` for every shape but `top-bar`, so a host reading it can
-  // never act on a value the app's own chrome has no row to draw.
-  const topBarMenuStyle =
-    menuType === "top-bar" &&
-    typeof rawStyle === "string" &&
-    Object.hasOwn(CONTRACT.themeTopBarMenuStyles, rawStyle)
-      ? rawStyle
-      : DEFAULT_TOP_BAR_MENU_STYLE;
-  return { menuType, topBarMenuStyle };
+  // sc-7044: the SHAPE is the whole answer. A `top-bar` app used to also choose
+  // which row carried its menu, and the `links` option drew the site header's
+  // own row of text links — a second way to say the same thing. The tab row is
+  // the only shape now, so a stored `topBarMenuStyle` is read by nobody.
+  return { menuType };
 }
 
 /**
@@ -330,8 +321,8 @@ export function resolveTopBarTokens(theme) {
     // `underline` keeps the tab in the bar's surface and marks it with an
     // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
     // surface and sits over the row's divider, so the tab and the page beneath
-    // read as one plane. Meaningless under the `links` style, which draws no
-    // tabs — a host reads it only where it has tabs to draw.
+    // read as one plane. Meaningless on a shape that draws no tab row — a host
+    // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
     // The surface an `attached` tab AND its content panel share. One value for
     // both, so the join cannot come apart: whatever the current tab is painted,
@@ -360,8 +351,8 @@ export function resolveTopBarTokens(theme) {
     tabPaddingX: tabSpaceOr(topBar.tabPaddingX, DEFAULT_TAB_PADDING_X),
     tabPaddingY: tabSpaceOr(topBar.tabPaddingY, DEFAULT_TAB_PADDING_Y),
     // A tab's own surface, authored or nothing. Null means the tab paints none
-    // and the bar shows through it, which is what both styles did before the
-    // keys existed — so an app that never set them is unchanged.
+    // and the bar shows through it, which is what the row did before the keys
+    // existed — so an app that never set them is unchanged.
     tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
     // Only meaningful where the style draws no panel: under `attached` the
     // active surface IS `contentSurface` above. Null under `underline` leaves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.124.0",
+  "version": "0.126.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"