@colixsystems/widget-sdk 0.139.0 → 0.141.0

package/README.md

@@ -70,7 +70,27 @@ 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.141.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.141.0 (contract 1.109.0)
+
+**The app's global navigation is the sidebar alone — `top-bar` and `bottom-tabs` leave `CONTRACT.themeMenuTypes` (sc-7352, REQ-NAV-STRUCTURE).** A top bar is now a PAGE's local bar drawing a saved menu (REQ-NAV-LOCAL, sc-7103): the same tab row the `top-bar` shape used to draw, themed by the same `topBar` tokens (`resolveTopBarTokens` is unchanged), worn by one page under the sidebar. Two "top bars" competing for one word and one token set was the reason.
+
+- `normaliseNavigation` resolves a stored `top-bar` or `bottom-tabs` to `sidebar`, so a host never has to guard the value. `menuItemCap` / `quickBarCap` keep their signatures (`quickBarCap("sidebar")` is still 5).
+- The global menu never lived in the shape (it is the pages' `show_in_menu` flags), so a workspace that stored a retired shape already draws the sidebar with the same menu. The sc-7352 backfill deletes the stored key BEFORE the shapes disappear; a bottom-tabs app's phone strip becomes the sidebar's quick bar.
+- Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.109.0`.
+
+### 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 +1782,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/contract.cjs

@@ -217,36 +217,20 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
 // author without every host actually drawing it.
 //
-// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
-// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
-// curated bar, so its own cap may drop a page -- the rail still lists every one.
-// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
-// moves behind a "More" sheet instead.
+// REQ-NAV-STRUCTURE (sc-7352): the app's GLOBAL navigation has exactly one
+// shape, the sidebar. A top bar is a PAGE's local bar drawing a saved menu
+// (REQ-NAV-LOCAL), themed by the `topBar` tokens, never an app-wide menu shape.
+// `maxItems` is the menu cap (none for a rail); `quickBarMaxItems` caps the
+// SECONDARY mobile quick bar, which may drop a page because the rail and the
+// drawer still list every one.
 const THEME_MENU_TYPES = Object.freeze({
   sidebar: Object.freeze({
     name: "Sidebar",
     summary:
       "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
     maxItems: null,
-    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
-    // the rail and the drawer still list every one -- the opposite of
-    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
     quickBarMaxItems: 5,
   }),
-  "top-bar": Object.freeze({
-    name: "Top bar",
-    summary:
-      "A tab row beneath the app header at every width -- icon and label per page, scrolling sideways when it runs out of room. No rail at any width.",
-    maxItems: null,
-    quickBarMaxItems: null,
-  }),
-  "bottom-tabs": Object.freeze({
-    name: "Bottom tabs",
-    summary:
-      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
-    maxItems: 4,
-    quickBarMaxItems: null,
-  }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
@@ -3976,7 +3960,17 @@ const CONTRACT = deepFreeze({
   //    a stored hex is untouched and still renders byte-identically, and an
   //    unresolvable binding falls back to the field's `themeDefault` rather
   //    than painting blank.
-  version: "1.108.0",
+  // 1.109.0: BREAKING on the pre-1.0 channel (sc-7352) — `themeMenuTypes`
+  //    loses `top-bar` and `bottom-tabs`: the app's global navigation is the
+  //    sidebar alone, and a top bar is a page's LOCAL bar drawing a saved menu
+  //    (REQ-NAV-LOCAL), themed by the same `topBar` tokens. A stored
+  //    `navigation.menuType` of a retired shape resolves to `sidebar` through
+  //    `normaliseNavigation`, so no host has to guard the value; the global
+  //    menu never lived in the shape, so such apps already draw the sidebar,
+  //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
+  //    strip becomes the sidebar's quick bar) BEFORE this ships.
+  //    `menuItemCap` / `quickBarCap` keep their signatures.
+  version: "1.109.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -217,36 +217,20 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
 // author without every host actually drawing it.
 //
-// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
-// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
-// curated bar, so its own cap may drop a page -- the rail still lists every one.
-// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
-// moves behind a "More" sheet instead.
+// REQ-NAV-STRUCTURE (sc-7352): the app's GLOBAL navigation has exactly one
+// shape, the sidebar. A top bar is a PAGE's local bar drawing a saved menu
+// (REQ-NAV-LOCAL), themed by the `topBar` tokens, never an app-wide menu shape.
+// `maxItems` is the menu cap (none for a rail); `quickBarMaxItems` caps the
+// SECONDARY mobile quick bar, which may drop a page because the rail and the
+// drawer still list every one.
 const THEME_MENU_TYPES = Object.freeze({
   sidebar: Object.freeze({
     name: "Sidebar",
     summary:
       "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
     maxItems: null,
-    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
-    // the rail and the drawer still list every one -- the opposite of
-    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
     quickBarMaxItems: 5,
   }),
-  "top-bar": Object.freeze({
-    name: "Top bar",
-    summary:
-      "A tab row beneath the app header at every width -- icon and label per page, scrolling sideways when it runs out of room. No rail at any width.",
-    maxItems: null,
-    quickBarMaxItems: null,
-  }),
-  "bottom-tabs": Object.freeze({
-    name: "Bottom tabs",
-    summary:
-      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
-    maxItems: 4,
-    quickBarMaxItems: null,
-  }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
@@ -3976,7 +3960,17 @@ const CONTRACT = deepFreeze({
   //    a stored hex is untouched and still renders byte-identically, and an
   //    unresolvable binding falls back to the field's `themeDefault` rather
   //    than painting blank.
-  version: "1.108.0",
+  // 1.109.0: BREAKING on the pre-1.0 channel (sc-7352) — `themeMenuTypes`
+  //    loses `top-bar` and `bottom-tabs`: the app's global navigation is the
+  //    sidebar alone, and a top bar is a page's LOCAL bar drawing a saved menu
+  //    (REQ-NAV-LOCAL), themed by the same `topBar` tokens. A stored
+  //    `navigation.menuType` of a retired shape resolves to `sidebar` through
+  //    `normaliseNavigation`, so no host has to guard the value; the global
+  //    menu never lived in the shape, so such apps already draw the sidebar,
+  //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
+  //    strip becomes the sidebar's quick bar) BEFORE this ships.
+  //    `menuItemCap` / `quickBarCap` keep their signatures.
+  version: "1.109.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -150,10 +150,11 @@ export function createToastController(
 ): ToastController;
 
 // REQ-NAV-STRUCTURE — the navigation SHAPE a host draws its chrome in. The
-// vocabulary is closed by `CONTRACT.themeMenuTypes`; these are the resolvers
-// both hosts switch on.
+// vocabulary is closed by `CONTRACT.themeMenuTypes`; since sc-7352 it holds
+// the sidebar alone (a top bar is a page's local bar, REQ-NAV-LOCAL), and any
+// stored value outside it resolves to `sidebar`.
 
-export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
+export type ThemeMenuType = "sidebar";
 
 export interface ResolvedNavigation {
   menuType: ThemeMenuType;
@@ -168,8 +169,7 @@ export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
 
 /**
  * How many menu pages this shape may draw at once, or `null` for no cap. The
- * cap's meaning differs per type: the sidebar's quick bar may drop a page past
- * it, a bottom-tabs strip must move its surplus behind a More sheet.
+ * sidebar has none — its rail and drawer list every menu page.
  */
 export function menuItemCap(menuType: string): number | null;
 
@@ -232,16 +232,14 @@ export interface TopBarTokens {
    *  label plus its indicator. Falls back to the RAIL's `activeColor` and then
    *  to the brand, so an app states its navigation colour once. */
   activeColor: string;
-  /** How a `tabs` menu row marks its current page. `underline` keeps the tab in
-   *  the bar's surface behind an indicator; `attached` makes it a folder tab
-   *  that takes `contentSurface` and sits over the row's divider. Meaningless
-   *  under the `links` style, which draws no tabs. */
+  /** How a local bar marks its current page. `underline` keeps the tab in the
+   *  bar's surface behind an indicator; `attached` cuts the bar away under the
+   *  current tab so the page shows through it. */
   tabStyle: "underline" | "attached";
-  /** The surface an `attached` tab AND its content panel share — always
-   *  opaque, because a translucent tab would show the bar through the page it
-   *  is part of. Honours `tabActiveBackgroundColor`, so moving the tab moves
-   *  the page with it. */
-  contentSurface: string;
+  /** Under `attached`, the colour the PANEL behind the row paints — the
+   *  authored `tabActiveBackgroundColor`, alpha kept — or null for the page's
+   *  own wash. The current tab paints nothing itself. */
+  contentSurface: string | null;
   /** A tab's own surface, authored or null. Null paints none and the bar shows
    *  through. */
   tabBackgroundColor: string | null;

package/dist/host.js

@@ -52,15 +52,14 @@ export {
   TOAST_DEFAULTS,
 } from "./toast-host.js";
 
-// REQ-NAV-STRUCTURE: the navigation-shape resolver both hosts draw their chrome
-// from. `normaliseNavigation` turns a stored `theme_config.navigation` block into
-// the resolved `{ menuType }` the chrome switches on; `menuItemCap` states how
-// many menu pages that shape may draw at once. One implementation, so a menu
-// type cannot mean one thing in the Player and another in the Expo export.
-// `resolveFooterTokens` is the footer strip's own token set, falling back to
-// the sidebar's so an untouched workspace keeps the appearance it has. It
-// exists because the strip IS the menu under `bottom-tabs`, where the sidebar
-// panel is hidden and those tokens can no longer be set at all.
+// REQ-NAV-STRUCTURE: the navigation resolver both hosts draw their chrome from.
+// `normaliseNavigation` turns a stored `theme_config.navigation` block into the
+// resolved `{ menuType }` — always `sidebar` since sc-7352 retired the other
+// shapes, so a stored value never needs guarding; `menuItemCap` / `quickBarCap`
+// state the caps. One implementation, so the chrome cannot mean one thing in
+// the Player and another in the Expo export. `resolveFooterTokens` is the quick
+// bar's own token set, falling back to the sidebar's so an untouched workspace
+// keeps the appearance it has.
 // REQ-THEME-14: `resolveSidebarTokens` and `resolveTopBarTokens` are the same
 // idea for the rail and the app bar, whose defaults used to live inline in each
 // host and had already drifted apart.

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/dist/navigation.cjs

@@ -59,10 +59,8 @@ function normaliseNavigation(navigation) {
 }
 
 /**
- * How many MENU pages the chrome may draw at once, or `null` for no cap.
- *
- * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
- * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ * How many MENU pages the chrome may draw at once, or `null` for no cap. The
+ * sidebar has none. Contrast `quickBarCap` below.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -90,13 +88,17 @@ function quickBarCap(menuType) {
 }
 
 // The strip's surface was hard-coded white on BOTH hosts and its items read the
-// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
-// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
-// tokens have nowhere to be set). `footer` gives it tokens of its own.
+// sidebar's tokens. `footer` gives the quick bar tokens of its own.
+//
+// Every colour falls back to the sidebar's, so a workspace that never opens the
+// panel keeps exactly the appearance it has today; only an explicit `footer`
+// value moves anything.
 //
-// Every field falls back to the sidebar's, so a workspace that never opens the
-// Footer panel keeps exactly the appearance it has today; only an explicit
-// `footer` value moves anything.
+// sc-7695: this block is the BOTTOM EDGE's, not the quick bar's alone. A page's
+// own bottom bar (REQ-NAV-LOCAL) is the same strip worn by one page and reads
+// exactly these values — the Design panel that edits them is named for that
+// bar, since the quick bar is on its way out (sc-7753) and the look outlives
+// it. No key is the bar's alone: two strips, one look.
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -176,11 +178,6 @@ function pageColor(config, alphaRule) {
   );
 }
 
-// An `attached` tab: opaque, or the bar shows through the page it joins.
-function pageSurface(config) {
-  return pageColor(config, opaqueOr);
-}
-
 // sc-6596: what an UNSET rail or bar is painted. Read at full strength — an
 // alpha on the bottom layer would mean nothing to chrome above it.
 function chromeSurface(config) {
@@ -223,12 +220,6 @@ function tabIndicatorOr(value) {
   return Math.min(Math.max(Math.round(value), 0), TAB_INDICATOR_MAX);
 }
 
-function opaqueOr(value) {
-  return isHexColor(value) && value.length !== 9 && value.length !== 5
-    ? value
-    : null;
-}
-
 // A gradient stop as the page readers admit one: flat hex, never alpha.
 function flatHexOrNull(value) {
   return isHexColor(value) && value.length !== 9 ? value : null;
@@ -330,18 +321,15 @@ function resolveTopBarTokens(theme) {
     // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
-    // The surface an `attached` tab AND its content panel share. One value for
-    // both, so the join cannot come apart: whatever the current tab is painted,
-    // the page beneath it is painted too. An authored active surface therefore
-    // moves both. Resolved HERE rather than by each host, because a tab that
-    // fails to match the page it is joined to reads as a mismatched box instead
-    // of a tab, and two hosts computing it separately is exactly how that
-    // drifts. Opaque by construction: a translucent tab would show the bar
-    // through the page it claims to be part of.
-    contentSurface: hexOr(
-      opaqueOr(topBar.tabActiveBackgroundColor),
-      pageSurface(config),
-    ),
+    // The surface the PANEL behind an `attached` row paints — the authored
+    // active colour, alpha and all, or nothing. Under `attached` the current
+    // tab itself paints NOTHING: it is a hole in the bar, and what shows
+    // through it is this panel, or the page's own wash when this is null. So
+    // the tab is exactly as see-through as the page, a gradient stays one
+    // gradient, and a translucent page never doubles up under a tab (sc-7352 —
+    // painting the tab a copy of the page could never do any of that). One
+    // value, resolved HERE, so both hosts paint the panel the same colour.
+    contentSurface: hexOrNull(topBar.tabActiveBackgroundColor),
     // REQ-NAV-STRUCTURE: the underline that marks the current tab, in px. Zero
     // turns it OFF and leaves the tab marked by its label colour alone, which
     // is a real choice rather than an unstyled state — so unlike the chrome
@@ -360,9 +348,9 @@ function resolveTopBarTokens(theme) {
     // and the bar shows through it, which is what the row did before the keys
     // existed — so an app that never set them is unchanged.
     tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
-    // Only meaningful where the style draws no panel: under `attached` the
-    // active surface IS `contentSurface` above. Null under `underline` leaves
-    // the current tab unpainted, marked by its indicator alone.
+    // Under `underline` the current tab's own surface, or null for none. Under
+    // `attached` the tab paints nothing and this colour is the PANEL's — see
+    // `contentSurface` above.
     tabActiveBackgroundColor: hexOrNull(topBar.tabActiveBackgroundColor),
   };
 }

package/dist/navigation.js

@@ -50,10 +50,8 @@ export function normaliseNavigation(navigation) {
 }
 
 /**
- * How many MENU pages the chrome may draw at once, or `null` for no cap.
- *
- * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
- * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ * How many MENU pages the chrome may draw at once, or `null` for no cap. The
+ * sidebar has none. Contrast `quickBarCap` below.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -81,13 +79,17 @@ export function quickBarCap(menuType) {
 }
 
 // The strip's surface was hard-coded white on BOTH hosts and its items read the
-// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
-// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
-// tokens have nowhere to be set). `footer` gives it tokens of its own.
+// sidebar's tokens. `footer` gives the quick bar tokens of its own.
+//
+// Every colour falls back to the sidebar's, so a workspace that never opens the
+// panel keeps exactly the appearance it has today; only an explicit `footer`
+// value moves anything.
 //
-// Every field falls back to the sidebar's, so a workspace that never opens the
-// Footer panel keeps exactly the appearance it has today; only an explicit
-// `footer` value moves anything.
+// sc-7695: this block is the BOTTOM EDGE's, not the quick bar's alone. A page's
+// own bottom bar (REQ-NAV-LOCAL) is the same strip worn by one page and reads
+// exactly these values — the Design panel that edits them is named for that
+// bar, since the quick bar is on its way out (sc-7753) and the look outlives
+// it. No key is the bar's alone: two strips, one look.
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -167,11 +169,6 @@ function pageColor(config, alphaRule) {
   );
 }
 
-// An `attached` tab: opaque, or the bar shows through the page it joins.
-function pageSurface(config) {
-  return pageColor(config, opaqueOr);
-}
-
 // sc-6596: what an UNSET rail or bar is painted. Read at full strength — an
 // alpha on the bottom layer would mean nothing to chrome above it.
 function chromeSurface(config) {
@@ -214,12 +211,6 @@ function tabIndicatorOr(value) {
   return Math.min(Math.max(Math.round(value), 0), TAB_INDICATOR_MAX);
 }
 
-function opaqueOr(value) {
-  return isHexColor(value) && value.length !== 9 && value.length !== 5
-    ? value
-    : null;
-}
-
 // A gradient stop as the page readers admit one: flat hex, never alpha.
 function flatHexOrNull(value) {
   return isHexColor(value) && value.length !== 9 ? value : null;
@@ -321,18 +312,15 @@ export function resolveTopBarTokens(theme) {
     // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
-    // The surface an `attached` tab AND its content panel share. One value for
-    // both, so the join cannot come apart: whatever the current tab is painted,
-    // the page beneath it is painted too. An authored active surface therefore
-    // moves both. Resolved HERE rather than by each host, because a tab that
-    // fails to match the page it is joined to reads as a mismatched box instead
-    // of a tab, and two hosts computing it separately is exactly how that
-    // drifts. Opaque by construction: a translucent tab would show the bar
-    // through the page it claims to be part of.
-    contentSurface: hexOr(
-      opaqueOr(topBar.tabActiveBackgroundColor),
-      pageSurface(config),
-    ),
+    // The surface the PANEL behind an `attached` row paints — the authored
+    // active colour, alpha and all, or nothing. Under `attached` the current
+    // tab itself paints NOTHING: it is a hole in the bar, and what shows
+    // through it is this panel, or the page's own wash when this is null. So
+    // the tab is exactly as see-through as the page, a gradient stays one
+    // gradient, and a translucent page never doubles up under a tab (sc-7352 —
+    // painting the tab a copy of the page could never do any of that). One
+    // value, resolved HERE, so both hosts paint the panel the same colour.
+    contentSurface: hexOrNull(topBar.tabActiveBackgroundColor),
     // REQ-NAV-STRUCTURE: the underline that marks the current tab, in px. Zero
     // turns it OFF and leaves the tab marked by its label colour alone, which
     // is a real choice rather than an unstyled state — so unlike the chrome
@@ -351,9 +339,9 @@ export function resolveTopBarTokens(theme) {
     // and the bar shows through it, which is what the row did before the keys
     // existed — so an app that never set them is unchanged.
     tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
-    // Only meaningful where the style draws no panel: under `attached` the
-    // active surface IS `contentSurface` above. Null under `underline` leaves
-    // the current tab unpainted, marked by its indicator alone.
+    // Under `underline` the current tab's own surface, or null for none. Under
+    // `attached` the tab paints nothing and this colour is the PANEL's — see
+    // `contentSurface` above.
     tabActiveBackgroundColor: hexOrNull(topBar.tabActiveBackgroundColor),
   };
 }

package/package.json

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