@colixsystems/widget-sdk 0.134.2 → 0.135.0

package/README.md

@@ -70,7 +70,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.134.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.135.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.135.0 (contract 1.104.0)
+
+**NFC tags are vetted, native-only (`react-native-nfc-manager`).** A widget can now read and write NFC tags on the Expo export — NDEF over `NfcManager.requestTechnology(NfcTech.Ndef)`, plus the raw technologies a badge, asset tag or transit card uses: `NfcTech.IsoDep` on both hosts, `NfcTech.MifareClassic` on Android, `NfcTech.MifareIOS` / `FelicaIOS` / `Iso15693IOS` on iOS. (There is no `NfcTech.FeliCa` — check `index.d.ts` before naming one.) This is the last common "tap a physical thing" input the allowlist was missing; barcode and QR already had `useBarcodeScanner()`.
+
+- **Native-only, and the browser is why.** Web NFC ships in Chrome on Android alone — Safari, Firefox and every desktop browser omit it — so there is no web build to pair with. Put the import in `widget.native.jsx` and give `widget.web.jsx` a real way in: a typed code field, or the SDK's `useBarcodeScanner()` QR path. The linter's `import-platform-mismatch` enforces the split.
+- **Opt-in per workspace — and `isSupported()` cannot see that.** The export claims the iOS NFC entitlement and the Android `NFC` permission only when the publisher enables the **NFC tags** device capability in Publish settings. `isSupported()` probes the **device** (`readingAvailable` on iOS, `hasSystemFeature` on Android), not the gate: on a capable phone in an app that never asked, it returns `true` and the read then fails — Android throws a `SecurityException` from `registerTagEvent`, iOS cannot open the reader session. So wrap `start()` / `requestTechnology()` in a `try` and render the **same** fallback from the `catch` that `widget.web.jsx` uses. That `catch` is the degradation path.
+- **Clean up the session.** `cancelTechnologyRequest()` in your effect cleanup; an abandoned request leaves the reader sheet up on iOS.
+- **It is a write capability too.** Read with `getNdefMessage()`; write with `writeNdefMessage(bytes)`, `formatNdef(bytes)` (Android only, for a blank tag) and `transceive(bytes)` on the `IsoDep` / `NfcA` / `NfcV` handlers. One capability covers both — Android expresses read and write through the single `android.permission.NFC` — so the workspace owner who enables it is consenting to every widget in the workspace being able to rewrite the tags their users tap. Raw ISO7816 `transceive` on iOS additionally needs `select-identifiers` on the entitlement, which the export does not declare; NDEF read and write work on both hosts.
+- **`makeReadOnly()` is irreversible.** It permanently locks the tag — no later write will ever succeed, on any device, by any app. Call it only where the feature genuinely wants a one-time-programmable tag, and never as a cleanup step after writing.
+
+### What's new in 0.134.2 (contract 1.103.0 — unchanged)
+
+**Defect fix: `useImageEditor()` now rejects the same inputs on both hosts, and two blob/state leaks are gone (sc-7205).** Review of the 0.126.0 hook found a real web↔native divergence and two bookkeeping bugs it had inherited from `useCamera`. `CONTRACT.version` does **not** move — the contract already promises identical validation across hosts; this makes the implementation honour it.
+
+- **An out-of-bounds crop now rejects `INVALID_ACTION` on web too.** A canvas silently padded the region outside the source with transparent — black once JPEG-encoded — and reported the padded dimensions, while both native platforms threw (and the throw was relabelled `DECODE_FAILED`). Dragging a crop past the edge is the commonest thing a crop UI produces.
+- **`compress` is range-checked on both hosts.** Out of range silently fell back to the browser's default quality on web and threw from `Bitmap.compress` on Android.
+- **`reset()` during an edit no longer wedges `editing` at `true`**, and **an edit still running at unmount now releases its blob**. Both bugs exist in `useCamera` too and are fixed there in the same change (CLAUDE.md §3).
+- A failed `base64` encode no longer leaks its object URL; a derived resize dimension is floored to match the native transformers; the web decode retries without CORS so it accepts the same sources native does at DECODE time (a cross-origin image whose host sends no `Access-Control-Allow-Origin` still taints the canvas and fails at encode with `ENCODE_FAILED`, where native succeeds — the browser's rule, not ours); and `isSupported()` no longer allocates a DOM node per render.
+
+The web broker also gains the test file it shipped without — the previous 16 cases all drove a *fake* broker, so none of the transform maths ever ran.
 
 ### What's new in 0.134.0 (contract 1.103.0)
 

package/dist/contract.cjs

@@ -1735,8 +1735,11 @@ const HOOKS = [
       "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) }. " +
+      "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
+      "compress must be 0..1. Both hosts answer INVALID_ACTION — the web Player by checking its own canvas before " +
+      "it draws, the export by mapping what its native transformer throws — so branch on the CODE, not the message. " +
+      "options: { format: \"jpeg\" | \"png\" | \"webp\" (default jpeg), " +
+      "compress: 0..1 (default 0.8; validated on both hosts, and the value itself is 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 " +
@@ -2747,6 +2750,13 @@ 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: "react-native-nfc-manager",
+    platforms: ["native"],
+    category: "system",
+    description:
+      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render the SAME fallback from the catch that widget.web.jsx uses - that catch IS the degradation path, not a nicety. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
+  },
   {
     specifier: "decimal.js",
     platforms: ["web", "native"],
@@ -3896,7 +3906,14 @@ const CONTRACT = deepFreeze({
   //    identically: a line needs a `| --- |` divider to become a table, and an
   //    `![alt](src)` image is still read as an image, never a link. Minor bump
   //    on the pre-1.0 channel.
-  version: "1.103.0",
+  // 1.104.0: additive - `react-native-nfc-manager` joins VETTED_IMPORTS as a
+  // native-only `system` package. Widgets had no way to read a tag at all, so
+  // badge check-in, asset tracking and inventory counts against NFC labels were
+  // unbuildable. Native-only because Web NFC exists only in Chrome on Android -
+  // the web half is a widget.web.jsx typed-code or QR path. Pinned in the
+  // export and gated behind the `nfc` export capability, because its iOS
+  // entitlement obliges every App ID that carries it.
+  version: "1.104.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1735,8 +1735,11 @@ const HOOKS = [
       "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) }. " +
+      "{ flip: \"horizontal\" | \"vertical\" }. A crop rect must lie INSIDE the surface the earlier actions produced, and " +
+      "compress must be 0..1. Both hosts answer INVALID_ACTION — the web Player by checking its own canvas before " +
+      "it draws, the export by mapping what its native transformer throws — so branch on the CODE, not the message. " +
+      "options: { format: \"jpeg\" | \"png\" | \"webp\" (default jpeg), " +
+      "compress: 0..1 (default 0.8; validated on both hosts, and the value itself is 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 " +
@@ -2747,6 +2750,13 @@ 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: "react-native-nfc-manager",
+    platforms: ["native"],
+    category: "system",
+    description:
+      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render the SAME fallback from the catch that widget.web.jsx uses - that catch IS the degradation path, not a nicety. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
+  },
   {
     specifier: "decimal.js",
     platforms: ["web", "native"],
@@ -3896,7 +3906,14 @@ const CONTRACT = deepFreeze({
   //    identically: a line needs a `| --- |` divider to become a table, and an
   //    `![alt](src)` image is still read as an image, never a link. Minor bump
   //    on the pre-1.0 channel.
-  version: "1.103.0",
+  // 1.104.0: additive - `react-native-nfc-manager` joins VETTED_IMPORTS as a
+  // native-only `system` package. Widgets had no way to read a tag at all, so
+  // badge check-in, asset tracking and inventory counts against NFC labels were
+  // unbuildable. Native-only because Web NFC exists only in Chrome on Android -
+  // the web half is a widget.web.jsx typed-code or QR path. Pinned in the
+  // export and gated behind the `nfc` export capability, because its iOS
+  // entitlement obliges every App ID that carries it.
+  version: "1.104.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1519,6 +1519,10 @@ export function useCamera(options) {
   // life of the document, so the hook owns revoking the one it replaced.
   const releaseRef = useRef(null);
   const runRef = useRef(0);
+  // How many requests are still open. `loading` tracks "any request running",
+  // which a run token alone cannot express: reset() bumps the token, so the
+  // superseded request's finally-block could never clear the flag.
+  const inFlightRef = useRef(0);
 
   const supported = Boolean(
     clientRef.current &&
@@ -1539,7 +1543,17 @@ export function useCamera(options) {
     }
   }, []);
 
-  useEffect(() => () => release(), [release]);
+  // Bump the token as well as releasing: a request still open at unmount
+  // resolves into the supersede branch (which releases the asset it got)
+  // instead of the success branch, which would write to a dead ref and strand
+  // the blob for the life of the document.
+  useEffect(
+    () => () => {
+      runRef.current += 1;
+      release();
+    },
+    [release],
+  );
 
   const reset = useCallback(() => {
     runRef.current += 1;
@@ -1570,6 +1584,7 @@ export function useCamera(options) {
       setLoading(true);
       setError(null);
       try {
+        inFlightRef.current += 1;
         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.
@@ -1588,7 +1603,14 @@ export function useCamera(options) {
         if (run === runRef.current) setError(ce);
         throw ce;
       } finally {
-        if (run === runRef.current) setLoading(false);
+        inFlightRef.current -= 1;
+        // Clear when the NEWEST request settles (the widget is now showing its
+        // result) or when the last one does. Only the newest would leave the
+        // flag stuck after a reset(); only the last would keep it true while a
+        // superseded straggler is still open.
+        if (run === runRef.current || inFlightRef.current === 0) {
+          setLoading(false);
+        }
       }
     },
     [release],
@@ -1837,6 +1859,9 @@ export function useImageEditor() {
   // life of the document, so the hook owns revoking the one it replaced.
   const releaseRef = useRef(null);
   const runRef = useRef(0);
+  // See useCamera: `editing` means "any edit running", which the run token
+  // alone cannot express once reset() has bumped it.
+  const inFlightRef = useRef(0);
 
   const supported = Boolean(
     clientRef.current &&
@@ -1857,7 +1882,15 @@ export function useImageEditor() {
     }
   }, []);
 
-  useEffect(() => () => release(), [release]);
+  // Bump the token as well as releasing, so an edit still open at unmount
+  // takes the supersede branch and its blob is revoked rather than stranded.
+  useEffect(
+    () => () => {
+      runRef.current += 1;
+      release();
+    },
+    [release],
+  );
 
   const reset = useCallback(() => {
     runRef.current += 1;
@@ -1893,6 +1926,7 @@ export function useImageEditor() {
       setEditing(true);
       setError(null);
       try {
+        inFlightRef.current += 1;
         const next = await client.edit(
           uri,
           Array.isArray(actions) ? actions : [],
@@ -1915,7 +1949,14 @@ export function useImageEditor() {
         if (run === runRef.current) setError(ie);
         throw ie;
       } finally {
-        if (run === runRef.current) setEditing(false);
+        inFlightRef.current -= 1;
+        // Clear when the NEWEST edit settles (the widget is now showing its
+        // result) or when the last one does. Only the newest would leave the
+        // flag stuck after a reset(); only the last would keep it true while a
+        // superseded straggler is still open.
+        if (run === runRef.current || inFlightRef.current === 0) {
+          setEditing(false);
+        }
       }
     },
     [release],

package/dist/host.d.ts

@@ -308,3 +308,29 @@ export function decodeWidgetRoute(
 export function collectWidgetRoutes(
   rawParams: Record<string, string> | null | undefined,
 ): Record<string, Record<string, WidgetRouteValue>>;
+
+/** Longest heading/subheading the sign-in card accepts. */
+export const LOGIN_TEXT_MAX_LENGTH: number;
+
+export interface ThemeGradient {
+  type: "linear" | "radial";
+  from: string;
+  to: string;
+  angle: number;
+  stop?: number;
+}
+
+/** The app-wide background gradient, or null when unset/malformed. */
+export function normaliseThemeGradient(raw: unknown): ThemeGradient | null;
+
+export interface LoginDesign {
+  backgroundColor: string | null;
+  backgroundGradient: ThemeGradient | null;
+  backgroundImageUrl: string | null;
+  backgroundOverlay: string | null;
+  heading: string | null;
+  subheading: string | null;
+}
+
+/** The sign-in screen's authored design, or null when nothing is configured. */
+export function normaliseLoginDesign(raw: unknown): LoginDesign | null;

package/dist/host.js

@@ -79,3 +79,14 @@ export {
   collectWidgetRoutes,
   sameWidgetRouteValue,
 } from "./widget-route.js";
+
+// REQ-THEME-08 / REQ-PLR-05-CUSTOM (sc-7502): the app background gradient and
+// the sign-in screen's authored design. `normaliseThemeGradient` used to be a
+// hand-mirrored pair (a frontend util and a backend util, each told to stay in
+// lockstep with the other); both now delegate here, which is also what lets the
+// login design reuse it instead of becoming a fourth copy of the same rules.
+export {
+  LOGIN_TEXT_MAX_LENGTH,
+  normaliseThemeGradient,
+  normaliseLoginDesign,
+} from "./theme-background.js";

package/dist/theme-background.cjs

@@ -0,0 +1,138 @@
+// CommonJS mirror of theme-background.js — the compiler (Expo export) and the
+// Mason build runner are CJS and must resolve an app background and a login
+// design against the SAME rules the web hosts apply, or the two renders diverge.
+//
+// The BODY below is copied VERBATIM from theme-background.js; only the module
+// syntax differs. theme-background-parity.test.js pins both facts — identical
+// bodies AND identical behaviour over a shared case table — so drift fails CI.
+
+// REQ-THEME-08 / REQ-PLR-05-CUSTOM — the ONE implementation of the app's
+// background gradient and of the sign-in screen's design, shared by both hosts.
+//
+// Host-integration surface, re-exported from `host.js`: consumed only by the
+// platform hosts that render an app (the web Player / Studio Design page, and
+// the compiler that bakes the Expo export), never by a widget author.
+//
+// `normaliseThemeGradient` was a hand-mirrored PAIR — `frontend/src/utils/
+// theme.js` and `backend/src/core/utils/theme-gradient.ts`, each carrying a
+// "keep the two in lockstep" comment. Both now delegate here (CLAUDE.md §3),
+// which is also what lets the login design below reuse it rather than become a
+// fourth copy of the same rules.
+
+// The compiler's own `_HEX_COLOR`: 3-, 6- or 8-digit. Only the 8-digit form
+// carries alpha, which is what makes a tint a tint.
+const HEX_ANY = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+// The gradient stops predate alpha support and stay 3/6-digit (REQ-THEME-17:
+// the app background is read at full strength).
+const HEX_OPAQUE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+
+// Long enough for a tagline, short enough that it cannot become a payload or
+// blow out the card. The Studio counts against the same constant.
+const LOGIN_TEXT_MAX_LENGTH = 120;
+
+/**
+ * Shape: { type: "linear"|"radial", from: "#hex", to: "#hex", angle: 0-359,
+ * stop: 0-100 } — `stop` (sc-6543) is where the shift begins: the start colour
+ * holds solid up to stop% of the gradient line, then blends to `to`. 0 (the
+ * default) is the classic full-span blend and is omitted from the result.
+ * Returns null when the value is missing or malformed so callers short-circuit.
+ */
+function normaliseThemeGradient(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const from =
+    typeof raw.from === "string" && HEX_OPAQUE.test(raw.from) ? raw.from : null;
+  const to =
+    typeof raw.to === "string" && HEX_OPAQUE.test(raw.to) ? raw.to : null;
+  if (!from || !to) return null;
+  const type = raw.type === "radial" ? "radial" : "linear";
+  let angle = Number.isFinite(raw.angle) ? Math.round(raw.angle) : 180;
+  angle = ((angle % 360) + 360) % 360;
+  const stop = Number.isFinite(raw.stop)
+    ? Math.min(100, Math.max(0, Math.round(raw.stop)))
+    : 0;
+  // 0 is the default, so storing it would only be noise every consumer already
+  // assumes — and it keeps an existing gradient's stored shape unchanged.
+  return stop > 0 ? { type, from, to, angle, stop } : { type, from, to, angle };
+}
+
+function hexOrNull(raw) {
+  return typeof raw === "string" && HEX_ANY.test(raw.trim())
+    ? raw.trim()
+    : null;
+}
+
+// The URL is author-supplied and reaches a CSS `url(...)` on web and a baked
+// `{ uri: '...' }` literal on native, so the scheme is an allowlist: a
+// `javascript:`/`data:`/`vbscript:` value must never survive to either host.
+function normaliseImageUrl(raw) {
+  if (typeof raw !== "string") return null;
+  const url = raw.trim();
+  if (!url) return null;
+  // A workspace upload is served same-origin as an absolute path.
+  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  return /^https?:\/\/\S+$/i.test(url) ? url : null;
+}
+
+// A single tint laid over the image. Alpha lives in the 8-digit hex, so the
+// author controls opacity with the colour itself rather than a second field —
+// the same way `siteHeader.backgroundColor` already floats a header.
+function normaliseOverlay(raw) {
+  return hexOrNull(raw);
+}
+
+function normaliseText(raw) {
+  if (typeof raw !== "string") return null;
+  const text = raw.trim();
+  if (!text) return null;
+  return text.slice(0, LOGIN_TEXT_MAX_LENGTH);
+}
+
+/**
+ * The sign-in screen's authored design, read off `themeConfig.login`.
+ *
+ * Every field is optional and every omission means "keep what the app already
+ * does": an unset background inherits the app's own `backgroundColor` /
+ * `backgroundGradient`, and unset text leaves the card on the workspace name
+ * and its stock subtitle. Returns null when NOTHING is configured, so both
+ * hosts short-circuit to exactly their pre-sc-7502 render.
+ *
+ * @returns {{
+ *   backgroundColor: string|null,
+ *   backgroundGradient: object|null,
+ *   backgroundImageUrl: string|null,
+ *   backgroundOverlay: string|null,
+ *   heading: string|null,
+ *   subheading: string|null,
+ * }|null}
+ */
+function normaliseLoginDesign(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  // LINEAR ONLY, deliberately. The app background offers radial because App.js
+  // can afford the SVG figure that draws it (expo-linear-gradient has none);
+  // emitting a second copy of that figure into the login screen would be the
+  // duplication §3 forbids. Both hosts therefore support exactly linear here,
+  // so the two cannot diverge — radial can follow when the figure is shared.
+  const gradient = normaliseThemeGradient(raw.backgroundGradient);
+  const design = {
+    backgroundColor: hexOrNull(raw.backgroundColor),
+    backgroundGradient: gradient ? { ...gradient, type: "linear" } : null,
+    // REQ-THEME-10's asset-or-URL contract, as the app logo already uses it: a
+    // picked Studio asset wins, the pasted URL is the fallback. Each host
+    // resolves the asset id into `...Resolved` before calling — `useAssetUrl`
+    // on web, the compiler's asset lookup on native — because neither the SDK
+    // nor a pure function can reach the asset table.
+    backgroundImageUrl:
+      normaliseImageUrl(raw.backgroundImageUrlResolved) ||
+      normaliseImageUrl(raw.backgroundImageUrl),
+    backgroundOverlay: normaliseOverlay(raw.backgroundOverlay),
+    heading: normaliseText(raw.heading),
+    subheading: normaliseText(raw.subheading),
+  };
+  // A tint with no image would dim the app background for no reason the author
+  // asked for — it is a treatment OF the image, so it goes with it.
+  if (!design.backgroundImageUrl) design.backgroundOverlay = null;
+  const configured = Object.values(design).some((value) => value !== null);
+  return configured ? design : null;
+}
+
+module.exports = { LOGIN_TEXT_MAX_LENGTH, normaliseThemeGradient, normaliseLoginDesign };

package/dist/theme-background.js

@@ -0,0 +1,128 @@
+// REQ-THEME-08 / REQ-PLR-05-CUSTOM — the ONE implementation of the app's
+// background gradient and of the sign-in screen's design, shared by both hosts.
+//
+// Host-integration surface, re-exported from `host.js`: consumed only by the
+// platform hosts that render an app (the web Player / Studio Design page, and
+// the compiler that bakes the Expo export), never by a widget author.
+//
+// `normaliseThemeGradient` was a hand-mirrored PAIR — `frontend/src/utils/
+// theme.js` and `backend/src/core/utils/theme-gradient.ts`, each carrying a
+// "keep the two in lockstep" comment. Both now delegate here (CLAUDE.md §3),
+// which is also what lets the login design below reuse it rather than become a
+// fourth copy of the same rules.
+
+// The compiler's own `_HEX_COLOR`: 3-, 6- or 8-digit. Only the 8-digit form
+// carries alpha, which is what makes a tint a tint.
+const HEX_ANY = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+// The gradient stops predate alpha support and stay 3/6-digit (REQ-THEME-17:
+// the app background is read at full strength).
+const HEX_OPAQUE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+
+// Long enough for a tagline, short enough that it cannot become a payload or
+// blow out the card. The Studio counts against the same constant.
+export const LOGIN_TEXT_MAX_LENGTH = 120;
+
+/**
+ * Shape: { type: "linear"|"radial", from: "#hex", to: "#hex", angle: 0-359,
+ * stop: 0-100 } — `stop` (sc-6543) is where the shift begins: the start colour
+ * holds solid up to stop% of the gradient line, then blends to `to`. 0 (the
+ * default) is the classic full-span blend and is omitted from the result.
+ * Returns null when the value is missing or malformed so callers short-circuit.
+ */
+export function normaliseThemeGradient(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const from =
+    typeof raw.from === "string" && HEX_OPAQUE.test(raw.from) ? raw.from : null;
+  const to =
+    typeof raw.to === "string" && HEX_OPAQUE.test(raw.to) ? raw.to : null;
+  if (!from || !to) return null;
+  const type = raw.type === "radial" ? "radial" : "linear";
+  let angle = Number.isFinite(raw.angle) ? Math.round(raw.angle) : 180;
+  angle = ((angle % 360) + 360) % 360;
+  const stop = Number.isFinite(raw.stop)
+    ? Math.min(100, Math.max(0, Math.round(raw.stop)))
+    : 0;
+  // 0 is the default, so storing it would only be noise every consumer already
+  // assumes — and it keeps an existing gradient's stored shape unchanged.
+  return stop > 0 ? { type, from, to, angle, stop } : { type, from, to, angle };
+}
+
+function hexOrNull(raw) {
+  return typeof raw === "string" && HEX_ANY.test(raw.trim())
+    ? raw.trim()
+    : null;
+}
+
+// The URL is author-supplied and reaches a CSS `url(...)` on web and a baked
+// `{ uri: '...' }` literal on native, so the scheme is an allowlist: a
+// `javascript:`/`data:`/`vbscript:` value must never survive to either host.
+function normaliseImageUrl(raw) {
+  if (typeof raw !== "string") return null;
+  const url = raw.trim();
+  if (!url) return null;
+  // A workspace upload is served same-origin as an absolute path.
+  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  return /^https?:\/\/\S+$/i.test(url) ? url : null;
+}
+
+// A single tint laid over the image. Alpha lives in the 8-digit hex, so the
+// author controls opacity with the colour itself rather than a second field —
+// the same way `siteHeader.backgroundColor` already floats a header.
+function normaliseOverlay(raw) {
+  return hexOrNull(raw);
+}
+
+function normaliseText(raw) {
+  if (typeof raw !== "string") return null;
+  const text = raw.trim();
+  if (!text) return null;
+  return text.slice(0, LOGIN_TEXT_MAX_LENGTH);
+}
+
+/**
+ * The sign-in screen's authored design, read off `themeConfig.login`.
+ *
+ * Every field is optional and every omission means "keep what the app already
+ * does": an unset background inherits the app's own `backgroundColor` /
+ * `backgroundGradient`, and unset text leaves the card on the workspace name
+ * and its stock subtitle. Returns null when NOTHING is configured, so both
+ * hosts short-circuit to exactly their pre-sc-7502 render.
+ *
+ * @returns {{
+ *   backgroundColor: string|null,
+ *   backgroundGradient: object|null,
+ *   backgroundImageUrl: string|null,
+ *   backgroundOverlay: string|null,
+ *   heading: string|null,
+ *   subheading: string|null,
+ * }|null}
+ */
+export function normaliseLoginDesign(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  // LINEAR ONLY, deliberately. The app background offers radial because App.js
+  // can afford the SVG figure that draws it (expo-linear-gradient has none);
+  // emitting a second copy of that figure into the login screen would be the
+  // duplication §3 forbids. Both hosts therefore support exactly linear here,
+  // so the two cannot diverge — radial can follow when the figure is shared.
+  const gradient = normaliseThemeGradient(raw.backgroundGradient);
+  const design = {
+    backgroundColor: hexOrNull(raw.backgroundColor),
+    backgroundGradient: gradient ? { ...gradient, type: "linear" } : null,
+    // REQ-THEME-10's asset-or-URL contract, as the app logo already uses it: a
+    // picked Studio asset wins, the pasted URL is the fallback. Each host
+    // resolves the asset id into `...Resolved` before calling — `useAssetUrl`
+    // on web, the compiler's asset lookup on native — because neither the SDK
+    // nor a pure function can reach the asset table.
+    backgroundImageUrl:
+      normaliseImageUrl(raw.backgroundImageUrlResolved) ||
+      normaliseImageUrl(raw.backgroundImageUrl),
+    backgroundOverlay: normaliseOverlay(raw.backgroundOverlay),
+    heading: normaliseText(raw.heading),
+    subheading: normaliseText(raw.subheading),
+  };
+  // A tint with no image would dim the app background for no reason the author
+  // asked for — it is a treatment OF the image, so it goes with it.
+  if (!design.backgroundImageUrl) design.backgroundOverlay = null;
+  const configured = Object.values(design).some((value) => value !== null);
+  return configured ? design : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.134.2",
+  "version": "0.135.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",