@colixsystems/widget-sdk 0.139.0 → 0.140.0

package/README.md

@@ -70,7 +70,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.137.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.140.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.140.0 (contract 1.108.0)
+
+**Three rules make a generated widget's EDITABILITY checkable, and `lintEditability` joins the linter export (sc-7799).** The rules that already had a deterministic gate — the three basic style fields, `no-hardcoded-design`, `style-field-unread` — held every time. The ones left to prose drifted: `ui.group`, per-element coverage and author-editable copy were guidance only, so some widgets shipped a grouped Style section covering every element while others shipped the three basics and nothing else, and wording was routinely pinned in the source where no author could reach it.
+
+- **`style-group-missing`** — a `styleSchema` field with no `ui.group`, or one filed under a catch-all name (`Advanced`, `Other`, `Misc`, `Style`, `Styles`, `General`) that rebuilds the flat list grouping exists to split. The three basics belong under `"Basics"`; each per-element field under the Title Case singular name of the element it styles (`"Card"`, `"Title"`, `"Row"`).
+- **`style-elements-uncovered`** — a widget that renders several visual elements while its `styleSchema` carries nothing beyond `background`/`textColor`/`align`. A genuinely single-element widget is exempt by construction.
+- **`text-literal-unexposed`** — a string literal sitting directly in a `<Text>`: copy that reaches neither the author nor the translation pipeline.
+
+All three are `warning`, so `appstudio-widget lint` reports them and still exits 0 — the human author decides when to act. The AI widget agent publishes with no human in the loop and `_lintFindingsToPublishChecks` turns every finding into a publish check regardless of severity, so the same three **block** an agent publish and drive a repair turn, with no new severity plumbing.
+
+`lintEditability(manifest, files)` is bundle-level like `lintStyleWiring`, and needs `--manifest` for the same reason. It counts rendered elements PER FILE, though: joining `widget.web.jsx` and `widget.native.jsx` would double every tag and call a single-`<Text>` split-impl widget multi-element.
 
 ### What's new in 0.139.0 (contract 1.108.0)
 
@@ -1762,15 +1774,22 @@ npx appstudio-widget lint widget.web.jsx widget.native.jsx --manifest manifest.j
 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, lintStyleWiring } from "@colixsystems/widget-sdk/linter";
+import {
+  lintSource,
+  lintStyleWiring,
+  lintEditability,
+} 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 });
+const editability = lintEditability(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.
+Three more rules keep a widget EDITABLE once it ships (sc-7799), via the bundle-level `lintEditability(manifest, files)`. `style-group-missing` flags a `styleSchema` field with no `ui.group` — or one under a catch-all name — so a long Style section reads as labelled per-element fieldsets. `style-elements-uncovered` flags a multi-element widget whose Style section still only restyles the widget as a whole. `text-literal-unexposed` flags copy pinned in a `<Text>` — wording no control can change and no locale can translate. All three are warnings here and blocking for the AI widget agent; see *What's new in 0.140.0*.
+
+Pass `--manifest` to enable `style-field-unread` and the three editability rules — they need the manifest, and every source at once so a split-impl widget's per-host reads are seen together.
 
 `flex-basis-percent` flags a literal percentage `flexBasis` (sc-7274) — `"100%"`, `"50%"`, or the ternary a responsive cell writes. `flex-basis` sizes the MAIN axis, so in a column parent it asks for the parent's HEIGHT: under an ancestor that makes that height definite (a Grid cell stretches its child on the web Player) the child fills the container and, since a `View` never shrinks, overflows over everything below it. Say full-width with `width: "100%"` — correct in a column AND in a wrap row — and keep a NUMBER for a wrap threshold. A warning, because the percentage is right in a row and a text scan cannot see the parent.
 

package/dist/cli.js

@@ -8,7 +8,7 @@ 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, lintStyleWiring } from "./linter.js";
+import { lintSource, lintStyleWiring, lintEditability } from "./linter.js";
 import { startDevServer } from "./devserver.js";
 
 function usage() {
@@ -106,9 +106,14 @@ async function runLint(rest) {
   const wiring = manifest
     ? lintStyleWiring(manifest, files)
     : { ok: true, findings: [] };
+  // sc-7799 — same manifest+bundle shape as the dead-control gate above.
+  const editability = manifest
+    ? lintEditability(manifest, files)
+    : { ok: true, findings: [] };
   const all = perFile
     .flatMap(([, r]) => r.findings)
-    .concat(wiring.findings);
+    .concat(wiring.findings)
+    .concat(editability.findings);
   if (all.length === 0) {
     stdout.write(`${label}: clean\n`);
     exit(0);
@@ -116,7 +121,7 @@ async function runLint(rest) {
   // 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 ok = perFile.every(([, r]) => r.ok) && wiring.ok;
+  const ok = perFile.every(([, r]) => r.ok) && wiring.ok && editability.ok;
   const errors = all.filter((f) => f.severity !== "warning").length;
   const stream = ok ? stdout : stderr;
   stream.write(
@@ -131,6 +136,10 @@ async function runLint(rest) {
     stream.write(`manifest.styleSchema:\n`);
     writeFindings(wiring.findings, stream);
   }
+  if (editability.findings.length > 0) {
+    stream.write(`manifest.editability:\n`);
+    writeFindings(editability.findings, stream);
+  }
   exit(ok ? 0 : 1);
 }
 

package/dist/linter.cjs

@@ -1438,11 +1438,7 @@ function lintStyleWiring(manifest, files) {
   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);
+  const sources = _bundleSources(files);
   if (sources.length === 0) return empty;
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
@@ -1471,6 +1467,266 @@ function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+// 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([
+  "advanced",
+  "other",
+  "misc",
+  "style",
+  "styles",
+  "general",
+]);
+
+// The three the basic-style gate mandates; they restyle the widget as a whole.
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
+  "background",
+  "textColor",
+  "align",
+]);
+
+// 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
+// one element, not two.
+const _SECOND_ELEMENT_TAGS = ["Image", "TextInput", "FlatList", "SectionList"];
+
+const _SEPARATOR_GLYPHS = new Set(["-", "–", "—", "•", "·", "…", "|", "/"]);
+
+// Names ride the finding; the remainder is counted, so one finding stays
+// inside the agent's per-message budget however many fields are wrong.
+const _EDITABILITY_LIST_CAP = 3;
+
+// Tighter for copy: each entry carries the text AND its line, so six of them
+// push the message past the report's 300-char truncation.
+const _LITERAL_LIST_CAP = 2;
+
+// Shared by both bundle-level gates — one normaliser, not two.
+function _bundleSources(files) {
+  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);
+  return sources.filter((s) => typeof s === "string" && s.length > 0);
+}
+
+function _plainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// Both the count and each entry are bounded: the backend wraps the label in
+// `[manifest.editability] … (line N: snippet)` and truncates at 300, so an
+// unbounded name list loses the tail of the advice that follows it.
+function _clip(text, max) {
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function _quoteList(names) {
+  const shown = names.slice(0, _EDITABILITY_LIST_CAP).map((n) => _clip(n, 16));
+  const more = names.length - shown.length;
+  return shown.join(", ") + (more > 0 ? `, …(+${more} more)` : "");
+}
+
+// Copy worth a control: a separator glyph or a bare number is chrome.
+function _isAuthoredCopy(text) {
+  if (text.length < 2) return false;
+  if (!/[A-Za-z]/.test(text)) return false;
+  return !_SEPARATOR_GLYPHS.has(text);
+}
+
+// The `>` that CLOSES a JSX tag, skipping quoted attribute values and any `>`
+// inside a `{…}` expression — `onPress={() => x}` carries one, and treating it
+// as the tag end reports the handler body as copy.
+function _tagEnd(code, from) {
+  let depth = 0;
+  let quote = null;
+  for (let i = from; i < code.length; i++) {
+    const ch = code[i];
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+    else if (ch === ">" && depth <= 0) return i;
+  }
+  return -1;
+}
+
+// The balanced `{…}` starting at `from`, or null.
+function _bracedSpan(code, from) {
+  if (code[from] !== "{") return null;
+  let depth = 0;
+  let quote = null;
+  for (let i = from; i < code.length; i++) {
+    const ch = code[i];
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return code.slice(from + 1, i);
+    }
+  }
+  return null;
+}
+
+// Copy pinned in a `<Text>`: a bare literal child, or a braced child that is
+// NOTHING BUT a string literal (`{"Hello"}`) — the one-pair-of-braces evasion.
+// A braced expression carrying an identifier is left alone: it may already be
+// a prop, and under-firing is right for a gate that blocks a publish.
+function _textLiteralOccurrences(codes, masks) {
+  const byText = new Map();
+  for (let f = 0; f < codes.length; f++) {
+    const code = codes[f];
+    // Locate tags on the string-blanked mask, so markup HELD IN a string is
+    // not read as markup. Both masks preserve offsets, so the child is read
+    // back from the kept-strings source at the very same index.
+    const mask = masks[f];
+    const re = /<Text\b/g;
+    let m;
+    while ((m = re.exec(mask)) !== null) {
+      const end = _tagEnd(mask, m.index);
+      if (end === -1) continue;
+      let i = end + 1;
+      while (i < code.length && /\s/.test(code[i])) i++;
+      let text = null;
+      if (code[i] === "{") {
+        const inner = _bracedSpan(code, i);
+        const lit =
+          inner && inner.trim().match(/^(["'`])((?:\\.|(?!\1).)*)\1$/);
+        // A template carrying `${…}` interpolates a value, so it is not a literal.
+        if (lit && !(lit[1] === "`" && lit[2].includes("${"))) text = lit[2];
+      } else {
+        const child = code.slice(i).match(/^([^<>{}\n]+)/);
+        if (child) text = child[1];
+      }
+      if (text === null) continue;
+      text = text.trim();
+      if (!_isAuthoredCopy(text) || byText.has(text)) continue;
+      // Split-impl carries the same copy twice; report the string, not the file.
+      byText.set(text, code.slice(0, i).split("\n").length);
+    }
+  }
+  return [...byText.entries()].map(([text, line]) => ({ text, line }));
+}
+
+// Per FILE: joining widget.web.jsx and widget.native.jsx doubles every tag.
+// A second element must be a DISTINCT visual kind beside the text — two
+// `<Text>` tags are as often a loading branch and its content as a title and
+// a body, and a blocking gate may not guess.
+function _rendersSeveralElements(code) {
+  if (!/<Text[\s>/]/.test(code)) return false;
+  return _SECOND_ELEMENT_TAGS.some((tag) =>
+    new RegExp(`<${tag}[\\s>/]`).test(code),
+  );
+}
+
+function _styleGroupFindings(manifest) {
+  const schema = _plainObject(manifest) ? manifest.styleSchema : null;
+  if (!_plainObject(schema)) return [];
+  const bad = Object.keys(schema).filter((field) => {
+    const def = schema[field];
+    const group = _plainObject(def) && _plainObject(def.ui) ? def.ui.group : "";
+    if (typeof group !== "string" || group.trim().length === 0) return true;
+    return _GENERIC_STYLE_GROUPS.has(group.trim().toLowerCase());
+  });
+  if (bad.length === 0) return [];
+  return [
+    {
+      rule: "style-group-missing",
+      severity: "warning",
+      label:
+        `styleSchema fields with no usable ui.group: ${_quoteList(
+          bad.map((f) => `"${f}"`),
+        )}. Group EVERY field — basics under "Basics", each per-element ` +
+        `field under the element it styles. A catch-all name is not a group.`,
+      line: 0,
+      snippet: _clip(bad[0], 12),
+    },
+  ];
+}
+
+function _styleCoverageFindings(manifest, codes) {
+  const schema = _plainObject(manifest) ? manifest.styleSchema : null;
+  if (!_plainObject(schema)) return [];
+  const fields = Object.keys(schema);
+  if (fields.length === 0) return [];
+  if (fields.some((f) => !_WHOLE_WIDGET_STYLE_FIELDS.has(f))) return [];
+  if (!codes.some(_rendersSeveralElements)) return [];
+  return [
+    {
+      rule: "style-elements-uncovered",
+      severity: "warning",
+      label:
+        `The widget renders more than one visual element but its styleSchema ` +
+        `stops at background/textColor/align. Add 2-4 grouped per-element ` +
+        `fields (cardBackground, titleColor, rowBackground, imageRadius), ` +
+        `each applied ONLY when set.`,
+      line: 0,
+      snippet: "",
+    },
+  ];
+}
+
+function _textLiteralFindings(occurrences) {
+  if (occurrences.length === 0) return [];
+  // Each entry is bounded so a long line of copy cannot push the whole
+  // message past the report's truncation and take the line numbers with it.
+  const listed = occurrences
+    .slice(0, _LITERAL_LIST_CAP)
+    .map((o) => `"${_clip(o.text, 16)}" (line ${o.line})`);
+  const more = occurrences.length - listed.length;
+  return [
+    {
+      rule: "text-literal-unexposed",
+      severity: "warning",
+      label:
+        `Copy pinned in a <Text> reaches neither author nor translation: ` +
+        `${listed.join(", ")}${more > 0 ? `, …(+${more} more)` : ""}. ` +
+        `Declare each as a propertySchema string defaulting to that text ` +
+        `and render the prop; fixed chrome uses t().`,
+      line: occurrences[0].line,
+      snippet: _clip(occurrences[0].text, 12),
+    },
+  ];
+}
+
+/**
+ * sc-7799 — the editability gates: what an author can still change once the
+ * widget ships. Bundle-level like `lintStyleWiring`, and for the same reason
+ * — one manifest serves both halves of a split-impl widget.
+ *
+ * Each rule emits ONE consolidated finding, because the agent's draft-findings
+ * report keeps only the first dozen checks and truncates each message: a
+ * per-field finding on a 14-field manifest would evict the render-time crash
+ * sitting behind it.
+ *
+ * @param {object} manifest widget manifest (`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 lintEditability(manifest, files) {
+  const sources = _bundleSources(files);
+  if (sources.length === 0) return { ok: true, findings: [] };
+  const codes = sources.map((s) => _stripNonCode(s, { keepStrings: true }));
+  const masks = sources.map((s) => _stripNonCode(s, { keepStrings: false }));
+  const findings = [
+    ..._styleGroupFindings(manifest),
+    ..._styleCoverageFindings(manifest, codes),
+    ..._textLiteralFindings(_textLiteralOccurrences(codes, masks)),
+  ];
+  // Every rule here is a warning by construction: the CLI must stay exit-0 for
+  // a human author, while the agent blocks on any finding regardless.
+  return { ok: true, findings };
+}
+
 function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -1553,6 +1809,7 @@ function lintSource(source, options) {
 module.exports = {
   lintSource,
   lintStyleWiring,
+  lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,
 };

package/dist/linter.js

@@ -1509,11 +1509,7 @@ export function lintStyleWiring(manifest, files) {
   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);
+  const sources = _bundleSources(files);
   if (sources.length === 0) return empty;
   const code = sources
     .map((s) => _stripNonCode(s, { keepStrings: true }))
@@ -1542,6 +1538,266 @@ export function lintStyleWiring(manifest, files) {
   return { ok: !hasErrors, findings };
 }
 
+// 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([
+  "advanced",
+  "other",
+  "misc",
+  "style",
+  "styles",
+  "general",
+]);
+
+// The three the basic-style gate mandates; they restyle the widget as a whole.
+const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
+  "background",
+  "textColor",
+  "align",
+]);
+
+// 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
+// one element, not two.
+const _SECOND_ELEMENT_TAGS = ["Image", "TextInput", "FlatList", "SectionList"];
+
+const _SEPARATOR_GLYPHS = new Set(["-", "–", "—", "•", "·", "…", "|", "/"]);
+
+// Names ride the finding; the remainder is counted, so one finding stays
+// inside the agent's per-message budget however many fields are wrong.
+const _EDITABILITY_LIST_CAP = 3;
+
+// Tighter for copy: each entry carries the text AND its line, so six of them
+// push the message past the report's 300-char truncation.
+const _LITERAL_LIST_CAP = 2;
+
+// Shared by both bundle-level gates — one normaliser, not two.
+function _bundleSources(files) {
+  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);
+  return sources.filter((s) => typeof s === "string" && s.length > 0);
+}
+
+function _plainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// Both the count and each entry are bounded: the backend wraps the label in
+// `[manifest.editability] … (line N: snippet)` and truncates at 300, so an
+// unbounded name list loses the tail of the advice that follows it.
+function _clip(text, max) {
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function _quoteList(names) {
+  const shown = names.slice(0, _EDITABILITY_LIST_CAP).map((n) => _clip(n, 16));
+  const more = names.length - shown.length;
+  return shown.join(", ") + (more > 0 ? `, …(+${more} more)` : "");
+}
+
+// Copy worth a control: a separator glyph or a bare number is chrome.
+function _isAuthoredCopy(text) {
+  if (text.length < 2) return false;
+  if (!/[A-Za-z]/.test(text)) return false;
+  return !_SEPARATOR_GLYPHS.has(text);
+}
+
+// The `>` that CLOSES a JSX tag, skipping quoted attribute values and any `>`
+// inside a `{…}` expression — `onPress={() => x}` carries one, and treating it
+// as the tag end reports the handler body as copy.
+function _tagEnd(code, from) {
+  let depth = 0;
+  let quote = null;
+  for (let i = from; i < code.length; i++) {
+    const ch = code[i];
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+    else if (ch === ">" && depth <= 0) return i;
+  }
+  return -1;
+}
+
+// The balanced `{…}` starting at `from`, or null.
+function _bracedSpan(code, from) {
+  if (code[from] !== "{") return null;
+  let depth = 0;
+  let quote = null;
+  for (let i = from; i < code.length; i++) {
+    const ch = code[i];
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return code.slice(from + 1, i);
+    }
+  }
+  return null;
+}
+
+// Copy pinned in a `<Text>`: a bare literal child, or a braced child that is
+// NOTHING BUT a string literal (`{"Hello"}`) — the one-pair-of-braces evasion.
+// A braced expression carrying an identifier is left alone: it may already be
+// a prop, and under-firing is right for a gate that blocks a publish.
+function _textLiteralOccurrences(codes, masks) {
+  const byText = new Map();
+  for (let f = 0; f < codes.length; f++) {
+    const code = codes[f];
+    // Locate tags on the string-blanked mask, so markup HELD IN a string is
+    // not read as markup. Both masks preserve offsets, so the child is read
+    // back from the kept-strings source at the very same index.
+    const mask = masks[f];
+    const re = /<Text\b/g;
+    let m;
+    while ((m = re.exec(mask)) !== null) {
+      const end = _tagEnd(mask, m.index);
+      if (end === -1) continue;
+      let i = end + 1;
+      while (i < code.length && /\s/.test(code[i])) i++;
+      let text = null;
+      if (code[i] === "{") {
+        const inner = _bracedSpan(code, i);
+        const lit =
+          inner && inner.trim().match(/^(["'`])((?:\\.|(?!\1).)*)\1$/);
+        // A template carrying `${…}` interpolates a value, so it is not a literal.
+        if (lit && !(lit[1] === "`" && lit[2].includes("${"))) text = lit[2];
+      } else {
+        const child = code.slice(i).match(/^([^<>{}\n]+)/);
+        if (child) text = child[1];
+      }
+      if (text === null) continue;
+      text = text.trim();
+      if (!_isAuthoredCopy(text) || byText.has(text)) continue;
+      // Split-impl carries the same copy twice; report the string, not the file.
+      byText.set(text, code.slice(0, i).split("\n").length);
+    }
+  }
+  return [...byText.entries()].map(([text, line]) => ({ text, line }));
+}
+
+// Per FILE: joining widget.web.jsx and widget.native.jsx doubles every tag.
+// A second element must be a DISTINCT visual kind beside the text — two
+// `<Text>` tags are as often a loading branch and its content as a title and
+// a body, and a blocking gate may not guess.
+function _rendersSeveralElements(code) {
+  if (!/<Text[\s>/]/.test(code)) return false;
+  return _SECOND_ELEMENT_TAGS.some((tag) =>
+    new RegExp(`<${tag}[\\s>/]`).test(code),
+  );
+}
+
+function _styleGroupFindings(manifest) {
+  const schema = _plainObject(manifest) ? manifest.styleSchema : null;
+  if (!_plainObject(schema)) return [];
+  const bad = Object.keys(schema).filter((field) => {
+    const def = schema[field];
+    const group = _plainObject(def) && _plainObject(def.ui) ? def.ui.group : "";
+    if (typeof group !== "string" || group.trim().length === 0) return true;
+    return _GENERIC_STYLE_GROUPS.has(group.trim().toLowerCase());
+  });
+  if (bad.length === 0) return [];
+  return [
+    {
+      rule: "style-group-missing",
+      severity: "warning",
+      label:
+        `styleSchema fields with no usable ui.group: ${_quoteList(
+          bad.map((f) => `"${f}"`),
+        )}. Group EVERY field — basics under "Basics", each per-element ` +
+        `field under the element it styles. A catch-all name is not a group.`,
+      line: 0,
+      snippet: _clip(bad[0], 12),
+    },
+  ];
+}
+
+function _styleCoverageFindings(manifest, codes) {
+  const schema = _plainObject(manifest) ? manifest.styleSchema : null;
+  if (!_plainObject(schema)) return [];
+  const fields = Object.keys(schema);
+  if (fields.length === 0) return [];
+  if (fields.some((f) => !_WHOLE_WIDGET_STYLE_FIELDS.has(f))) return [];
+  if (!codes.some(_rendersSeveralElements)) return [];
+  return [
+    {
+      rule: "style-elements-uncovered",
+      severity: "warning",
+      label:
+        `The widget renders more than one visual element but its styleSchema ` +
+        `stops at background/textColor/align. Add 2-4 grouped per-element ` +
+        `fields (cardBackground, titleColor, rowBackground, imageRadius), ` +
+        `each applied ONLY when set.`,
+      line: 0,
+      snippet: "",
+    },
+  ];
+}
+
+function _textLiteralFindings(occurrences) {
+  if (occurrences.length === 0) return [];
+  // Each entry is bounded so a long line of copy cannot push the whole
+  // message past the report's truncation and take the line numbers with it.
+  const listed = occurrences
+    .slice(0, _LITERAL_LIST_CAP)
+    .map((o) => `"${_clip(o.text, 16)}" (line ${o.line})`);
+  const more = occurrences.length - listed.length;
+  return [
+    {
+      rule: "text-literal-unexposed",
+      severity: "warning",
+      label:
+        `Copy pinned in a <Text> reaches neither author nor translation: ` +
+        `${listed.join(", ")}${more > 0 ? `, …(+${more} more)` : ""}. ` +
+        `Declare each as a propertySchema string defaulting to that text ` +
+        `and render the prop; fixed chrome uses t().`,
+      line: occurrences[0].line,
+      snippet: _clip(occurrences[0].text, 12),
+    },
+  ];
+}
+
+/**
+ * sc-7799 — the editability gates: what an author can still change once the
+ * widget ships. Bundle-level like `lintStyleWiring`, and for the same reason
+ * — one manifest serves both halves of a split-impl widget.
+ *
+ * Each rule emits ONE consolidated finding, because the agent's draft-findings
+ * report keeps only the first dozen checks and truncates each message: a
+ * per-field finding on a 14-field manifest would evict the render-time crash
+ * sitting behind it.
+ *
+ * @param {object} manifest widget manifest (`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 lintEditability(manifest, files) {
+  const sources = _bundleSources(files);
+  if (sources.length === 0) return { ok: true, findings: [] };
+  const codes = sources.map((s) => _stripNonCode(s, { keepStrings: true }));
+  const masks = sources.map((s) => _stripNonCode(s, { keepStrings: false }));
+  const findings = [
+    ..._styleGroupFindings(manifest),
+    ..._styleCoverageFindings(manifest, codes),
+    ..._textLiteralFindings(_textLiteralOccurrences(codes, masks)),
+  ];
+  // Every rule here is a warning by construction: the CLI must stay exit-0 for
+  // a human author, while the agent blocks on any finding regardless.
+  return { ok: true, findings };
+}
+
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.139.0",
+  "version": "0.140.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/theme-token-refs.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-flex-basis-percent.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__/flatten-entry.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__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.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 src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/theme-token-refs.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-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-editability.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__/flatten-entry.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__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.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 src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
   },
   "engines": {
     "node": ">=18"