@colixsystems/widget-sdk 0.276.0 → 0.277.1

package/dist/linter.js

@@ -1584,13 +1584,22 @@ function _rawUseMemoIntoDatastoreQueryRules(source) {
 // `.roles` re-implements the table ACL client-side and drifts from it the
 // moment the ACL changes; `useCanWrite(tableId)` reads the same rule the
 // write endpoint enforces. Flags only when the file has NOT already reached
-// for it.
+// for it, and only on useUser()'s own value: `theme.typography.roles` is a
+// style read (sc-15204).
+function _readsUserRoles(code) {
+  const named = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*useUser\s*\(\s*\)/.exec(code);
+  if (named && new RegExp(`\\b${named[1].replace(/\$/g, "\\$")}\\??\\.(groupIds|roles)\\b`).test(code)) return true;
+  const destructured = /\b(?:const|let|var)\s*\{([^}]*)\}\s*=\s*useUser\s*\(\s*\)/.exec(code);
+  if (destructured && /\b(groupIds|roles)\b/.test(destructured[1])) return true;
+  return /\buseUser\s*\(\s*\)\s*\??\.(groupIds|roles)\b/.test(code);
+}
+
 function _handRolledWriteGateRules(source) {
   const code = _stripNonCode(source);
   if (/\buseCanWrite\s*\(/.test(code)) return [];
   const userCall = /\buseUser\s*\(\s*\)/.exec(code);
   if (!userCall) return [];
-  if (!/\.(groupIds|roles)\b/.test(code)) return [];
+  if (!_readsUserRoles(code)) return [];
   const hasWrite =
     /\.(create|update)\s*\(/.test(code) ||
     /\buseDatastoreMutation\s*\(/.test(code);

package/dist/lucideIconName.cjs

@@ -1,8 +1,16 @@
-// CommonJS twin of lucideIconName.js for the backend (the page service +
-// any other Node consumer require this). Keep the two in sync — same
-// algorithm, same behaviour. See lucideIconName.js for the rationale.
+// GENERATED from lucideIconName.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change lucideIconName.js, then run `npm run generate:cjs` in packages/widget-sdk.
 "use strict";
 
+// Normalize a human-typed Lucide icon name to the PascalCase form Lucide
+// exports its components under. The lucide.dev gallery shows kebab-case
+// (`arrow-right`) and its copy button hands you kebab-case, but
+// `lucide-react` / `lucide-react-native` key their components in PascalCase
+// (`ArrowRight`). This bridges the two so any of kebab / snake / spaced /
+// camel / PascalCase resolves: `arrow-right`, `arrow_right`, `arrow right`,
+// `arrowRight`, and `ArrowRight` all become `ArrowRight`; `building-2` becomes
+// `Building2`. Non-strings and blanks return "" so callers fall back to a
+// placeholder. Already-PascalCase names pass through unchanged.
 function normalizeLucideIconName(name) {
   if (typeof name !== "string") return "";
   const trimmed = name.trim();
@@ -13,5 +21,6 @@ function normalizeLucideIconName(name) {
     .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
     .join("");
 }
-
-module.exports = { normalizeLucideIconName };
+module.exports = {
+  normalizeLucideIconName,
+};

package/dist/manifest.cjs

@@ -1,11 +1,12 @@
-// CommonJS mirror of manifest.js. Lets backend services (CJS) call
-// `validateManifest(...)` without a dynamic-import detour. The two files
-// share their constants by mutual import via createRequire — manifest.js
-// re-exports the same functions defined here so there is exactly one
-// implementation.
+// GENERATED from manifest.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change manifest.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
 
 const { CONTRACT } = require("./contract.cjs");
 
+// Structural validation of a widget manifest, shared by the CLI, hosts and backend.
+
+
 const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
 
 // sc-4505 — a payload / input field map: { <field>: { type, label? } }. This is
@@ -120,16 +121,7 @@ function validateManifestTranslations(translations, manifestId, errors) {
   }
 }
 
-// REQ-MKT-ACTION (sc-4879): a widget no longer declares server-side actions.
-//
-// `manifest.actions` was how an automation shipped before Actions existed as
-// their own marketplace deliverable — a widget was two products in one package,
-// a component that renders and a script that never renders at all. It is now
-// REFUSED rather than ignored: an author who declares it believes the
-// automation will ship, and silence would publish that misunderstanding.
-//
-// The replacement is a marketplace Action (`@colixsystems/action-sdk`), which
-// the workspace installs and configures on its own.
+// REQ-MKT-ACTION (sc-4879): refused, not ignored — the author expects it to ship.
 function validateManifestActions(_actions, errors) {
   errors.push(
     "manifest.actions is no longer supported — ship the automation as a " +

package/dist/manifest.js

@@ -1,10 +1,6 @@
-// CommonJS mirror of manifest.js. Lets backend services (CJS) call
-// `validateManifest(...)` without a dynamic-import detour. The two files
-// share their constants by mutual import via createRequire — manifest.js
-// re-exports the same functions defined here so there is exactly one
-// implementation.
+// Structural validation of a widget manifest, shared by the CLI, hosts and backend.
 
-import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
+import { CONTRACT } from "./contract.js";
 
 const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
 
@@ -39,20 +35,6 @@ const VALID_CATEGORIES = new Set([
 ]);
 const VALID_PLATFORMS = new Set(["web", "native"]);
 
-// REQ-WIDGET-ACTION — structural validation for manifest-declared server
-// actions. Mirrors the backend action.service caps; the runner re-validates
-// the cron expression (node-cron) and binds the tenant-local API key + table
-// at enable time, so we only check shape + size here (cross-env: no Buffer).
-const VALID_ACTION_TRIGGERS = new Set([
-  "schedule",
-  "record_created",
-  "record_updated",
-  "record_deleted",
-]);
-const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
-const ACTION_TIMEOUT_MIN_MS = 100;
-const ACTION_TIMEOUT_MAX_MS = 5 * 60 * 1000;
-
 // REQ-L10N-WIDGET — caps + patterns for manifest-declared translations.
 // The relative key pattern is deliberately tighter than the dictionary's
 // own KEY_RE: once the host namespaces it (`widget.<id>.<key>`) the result
@@ -134,54 +116,13 @@ function validateManifestTranslations(translations, manifestId, errors) {
   }
 }
 
-function validateManifestActions(actions, errors) {
-  if (!Array.isArray(actions)) {
-    errors.push("manifest.actions must be an array (omit it or use [] for none)");
-    return;
-  }
-  const seenKeys = new Set();
-  for (const a of actions) {
-    if (a === null || typeof a !== "object") {
-      errors.push("manifest.actions entries must be objects");
-      break;
-    }
-    if (!isNonEmptyString(a.key)) {
-      errors.push("manifest.actions[].key must be a non-empty string");
-    } else if (seenKeys.has(a.key)) {
-      errors.push(`manifest.actions[].key "${a.key}" is duplicated`);
-    } else {
-      seenKeys.add(a.key);
-    }
-    pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
-    const triggerTypes = normaliseActionTriggerTypes(a);
-    if (triggerTypes === null) {
-      errors.push(
-        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
-      );
-    } else if (triggerTypes.includes("schedule")) {
-      pushIf(
-        errors,
-        isNonEmptyString(a.scheduleCron),
-        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
-      );
-    }
-    if (!isNonEmptyString(a.scriptSource)) {
-      errors.push("manifest.actions[].scriptSource must be a non-empty string");
-    } else if (utf8ByteLength(a.scriptSource) > ACTION_SCRIPT_MAX_BYTES) {
-      errors.push("manifest.actions[].scriptSource exceeds 200 KiB");
-    }
-    if (a.timeoutMs !== undefined) {
-      const t = Number(a.timeoutMs);
-      if (!Number.isFinite(t) || t < ACTION_TIMEOUT_MIN_MS || t > ACTION_TIMEOUT_MAX_MS) {
-        errors.push("manifest.actions[].timeoutMs must be between 100 and 300000");
-      }
-    }
-    if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
-      errors.push(
-        "manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install",
-      );
-    }
-  }
+// REQ-MKT-ACTION (sc-4879): refused, not ignored — the author expects it to ship.
+function validateManifestActions(_actions, errors) {
+  errors.push(
+    "manifest.actions is no longer supported — ship the automation as a " +
+      "marketplace Action (@colixsystems/action-sdk) instead of declaring it " +
+      "on a widget",
+  );
 }
 
 function canonicalCategory(c) {
@@ -361,7 +302,7 @@ function validateManifest(m) {
     }
   }
 
-  // `actions` is optional (additive in SDK 1.8.0) — only validate when present.
+  // Present at all is now an error (sc-4879) — see validateManifestActions.
   if (manifest.actions !== undefined) {
     validateManifestActions(manifest.actions, errors);
   }

package/dist/navigation.cjs

@@ -1,11 +1,8 @@
-// CommonJS mirror of navigation.js — the CJS compiler and the Mason build runner
-// resolve a `theme_config.navigation` block with the SAME rules the web host
-// applies, so an app's menu type cannot mean one thing on web and another in the
-// exported Expo app.
-//
-// The BODY below is copied VERBATIM from navigation.js; only the module syntax
-// differs. navigation-parity.test.js pins both facts — identical bodies AND
-// identical behaviour over a shared case table — so drift fails CI.
+// GENERATED from navigation.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change navigation.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
+
+const { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } = require("./contract.cjs");
 
 // REQ-NAV-STRUCTURE — the host side of an app's navigation SHAPE and the
 // tokens its footer strip is painted with.
@@ -25,7 +22,6 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-const { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } = require("./contract.cjs");
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -895,5 +891,29 @@ function borderWidthOr(...values) {
   }
   return BORDER_WIDTH_MIN;
 }
-
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, FOOTER_SIZES, clampFooterSize, FOOTER_HOME_LINE_CLEARANCE_PX, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere, isDarkSurface, resolveAppLogo };
+module.exports = {
+  normaliseNavigation,
+  menuItemCap,
+  resolveFooterTokens,
+  FOOTER_SIZES,
+  clampFooterSize,
+  FOOTER_HOME_LINE_CLEARANCE_PX,
+  resolveSidebarTokens,
+  TOP_STRIPE_SLOTS,
+  TOP_STRIPE_ALWAYS_SHOWN_SLOTS,
+  MIN_TOP_STRIPE_HEIGHT_PX,
+  MAX_TOP_STRIPE_HEIGHT_PX,
+  MIN_TOP_STRIPE_PADDING_X_PX,
+  MAX_TOP_STRIPE_PADDING_X_PX,
+  MAX_TOP_STRIPE_OFFSET_Y_PX,
+  DEFAULT_TOP_STRIPE_HEIGHT_PX,
+  DEFAULT_TOP_STRIPE_PADDING_X_PX,
+  topStripeShowKey,
+  resolveTopStripeLayout,
+  isDarkSurface,
+  resolveAppLogo,
+  resolveTopBarTokens,
+  resolveSidebarUnfold,
+  resolveLocalNavModel,
+  drawsLocalNavAnywhere,
+};

package/dist/source-mask.cjs

@@ -0,0 +1,169 @@
+// GENERATED from source-mask.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change source-mask.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
+
+// sc-6086: the shared source masker, extracted verbatim from linter.js so the
+// linter, the packer's import scanner, and the dev-server guard all agree on
+// what is code and what is a comment or string literal (CLAUDE.md §3).
+//
+// Length-preserving: every blanked character becomes a space and newlines are
+// kept, so an index into the mask is the SAME index in the original source.
+// That is what lets a caller match against the mask and splice the original.
+
+// Replace the *content* of comments and string / template literals with
+// spaces so the banned-identifier scan only ever sees executable code. A
+// banned host-escape identifier (`window`, `document`, `eval`, `process`, …)
+// is only dangerous as a real identifier reference — never as prose in a
+// `//` comment or as character data inside a string — so matching the bare
+// word there is a false positive that blocks an otherwise-clean widget (a
+// comment that reads "the hour window the grid renders" must not trip
+// `no-window`).
+//
+// Newlines are preserved verbatim so reported line numbers still line up
+// with the original source. Template-literal `${ … }` expression holes are
+// left intact: real code lives there and must still be scanned (`${window}`
+// is a genuine escape). Backslash escapes inside strings/templates are
+// consumed so an escaped quote (`"\""`) doesn't end the literal early.
+function stripNonCode(
+  source,
+  { keepStrings = false, keepTemplates = keepStrings } = {},
+) {
+  let out = "";
+  const n = source.length;
+  let mode = "code"; // code | line | block | sq | dq | tmpl
+  // Brace depth, plus a stack of the depths at which an enclosing template
+  // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
+  // strings, or nested templates) be told apart from the literal text.
+  let braceDepth = 0;
+  const tmplStack = [];
+  const keep = (ch) => {
+    out += ch;
+  };
+  const blank = (ch) => {
+    out += ch === "\n" || ch === "\r" ? ch : " ";
+  };
+  // String / template CONTENT: blanked for the banned-identifier scan
+  // (prose must not trip `no-window`), kept for the host-API-URL scan,
+  // whose whole job is to find a URL literal.
+  const str = keepStrings ? keep : blank;
+  // An import specifier is always a quoted string, never a template literal —
+  // so the import scanner keeps quoted content and blanks templates, which is
+  // what stops an `import … from "./x"` line inside a backtick block from
+  // reading as a real statement.
+  const tmplStr = keepTemplates ? keep : blank;
+  let i = 0;
+  while (i < n) {
+    const ch = source[i];
+    const nx = source[i + 1];
+    if (mode === "code") {
+      if (ch === "/" && nx === "/") {
+        mode = "line";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "/" && nx === "*") {
+        mode = "block";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "'") {
+        mode = "sq";
+        str(ch);
+        i += 1;
+      } else if (ch === '"') {
+        mode = "dq";
+        str(ch);
+        i += 1;
+      } else if (ch === "`") {
+        mode = "tmpl";
+        tmplStr(ch);
+        i += 1;
+      } else if (ch === "{") {
+        braceDepth += 1;
+        keep(ch);
+        i += 1;
+      } else if (ch === "}") {
+        braceDepth -= 1;
+        if (
+          tmplStack.length > 0 &&
+          tmplStack[tmplStack.length - 1] === braceDepth
+        ) {
+          tmplStack.pop();
+          mode = "tmpl";
+          str(ch);
+        } else {
+          keep(ch);
+        }
+        i += 1;
+      } else {
+        keep(ch);
+        i += 1;
+      }
+    } else if (mode === "line") {
+      if (ch === "\n") {
+        mode = "code";
+        keep(ch);
+      } else {
+        blank(ch);
+      }
+      i += 1;
+    } else if (mode === "block") {
+      if (ch === "*" && nx === "/") {
+        mode = "code";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    } else if (mode === "sq" || mode === "dq") {
+      const quote = mode === "sq" ? "'" : '"';
+      if (ch === "\\") {
+        str(ch);
+        if (i + 1 < n) str(nx);
+        i += 2;
+      } else if (ch === quote) {
+        mode = "code";
+        str(ch);
+        i += 1;
+      } else if (ch === "\n") {
+        // A bare newline terminates an unterminated string in JS; bail back
+        // to code so malformed input can't blank the rest of the file.
+        mode = "code";
+        keep(ch);
+        i += 1;
+      } else {
+        str(ch);
+        i += 1;
+      }
+    } else {
+      // mode === "tmpl"
+      if (ch === "\\") {
+        tmplStr(ch);
+        if (i + 1 < n) tmplStr(nx);
+        i += 2;
+      } else if (ch === "`") {
+        mode = "code";
+        tmplStr(ch);
+        i += 1;
+      } else if (ch === "$" && nx === "{") {
+        // Enter an expression hole. Remember the brace depth the template
+        // resumes at, then count the `{` so its matching `}` is recognised.
+        tmplStack.push(braceDepth);
+        braceDepth += 1;
+        mode = "code";
+        keep(ch);
+        keep(nx);
+        i += 2;
+      } else {
+        tmplStr(ch);
+        i += 1;
+      }
+    }
+  }
+  return out;
+}
+module.exports = {
+  stripNonCode,
+};

package/dist/theme-appearance.cjs

@@ -1,9 +1,12 @@
-// CommonJS mirror of theme-appearance.js, for the backend's theme coercion and
-// the compiler. The BODY is copied VERBATIM; theme-appearance-parity.test.js
-// pins identical bodies and identical behaviour.
+// GENERATED from theme-appearance.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change theme-appearance.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
 
 const { isHexColor, APPEARANCE_PREFERENCES } = require("./contract.cjs");
 
+// APPEARANCE_PREFERENCES: what an app opens on and a user may choose.
+
+
 // REQ-THEME-APPEARANCE (sc-12335) — the ONE implementation of an app's light and
 // dark palettes, and of which one is showing. Host surface, not author API.
 
@@ -181,10 +184,9 @@ function themeInBothModes(theme, mode, twin) {
   if (mode !== "dark") return withDarkPalette(base, twinPalette);
   return withDarkPalette(overlayPalette(base, twinPalette), recolourablePalette(base));
 }
-
 module.exports = {
-  APPEARANCE_MODES,
   APPEARANCE_PREFERENCES,
+  APPEARANCE_MODES,
   themePaletteOf,
   normaliseAppearance,
   resolveAppearancePreference,

package/dist/theme-appearance.js

@@ -1,6 +1,6 @@
+// APPEARANCE_PREFERENCES: what an app opens on and a user may choose.
 import { isHexColor, APPEARANCE_PREFERENCES } from "./contract.js";
 
-// What an app opens on and a user may choose; one list, in the contract.
 export { APPEARANCE_PREFERENCES };
 
 // REQ-THEME-APPEARANCE (sc-12335) — the ONE implementation of an app's light and

package/dist/theme-background.cjs

@@ -1,10 +1,6 @@
-// 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.
+// GENERATED from theme-background.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change theme-background.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
 
 // 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.
@@ -169,7 +165,6 @@ function resolveLoginTextVisibility(login) {
     subheading: own.hideSubheading !== true,
   };
 }
-
 module.exports = {
   LOGIN_TEXT_MAX_LENGTH,
   normaliseThemeGradient,

package/dist/theme-components.cjs

@@ -1,10 +1,8 @@
-// CommonJS mirror of theme-components.js — the Mason build runner (CJS)
-// validates a `set_theme` components blob against the SAME vocabulary the hosts
-// apply, so what a planner may persist and what a widget renders cannot diverge.
-//
-// The BODY below is copied VERBATIM from theme-components.js; only the module
-// syntax differs. theme-components-parity.test.js pins both facts — identical
-// bodies AND identical behaviour over a shared case table — so drift fails CI.
+// GENERATED from theme-components.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change theme-components.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
+
+const { CONTRACT, normaliseComponentGradient } = require("./contract.cjs");
 
 // REQ-THEME-15 (sc-1497) — the host side of per-component style tokens.
 //
@@ -23,7 +21,6 @@
 // widget reads. The Mason build runner validates `set_theme` against the SAME
 // literal, so what a planner may emit and what a host applies cannot diverge.
 
-const { CONTRACT, normaliseComponentGradient } = require("./contract.cjs");
 
 // 3-, 6- and 8-digit hex, matching what the build runner persists — the host
 // must never drop a colour the runner already accepted.
@@ -402,5 +399,11 @@ function applyThemeComponentStyle(manifestId, theme, props, styleSchema) {
   const authored = isPlainObject(base.style) ? base.style : null;
   return { ...base, style: { ...themed, ...authored } };
 }
-
-module.exports = { normaliseThemeComponents, normaliseWidgetStyleFields, normaliseWidgetStyles, applyThemeComponentStyle, styleValueBytes, MAX_STYLE_STRING_LENGTH };
+module.exports = {
+  normaliseThemeComponents,
+  MAX_STYLE_STRING_LENGTH,
+  styleValueBytes,
+  normaliseWidgetStyleFields,
+  normaliseWidgetStyles,
+  applyThemeComponentStyle,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.276.0",
+  "version": "0.277.1",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -61,7 +61,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "generate:contract": "node scripts/contract-cjs.js",
+    "generate:cjs": "node scripts/generate-cjs.js",
     "test": "node --test \"src/__tests__/*.test.js\""
   },
   "engines": {

package/src/contract.js

@@ -1,7 +1,7 @@
 // The widget SDK contract: the ONE source the linter, the AI agents, the
 // compiler and both hosts read. `contract.cjs` is GENERATED from `contract.js`
-// (`npm run generate:contract`) for CommonJS consumers — never edit it by hand;
-// contract-cjs-generated.test.js fails when it is stale.
+// (`npm run generate:cjs`) for CommonJS consumers — never edit it by hand;
+// cjs-generated.test.js fails when it is stale.
 
 // REQ-AI-AGENT-DESIGN (sc-3696): the ONE cross-platform elevation vocabulary.
 // `shadow*` applies on iOS + react-native-web, `elevation` drives Android.