@colixsystems/widget-sdk 0.111.0 → 0.112.0

package/README.md

@@ -69,8 +69,36 @@ 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.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 +1320,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/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.112.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-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"