@colixsystems/widget-sdk 0.270.0 → 0.272.0

package/README.md

@@ -86,7 +86,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.270.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.272.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.272.0 (contract 1.222.0)
+
+**Breaking for authors: more routes to the page's global object are banned.** `self`, `top`, `parent`, `frames` and `opener` are other names for `window`, `frameElement` leads to the host document, and a function's `.constructor` is `Function()`. The linter now refuses them (`no-self`, `no-top`, `no-parent`, `no-frames`, `no-opener`, `no-frameelement`, `no-constructor-access`), refuses `eval` and `Function` as any reference, not only as a call (`const e = eval`, `(0, eval)(…)`), and refuses a `\u` escape that spells a letter, digit, `_` or `$` in code (`no-identifier-escape`), which would hide a name from the scan. A widget version that uses them fails lint at submission; versions already published keep running.
+
+- **`self` / `top` / `parent` / `frames` / `opener`** are refused wherever they read a variable: `top[k]`, `{ ...self }`, `typeof parent`, `c ? frames : x`. That includes a local variable with one of these names, so rename it (`const [rootTop, setRootTop] = useState(null)`, `const parentId = …`). A property (`insets.top`, `node.parent`), an object key (`{ top: 0 }`, `const { top: topInset } = insets`) and a word in JSX text after another word on the same line (`Back to top`) are fine. JSX text that is only the word (`<Text>top</Text>`) or starts a line is refused; render it as `{"top"}` or through `t()`.
+- **`.constructor`** is refused as a property read (`x.constructor`, `x?.constructor`), a destructured key (`const { constructor } = fn`) and the quoted name (`x["constructor"]`, `Reflect.get(p, "constructor")`). A class component's own `constructor(props)` method is fine.
+- **`Function`** stays allowed after `instanceof` (`v instanceof Function`); prefer `typeof v === "function"`. To test for a plain object, compare `Object.getPrototypeOf(x) === Object.prototype`.
+
+### What's new in 0.271.0 (contract 1.221.0)
+
+**Basic styling in one call.** Spread `BASIC_STYLE_SCHEMA` into `manifest.styleSchema` and call `basicStyle(style)` in the component: the five basic style fields (`background`, `textColor`, `align`, `padding`, `margin`) are declared and applied without wiring each by hand. See *Basic styling* under *Design & visual polish*.
 
 ### What's new in 0.270.0 (contract 1.220.0)
 
@@ -3345,6 +3357,22 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 **Decide before you build:** the widget's shape (card, list, form, control), its hierarchy (the one thing the eye lands on first), its single accent moment, and its empty/loading/error look — then compose. Specific decisions make a distinctive widget; leaving them to default makes a generic one.
 
+- **Basic styling: one schema, one call.** Every generated widget offers five whole-widget style fields: `background`, `textColor`, `align`, `padding` and `margin`. Spread `BASIC_STYLE_SCHEMA` into your manifest's `styleSchema`, then apply them with `basicStyle(style)`. It returns `{ root, text }`: spread `root` on the outermost `View` (background, align as `alignItems`, per-side padding and margin) and `text` on each `Text` in a theme text colour. A field the author left unset emits nothing, so your theme-based styles show through. `appstudio-widget lint` counts the call as reading all five. When `submit_widget_source` or the Studio's widget builder publishes a widget that calls `basicStyle()`, any of the five its manifest leaves out is declared for it.
+
+  ```jsx
+  import { View, Text, basicStyle, BASIC_STYLE_SCHEMA } from "@colixsystems/widget-sdk";
+
+  export const manifest = { /* … */ styleSchema: { ...BASIC_STYLE_SCHEMA, titleColor: { type: "color", label: "Title", ui: { group: "Title" } } } };
+
+  export default function Hero({ title, style = {} }) {
+    const basic = basicStyle(style);
+    return (
+      <View style={[styles.root, basic.root]}>
+        <Text style={[styles.title, basic.text, style.titleColor && { color: style.titleColor }]}>{title}</Text>
+      </View>
+    );
+  }
+  ```
 - **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
 - **Style text by its ROLE, not by inventing a size and weight.** `theme.typography.roles` carries the workspace's type scale as six semantic tiers — `display`, `title`, `subtitle`, `body`, `caption`, `overline` — each already resolved to a `fontSize`, `fontWeight`, `fontStyle`, `lineHeight` (a MULTIPLE of the size), `letterSpacing`, `textTransform` and a `colorToken`. Pick the tier the text IS, rather than choosing `fontSize: 16, fontWeight: "600"` yourself: your widget's section title is `title`, each card or row title is `subtitle`, running text is `body`, timestamps and helper text are `caption`, a small kicker or column label is `overline`, and a headline stat is `display`. This is what stops one widget rendering a subtitle bold while the widget beside it renders one italic, and it lets the workspace re-tune every subtitle in the app from Theme Settings in one edit. **Two tokens need converting rather than copying** — `lineHeight` is a multiple (React Native wants absolute pixels, so the raw `1.15` gives you a one-pixel line box) and `colorToken` names a colour rather than being one:
@@ -3473,6 +3501,10 @@ joined — it then reads back as `{ id, name, invited: true }`, with no `email`
 behind it. `status: 'open'` is every invite that is neither accepted nor revoked
 (`pending`, `not_sent` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
 
+Only a signed-in member viewer sees a `USER` cell's `email`. A visitor who is not
+signed in, and an anonymous account, read a member as `{ id, name }`, so render
+`name` and treat `email` as optional.
+
 **The gate is `users.write`, not `users.read`.** A pending invite exposes the email of
 someone who is not a member yet, so the backend gates the entire invite surface —
 listing included — on the `users.write` capability plus a signed `users.write:*`
@@ -3756,7 +3788,7 @@ 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) and for the styling rules below. **Only error-severity findings change the exit code**; warnings print and exit 0.
+Scans for banned patterns (every `CONTRACT.bannedApis` entry — `eval`, `Function`, dynamic `import()`, `window` and its other names `self` / `top` / `parent` / `frames`, `.constructor`, … — and direct imports of host stores) and for the styling rules below. **Only error-severity findings change the exit code**; warnings print and exit 0.
 
 ```js
 import {

package/dist/basic-style.js

@@ -0,0 +1,37 @@
+// The five style fields every generated widget declares, in one call: spread
+// BASIC_STYLE_SCHEMA into `manifest.styleSchema`, apply `basicStyle(style)`.
+// Platform-free, so the web and native entries export this one module.
+
+import { CONTRACT } from "./contract.js";
+import { spacingOverlay } from "./card-style.js";
+
+export const BASIC_STYLE_SCHEMA = CONTRACT.basicStyleSchema;
+
+const ALIGN_ITEMS = Object.freeze({
+  left: "flex-start",
+  center: "center",
+  right: "flex-end",
+});
+
+/**
+ * The basic style fields as React Native styles. Each is emitted only when the
+ * author set it, so the widget's own theme-based styles show through.
+ *
+ * @param {object} [style] the widget's `props.style`
+ * @returns {{ root: object, text: object|null }} `root` for the outermost
+ *   View (backgroundColor, alignItems, padding, margin); `text` (`{ color }`)
+ *   for each Text coloured by a theme text token.
+ */
+export function basicStyle(style) {
+  const s = style || {};
+  const alignItems = ALIGN_ITEMS[s.align];
+  return {
+    root: {
+      ...(s.background ? { backgroundColor: s.background } : null),
+      ...(alignItems ? { alignItems } : null),
+      ...spacingOverlay(s.padding, "padding"),
+      ...spacingOverlay(s.margin, "margin"),
+    },
+    text: s.textColor ? { color: s.textColor } : null,
+  };
+}

package/dist/contract.cjs

@@ -389,6 +389,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -4508,6 +4540,20 @@ const BANNED_APIS = [
     reason:
       "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
   },
+  ...["self", "top", "parent", "frames", "opener"].map((identifier) => ({
+    identifier,
+    reason:
+      "Another name for window. Refused where it reads a variable, so rename a local one; `insets.top` and `{ top: 0 }` are fine.",
+  })),
+  {
+    identifier: "frameElement",
+    reason: "The element framing the page, a route to the host document.",
+  },
+  {
+    identifier: ".constructor",
+    reason:
+      "Reaches Function(), which evaluates strings. Refused as a property read or quoted name; a class's own constructor() method is fine.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -6508,7 +6554,12 @@ const CONTRACT = deepFreeze({
   //    every query, record, figure and aggregate on that table, app-wide.
   // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
-  version: "1.220.0",
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  // 1.222.0: stricter (sc-14479) — `self`, `top`, `parent`, `frames`,
+  //    `opener`, `frameElement` and `.constructor` join bannedApis; `eval` and
+  //    `Function` are refused as any reference, not only as a call.
+  version: "1.222.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6533,6 +6584,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/contract.js

@@ -386,6 +386,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -4505,6 +4537,20 @@ const BANNED_APIS = [
     reason:
       "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
   },
+  ...["self", "top", "parent", "frames", "opener"].map((identifier) => ({
+    identifier,
+    reason:
+      "Another name for window. Refused where it reads a variable, so rename a local one; `insets.top` and `{ top: 0 }` are fine.",
+  })),
+  {
+    identifier: "frameElement",
+    reason: "The element framing the page, a route to the host document.",
+  },
+  {
+    identifier: ".constructor",
+    reason:
+      "Reaches Function(), which evaluates strings. Refused as a property read or quoted name; a class's own constructor() method is fine.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -6505,7 +6551,12 @@ const CONTRACT = deepFreeze({
   //    every query, record, figure and aggregate on that table, app-wide.
   // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
-  version: "1.220.0",
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  // 1.222.0: stricter (sc-14479) — `self`, `top`, `parent`, `frames`,
+  //    `opener`, `frameElement` and `.constructor` join bannedApis; `eval` and
+  //    `Function` are refused as any reference, not only as a call.
+  version: "1.222.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6530,6 +6581,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/index.d.ts

@@ -5576,6 +5576,27 @@ export function roleColor(tokens: any, colors: any): string | undefined;
  */
 export function textRoleStyle(role: TextRole | string, typography: any, colors?: any): Record<string, any>;
 
+/**
+ * The five style fields every generated widget declares — `background`,
+ * `textColor`, `align`, `padding` and `margin` — as styleSchema entries.
+ * Spread it into `manifest.styleSchema`; `basicStyle()` applies it.
+ */
+export const BASIC_STYLE_SCHEMA: Readonly<WidgetPropertySchema>;
+/**
+ * The basic style fields as React Native styles, each only when set. Spread
+ * `root` on the outermost View and `text` on each Text in a theme text colour.
+ *
+ * @example
+ *   const basic = basicStyle(style);
+ *   <View style={[styles.root, basic.root]}>
+ *     <Text style={[styles.title, basic.text]}>{title}</Text>
+ *   </View>
+ */
+export function basicStyle(style?: Record<string, any> | null): {
+  root: Record<string, any>;
+  text: { color: string } | null;
+};
+
 // ----------------------------------------------------- formatted content
 // sc-6970 — widgets have no HTML path: they render through React Native
 // primitives, which have no `dangerouslySetInnerHTML` on either host. Content

package/dist/index.js

@@ -268,6 +268,8 @@ export {
   gradientProps,
   cardGradientProps,
 } from "./card-style.js";
+// The five style fields every generated widget declares, in one call.
+export { BASIC_STYLE_SCHEMA, basicStyle } from "./basic-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
 export { Button, IconButton, BUTTON_VARIANTS } from "./button.js";
 export {

package/dist/index.native.js

@@ -261,6 +261,8 @@ export {
   gradientProps,
   cardGradientProps,
 } from "./card-style.js";
+// The five style fields every generated widget declares, in one call.
+export { BASIC_STYLE_SCHEMA, basicStyle } from "./basic-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
 export { Button, IconButton, BUTTON_VARIANTS } from "./button.native.js";
 export {

package/dist/linter.cjs

@@ -13,42 +13,151 @@
 const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 const { LUCIDE_ICON_NAMES, LUCIDE_VERSION } = require("./lucideIconNames.cjs");
 
+// Per-identifier match rule, run over the whole masked source. Most banned
+// identifiers compile to a whole-word match.
 function _ruleForIdentifier(identifier, reason) {
   const id = identifier;
   if (id === "Function") {
+    // Any reference, so an alias (`const F = Function`) is refused too.
     return {
       id: "no-function-constructor",
       label: `${reason} (banned: Function() constructor)`,
-      pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
+      pattern: /(?<![\w$])Function(?![\w$])/g,
+      accept: (code, index) =>
+        !_isMemberName(code, index) && _wordBefore(code, index) !== "instanceof",
     };
   }
   if (id === "new Function") {
     return {
       id: "no-new-function",
       label: `${reason} (banned: new Function())`,
-      pattern: /\bnew\s+Function\s*\(/,
+      pattern: /\bnew\s+Function\s*\(/g,
     };
   }
   if (id === "import(") {
     return {
       id: "no-dynamic-import",
       label: `${reason} (banned: dynamic import())`,
-      pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
+      pattern: /(?<![\w$.])import\s*\(/g,
     };
   }
   if (id === "eval") {
+    // Any reference, so indirect `(0, eval)(…)` is refused too.
     return {
       id: "no-eval",
       label: `${reason} (banned: eval)`,
-      pattern: /\beval\s*\(/,
+      pattern: /(?<![\w$])eval(?![\w$])/g,
+    };
+  }
+  if (id === ".constructor") {
+    return {
+      id: "no-constructor-access",
+      label: `${reason} (banned: .constructor)`,
+      // Also `{ constructor: F } = fn`; a class's `constructor(` passes.
+      pattern: /\.\s*constructor(?![\w$])|(?<![\w$.])constructor(?![\w$])(?!\s*\()/g,
+      stringPattern: /(["'`])constructor\1/g,
     };
   }
   const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return {
-    id: `no-${id.toLowerCase()}`,
-    label: `${reason} (banned: ${id})`,
-    pattern: new RegExp(`\\b${escaped}\\b`),
-  };
+  const rule = { id: `no-${id.toLowerCase()}`, label: `${reason} (banned: ${id})` };
+  if (_GLOBAL_OBJECT_ALIASES.has(id)) {
+    // Also a common property name, so only a read of the variable is refused.
+    return {
+      ...rule,
+      pattern: new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`, "g"),
+      accept: (code, index) => _readsVariable(code, index, id.length),
+    };
+  }
+  return { ...rule, pattern: new RegExp(`\\b${escaped}\\b`, "g") };
+}
+
+// Other names for the page's global object that are also everyday property
+// names (`insets.top`, `node.parent`).
+const _GLOBAL_OBJECT_ALIASES = new Set(["self", "top", "parent", "frames", "opener"]);
+
+// Read-leading keywords `_EXPRESSION_LEAD_WORDS` leaves out.
+const _READ_LEAD_WORDS = new Set(["new", "extends", "default"]);
+
+// Index of the last non-space character before `index`, and whether a
+// newline lies between.
+function _tokenBefore(code, index) {
+  let at = index - 1;
+  let newline = false;
+  for (; at >= 0 && /\s/.test(code[at]); at -= 1) {
+    if (code[at] === "\n") newline = true;
+  }
+  return { at, newline };
+}
+
+function _wordBefore(code, index) {
+  const { at } = _tokenBefore(code, index);
+  let start = at + 1;
+  while (start > 0 && /[\w$]/.test(code[start - 1])) start -= 1;
+  return code.slice(start, at + 1);
+}
+
+// `x.name` / `x?.name`, but not a spread (`...name`) and not the decimal point
+// of an integer (`1.` + newline starts a new statement).
+function _isMemberName(code, index) {
+  const { at } = _tokenBefore(code, index);
+  if (code[at] !== ".") return false;
+  if (code[at - 1] === ".") return false;
+  return !/(^|[^\w$.])\d[\d_]*$/.test(code.slice(Math.max(0, at - 64), at));
+}
+
+// Whether the name at `index` reads its variable. A member name, an object
+// key, a write, and a word after a declaration keyword or JSX text on the
+// same line do not.
+function _readsVariable(code, index, length) {
+  if (_isMemberName(code, index)) return false;
+  const { at: before, newline } = _tokenBefore(code, index);
+  let after = index + length;
+  while (after < code.length && /\s/.test(code[after])) after += 1;
+  const prev = code[before] || "";
+  if (code[after] === ":" && (prev === "{" || prev === ",")) return false;
+  if (code[after] === "=" && !/[=>]/.test(code[after + 1] || "")) return false;
+  if (newline || !/[\w$]/.test(prev)) return true;
+  const word = _wordBefore(code, index);
+  return _EXPRESSION_LEAD_WORDS.has(word) || _READ_LEAD_WORDS.has(word);
+}
+
+// A `\u` escape spelling an ASCII identifier character (`\u0077indow`).
+const _IDENTIFIER_ESCAPE_RE = /\\u(?:\{0*([0-9a-fA-F]{1,6})\}|([0-9a-fA-F]{4}))/g;
+
+function _escapesAsciiIdentifier(code, index) {
+  // A fresh regex: matchAll clones the shared one with its lastIndex.
+  const at = new RegExp(_IDENTIFIER_ESCAPE_RE.source, "y");
+  at.lastIndex = index;
+  const m = at.exec(code);
+  const ch = String.fromCodePoint(parseInt(m[1] || m[2], 16));
+  return /^[\w$]$/.test(ch);
+}
+
+// One finding per rule per line, in line order, then rule order. Masking keeps
+// every index, so a match's line is the source's line.
+function _bannedApiFindings(source, lines) {
+  const masks = [_stripNonCode(source), _stripNonCode(source, { keepStrings: true })];
+  const hits = [];
+  RULES.forEach((rule, order) => {
+    const ruleLines = new Set();
+    [rule.pattern, rule.stringPattern].forEach((pattern, maskIndex) => {
+      if (!pattern) return;
+      const code = masks[maskIndex];
+      const lineAt = _lineCounter(code);
+      for (const match of code.matchAll(pattern)) {
+        if (!rule.accept || rule.accept(code, match.index)) ruleLines.add(lineAt(match.index));
+      }
+    });
+    for (const line of ruleLines) hits.push({ rule, order, line });
+  });
+  hits.sort((a, b) => a.line - b.line || a.order - b.order);
+  return hits.map(({ rule, line }) => ({
+    rule: rule.id,
+    severity: "error",
+    label: rule.label,
+    line,
+    snippet: lines[line - 1].trim().slice(0, 200),
+  }));
 }
 
 const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
@@ -209,7 +318,14 @@ const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
     label: "widgets must not import the host's auth store",
-    pattern: /useAuthStore/,
+    pattern: /useAuthStore/g,
+  },
+  {
+    id: "no-identifier-escape",
+    label:
+      "a \\u escape spelling a letter, digit, _ or $ hides a name from the banned-API scan; write the name plainly",
+    pattern: _IDENTIFIER_ESCAPE_RE,
+    accept: _escapesAsciiIdentifier,
   },
 ];
 
@@ -1946,11 +2062,15 @@ function lintStyleWiring(manifest, files) {
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
     .join("\n");
+  const appliedByHelper = callsBasicStyle(sources)
+    ? _WHOLE_WIDGET_STYLE_FIELDS
+    : new Set();
   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 (appliedByHelper.has(field)) continue;
     if (new RegExp(`\\b${field}\\b`).test(code)) continue;
     findings.push({
       rule: "style-field-unread",
@@ -1961,7 +2081,8 @@ function lintStyleWiring(manifest, files) {
         `— 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.`,
+        `none. If it is not styleable, drop it from styleSchema instead.` +
+        (_WHOLE_WIDGET_STYLE_FIELDS.has(field) ? _BASIC_STYLE_FIX : ""),
       line: 0,
       snippet: field,
     });
@@ -1970,6 +2091,26 @@ function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+const _BASIC_STYLE_CALL = /\bbasicStyle\s*\(/;
+
+const _BASIC_STYLE_FIX =
+  ` The one-line fix for every basic field: basicStyle(props.style) from ` +
+  `@colixsystems/widget-sdk — spread its .root on the outermost View and ` +
+  `its .text on each Text in a theme text colour.`;
+
+/**
+ * Whether the bundle calls `basicStyle()`, which applies every basic style
+ * field (`CONTRACT.basicStyleSchema`) in one call.
+ *
+ * @param {object|string[]|string} files bundle sources, as `lintStyleWiring` takes them
+ * @returns {boolean}
+ */
+function callsBasicStyle(files) {
+  return _bundleSources(files).some((s) =>
+    _BASIC_STYLE_CALL.test(_stripNonCode(s)),
+  );
+}
+
 // sc-7799 — a group name that groups everything defeats the rule: one
 // catch-all fieldset reads exactly like the flat list it replaced.
 const _GENERIC_STYLE_GROUPS = new Set([
@@ -1982,16 +2123,9 @@ const _GENERIC_STYLE_GROUPS = new Set([
 ]);
 
 // The five the basic-style gate mandates; they restyle the widget as a whole.
-// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
-// — a mandated field missing here reads as per-element coverage the widget does
-// not have, which silently retires this rule for EVERY generated widget.
-const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
-  "background",
-  "textColor",
-  "align",
-  "padding",
-  "margin",
-]);
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set(
+  Object.keys(CONTRACT.basicStyleSchema),
+);
 
 // A second element an author would style apart from the text. Pressable and
 // Button are deliberately absent: a touch target wrapping the only label is
@@ -2312,26 +2446,9 @@ function lintSource(source, options) {
   }
   const findings = [];
   const lines = source.split(/\r?\n/);
-  // Scan code with comments + string/template text blanked out so a banned
-  // identifier only fires on an actual code reference, not on the same word
-  // appearing in prose or string data. `codeLines` lines up 1:1 with `lines`
-  // (masking preserves newlines), so the reported snippet still comes from
-  // the original source.
-  const codeLines = _stripNonCode(source).split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const codeLine = codeLines[i];
-    for (const rule of RULES) {
-      if (rule.pattern.test(codeLine)) {
-        findings.push({
-          rule: rule.id,
-          severity: "error",
-          label: rule.label,
-          line: i + 1,
-          snippet: lines[i].trim().slice(0, 200),
-        });
-      }
-    }
-  }
+  // Comments and string text are masked, so a banned identifier fires only on
+  // code, never on the same word in prose or string data.
+  findings.push(..._bannedApiFindings(source, lines));
   findings.push(
     ..._importRules(source, options && options.manifest).map((f) => ({
       ...f,
@@ -2385,6 +2502,7 @@ function lintSource(source, options) {
 module.exports = {
   lintSource,
   lintStyleWiring,
+  callsBasicStyle,
   lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,

package/dist/linter.js

@@ -9,47 +9,151 @@
 import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
 import { LUCIDE_ICON_NAMES, LUCIDE_VERSION } from "./lucideIconNames.js";
 
-// Per-identifier match rule. Most banned identifiers compile to a
-// whole-word match; a few have special syntax (`Function(`, `new Function`,
-// `import(`) that needs a tighter regex.
+// Per-identifier match rule, run over the whole masked source. Most banned
+// identifiers compile to a whole-word match.
 function _ruleForIdentifier(identifier, reason) {
   const id = identifier;
   if (id === "Function") {
+    // Any reference, so an alias (`const F = Function`) is refused too.
     return {
       id: "no-function-constructor",
       label: `${reason} (banned: Function() constructor)`,
-      pattern: /(^|[^A-Za-z0-9_$.])Function\s*\(/,
+      pattern: /(?<![\w$])Function(?![\w$])/g,
+      accept: (code, index) =>
+        !_isMemberName(code, index) && _wordBefore(code, index) !== "instanceof",
     };
   }
   if (id === "new Function") {
     return {
       id: "no-new-function",
       label: `${reason} (banned: new Function())`,
-      pattern: /\bnew\s+Function\s*\(/,
+      pattern: /\bnew\s+Function\s*\(/g,
     };
   }
   if (id === "import(") {
     return {
       id: "no-dynamic-import",
       label: `${reason} (banned: dynamic import())`,
-      pattern: /(^|[^A-Za-z0-9_$.])import\s*\(/,
+      pattern: /(?<![\w$.])import\s*\(/g,
     };
   }
   if (id === "eval") {
+    // Any reference, so indirect `(0, eval)(…)` is refused too.
     return {
       id: "no-eval",
       label: `${reason} (banned: eval)`,
-      pattern: /\beval\s*\(/,
+      pattern: /(?<![\w$])eval(?![\w$])/g,
+    };
+  }
+  if (id === ".constructor") {
+    return {
+      id: "no-constructor-access",
+      label: `${reason} (banned: .constructor)`,
+      // Also `{ constructor: F } = fn`; a class's `constructor(` passes.
+      pattern: /\.\s*constructor(?![\w$])|(?<![\w$.])constructor(?![\w$])(?!\s*\()/g,
+      stringPattern: /(["'`])constructor\1/g,
     };
   }
-  // Default: word-boundary anchored. Used for the simple identifier
-  // forms (`window`, `document`, `process`, ...).
   const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return {
-    id: `no-${id.toLowerCase()}`,
-    label: `${reason} (banned: ${id})`,
-    pattern: new RegExp(`\\b${escaped}\\b`),
-  };
+  const rule = { id: `no-${id.toLowerCase()}`, label: `${reason} (banned: ${id})` };
+  if (_GLOBAL_OBJECT_ALIASES.has(id)) {
+    // Also a common property name, so only a read of the variable is refused.
+    return {
+      ...rule,
+      pattern: new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`, "g"),
+      accept: (code, index) => _readsVariable(code, index, id.length),
+    };
+  }
+  return { ...rule, pattern: new RegExp(`\\b${escaped}\\b`, "g") };
+}
+
+// Other names for the page's global object that are also everyday property
+// names (`insets.top`, `node.parent`).
+const _GLOBAL_OBJECT_ALIASES = new Set(["self", "top", "parent", "frames", "opener"]);
+
+// Read-leading keywords `_EXPRESSION_LEAD_WORDS` leaves out.
+const _READ_LEAD_WORDS = new Set(["new", "extends", "default"]);
+
+// Index of the last non-space character before `index`, and whether a
+// newline lies between.
+function _tokenBefore(code, index) {
+  let at = index - 1;
+  let newline = false;
+  for (; at >= 0 && /\s/.test(code[at]); at -= 1) {
+    if (code[at] === "\n") newline = true;
+  }
+  return { at, newline };
+}
+
+function _wordBefore(code, index) {
+  const { at } = _tokenBefore(code, index);
+  let start = at + 1;
+  while (start > 0 && /[\w$]/.test(code[start - 1])) start -= 1;
+  return code.slice(start, at + 1);
+}
+
+// `x.name` / `x?.name`, but not a spread (`...name`) and not the decimal point
+// of an integer (`1.` + newline starts a new statement).
+function _isMemberName(code, index) {
+  const { at } = _tokenBefore(code, index);
+  if (code[at] !== ".") return false;
+  if (code[at - 1] === ".") return false;
+  return !/(^|[^\w$.])\d[\d_]*$/.test(code.slice(Math.max(0, at - 64), at));
+}
+
+// Whether the name at `index` reads its variable. A member name, an object
+// key, a write, and a word after a declaration keyword or JSX text on the
+// same line do not.
+function _readsVariable(code, index, length) {
+  if (_isMemberName(code, index)) return false;
+  const { at: before, newline } = _tokenBefore(code, index);
+  let after = index + length;
+  while (after < code.length && /\s/.test(code[after])) after += 1;
+  const prev = code[before] || "";
+  if (code[after] === ":" && (prev === "{" || prev === ",")) return false;
+  if (code[after] === "=" && !/[=>]/.test(code[after + 1] || "")) return false;
+  if (newline || !/[\w$]/.test(prev)) return true;
+  const word = _wordBefore(code, index);
+  return _EXPRESSION_LEAD_WORDS.has(word) || _READ_LEAD_WORDS.has(word);
+}
+
+// A `\u` escape spelling an ASCII identifier character (`\u0077indow`).
+const _IDENTIFIER_ESCAPE_RE = /\\u(?:\{0*([0-9a-fA-F]{1,6})\}|([0-9a-fA-F]{4}))/g;
+
+function _escapesAsciiIdentifier(code, index) {
+  // A fresh regex: matchAll clones the shared one with its lastIndex.
+  const at = new RegExp(_IDENTIFIER_ESCAPE_RE.source, "y");
+  at.lastIndex = index;
+  const m = at.exec(code);
+  const ch = String.fromCodePoint(parseInt(m[1] || m[2], 16));
+  return /^[\w$]$/.test(ch);
+}
+
+// One finding per rule per line, in line order, then rule order. Masking keeps
+// every index, so a match's line is the source's line.
+function _bannedApiFindings(source, lines) {
+  const masks = [_stripNonCode(source), _stripNonCode(source, { keepStrings: true })];
+  const hits = [];
+  RULES.forEach((rule, order) => {
+    const ruleLines = new Set();
+    [rule.pattern, rule.stringPattern].forEach((pattern, maskIndex) => {
+      if (!pattern) return;
+      const code = masks[maskIndex];
+      const lineAt = _lineCounter(code);
+      for (const match of code.matchAll(pattern)) {
+        if (!rule.accept || rule.accept(code, match.index)) ruleLines.add(lineAt(match.index));
+      }
+    });
+    for (const line of ruleLines) hits.push({ rule, order, line });
+  });
+  hits.sort((a, b) => a.line - b.line || a.order - b.order);
+  return hits.map(({ rule, line }) => ({
+    rule: rule.id,
+    severity: "error",
+    label: rule.label,
+    line,
+    snippet: lines[line - 1].trim().slice(0, 200),
+  }));
 }
 
 const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
@@ -73,7 +177,14 @@ const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
     label: "widgets must not import the host's auth store",
-    pattern: /useAuthStore/,
+    pattern: /useAuthStore/g,
+  },
+  {
+    id: "no-identifier-escape",
+    label:
+      "a \\u escape spelling a letter, digit, _ or $ hides a name from the banned-API scan; write the name plainly",
+    pattern: _IDENTIFIER_ESCAPE_RE,
+    accept: _escapesAsciiIdentifier,
   },
 ];
 
@@ -2009,11 +2120,15 @@ export function lintStyleWiring(manifest, files) {
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
     .join("\n");
+  const appliedByHelper = callsBasicStyle(sources)
+    ? _WHOLE_WIDGET_STYLE_FIELDS
+    : new Set();
   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 (appliedByHelper.has(field)) continue;
     if (new RegExp(`\\b${field}\\b`).test(code)) continue;
     findings.push({
       rule: "style-field-unread",
@@ -2024,7 +2139,8 @@ export function lintStyleWiring(manifest, files) {
         `— 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.`,
+        `none. If it is not styleable, drop it from styleSchema instead.` +
+        (_WHOLE_WIDGET_STYLE_FIELDS.has(field) ? _BASIC_STYLE_FIX : ""),
       line: 0,
       snippet: field,
     });
@@ -2033,6 +2149,26 @@ export function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+const _BASIC_STYLE_CALL = /\bbasicStyle\s*\(/;
+
+const _BASIC_STYLE_FIX =
+  ` The one-line fix for every basic field: basicStyle(props.style) from ` +
+  `@colixsystems/widget-sdk — spread its .root on the outermost View and ` +
+  `its .text on each Text in a theme text colour.`;
+
+/**
+ * Whether the bundle calls `basicStyle()`, which applies every basic style
+ * field (`CONTRACT.basicStyleSchema`) in one call.
+ *
+ * @param {object|string[]|string} files bundle sources, as `lintStyleWiring` takes them
+ * @returns {boolean}
+ */
+export function callsBasicStyle(files) {
+  return _bundleSources(files).some((s) =>
+    _BASIC_STYLE_CALL.test(_stripNonCode(s)),
+  );
+}
+
 // sc-7799 — a group name that groups everything defeats the rule: one
 // catch-all fieldset reads exactly like the flat list it replaced.
 const _GENERIC_STYLE_GROUPS = new Set([
@@ -2045,16 +2181,9 @@ const _GENERIC_STYLE_GROUPS = new Set([
 ]);
 
 // The five the basic-style gate mandates; they restyle the widget as a whole.
-// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
-// — a mandated field missing here reads as per-element coverage the widget does
-// not have, which silently retires this rule for EVERY generated widget.
-const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
-  "background",
-  "textColor",
-  "align",
-  "padding",
-  "margin",
-]);
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set(
+  Object.keys(CONTRACT.basicStyleSchema),
+);
 
 // A second element an author would style apart from the text. Pressable and
 // Button are deliberately absent: a touch target wrapping the only label is
@@ -2375,26 +2504,9 @@ export function lintSource(source, options) {
   }
   const findings = [];
   const lines = source.split(/\r?\n/);
-  // Scan code with comments + string/template text blanked out so a banned
-  // identifier only fires on an actual code reference, not on the same word
-  // appearing in prose or string data. `codeLines` lines up 1:1 with `lines`
-  // (masking preserves newlines), so the reported snippet still comes from
-  // the original source.
-  const codeLines = _stripNonCode(source).split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const codeLine = codeLines[i];
-    for (const rule of RULES) {
-      if (rule.pattern.test(codeLine)) {
-        findings.push({
-          rule: rule.id,
-          severity: "error",
-          label: rule.label,
-          line: i + 1,
-          snippet: lines[i].trim().slice(0, 200),
-        });
-      }
-    }
-  }
+  // Comments and string text are masked, so a banned identifier fires only on
+  // code, never on the same word in prose or string data.
+  findings.push(..._bannedApiFindings(source, lines));
   // REQ-WSDK-PLATFORM §3.4: import-specifier validation.
   findings.push(
     ..._importRules(source, options && options.manifest).map((f) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.270.0",
+  "version": "0.272.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -386,6 +386,38 @@ const THEME_SPACING_SCALE = Object.freeze({
   default: 1,
 });
 
+// The style fields every generated widget declares, with the controls the
+// Studio renders for them. One source for `BASIC_STYLE_SCHEMA` /
+// `basicStyle()`, the linter, the publish gate and the Mason plan gate.
+const BASIC_STYLE_GROUP = Object.freeze({ group: "Basics" });
+const BASIC_SPACING_RANGE = Object.freeze({ min: 0, max: 64 });
+const BASIC_STYLE_SCHEMA = Object.freeze({
+  background: Object.freeze({ type: "color", label: "Background", ui: BASIC_STYLE_GROUP }),
+  textColor: Object.freeze({ type: "color", label: "Text color", ui: BASIC_STYLE_GROUP }),
+  align: Object.freeze({
+    type: "select",
+    label: "Align",
+    enum: Object.freeze([
+      Object.freeze({ value: "left", label: "Left" }),
+      Object.freeze({ value: "center", label: "Center" }),
+      Object.freeze({ value: "right", label: "Right" }),
+    ]),
+    ui: BASIC_STYLE_GROUP,
+  }),
+  padding: Object.freeze({
+    type: "spacing",
+    label: "Padding",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+  margin: Object.freeze({
+    type: "spacing",
+    label: "Margin",
+    validation: BASIC_SPACING_RANGE,
+    ui: BASIC_STYLE_GROUP,
+  }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -4505,6 +4537,20 @@ const BANNED_APIS = [
     reason:
       "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
   },
+  ...["self", "top", "parent", "frames", "opener"].map((identifier) => ({
+    identifier,
+    reason:
+      "Another name for window. Refused where it reads a variable, so rename a local one; `insets.top` and `{ top: 0 }` are fine.",
+  })),
+  {
+    identifier: "frameElement",
+    reason: "The element framing the page, a route to the host document.",
+  },
+  {
+    identifier: ".constructor",
+    reason:
+      "Reaches Function(), which evaluates strings. Refused as a property read or quoted name; a class's own constructor() method is fine.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -6505,7 +6551,12 @@ const CONTRACT = deepFreeze({
   //    every query, record, figure and aggregate on that table, app-wide.
   // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
   //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
-  version: "1.220.0",
+  // 1.221.0: additive (sc-14460) — `basicStyleSchema`, exported as
+  //    `BASIC_STYLE_SCHEMA`, and `basicStyle(style)`, which applies it.
+  // 1.222.0: stricter (sc-14479) — `self`, `top`, `parent`, `frames`,
+  //    `opener`, `frameElement` and `.constructor` join bannedApis; `eval` and
+  //    `Function` are refused as any reference, not only as a call.
+  version: "1.222.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6530,6 +6581,7 @@ const CONTRACT = deepFreeze({
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
+  basicStyleSchema: BASIC_STYLE_SCHEMA,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.