@colixsystems/widget-sdk 0.103.0 → 0.105.0

package/README.md

@@ -68,7 +68,29 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.103.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.105.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.105.0 (contract unchanged)
+
+**New linter rule `sdk-export-not-imported` — self-containment now covers the SDK surface, not just `React` (sc-5897).** `react-not-imported` (0.62.0) enforced that a referenced `React` global must be imported, but there was no equivalent rule for the SDK's own exports: source that called `useFilestoreFile(id)` — or rendered `<View>` — without naming it in `import { … } from "@colixsystems/widget-sdk"` linted clean, bundled clean, and threw `ReferenceError: useFilestoreFile is not defined` at render. The two failures are one bug, so they now share one detector, keyed off the names `CONTRACT.hooks` and `CONTRACT.primitives` already enumerate — a hook added to the contract is covered with no second list to maintain.
+
+The scan is AST-free, so it flags only the three reference forms text can decide with certainty: a call `NAME(`, a member read `NAME.` (`StyleSheet.create`), and a JSX element `<NAME`. Any other occurrence of the word — an import specifier, a local declaration or destructure, a property key, JSX text, a comment or string — means a binding the scan cannot see may exist, and the name is abandoned rather than flagged. `error` severity with no opt-out, matching `react-not-imported`. Author fix: add the name to your SDK import. `CONTRACT` is unchanged (no new field).
+### What's new in 0.104.0 (contract 1.79.0)
+
+**Each corner can be rounded on its own — the `cornerRadius` property type.** A radius was a single number, so every rounded surface was rounded on all four corners: a card that meets the screen edge, a tab rounded only on top, or a bubble with one squared corner had no expression.
+
+Declare `{ type: "cornerRadius", label: "Corner radius", validation: { min: 0, max: 48 } }` in your `propertySchema` or `styleSchema`. The Studio renders a slider with a typeable number that sets all four corners, plus a disclosure for setting each one. The authored value is `number | { topLeft, topRight, bottomRight, bottomLeft }` — the scalar form is unchanged, so every value stored before is still valid.
+
+Resolve it with the two new exports rather than reading the raw value, because they hide the shape and spell the style props the way BOTH hosts accept:
+
+```js
+import { normaliseCornerRadius, cornerRadiusStyle } from "@colixsystems/widget-sdk";
+
+const radius = normaliseCornerRadius(style.radius, 0, 48);
+return <View style={[styles.card, cornerRadiusStyle(radius)]} />;
+```
+
+`normaliseCornerRadius(value, fallback, max)` returns all four corners resolved and clamped; `cornerRadiusStyle(radius, format)` emits the `borderRadius` shorthand when they agree and the four long-hand props when they differ (pass `n => `+"`${n}px`"+`` for the DOM). `isUniformCornerRadius` and `hasCornerRadius` round out the set. `CONTRACT.version` → `1.79.0`. Additive: every value accepted before is accepted now.
 
 ### What's new in 0.103.0 (contract 1.78.0)
 

package/dist/contract.cjs

@@ -239,6 +239,15 @@ const FORM_SUBMIT_FIELDS = Object.freeze({
   gradient: "submitGradient",
 });
 
+// The Link card's action button -- its own `button*` names, kept distinct from
+// the card surface the button sits on.
+const LINK_ACTION_FIELDS = Object.freeze({
+  background: "buttonBackground",
+  textColor: "buttonTextColor",
+  gradient: "buttonGradient",
+  radius: "buttonRadius",
+});
+
 // REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
 // ANY widget that reads them -- including a Mason-generated one, whose id can
 // never appear in a hand-maintained allowlist. That allowlist is why "make the
@@ -308,6 +317,8 @@ const THEME_COMPONENTS = Object.freeze({
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
+      // sc-5757: the Link card's action button, so the button scope reaches it.
+      "appstudio.link": LINK_ACTION_FIELDS,
     }),
   }),
   card: Object.freeze({
@@ -331,6 +342,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
       "appstudio.user-management": CARD_SURFACE_FIELDS,
+      "appstudio.link": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -3275,6 +3287,9 @@ const CONTRACT = deepFreeze({
   //    PAGE_ROUTES maps both to the screen name), but the contract said
   //    `pageId` only, so data-driven widgets — whose rows carry slugs —
   //    invented params patterns that navigate nowhere. No code changed shape.
+  // 1.79.0: additive (sc-5890) — the `cornerRadius` property type: a radius
+  // value is `number | { topLeft, topRight, bottomRight, bottomLeft }`, resolved
+  // by `normaliseCornerRadius` and emitted by `cornerRadiusStyle`.
   // 1.78.0: additive (sc-5646) — `widgetStyles` carries every value shape a
   //    `styleSchema` field can produce, not just scalars and gradients. The
   //    Studio offers the SAME field in the widget editor and in Theme
@@ -3286,7 +3301,7 @@ const CONTRACT = deepFreeze({
   //    per-scalar limits never stated, so the worst-case unauthenticated
   //    payload is SMALLER than before. `__proto__`-style keys are refused at
   //    every level. Additive: every value accepted before is accepted now.
-  version: "1.78.0",
+  version: "1.79.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -239,6 +239,15 @@ const FORM_SUBMIT_FIELDS = Object.freeze({
   gradient: "submitGradient",
 });
 
+// The Link card's action button -- its own `button*` names, kept distinct from
+// the card surface the button sits on.
+const LINK_ACTION_FIELDS = Object.freeze({
+  background: "buttonBackground",
+  textColor: "buttonTextColor",
+  gradient: "buttonGradient",
+  radius: "buttonRadius",
+});
+
 // REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
 // ANY widget that reads them -- including a Mason-generated one, whose id can
 // never appear in a hand-maintained allowlist. That allowlist is why "make the
@@ -308,6 +317,8 @@ const THEME_COMPONENTS = Object.freeze({
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
+      // sc-5757: the Link card's action button, so the button scope reaches it.
+      "appstudio.link": LINK_ACTION_FIELDS,
     }),
   }),
   card: Object.freeze({
@@ -331,6 +342,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
       "appstudio.user-management": CARD_SURFACE_FIELDS,
+      "appstudio.link": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -3275,6 +3287,9 @@ const CONTRACT = deepFreeze({
   //    PAGE_ROUTES maps both to the screen name), but the contract said
   //    `pageId` only, so data-driven widgets — whose rows carry slugs —
   //    invented params patterns that navigate nowhere. No code changed shape.
+  // 1.79.0: additive (sc-5890) — the `cornerRadius` property type: a radius
+  // value is `number | { topLeft, topRight, bottomRight, bottomLeft }`, resolved
+  // by `normaliseCornerRadius` and emitted by `cornerRadiusStyle`.
   // 1.78.0: additive (sc-5646) — `widgetStyles` carries every value shape a
   //    `styleSchema` field can produce, not just scalars and gradients. The
   //    Studio offers the SAME field in the widget editor and in Theme
@@ -3286,7 +3301,7 @@ const CONTRACT = deepFreeze({
   //    per-scalar limits never stated, so the worst-case unauthenticated
   //    payload is SMALLER than before. `__proto__`-style keys are refused at
   //    every level. Additive: every value accepted before is accepted now.
-  version: "1.78.0",
+  version: "1.79.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/corner-radius.js

@@ -0,0 +1,95 @@
+// REQ-LAY-16 (sc-5890): the per-corner radius vocabulary. ONE normaliser and
+// ONE style emitter for the web Player, the Builder canvas, the exported Expo
+// app, and any custom widget declaring a `cornerRadius` field — so the four can
+// never disagree about what a radius value means.
+//
+// The authored value is `number | { topLeft, topRight, bottomRight, bottomLeft }`.
+// The scalar form is the one sc-3797 shipped and is still what most styles hold,
+// so it stays first-class rather than being migrated away: widening the shape
+// beats adding a second key beside it (CLAUDE.md §3).
+//
+// Both hosts spell the long-hand props identically (`borderTopLeftRadius` &co in
+// React inline style AND in React Native), which is why one emitter serves both.
+
+export const CORNER_RADIUS_KEYS = Object.freeze([
+  "topLeft",
+  "topRight",
+  "bottomRight",
+  "bottomLeft",
+]);
+
+const LONGHAND_PROP = Object.freeze({
+  topLeft: "borderTopLeftRadius",
+  topRight: "borderTopRightRadius",
+  bottomRight: "borderBottomRightRadius",
+  bottomLeft: "borderBottomLeftRadius",
+});
+
+function clampCorner(value, fallback, max) {
+  // Unset (undefined/null/"") falls back; an explicit 0 is honoured — that
+  // distinction is what makes "square just this corner" expressible.
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(Math.round(n), 0), max);
+}
+
+/**
+ * Resolve an authored radius to its four corners.
+ *
+ * @param {number|object|null|undefined} value the authored `number | {corners}`
+ * @param {number} [fallback] the value each unset corner takes
+ * @param {number} [max] the upper clamp, matching the field's declared max
+ * @returns {{topLeft:number, topRight:number, bottomRight:number, bottomLeft:number}}
+ */
+export function normaliseCornerRadius(value, fallback = 0, max = 48) {
+  const base = clampCorner(
+    typeof value === "number" || typeof value === "string" ? value : undefined,
+    clampCorner(fallback, 0, max),
+    max,
+  );
+  const corners = value && typeof value === "object" ? value : null;
+  const out = {};
+  for (const key of CORNER_RADIUS_KEYS) {
+    out[key] = clampCorner(corners ? corners[key] : undefined, base, max);
+  }
+  return out;
+}
+
+/** True when all four corners resolve to the same number. */
+export function isUniformCornerRadius(radius) {
+  if (!radius) return true;
+  const { topLeft } = radius;
+  return CORNER_RADIUS_KEYS.every((key) => radius[key] === topLeft);
+}
+
+/**
+ * The style props for a resolved radius, in the spelling BOTH hosts accept.
+ * A uniform radius emits the `borderRadius` shorthand so an untouched style is
+ * byte-identical to what sc-3797 produced; only a genuinely mixed radius pays
+ * for the four long-hand props. A radius of all-zero emits nothing at all.
+ *
+ * @param {object|null} radius output of {@link normaliseCornerRadius}
+ * @param {(n: number) => any} [format] wraps each number — the DOM needs "12px"
+ * @returns {object|null}
+ */
+export function cornerRadiusStyle(radius, format) {
+  if (!radius) return null;
+  const wrap = format || ((n) => n);
+  if (isUniformCornerRadius(radius)) {
+    return radius.topLeft > 0 ? { borderRadius: wrap(radius.topLeft) } : null;
+  }
+  const out = {};
+  for (const key of CORNER_RADIUS_KEYS) {
+    out[LONGHAND_PROP[key]] = wrap(radius[key]);
+  }
+  return out;
+}
+
+/**
+ * True when the authored value asks for anything rounded. Callers use it to
+ * decide whether a background layer needs clipping at all.
+ */
+export function hasCornerRadius(radius) {
+  return Boolean(radius) && CORNER_RADIUS_KEYS.some((key) => radius[key] > 0);
+}

package/dist/index.d.ts

@@ -53,6 +53,10 @@ export type WidgetPropertyType =
   // label, required, optionsSource, inlineOptions, optionsTableId,
   // optionsValueColumn, optionsLabelColumn }.
   | "fieldList"
+  // REQ-LAY-16 (sc-5890): corner-radius picker. Value is
+  // `number | { topLeft, topRight, bottomRight, bottomLeft }` — a scalar rounds
+  // all four corners, the object rounds each independently.
+  | "cornerRadius"
   | "expression"
   | "eventBinding"
   | "object"
@@ -692,6 +696,44 @@ export function validateProps<T = Record<string, unknown>>(
   props: unknown,
 ): { ok: true; value: T } | { ok: false; errors: string[] };
 
+/**
+ * REQ-LAY-16 (sc-5890): the per-corner radius vocabulary. A `cornerRadius`
+ * field's authored value is a scalar or a per-corner object; resolve it with
+ * `normaliseCornerRadius` and turn it into style props with `cornerRadiusStyle`
+ * — both hosts spell the long-hand props identically, so one call serves the
+ * web Player and the Expo export.
+ */
+export type CornerRadiusKey =
+  | "topLeft"
+  | "topRight"
+  | "bottomRight"
+  | "bottomLeft";
+
+export type CornerRadiusValue = number | Partial<Record<CornerRadiusKey, number>>;
+
+export type ResolvedCornerRadius = Record<CornerRadiusKey, number>;
+
+export const CORNER_RADIUS_KEYS: readonly CornerRadiusKey[];
+
+export function normaliseCornerRadius(
+  value: CornerRadiusValue | null | undefined,
+  fallback?: number,
+  max?: number,
+): ResolvedCornerRadius;
+
+export function isUniformCornerRadius(
+  radius: ResolvedCornerRadius | null | undefined,
+): boolean;
+
+export function cornerRadiusStyle<T = number>(
+  radius: ResolvedCornerRadius | null | undefined,
+  format?: (n: number) => T,
+): Record<string, T> | null;
+
+export function hasCornerRadius(
+  radius: ResolvedCornerRadius | null | undefined,
+): boolean;
+
 export interface Query {
   filter?: Record<string, unknown>;
   sort?: Array<{ field: string; dir: "asc" | "desc" }>;

package/dist/index.js

@@ -5,6 +5,14 @@
 export { defineWidget } from "./define-widget.js";
 export { validateManifest, canonicalCategory } from "./manifest.js";
 export { validatePropertySchema, validateProps } from "./property-schema.js";
+// REQ-LAY-16 (sc-5890): per-corner radius — one normaliser/emitter for both hosts.
+export {
+  CORNER_RADIUS_KEYS,
+  normaliseCornerRadius,
+  isUniformCornerRadius,
+  cornerRadiusStyle,
+  hasCornerRadius,
+} from "./corner-radius.js";
 export {
   WidgetContextProvider,
   DatastoreError,

package/dist/index.native.js

@@ -5,6 +5,14 @@
 export { defineWidget } from "./define-widget.js";
 export { validateManifest, canonicalCategory } from "./manifest.js";
 export { validatePropertySchema, validateProps } from "./property-schema.js";
+// REQ-LAY-16 (sc-5890): per-corner radius — one normaliser/emitter for both hosts.
+export {
+  CORNER_RADIUS_KEYS,
+  normaliseCornerRadius,
+  isUniformCornerRadius,
+  cornerRadiusStyle,
+  hasCornerRadius,
+} from "./corner-radius.js";
 export {
   WidgetContextProvider,
   DatastoreError,

package/dist/linter.cjs

@@ -714,43 +714,129 @@ function _lucideIconRules(source) {
   return findings;
 }
 
-// sc-2353 — widget source must be self-contained. The automatic JSX runtime
-// binds jsx/jsxs from react/jsx-runtime but never `React` itself, so a widget
-// that reaches for the bare `React` global (React.createElement / React.Fragment
-// / React.memo / React.useMemo) without importing it renders fine until a
-// non-initial code path hits the reference, then throws "React is not defined".
-// The platform does NOT inject a React binding — require an explicit
-// `import React from "react"` (or `import * as React`) whenever the source
-// references React, so the bundle is self-contained on both hosts and survives
-// a download → re-upload round-trip. Plain JSX needs no React import.
-const _REACT_DEFAULT_IMPORT_RE = /\bimport\s+(?:React\b|\*\s+as\s+React\b)/;
-const _REACT_MEMBER_USE_RE = /\bReact\s*\./;
-function _reactInScopeRules(source) {
+// sc-2353 / sc-5897 — widget source must be SELF-CONTAINED: every identifier it
+// references needs a binding in that file. Two rules share ONE detector here
+// because they are one bug with one cause (CLAUDE.md §3):
+//
+//   * `react-not-imported` (sc-2353) — the automatic JSX runtime binds
+//     jsx/jsxs from react/jsx-runtime but never `React` itself, so source that
+//     reaches for the bare `React` global (React.createElement / React.Fragment
+//     / React.memo) renders fine until a non-initial code path hits the
+//     reference, then throws "React is not defined". The platform does NOT
+//     inject a React binding. Plain JSX needs no React import.
+//   * `sdk-export-not-imported` (sc-5897) — an SDK hook or primitive referenced
+//     as a bare identifier (`useFilestoreFile(id)`, `<View>`) with no import
+//     throws the same ReferenceError. It used to lint clean and surface only at
+//     the render.smoke gate, where "<name> is not defined" is softenable — so
+//     it was demoted to an advisory warning and burned repair turns instead of
+//     being rejected deterministically here.
+//
+// The scan is AST-free, so it flags ONLY the three reference forms text can
+// decide with certainty — a call `NAME(`, a member read `NAME.`, and a JSX
+// element `<NAME`. Any OTHER occurrence of the word (an import specifier, a
+// declaration, a destructured local, a property key, JSX text) means a binding
+// this scan cannot see may exist, so the name is abandoned rather than flagged:
+// missing a real bug is recoverable, a false `error` with no opt-out blocks a
+// legitimate publish.
+const _IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// CONTRACT enumerates the SDK's public hooks and primitives, so a name added
+// there is covered here without a second hand-maintained list.
+const _SDK_EXPORT_NAMES = Array.from(
+  new Set(
+    [...CONTRACT.hooks, ...CONTRACT.primitives]
+      .map((entry) => entry && entry.name)
+      .filter((name) => typeof name === "string" && _IDENTIFIER_RE.test(name)),
+  ),
+);
+
+// The only words that may legally precede an expression. A DECLARATION keyword
+// (`function`/`const`/`import`/`new`/`as`/…) is absent by design, and so is
+// every other identifier: `Call useTheme() now` is not valid JS, so a word lead
+// outside this set means the match sits in JSX text, not in code.
+const _EXPRESSION_LEAD_WORDS = new Set([
+  "return",
+  "await",
+  "typeof",
+  "void",
+  "delete",
+  "yield",
+  "throw",
+  "case",
+  "in",
+  "of",
+  "do",
+  "else",
+  "instanceof",
+]);
+
+// 1-based line of the first unbound reference to `name`, or 0 when the name is
+// bound, never referenced, or referenced in a form this scan cannot decide.
+function _unboundReferenceLine(code, name) {
+  if (!code.includes(name)) return 0;
+  // `NAME(…) {` is a function / method DEFINITION, not a call.
+  if (new RegExp(`\\b${name}\\s*\\([^()]*\\)\\s*\\{`).test(code)) return 0;
+  const word = new RegExp(`\\b${name}\\b`, "g");
+  let firstIndex = -1;
+  let match;
+  while ((match = word.exec(code))) {
+    const before = code.slice(0, match.index).replace(/\s+$/, "");
+    // `obj.NAME` / `obj?.NAME` / `{...NAME}` — never this binding.
+    if (before.endsWith(".")) continue;
+    const lead = before.slice(-1);
+    if (/[A-Za-z0-9_$]/.test(lead)) {
+      const leadWord = (before.match(/[A-Za-z_$][A-Za-z0-9_$]*$/) || [""])[0];
+      if (!_EXPRESSION_LEAD_WORDS.has(leadWord)) return 0;
+    } else if (lead === ">" && !before.endsWith("=>")) {
+      // A `>` that is not an arrow closes a JSX tag, so what follows is text.
+      return 0;
+    }
+    const after = code.slice(match.index + name.length).replace(/^\s+/, "");
+    const isReference =
+      /<\s*\/?$/.test(before) || after.startsWith("(") || after.startsWith(".");
+    if (!isReference) return 0;
+    if (firstIndex < 0) firstIndex = match.index;
+  }
+  if (firstIndex < 0) return 0;
+  return code.slice(0, firstIndex).split(/\r?\n/).length;
+}
+
+function _selfContainedReferenceRules(source) {
   const findings = [];
   const code = _stripNonCode(source);
-  if (!_REACT_MEMBER_USE_RE.test(code)) return findings;
-  if (_REACT_DEFAULT_IMPORT_RE.test(code)) return findings;
-  const codeLines = code.split(/\r?\n/);
   const sourceLines = source.split(/\r?\n/);
-  let line = 0;
-  for (let i = 0; i < codeLines.length; i += 1) {
-    if (_REACT_MEMBER_USE_RE.test(codeLines[i])) {
-      line = i + 1;
-      break;
-    }
+  const snippetAt = (line) => (sourceLines[line - 1] || "").trim().slice(0, 200);
+
+  const reactLine = _unboundReferenceLine(code, "React");
+  if (reactLine) {
+    findings.push({
+      rule: "react-not-imported",
+      severity: "error",
+      label:
+        "source references the `React` global (e.g. React.createElement / " +
+        "React.Fragment) but never imports it — widget source must be " +
+        'self-contained. Add `import React from "react";` at the top, or drop ' +
+        "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
+        "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
+      line: reactLine,
+      snippet: snippetAt(reactLine),
+    });
+  }
+
+  for (const name of _SDK_EXPORT_NAMES) {
+    const line = _unboundReferenceLine(code, name);
+    if (!line) continue;
+    findings.push({
+      rule: "sdk-export-not-imported",
+      severity: "error",
+      label:
+        `\`${name}\` is used but never imported — it throws ` +
+        `"${name} is not defined" at render. Import it from ` +
+        '"@colixsystems/widget-sdk"; widget source must be self-contained.',
+      line,
+      snippet: snippetAt(line),
+    });
   }
-  findings.push({
-    rule: "react-not-imported",
-    severity: "error",
-    label:
-      "source references the `React` global (e.g. React.createElement / " +
-      "React.Fragment) but never imports it — widget source must be " +
-      'self-contained. Add `import React from "react";` at the top, or drop ' +
-      "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
-      "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
-    line,
-    snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
-  });
   return findings;
 }
 
@@ -1195,7 +1281,7 @@ function lintSource(source, options) {
   findings.push(..._translationApiRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
-  findings.push(..._reactInScopeRules(source));
+  findings.push(..._selfContainedReferenceRules(source));
   findings.push(..._imagePercentHeightRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.

package/dist/linter.js

@@ -835,43 +835,129 @@ function _lucideIconRules(source) {
   return findings;
 }
 
-// sc-2353 — widget source must be self-contained. The automatic JSX runtime
-// binds jsx/jsxs from react/jsx-runtime but never `React` itself, so a widget
-// that reaches for the bare `React` global (React.createElement / React.Fragment
-// / React.memo / React.useMemo) without importing it renders fine until a
-// non-initial code path hits the reference, then throws "React is not defined".
-// The platform does NOT inject a React binding — require an explicit
-// `import React from "react"` (or `import * as React`) whenever the source
-// references React, so the bundle is self-contained on both hosts and survives
-// a download → re-upload round-trip. Plain JSX needs no React import.
-const _REACT_DEFAULT_IMPORT_RE = /\bimport\s+(?:React\b|\*\s+as\s+React\b)/;
-const _REACT_MEMBER_USE_RE = /\bReact\s*\./;
-function _reactInScopeRules(source) {
+// sc-2353 / sc-5897 — widget source must be SELF-CONTAINED: every identifier it
+// references needs a binding in that file. Two rules share ONE detector here
+// because they are one bug with one cause (CLAUDE.md §3):
+//
+//   * `react-not-imported` (sc-2353) — the automatic JSX runtime binds
+//     jsx/jsxs from react/jsx-runtime but never `React` itself, so source that
+//     reaches for the bare `React` global (React.createElement / React.Fragment
+//     / React.memo) renders fine until a non-initial code path hits the
+//     reference, then throws "React is not defined". The platform does NOT
+//     inject a React binding. Plain JSX needs no React import.
+//   * `sdk-export-not-imported` (sc-5897) — an SDK hook or primitive referenced
+//     as a bare identifier (`useFilestoreFile(id)`, `<View>`) with no import
+//     throws the same ReferenceError. It used to lint clean and surface only at
+//     the render.smoke gate, where "<name> is not defined" is softenable — so
+//     it was demoted to an advisory warning and burned repair turns instead of
+//     being rejected deterministically here.
+//
+// The scan is AST-free, so it flags ONLY the three reference forms text can
+// decide with certainty — a call `NAME(`, a member read `NAME.`, and a JSX
+// element `<NAME`. Any OTHER occurrence of the word (an import specifier, a
+// declaration, a destructured local, a property key, JSX text) means a binding
+// this scan cannot see may exist, so the name is abandoned rather than flagged:
+// missing a real bug is recoverable, a false `error` with no opt-out blocks a
+// legitimate publish.
+const _IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// CONTRACT enumerates the SDK's public hooks and primitives, so a name added
+// there is covered here without a second hand-maintained list.
+const _SDK_EXPORT_NAMES = Array.from(
+  new Set(
+    [...CONTRACT.hooks, ...CONTRACT.primitives]
+      .map((entry) => entry && entry.name)
+      .filter((name) => typeof name === "string" && _IDENTIFIER_RE.test(name)),
+  ),
+);
+
+// The only words that may legally precede an expression. A DECLARATION keyword
+// (`function`/`const`/`import`/`new`/`as`/…) is absent by design, and so is
+// every other identifier: `Call useTheme() now` is not valid JS, so a word lead
+// outside this set means the match sits in JSX text, not in code.
+const _EXPRESSION_LEAD_WORDS = new Set([
+  "return",
+  "await",
+  "typeof",
+  "void",
+  "delete",
+  "yield",
+  "throw",
+  "case",
+  "in",
+  "of",
+  "do",
+  "else",
+  "instanceof",
+]);
+
+// 1-based line of the first unbound reference to `name`, or 0 when the name is
+// bound, never referenced, or referenced in a form this scan cannot decide.
+function _unboundReferenceLine(code, name) {
+  if (!code.includes(name)) return 0;
+  // `NAME(…) {` is a function / method DEFINITION, not a call.
+  if (new RegExp(`\\b${name}\\s*\\([^()]*\\)\\s*\\{`).test(code)) return 0;
+  const word = new RegExp(`\\b${name}\\b`, "g");
+  let firstIndex = -1;
+  let match;
+  while ((match = word.exec(code))) {
+    const before = code.slice(0, match.index).replace(/\s+$/, "");
+    // `obj.NAME` / `obj?.NAME` / `{...NAME}` — never this binding.
+    if (before.endsWith(".")) continue;
+    const lead = before.slice(-1);
+    if (/[A-Za-z0-9_$]/.test(lead)) {
+      const leadWord = (before.match(/[A-Za-z_$][A-Za-z0-9_$]*$/) || [""])[0];
+      if (!_EXPRESSION_LEAD_WORDS.has(leadWord)) return 0;
+    } else if (lead === ">" && !before.endsWith("=>")) {
+      // A `>` that is not an arrow closes a JSX tag, so what follows is text.
+      return 0;
+    }
+    const after = code.slice(match.index + name.length).replace(/^\s+/, "");
+    const isReference =
+      /<\s*\/?$/.test(before) || after.startsWith("(") || after.startsWith(".");
+    if (!isReference) return 0;
+    if (firstIndex < 0) firstIndex = match.index;
+  }
+  if (firstIndex < 0) return 0;
+  return code.slice(0, firstIndex).split(/\r?\n/).length;
+}
+
+function _selfContainedReferenceRules(source) {
   const findings = [];
   const code = _stripNonCode(source);
-  if (!_REACT_MEMBER_USE_RE.test(code)) return findings;
-  if (_REACT_DEFAULT_IMPORT_RE.test(code)) return findings;
-  const codeLines = code.split(/\r?\n/);
   const sourceLines = source.split(/\r?\n/);
-  let line = 0;
-  for (let i = 0; i < codeLines.length; i += 1) {
-    if (_REACT_MEMBER_USE_RE.test(codeLines[i])) {
-      line = i + 1;
-      break;
-    }
+  const snippetAt = (line) => (sourceLines[line - 1] || "").trim().slice(0, 200);
+
+  const reactLine = _unboundReferenceLine(code, "React");
+  if (reactLine) {
+    findings.push({
+      rule: "react-not-imported",
+      severity: "error",
+      label:
+        "source references the `React` global (e.g. React.createElement / " +
+        "React.Fragment) but never imports it — widget source must be " +
+        'self-contained. Add `import React from "react";` at the top, or drop ' +
+        "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
+        "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
+      line: reactLine,
+      snippet: snippetAt(reactLine),
+    });
+  }
+
+  for (const name of _SDK_EXPORT_NAMES) {
+    const line = _unboundReferenceLine(code, name);
+    if (!line) continue;
+    findings.push({
+      rule: "sdk-export-not-imported",
+      severity: "error",
+      label:
+        `\`${name}\` is used but never imported — it throws ` +
+        `"${name} is not defined" at render. Import it from ` +
+        '"@colixsystems/widget-sdk"; widget source must be self-contained.',
+      line,
+      snippet: snippetAt(line),
+    });
   }
-  findings.push({
-    rule: "react-not-imported",
-    severity: "error",
-    label:
-      "source references the `React` global (e.g. React.createElement / " +
-      "React.Fragment) but never imports it — widget source must be " +
-      'self-contained. Add `import React from "react";` at the top, or drop ' +
-      "the bare `React` reference in favour of a JSX fragment `<>…</>` and the " +
-      "SDK hooks (useState / useMemo / …) and primitives (View / Text / …).",
-    line,
-    snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
-  });
   return findings;
 }
 
@@ -1372,8 +1458,9 @@ export function lintSource(source, options) {
   findings.push(..._translationApiRules(source));
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
-  // sc-2353 — widget source must be self-contained (reference React ⇒ import it).
-  findings.push(..._reactInScopeRules(source));
+  // sc-2353 / sc-5897 — widget source must be self-contained: a referenced
+  // `React` global or SDK export with no import throws at render.
+  findings.push(..._selfContainedReferenceRules(source));
   // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
   findings.push(..._imagePercentHeightRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own

package/dist/property-schema.js

@@ -1,6 +1,8 @@
 // Property schema validation per docs/architecture/widget-marketplace.md §2.2.
 // Drives the schema-driven Properties Panel and validates persisted page JSON.
 
+import { CORNER_RADIUS_KEYS } from "./corner-radius.js";
+
 const VALID_TYPES = new Set([
   "string", "number", "boolean",
   "color", "icon", "image",
@@ -47,6 +49,14 @@ const VALID_TYPES = new Set([
   // NOT copied, so tenant-copy leaves the id as-is (it resolves to the space
   // root if absent in the target).
   "folderRef",
+  // REQ-LAY-16 (sc-5890): `cornerRadius` is a corner-radius picker. Its value
+  // is `number | { topLeft, topRight, bottomRight, bottomLeft }` — a scalar
+  // rounds all four, the object rounds each independently. The Studio renders
+  // a slider + typeable number with a per-corner disclosure; a widget turns
+  // the value into style props with `cornerRadiusStyle(normaliseCornerRadius(v))`,
+  // which both hosts spell identically. Plain numbers, so tenant-copy needs
+  // no remap.
+  "cornerRadius",
   "expression", "eventBinding",
   "object", "array",
 ]);
@@ -152,6 +162,36 @@ function coerceLeaf(def, value, path, errors) {
     case "boolean":
       if (typeof value !== "boolean") errors.push(`${path}: expected boolean`);
       return value;
+    case "cornerRadius": {
+      // REQ-LAY-16: a scalar rounds all four corners; an object rounds each.
+      // Every corner is optional so a half-set object stays valid while the
+      // author is still adjusting — an unset corner falls back to the scalar.
+      const { min = 0, max } = def.validation || {};
+      const checkCorner = (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") {
+        checkCorner(value, path);
+        return value;
+      }
+      if (!isPlainObject(value)) {
+        errors.push(`${path}: expected number or per-corner object`);
+        return value;
+      }
+      for (const [k, n] of Object.entries(value)) {
+        if (!CORNER_RADIUS_KEYS.includes(k)) {
+          errors.push(`${path}.${k}: unknown corner`);
+        } else if (n !== undefined && n !== null) {
+          checkCorner(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.103.0",
+  "version": "0.105.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__/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__/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__/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"
   },
   "engines": {
     "node": ">=18"