@colixsystems/widget-sdk 0.110.0 → 0.112.0

package/README.md

@@ -69,7 +69,50 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.110.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.
+
+Declare `{ type: "spacing", label: "Padding", validation: { min: 0, max: 64 } }` in your `propertySchema` or `styleSchema`. The Studio renders a slider with a typeable number that sets all four sides, plus a disclosure for setting each one. The authored value is `number | { top, right, bottom, left }` — the scalar form is unchanged, so every value stored before is still valid.
+
+```js
+import { normaliseSpacing, spacingStyle } from "@colixsystems/widget-sdk";
+
+const padding = normaliseSpacing(props.style?.padding, 0, 64);
+return <View style={[styles.card, spacingStyle(padding, "padding")]} />;
+```
+
+`normaliseSpacing(value, fallback, max)` returns all four sides resolved and clamped; `spacingStyle(spacing, property, format)` emits the `padding`/`margin` shorthand when the sides agree and the four long-hand props when they differ (pass `` n => `${n}px` `` for the DOM). `mapSpacing` pushes each side through your own scaling, `isUniformSpacing` and `isZeroSpacing` round out the set. `CONTRACT.version` → `1.85.0`. Additive: every value accepted before is accepted now.
 
 ### What's new in 0.110.0 (contract 1.84.0)
 
@@ -1277,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/contract.cjs

@@ -3374,7 +3374,19 @@ const CONTRACT = deepFreeze({
   //    one `headerTintColor` cannot express; an authored `topBar.textColor`
   //    drives both. `show` is deliberately absent -- it depends on the menu
   //    type, not the theme, and is a no-op on native.
-  version: "1.84.0",
+  //
+  // 1.85.0: additive (sc-6447) — the `spacing` property type: a padding or
+  //    margin value is `number | { top, right, bottom, left }`, resolved by
+  //    `normaliseSpacing` and emitted by `spacingStyle(resolved, "padding" |
+  //    "margin")`. Padding and margin were the last four-valued members of the
+  //    box model an author could only set on all sides at once, while
+  //    `cornerRadius` (1.79.0) already offered each corner — so the same
+  //    master-plus-disclosure control now backs all three. The scalar form is
+  //    unchanged and still emits the shorthand, so an existing style renders
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3374,7 +3374,19 @@ const CONTRACT = deepFreeze({
   //    one `headerTintColor` cannot express; an authored `topBar.textColor`
   //    drives both. `show` is deliberately absent -- it depends on the menu
   //    type, not the theme, and is a no-op on native.
-  version: "1.84.0",
+  //
+  // 1.85.0: additive (sc-6447) — the `spacing` property type: a padding or
+  //    margin value is `number | { top, right, bottom, left }`, resolved by
+  //    `normaliseSpacing` and emitted by `spacingStyle(resolved, "padding" |
+  //    "margin")`. Padding and margin were the last four-valued members of the
+  //    box model an author could only set on all sides at once, while
+  //    `cornerRadius` (1.79.0) already offered each corner — so the same
+  //    master-plus-disclosure control now backs all three. The scalar form is
+  //    unchanged and still emits the shorthand, so an existing style renders
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.js

@@ -13,6 +13,14 @@ export {
   cornerRadiusStyle,
   hasCornerRadius,
 } from "./corner-radius.js";
+export {
+  SPACING_KEYS,
+  normaliseSpacing,
+  isUniformSpacing,
+  isZeroSpacing,
+  mapSpacing,
+  spacingStyle,
+} from "./spacing.js";
 export {
   WidgetContextProvider,
   DatastoreError,

package/dist/index.native.js

@@ -13,6 +13,14 @@ export {
   cornerRadiusStyle,
   hasCornerRadius,
 } from "./corner-radius.js";
+export {
+  SPACING_KEYS,
+  normaliseSpacing,
+  isUniformSpacing,
+  isZeroSpacing,
+  mapSpacing,
+  spacingStyle,
+} from "./spacing.js";
 export {
   WidgetContextProvider,
   DatastoreError,

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/dist/property-schema.js

@@ -2,6 +2,7 @@
 // Drives the schema-driven Properties Panel and validates persisted page JSON.
 
 import { CORNER_RADIUS_KEYS } from "./corner-radius.js";
+import { SPACING_KEYS } from "./spacing.js";
 
 const VALID_TYPES = new Set([
   "string", "number", "boolean",
@@ -57,6 +58,13 @@ const VALID_TYPES = new Set([
   // which both hosts spell identically. Plain numbers, so tenant-copy needs
   // no remap.
   "cornerRadius",
+  // REQ-LAY-17 (sc-6447): `spacing` is a padding/margin picker. Its value is
+  // `number | { top, right, bottom, left }` — a scalar spaces all four sides,
+  // the object spaces each independently. The Studio renders a slider +
+  // typeable number with a per-side disclosure; a widget turns the value into
+  // style props with `spacingStyle(normaliseSpacing(v), "padding")`, which both
+  // hosts spell identically. Plain numbers, so tenant-copy needs no remap.
+  "spacing",
   "expression", "eventBinding",
   "object", "array",
 ]);
@@ -192,6 +200,36 @@ function coerceLeaf(def, value, path, errors) {
       }
       return value;
     }
+    case "spacing": {
+      // REQ-LAY-17: a scalar spaces all four sides; an object spaces each.
+      // Every side is optional so a half-set object stays valid while the
+      // author is still adjusting — an unset side falls back to the scalar.
+      const { min = 0, max } = def.validation || {};
+      const checkSide = (n, at) => {
+        if (typeof n !== "number" || Number.isNaN(n)) {
+          errors.push(`${at}: expected number`);
+          return;
+        }
+        if (n < min) errors.push(`${at}: must be >= ${min}`);
+        if (max !== undefined && n > max) errors.push(`${at}: must be <= ${max}`);
+      };
+      if (typeof value === "number") {
+        checkSide(value, path);
+        return value;
+      }
+      if (!isPlainObject(value)) {
+        errors.push(`${path}: expected number or per-side object`);
+        return value;
+      }
+      for (const [k, n] of Object.entries(value)) {
+        if (!SPACING_KEYS.includes(k)) {
+          errors.push(`${path}.${k}: unknown side`);
+        } else if (n !== undefined && n !== null) {
+          checkSide(n, `${path}.${k}`);
+        }
+      }
+      return value;
+    }
     case "select":
       if (Array.isArray(def.enum) && !def.enum.some((e) => e.value === value)) {
         errors.push(`${path}: value not in enum`);

package/dist/spacing.js

@@ -0,0 +1,118 @@
+// REQ-LAY-17 (sc-6447): the per-side spacing vocabulary. ONE normaliser and ONE
+// style emitter for the web Player, the Builder canvas, the exported Expo app,
+// and any custom widget declaring a `padding`/`margin` field — so the four can
+// never disagree about what a spacing value means.
+//
+// The authored value is `number | { top, right, bottom, left }`. The scalar form
+// is what every existing style holds, so it stays first-class rather than being
+// migrated away: widening the shape beats adding a second key beside it
+// (CLAUDE.md §3). This mirrors `corner-radius.js` deliberately — padding/margin
+// and cornerRadius are the four-valued members of one box model, and an author
+// meets the same affordance in both.
+//
+// Both hosts spell the long-hand props identically (`paddingTop` / `marginTop`
+// &co in React inline style AND in React Native), which is why one emitter
+// serves both.
+
+export const SPACING_KEYS = Object.freeze(["top", "right", "bottom", "left"]);
+
+// The CSS/RN suffix per side. `padding` + "Top" and `margin` + "Top" are both
+// valid on web and native, so the property name is the caller's to choose.
+const LONGHAND_SUFFIX = Object.freeze({
+  top: "Top",
+  right: "Right",
+  bottom: "Bottom",
+  left: "Left",
+});
+
+function clampSide(value, fallback, max) {
+  // Unset (undefined/null/"") falls back; an explicit 0 is honoured — that
+  // distinction is what makes "no padding on just this side" expressible.
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  // Truncates, where `corner-radius.js` rounds: padding and margin have always
+  // truncated (`clampInt` / `clampMargin`), and changing that would shift every
+  // existing fractional value by a pixel.
+  return Math.min(Math.max(Math.trunc(n), 0), max);
+}
+
+/**
+ * Resolve an authored spacing to its four sides.
+ *
+ * @param {number|object|null|undefined} value the authored `number | {sides}`
+ * @param {number} [fallback] the value each unset side takes
+ * @param {number} [max] the upper clamp, matching the field's declared max
+ * @returns {{top:number, right:number, bottom:number, left:number}}
+ */
+export function normaliseSpacing(value, fallback = 0, max = 64) {
+  const base = clampSide(
+    typeof value === "number" || typeof value === "string" ? value : undefined,
+    clampSide(fallback, 0, max),
+    max,
+  );
+  const sides = value && typeof value === "object" ? value : null;
+  const out = {};
+  for (const key of SPACING_KEYS) {
+    out[key] = clampSide(sides ? sides[key] : undefined, base, max);
+  }
+  return out;
+}
+
+/** True when all four sides resolve to the same number. */
+export function isUniformSpacing(spacing) {
+  if (!spacing) return true;
+  const { top } = spacing;
+  return SPACING_KEYS.every((key) => spacing[key] === top);
+}
+
+/** True when every side resolves to 0 — i.e. the value asks for no spacing. */
+export function isZeroSpacing(spacing) {
+  return !spacing || SPACING_KEYS.every((key) => !spacing[key]);
+}
+
+/**
+ * Map every side through `fn`, keeping the resolved shape. Used to push each
+ * side through the responsive/theme scaling the scalar form already got, so a
+ * per-side value scales down on a phone exactly like a uniform one.
+ *
+ * @param {object|null} spacing output of {@link normaliseSpacing}
+ * @param {(n: number) => number} fn
+ * @returns {object|null}
+ */
+export function mapSpacing(spacing, fn) {
+  if (!spacing) return null;
+  const out = {};
+  for (const key of SPACING_KEYS) {
+    const next = Number(fn(spacing[key]));
+    out[key] = Number.isFinite(next) ? next : spacing[key];
+  }
+  return out;
+}
+
+/**
+ * The style props for a resolved spacing, in the spelling BOTH hosts accept.
+ * A uniform value emits the shorthand so an untouched style is byte-identical
+ * to what the scalar form produced; only a genuinely mixed value pays for the
+ * four long-hand props.
+ *
+ * This emitter is MECHANICAL — it always emits, including an all-zero value.
+ * The zero policy differs per box property (a container's `padding: 0` has
+ * always been written, while a zero `margin` has always emitted nothing), so it
+ * belongs with each caller via {@link isZeroSpacing}, not baked in here.
+ *
+ * @param {object|null} spacing output of {@link normaliseSpacing}
+ * @param {"padding"|"margin"} [property] which box property to spell
+ * @param {(n: number) => any} [format] wraps each number — the DOM needs "12px"
+ * @returns {object|null}
+ */
+export function spacingStyle(spacing, property = "padding", format) {
+  if (!spacing) return null;
+  const wrap = format || ((n) => n);
+  if (isUniformSpacing(spacing)) return { [property]: wrap(spacing.top) };
+  const out = {};
+  for (const key of SPACING_KEYS) {
+    out[`${property}${LONGHAND_SUFFIX[key]}`] = wrap(spacing[key]);
+  }
+  return out;
+}

package/package.json

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