@colixsystems/widget-sdk 0.111.0 → 0.113.0

package/README.md

@@ -37,6 +37,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
 | **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
 | **CORE** | `useSpeechToText(options?)` | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
+| **CORE** | `useCamera(options?)` | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (file input) and the Expo export (`expo-image-picker`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
@@ -69,8 +70,55 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.111.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.112.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.113.0 (contract 1.86.0)
+
+**New `useCamera()` hook — take a photo or pick one from the device library.** A new CORE hook reading a new `camera` capability on the existing `ctx.device` slice. Returns `{ asset, loading, error, supported, capture, pick, reset }`. Capture is **imperative** — call `capture()` or `pick()` from a user gesture (a `Pressable.onPress`); the browser and the mobile OS gate the permission prompt on a gesture, so it NEVER opens on mount. `options` (`{ allowsEditing, quality }`) pass through to the host. It needs **no manifest scope** and **no `requestedScopes` entry**.
+
+**Dismissing the picker resolves `null`, not an error.** Backing out is the most common outcome, so it is deliberately not a rejection — your happy path needs no `try/catch`. A genuine failure (permission refused, no host broker) rejects with a structured `CameraError` (new named export) carrying a stable `.code` (`PERMISSION_DENIED` / `UNSUPPORTED` / `INTERNAL`).
+
+**One upload path on both hosts.** The resolved asset is normalised to `{ uri, name, mimeType, width, height, size, file }`, where `uri` is directly displayable (`<Image source={{ uri }} />`) and `file` is already the right upload part for the platform — a `File` on web, a `{ uri, name, type }` triple on native. So the same three lines work everywhere:
+
+```js
+const fd = new FormData();
+fd.append("file", asset.file);
+await ctx.assets.upload(fd);
+```
+
+`options` (`{ allowsEditing, quality }`) are **hints**: the Expo export applies both, the web file input applies neither — so never depend on a cropped result or a capped file size. `reset()` clears the asset and releases it (on web that revokes the blob URL, which otherwise leaks for the life of the document). **Gate your camera button on `supported`** — a host that brokers no camera reports `false` rather than throwing. The web Player brokers it via a file input (`capture="environment"` opens the camera on a phone); the Expo export via `expo-image-picker`, whose config plugin declares the camera and photo-library permissions the runtime needs.
+
+Additive — one new hook, one new optional context-slice member; no existing export changed signature.
+
+
+### What's new in 0.112.0 (contract unchanged at 1.85.0)
+
+**Two linter rules make the styling contract checkable, and `lintStyleWiring` joins the linter export (sc-6455).** Every visual value a widget writes reaches the app's owner through one of exactly two channels — a **theme token** (`useTheme()`), which is the app-wide default and follows a look change, or a **`styleSchema` field** read off `props.style`, which the Studio offers per instance in the widget editor *and* app-wide under **Design → Widget appearance**. A literal reaches neither: it outranks the theme permanently and no control on either surface can move it, so the owner finds a corner of their app they cannot restyle. Until now that rule was documentation only.
+
+- **`no-hardcoded-design`** flags a colour literal (`#rgb` / `#rrggbb` / `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`), a `fontFamily` string literal, or a numeric `fontSize`. A `fontSize` resolved off a theme token or a style field (`style.valueSize ?? 18`) is *not* flagged — a literal `default` beside a declared field is the contract working. Raw `padding` / `margin` / `borderRadius` numbers are deliberately out of scope: measured layout legitimately carries them, so a spacing rule would be noise.
+- **`style-field-unread`** flags a `styleSchema` field whose name appears nowhere in the widget's source — a dead control the author moves to no effect. It runs over the WHOLE bundle, not per file, so a split-impl widget that reads a field in `widget.web.jsx` and not in `widget.native.jsx` is correctly counted as wired.
+
+A value that genuinely cannot be a token — a categorical series palette, a video letterbox, a scannable QR plate — is licensed with a preceding comment. **The reason is mandatory**; a bare marker licenses nothing. A marker on its own line covers the whole statement below it (bracket-balanced, so one marker covers a multi-line palette); a trailing marker covers only its own line.
+
+```js
+// appstudio-design-ok: categorical series identity cannot come from one accent
+const SERIES = ["#ff6b5b", "#3b82f6", "#10b981"];
+
+const letterbox = { backgroundColor: "#000" }; // appstudio-design-ok: video letterbox
+```
+
+Both rules are **warning** severity, so `appstudio-widget lint` reports them and still exits 0 — you decide when to act on them. They are **blocking** for the AI widget agent, which publishes with no human in the loop.
+
+`lint` now takes a whole bundle, and `--manifest` enables the wiring check:
+
+```sh
+npx appstudio-widget lint widget.web.jsx widget.native.jsx --manifest manifest.js
+```
+
+```js
+import { lintStyleWiring } from "@colixsystems/widget-sdk/linter";
+const report = lintStyleWiring(manifest, { "widget.jsx": source });
+```
 ### What's new in 0.111.0 (contract 1.85.0)
 
 **Each side can be spaced on its own — the `spacing` property type (sc-6447).** Padding and margin were single numbers, so every inset applied to all four sides at once: a hero with generous top padding and none at the bottom, or a card held off only its left neighbour, had no expression. `cornerRadius` already offered each corner (0.104.0); padding and margin were the last four-valued members of the box model that did not.
@@ -1292,16 +1340,23 @@ that renders on one platform and blanks on the other.
 ## Linter
 
 ```sh
-npx appstudio-widget lint path/to/widget.js
+npx appstudio-widget lint path/to/widget.jsx
+npx appstudio-widget lint widget.web.jsx widget.native.jsx --manifest manifest.js
 ```
 
-Scans for banned patterns (`eval`, `new Function`, dynamic `import()`, direct imports of host stores, raw axios). Exits 1 on findings.
+Scans for banned patterns (`eval`, `new Function`, dynamic `import()`, direct imports of host stores, raw axios) and for the styling rules below. **Only error-severity findings change the exit code**; warnings print and exit 0.
 
 ```js
-import { lintSource } from "@colixsystems/widget-sdk/linter";
-const report = lintSource(source);
+import { lintSource, lintStyleWiring } from "@colixsystems/widget-sdk/linter";
+const report = lintSource(source, { manifest });
+// Bundle-level — pass every file the widget ships:
+const wiring = lintStyleWiring(manifest, { "widget.jsx": source });
 ```
 
+Two rules keep a widget's look reachable from the Studio (sc-6455). `no-hardcoded-design` flags a colour literal, a `fontFamily` string, or a numeric `fontSize` — values that outrank the theme permanently and that no control can move. `style-field-unread` flags a `styleSchema` field the source never reads, which renders a control that does nothing. Both are warnings for a human author and blocking for the AI widget agent. License a genuinely un-tokenizable value with a preceding `// appstudio-design-ok: <reason>` (the reason is required); see *What's new in 0.110.0*.
+
+Pass `--manifest` to enable `style-field-unread` — it needs the manifest, and it needs every source at once so a split-impl widget's per-host field reads are seen together.
+
 ## Local dev loop (`appstudio-widget dev`)
 
 Author a marketplace widget with live reload instead of the publish → submit →

package/dist/cli.js

@@ -1,19 +1,22 @@
 #!/usr/bin/env node
 // CLI entry for `appstudio-widget`.
-//   appstudio-widget lint <path>                          — validate a widget source
+//   appstudio-widget lint <file.jsx...> [--manifest path]  — validate a widget bundle
 //   appstudio-widget dev <entry.jsx> [--port N] [--manifest path]
 //                                                          — REQ-WSDK-DEVKIT local dev server
 
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { argv, exit, stderr, stdout } from "node:process";
-import { lintSource } from "./linter.js";
+import { lintSource, lintStyleWiring } from "./linter.js";
 import { startDevServer } from "./devserver.js";
 
 function usage() {
   stderr.write(
     "Usage:\n" +
-      "  appstudio-widget lint <path>\n" +
+      "  appstudio-widget lint <file.jsx...> [--manifest <path>]\n" +
+      "    Pass every file the widget ships plus --manifest to also check " +
+      "that each styleSchema field is actually read.\n" +
       "  appstudio-widget dev <entry.jsx|widget-dir> [--port <n>] [--manifest <path>]\n" +
       "    A directory containing widget.json runs in multi-file mode " +
       "(REQ-WSDK-DEVKIT v2): the dev server reads the canonical web entry, " +
@@ -49,34 +52,84 @@ function parseFlags(args) {
   return { flags, positionals };
 }
 
-function runLint(rest) {
-  if (rest.length === 0) usage();
-  const filePath = resolve(rest[0]);
-  let source;
-  try {
-    source = readFileSync(filePath, "utf8");
-  } catch (err) {
-    stderr.write(`Could not read ${filePath}: ${err.message}\n`);
-    exit(1);
+async function loadManifest(path) {
+  const abs = resolve(path);
+  if (abs.endsWith(".json")) return JSON.parse(readFileSync(abs, "utf8"));
+  const mod = await import(pathToFileURL(abs).href);
+  return mod.default || mod.manifest || mod;
+}
+
+function writeFindings(findings, stream) {
+  for (const f of findings) {
+    const severity = f.severity === "warning" ? "warning" : "error";
+    const where = f.line ? ` line ${f.line}` : "";
+    stream.write(
+      `  ${severity} [${f.rule}]${where}: ${f.label}\n    ${f.snippet}\n`,
+    );
+  }
+}
+
+// sc-6455 — lint a BUNDLE, not just a file. The dead-control gate has to see
+// every source at once: a split-impl widget legitimately reads a style field
+// in widget.web.jsx and not in widget.native.jsx, and checking one file alone
+// would call that field dead. Pass --manifest to enable it; a single file
+// with no manifest lints exactly as it always did.
+async function runLint(rest) {
+  const { flags, positionals } = parseFlags(rest);
+  if (positionals.length === 0) usage();
+  const files = {};
+  for (const p of positionals) {
+    const filePath = resolve(p);
+    try {
+      files[filePath] = readFileSync(filePath, "utf8");
+    } catch (err) {
+      stderr.write(`Could not read ${filePath}: ${err.message}\n`);
+      exit(1);
+    }
+  }
+  let manifest = null;
+  if (typeof flags.manifest === "string") {
+    try {
+      manifest = await loadManifest(flags.manifest);
+    } catch (err) {
+      stderr.write(
+        `Could not read manifest ${flags.manifest}: ${err.message}\n`,
+      );
+      exit(1);
+    }
   }
-  const { ok, findings } = lintSource(source);
-  if (findings.length === 0) {
-    stdout.write(`${filePath}: clean\n`);
+  const label = positionals.join(", ");
+  const perFile = Object.entries(files).map(([filePath, source]) => [
+    filePath,
+    lintSource(source, manifest ? { manifest } : undefined),
+  ]);
+  const wiring = manifest
+    ? lintStyleWiring(manifest, files)
+    : { ok: true, findings: [] };
+  const all = perFile
+    .flatMap(([, r]) => r.findings)
+    .concat(wiring.findings);
+  if (all.length === 0) {
+    stdout.write(`${label}: clean\n`);
     exit(0);
   }
   // sc-3493 — a warning-severity finding used to be swallowed: `ok` stays true
   // for warnings, so the CLI printed "clean" and dropped them. A warning nobody
   // sees is pointless. Report every finding; only errors change the exit code.
-  const errors = findings.filter((f) => f.severity !== "warning").length;
+  const ok = perFile.every(([, r]) => r.ok) && wiring.ok;
+  const errors = all.filter((f) => f.severity !== "warning").length;
   const stream = ok ? stdout : stderr;
   stream.write(
-    `${filePath}: ${errors} error(s), ${findings.length - errors} warning(s)\n`,
+    `${label}: ${errors} error(s), ${all.length - errors} warning(s)\n`,
   );
-  for (const f of findings) {
-    const severity = f.severity === "warning" ? "warning" : "error";
-    stream.write(
-      `  ${severity} [${f.rule}] line ${f.line}: ${f.label}\n    ${f.snippet}\n`,
-    );
+  for (const [filePath, r] of perFile) {
+    if (r.findings.length === 0) continue;
+    if (perFile.length > 1) stream.write(`${filePath}:\n`);
+    writeFindings(r.findings, stream);
+  }
+  if (wiring.findings.length > 0) {
+    stream.write(`manifest.styleSchema:\n`);
+    writeFindings(wiring.findings, stream);
   }
   exit(ok ? 0 : 1);
 }

package/dist/contract.cjs

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

package/dist/contract.js

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

package/dist/hooks.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/index.native.js

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

package/dist/linter.cjs

@@ -1234,6 +1234,165 @@ function narrowManifestForFile(manifest, filename) {
   return manifest;
 }
 
+// sc-6455 — the design-token gate. A widget's look must come from the theme
+// (`useTheme()`) or from a `styleSchema` field the author can move. A literal
+// colour or font pinned in the source outranks BOTH permanently, so neither
+// the workspace theme nor Design -> Widget appearance can ever reach it.
+//
+// Deliberately narrow: colour literals, a `fontFamily` string, and a bare
+// numeric `fontSize`. Raw padding/margin/borderRadius numbers are NOT flagged
+// — measured layout legitimately carries them (a `flexBasis` cell width the
+// designer skill itself teaches), so a spacing rule would be noise that
+// devalues the three unambiguous ones.
+const _DESIGN_HEX_RE =
+  /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![0-9a-fA-F])/;
+const _DESIGN_FUNC_COLOR_RE = /\b(?:rgba?|hsla?)\s*\(/;
+const _DESIGN_FONT_FAMILY_RE = /\bfontFamily\s*:\s*["'`]\s*\S/;
+const _DESIGN_FONT_SIZE_RE = /\bfontSize\s*:\s*-?\d/;
+// A line that already reads the theme or the author's style object is
+// resolving a DECLARED fallback, not pinning a look — `style.valueSize ?? 18`
+// is exactly what a styleSchema `default` is for. Colour literals are held to
+// the stricter bar: `theme.colors` always has a role to fall back to.
+const _DESIGN_TOKEN_REF_RE = /\btheme\s*[.?[]|\bstyle\s*[.?[]|\bprops\.style\b/;
+const _DESIGN_OK_RE = /appstudio-design-ok\s*:\s*\S/;
+
+/**
+ * Lines licensed by an `// appstudio-design-ok: <reason>` marker.
+ *
+ * The reason is mandatory — a bare marker licenses nothing. A TRAILING marker
+ * covers only its own line; a marker on its OWN line covers the statement
+ * that follows it, bracket-balanced, so a multi-line categorical palette needs
+ * one marker rather than forty. Balance is counted on brace-blanked code so a
+ * bracket inside a string cannot unbalance the span.
+ */
+function _designExemptLines(source) {
+  const lines = source.split(/\r?\n/);
+  const balance = _stripNonCode(source).split(/\r?\n/);
+  const exempt = new Set();
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!_DESIGN_OK_RE.test(lines[i])) continue;
+    exempt.add(i + 1);
+    if (!/^\s*(?:\/\/|\/\*|\*)/.test(lines[i])) continue;
+    let depth = 0;
+    let started = false;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      exempt.add(j + 1);
+      const text = balance[j] || "";
+      if (!started && text.trim() === "") continue;
+      for (const ch of text) {
+        if (ch === "(" || ch === "[" || ch === "{") {
+          depth += 1;
+          started = true;
+        } else if (ch === ")" || ch === "]" || ch === "}") {
+          depth -= 1;
+        }
+      }
+      if (started && depth <= 0) break;
+      if (!started) break;
+    }
+  }
+  return exempt;
+}
+
+function _hardcodedDesignRules(source) {
+  // Comments blanked, string CONTENT kept — a colour literal IS a string.
+  const code = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  const exempt = _designExemptLines(source);
+  const findings = [];
+  for (let i = 0; i < code.length; i += 1) {
+    if (exempt.has(i + 1)) continue;
+    const line = code[i];
+    let what = null;
+    if (_DESIGN_HEX_RE.test(line) || _DESIGN_FUNC_COLOR_RE.test(line)) {
+      what = "a colour literal";
+    } else if (_DESIGN_FONT_FAMILY_RE.test(line)) {
+      what = "a font-family name";
+    } else if (
+      _DESIGN_FONT_SIZE_RE.test(line) &&
+      !_DESIGN_TOKEN_REF_RE.test(line)
+    ) {
+      what = "a pixel font size";
+    }
+    if (!what) continue;
+    findings.push({
+      rule: "no-hardcoded-design",
+      severity: "warning",
+      label:
+        `${what} pinned in the source is beyond the reach of BOTH the ` +
+        `workspace theme and the author's Style controls. Read it from ` +
+        `useTheme() (theme.colors.* / theme.typography.*), or declare a ` +
+        `styleSchema field and apply props.style.<field>. License a value ` +
+        `that truly cannot be a token — a series palette, a video ` +
+        `letterbox, a QR plate — with a preceding ` +
+        `"// appstudio-design-ok: <reason>".`,
+      line: i + 1,
+      snippet: (sourceLines[i] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+/**
+ * sc-6455 — a `styleSchema` field the bundle never mentions is a DEAD
+ * control: the Studio renders it in the widget editor and again on
+ * Design -> Widget appearance, the author moves it, and nothing happens.
+ *
+ * Bundle-level, NOT per-file. A split-impl widget legitimately reads a field
+ * in `widget.web.jsx` and not in `widget.native.jsx`, so a per-file scan
+ * would flag every one of them — which is also why this cannot live inside
+ * `lintSource`.
+ *
+ * Deliberately conservative: the field counts as wired when its NAME appears
+ * anywhere in any file's code, so `style.cardRadius`, `style["cardRadius"]`
+ * and `const { cardRadius } = style` all satisfy it. That leaves a field
+ * mentioned but misapplied uncaught, and catches the one that reaches an
+ * author — declared, then forgotten.
+ *
+ * @param {object} manifest widget manifest (reads `styleSchema` only)
+ * @param {object|string[]|string} files bundle sources — a `{ name: source }`
+ *   map, an array of sources, or one source string
+ * @returns {{ ok: boolean, findings: Array<{ rule: string, severity: string, label: string, line: number, snippet: string }> }}
+ */
+function lintStyleWiring(manifest, files) {
+  const empty = { ok: true, findings: [] };
+  const schema = manifest && manifest.styleSchema;
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return empty;
+  }
+  let sources = [];
+  if (typeof files === "string") sources = [files];
+  else if (Array.isArray(files)) sources = files;
+  else if (files && typeof files === "object") sources = Object.values(files);
+  sources = sources.filter((s) => typeof s === "string" && s.length > 0);
+  if (sources.length === 0) return empty;
+  const code = sources
+    .map((s) => _stripNonCode(s, { keepStrings: true }))
+    .join("\n");
+  const findings = [];
+  for (const field of Object.keys(schema)) {
+    // A key that is not a bare identifier cannot be scanned by name; the
+    // manifest validator rejects those anyway.
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) continue;
+    if (new RegExp(`\\b${field}\\b`).test(code)) continue;
+    findings.push({
+      rule: "style-field-unread",
+      severity: "warning",
+      label:
+        `manifest.styleSchema declares "${field}" but the name appears ` +
+        `nowhere in the source, so the control the Studio renders for it ` +
+        `— per instance, and app-wide under Design -> Widget appearance — ` +
+        `moves nothing. Read it from props.style and apply it ONLY when ` +
+        `set, so the theme still shows through while the author has chosen ` +
+        `none. If it is not styleable, drop it from styleSchema instead.`,
+      line: 0,
+      snippet: field,
+    });
+  }
+  const hasErrors = findings.some((f) => f.severity !== "warning");
+  return { ok: !hasErrors, findings };
+}
+
 function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -1286,6 +1445,8 @@ function lintSource(source, options) {
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));
+  // sc-6455 — soft warning: a colour/font literal the theme can never reach.
+  findings.push(..._hardcodedDesignRules(source));
   findings.push(..._writeGatedOnUserRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
@@ -1306,4 +1467,9 @@ function lintSource(source, options) {
   return { ok: !hasErrors, findings };
 }
 
-module.exports = { lintSource, bannedIdentifiers, narrowManifestForFile };
+module.exports = {
+  lintSource,
+  lintStyleWiring,
+  bannedIdentifiers,
+  narrowManifestForFile,
+};

package/dist/linter.js

@@ -1409,6 +1409,165 @@ export function narrowManifestForFile(manifest, filename) {
   return manifest;
 }
 
+// sc-6455 — the design-token gate. A widget's look must come from the theme
+// (`useTheme()`) or from a `styleSchema` field the author can move. A literal
+// colour or font pinned in the source outranks BOTH permanently, so neither
+// the workspace theme nor Design -> Widget appearance can ever reach it.
+//
+// Deliberately narrow: colour literals, a `fontFamily` string, and a bare
+// numeric `fontSize`. Raw padding/margin/borderRadius numbers are NOT flagged
+// — measured layout legitimately carries them (a `flexBasis` cell width the
+// designer skill itself teaches), so a spacing rule would be noise that
+// devalues the three unambiguous ones.
+const _DESIGN_HEX_RE =
+  /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![0-9a-fA-F])/;
+const _DESIGN_FUNC_COLOR_RE = /\b(?:rgba?|hsla?)\s*\(/;
+const _DESIGN_FONT_FAMILY_RE = /\bfontFamily\s*:\s*["'`]\s*\S/;
+const _DESIGN_FONT_SIZE_RE = /\bfontSize\s*:\s*-?\d/;
+// A line that already reads the theme or the author's style object is
+// resolving a DECLARED fallback, not pinning a look — `style.valueSize ?? 18`
+// is exactly what a styleSchema `default` is for. Colour literals are held to
+// the stricter bar: `theme.colors` always has a role to fall back to.
+const _DESIGN_TOKEN_REF_RE = /\btheme\s*[.?[]|\bstyle\s*[.?[]|\bprops\.style\b/;
+const _DESIGN_OK_RE = /appstudio-design-ok\s*:\s*\S/;
+
+/**
+ * Lines licensed by an `// appstudio-design-ok: <reason>` marker.
+ *
+ * The reason is mandatory — a bare marker licenses nothing. A TRAILING marker
+ * covers only its own line; a marker on its OWN line covers the statement
+ * that follows it, bracket-balanced, so a multi-line categorical palette needs
+ * one marker rather than forty. Balance is counted on brace-blanked code so a
+ * bracket inside a string cannot unbalance the span.
+ */
+function _designExemptLines(source) {
+  const lines = source.split(/\r?\n/);
+  const balance = _stripNonCode(source).split(/\r?\n/);
+  const exempt = new Set();
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!_DESIGN_OK_RE.test(lines[i])) continue;
+    exempt.add(i + 1);
+    if (!/^\s*(?:\/\/|\/\*|\*)/.test(lines[i])) continue;
+    let depth = 0;
+    let started = false;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      exempt.add(j + 1);
+      const text = balance[j] || "";
+      if (!started && text.trim() === "") continue;
+      for (const ch of text) {
+        if (ch === "(" || ch === "[" || ch === "{") {
+          depth += 1;
+          started = true;
+        } else if (ch === ")" || ch === "]" || ch === "}") {
+          depth -= 1;
+        }
+      }
+      if (started && depth <= 0) break;
+      if (!started) break;
+    }
+  }
+  return exempt;
+}
+
+function _hardcodedDesignRules(source) {
+  // Comments blanked, string CONTENT kept — a colour literal IS a string.
+  const code = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  const exempt = _designExemptLines(source);
+  const findings = [];
+  for (let i = 0; i < code.length; i += 1) {
+    if (exempt.has(i + 1)) continue;
+    const line = code[i];
+    let what = null;
+    if (_DESIGN_HEX_RE.test(line) || _DESIGN_FUNC_COLOR_RE.test(line)) {
+      what = "a colour literal";
+    } else if (_DESIGN_FONT_FAMILY_RE.test(line)) {
+      what = "a font-family name";
+    } else if (
+      _DESIGN_FONT_SIZE_RE.test(line) &&
+      !_DESIGN_TOKEN_REF_RE.test(line)
+    ) {
+      what = "a pixel font size";
+    }
+    if (!what) continue;
+    findings.push({
+      rule: "no-hardcoded-design",
+      severity: "warning",
+      label:
+        `${what} pinned in the source is beyond the reach of BOTH the ` +
+        `workspace theme and the author's Style controls. Read it from ` +
+        `useTheme() (theme.colors.* / theme.typography.*), or declare a ` +
+        `styleSchema field and apply props.style.<field>. License a value ` +
+        `that truly cannot be a token — a series palette, a video ` +
+        `letterbox, a QR plate — with a preceding ` +
+        `"// appstudio-design-ok: <reason>".`,
+      line: i + 1,
+      snippet: (sourceLines[i] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
+/**
+ * sc-6455 — a `styleSchema` field the bundle never mentions is a DEAD
+ * control: the Studio renders it in the widget editor and again on
+ * Design -> Widget appearance, the author moves it, and nothing happens.
+ *
+ * Bundle-level, NOT per-file. A split-impl widget legitimately reads a field
+ * in `widget.web.jsx` and not in `widget.native.jsx`, so a per-file scan
+ * would flag every one of them — which is also why this cannot live inside
+ * `lintSource`.
+ *
+ * Deliberately conservative: the field counts as wired when its NAME appears
+ * anywhere in any file's code, so `style.cardRadius`, `style["cardRadius"]`
+ * and `const { cardRadius } = style` all satisfy it. That leaves a field
+ * mentioned but misapplied uncaught, and catches the one that reaches an
+ * author — declared, then forgotten.
+ *
+ * @param {object} manifest widget manifest (reads `styleSchema` only)
+ * @param {object|string[]|string} files bundle sources — a `{ name: source }`
+ *   map, an array of sources, or one source string
+ * @returns {{ ok: boolean, findings: Array<{ rule: string, severity: string, label: string, line: number, snippet: string }> }}
+ */
+export function lintStyleWiring(manifest, files) {
+  const empty = { ok: true, findings: [] };
+  const schema = manifest && manifest.styleSchema;
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return empty;
+  }
+  let sources = [];
+  if (typeof files === "string") sources = [files];
+  else if (Array.isArray(files)) sources = files;
+  else if (files && typeof files === "object") sources = Object.values(files);
+  sources = sources.filter((s) => typeof s === "string" && s.length > 0);
+  if (sources.length === 0) return empty;
+  const code = sources
+    .map((s) => _stripNonCode(s, { keepStrings: true }))
+    .join("\n");
+  const findings = [];
+  for (const field of Object.keys(schema)) {
+    // A key that is not a bare identifier cannot be scanned by name; the
+    // manifest validator rejects those anyway.
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field)) continue;
+    if (new RegExp(`\\b${field}\\b`).test(code)) continue;
+    findings.push({
+      rule: "style-field-unread",
+      severity: "warning",
+      label:
+        `manifest.styleSchema declares "${field}" but the name appears ` +
+        `nowhere in the source, so the control the Studio renders for it ` +
+        `— per instance, and app-wide under Design -> Widget appearance — ` +
+        `moves nothing. Read it from props.style and apply it ONLY when ` +
+        `set, so the theme still shows through while the author has chosen ` +
+        `none. If it is not styleable, drop it from styleSchema instead.`,
+      line: 0,
+      snippet: field,
+    });
+  }
+  const hasErrors = findings.some((f) => f.severity !== "warning");
+  return { ok: !hasErrors, findings };
+}
+
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -1466,6 +1625,8 @@ export function lintSource(source, options) {
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));
+  // sc-6455 — soft warning: a colour/font literal the theme can never reach.
+  findings.push(..._hardcodedDesignRules(source));
   findings.push(..._writeGatedOnUserRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.111.0",
+  "version": "0.113.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js"
   },
   "engines": {
     "node": ">=18"