@colixsystems/widget-sdk 0.36.0 → 0.38.0

package/README.md

@@ -26,7 +26,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
-| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) then falls back to the raw key. |
+| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -47,7 +47,21 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.36.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.38.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.38.0
+
+**Predefined SHARED translation keys (REQ-L10N-SHARED).** The standard strings the default widgets repeat ("Submit", "Cancel", "Save", "Loading…", …) now have a tenant-wide shared namespace `shared.<key>` so an identical string is translated **once** and every widget that uses it inherits the translation.
+
+- **New contract field `CONTRACT.sharedTranslationKeys`** — the predefined map (`{ <key>: { en } }`) and the single source the host seeder reads.
+- **New exported helpers** `sharedTranslationPrefix()` / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)` (from `@colixsystems/widget-sdk/contract`).
+- **`useI18n().t(key)` resolution is now three-step**: the per-widget key (`widget.<id>.<key>`) first, then the shared key (`shared.<key>`) when `key` is one of the predefined shared keys, then the raw key / fallback. So a default widget that calls `t("submit")` picks up the shared translation with no manual key entry, and an author who sets `widget.<id>.submit` in the Translations admin still overrides **that instance only**. An author-invented bare key is never silently shared.
+- **The host auto-registers the shared keys** for a tenant at workspace-content seed time and whenever a marketplace or AI-generated widget is added — idempotent and non-destructive (an admin edit is never overwritten). Authors manage / translate them in the Studio Translations screen like any other key.
+- **`CONTRACT.version` → `1.28.0`** (additive: one new contract field + three helper exports + the `useI18n` shared-key step). No existing export changed signature.
+
+### What's new in 0.37.0
+
+**`react/jsx-runtime` + `react/jsx-dev-runtime` are now vetted imports.** A widget bundle compiled with React's *automatic* JSX runtime (Vite/esbuild's default) emits `import { jsx, jsxs, Fragment } from "react/jsx-runtime"` — code the author never writes by hand. The runtime already treated these as host-provided (the web loader shims both, the AI-agent sandbox stubs them, and the Developer guide documents them as externalized), but the linter's vetted list did not list them, so such a bundle failed publish static analysis with `import-not-vetted` on `react/jsx-runtime`. Both are now on `CONTRACT.vettedImports` as `core` subpaths of the already-vetted `react`. **`CONTRACT.version` → `1.27.0`** (additive: two vetted core subpaths). No existing entry changed shape.
 
 ### What's new in 0.36.0
 

package/dist/contract.cjs

@@ -1057,6 +1057,20 @@ const VETTED_IMPORTS = [
     category: "core",
     description: "React. Hooks, JSX, lifecycle. Unchanged.",
   },
+  {
+    specifier: "react/jsx-runtime",
+    platforms: ["web", "native"],
+    category: "core",
+    description:
+      "React's automatic JSX runtime (jsx/jsxs/Fragment). Not hand-written — the JSX transform injects this import when a bundle is compiled with the automatic runtime. Host-provided on both platforms (the web loader shims it; Metro resolves the real subpath of react), so it is externalized exactly like react.",
+  },
+  {
+    specifier: "react/jsx-dev-runtime",
+    platforms: ["web", "native"],
+    category: "core",
+    description:
+      "React's automatic JSX dev runtime (jsxDEV/Fragment). The development-mode counterpart to react/jsx-runtime, injected by the JSX transform in dev builds. Host-provided on both platforms, externalized like react.",
+  },
   {
     specifier: "@colixsystems/widget-sdk",
     platforms: ["web", "native"],
@@ -1271,6 +1285,65 @@ function widgetTranslationKey(id, key) {
   return `widget.${id}.${key}`;
 }
 
+// REQ-L10N-SHARED — predefined SHARED translation keys for the standard
+// strings the default widgets repeat ("Submit", "Cancel", "Loading…", …).
+// They live in ONE tenant-wide namespace (`shared.<key>`) rather than the
+// per-widget namespace, so identical strings translate ONCE and every widget
+// that calls `t("<sharedKey>")` resolves the same dictionary value. An author
+// still overrides any instance by setting `widget.<id>.<key>` in the
+// Translations admin — `useI18n` resolves the per-widget key FIRST, then the
+// shared key, then the raw key, so the override is per-instance.
+//
+// This is the analogue of `widget.<id>.` for cross-widget reuse: one prefix,
+// one definition (the hook reads + the backend seeder writes both call these),
+// so the wire key and the lookup key can never drift.
+const SHARED_TRANSLATION_PREFIX = "shared.";
+function sharedTranslationPrefix() {
+  return SHARED_TRANSLATION_PREFIX;
+}
+function sharedTranslationKey(key) {
+  return `${SHARED_TRANSLATION_PREFIX}${key}`;
+}
+
+// The predefined set. Map of bare key -> { en } (English default only; the
+// tenant adds target-language values once in the Translations admin and every
+// widget inherits them). Adding/removing a key is a CONTRACT change (it grows
+// the dictionary every tenant gets), so the list lives with the contract and
+// the seeder reads it from here — never a second copy.
+const SHARED_TRANSLATION_KEYS = Object.freeze({
+  submit: { en: "Submit" },
+  cancel: { en: "Cancel" },
+  save: { en: "Save" },
+  delete: { en: "Delete" },
+  edit: { en: "Edit" },
+  close: { en: "Close" },
+  confirm: { en: "Confirm" },
+  back: { en: "Back" },
+  next: { en: "Next" },
+  previous: { en: "Previous" },
+  yes: { en: "Yes" },
+  no: { en: "No" },
+  ok: { en: "OK" },
+  loading: { en: "Loading…" },
+  search: { en: "Search" },
+  no_results: { en: "No results" },
+  required: { en: "Required" },
+  retry: { en: "Retry" },
+  add: { en: "Add" },
+  remove: { en: "Remove" },
+});
+
+// True when `key` is one of the predefined shared keys — the discriminator
+// `useI18n` uses to decide whether to try the `shared.<key>` namespace. A key
+// the author invents is NOT shared (it stays per-widget) so authors can't
+// accidentally collide with another widget by reusing a bare name.
+function isSharedTranslationKey(key) {
+  return (
+    typeof key === "string" &&
+    Object.prototype.hasOwnProperty.call(SHARED_TRANSLATION_KEYS, key)
+  );
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -1459,7 +1532,36 @@ const CONTRACT = deepFreeze({
   //    `users.write:*`. New linter rule `scope-required-for-user-delete`
   //    flags a widget that calls `.remove()` without declaring the scope.
   //    No hook signature changed; `useUsers().remove` is unchanged.
-  version: "1.26.0",
+  //
+  // 1.27.0: additive — the vetted import allowlist gains `react/jsx-runtime`
+  //    and `react/jsx-dev-runtime`. These are subpaths of the already-vetted
+  //    `react`, injected automatically by the JSX transform when a bundle is
+  //    compiled with the automatic JSX runtime (Vite/esbuild's default). The
+  //    runtime already treats them as host-provided (the web loader shims both
+  //    in widgetLoader.js, the AI-agent sandbox stubs them, and the Developer
+  //    guide documents them as externalized), but the linter's vetted list did
+  //    not list them — so a first-party/marketplace bundle built with the
+  //    automatic runtime failed publish static analysis with `import-not-vetted`
+  //    on `react/jsx-runtime`. Adding them converges the linter onto the same
+  //    contract every other surface already honoured (CLAUDE.md §3). No
+  //    existing entry changed shape — minor bump on the pre-1.0 channel.
+  //
+  // 1.28.0: additive (REQ-L10N-SHARED) — predefined SHARED translation keys.
+  //    A new tenant-wide namespace `shared.<key>` carries the standard strings
+  //    the default widgets repeat ("Submit", "Cancel", "Loading…", …) so an
+  //    identical string is translated ONCE and every widget that calls
+  //    `t("<sharedKey>")` inherits it. New contract field
+  //    `sharedTranslationKeys` (the predefined map, the single source the
+  //    backend seeder reads) + new exported helpers `sharedTranslationPrefix()`
+  //    / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)`.
+  //    `useI18n().t(key)` now resolves the per-widget key first, THEN the
+  //    shared key (when `key` is one of the predefined shared keys), then the
+  //    raw key — so a default widget picks up the shared translation with no
+  //    manual key entry, and a `widget.<id>.<key>` override still wins per
+  //    instance. No existing hook, primitive, manifest field, or token changed
+  //    shape — minor bump on the pre-1.0 channel.
+  version: "1.28.0",
+  sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -1497,4 +1599,8 @@ module.exports = {
   requiredContextKeys,
   widgetTranslationPrefix,
   widgetTranslationKey,
+  sharedTranslationPrefix,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+  SHARED_TRANSLATION_KEYS,
 };

package/dist/contract.js

@@ -1057,6 +1057,20 @@ const VETTED_IMPORTS = [
     category: "core",
     description: "React. Hooks, JSX, lifecycle. Unchanged.",
   },
+  {
+    specifier: "react/jsx-runtime",
+    platforms: ["web", "native"],
+    category: "core",
+    description:
+      "React's automatic JSX runtime (jsx/jsxs/Fragment). Not hand-written — the JSX transform injects this import when a bundle is compiled with the automatic runtime. Host-provided on both platforms (the web loader shims it; Metro resolves the real subpath of react), so it is externalized exactly like react.",
+  },
+  {
+    specifier: "react/jsx-dev-runtime",
+    platforms: ["web", "native"],
+    category: "core",
+    description:
+      "React's automatic JSX dev runtime (jsxDEV/Fragment). The development-mode counterpart to react/jsx-runtime, injected by the JSX transform in dev builds. Host-provided on both platforms, externalized like react.",
+  },
   {
     specifier: "@colixsystems/widget-sdk",
     platforms: ["web", "native"],
@@ -1271,6 +1285,65 @@ function widgetTranslationKey(id, key) {
   return `widget.${id}.${key}`;
 }
 
+// REQ-L10N-SHARED — predefined SHARED translation keys for the standard
+// strings the default widgets repeat ("Submit", "Cancel", "Loading…", …).
+// They live in ONE tenant-wide namespace (`shared.<key>`) rather than the
+// per-widget namespace, so identical strings translate ONCE and every widget
+// that calls `t("<sharedKey>")` resolves the same dictionary value. An author
+// still overrides any instance by setting `widget.<id>.<key>` in the
+// Translations admin — `useI18n` resolves the per-widget key FIRST, then the
+// shared key, then the raw key, so the override is per-instance.
+//
+// This is the analogue of `widget.<id>.` for cross-widget reuse: one prefix,
+// one definition (the hook reads + the backend seeder writes both call these),
+// so the wire key and the lookup key can never drift.
+const SHARED_TRANSLATION_PREFIX = "shared.";
+function sharedTranslationPrefix() {
+  return SHARED_TRANSLATION_PREFIX;
+}
+function sharedTranslationKey(key) {
+  return `${SHARED_TRANSLATION_PREFIX}${key}`;
+}
+
+// The predefined set. Map of bare key -> { en } (English default only; the
+// tenant adds target-language values once in the Translations admin and every
+// widget inherits them). Adding/removing a key is a CONTRACT change (it grows
+// the dictionary every tenant gets), so the list lives with the contract and
+// the seeder reads it from here — never a second copy.
+const SHARED_TRANSLATION_KEYS = Object.freeze({
+  submit: { en: "Submit" },
+  cancel: { en: "Cancel" },
+  save: { en: "Save" },
+  delete: { en: "Delete" },
+  edit: { en: "Edit" },
+  close: { en: "Close" },
+  confirm: { en: "Confirm" },
+  back: { en: "Back" },
+  next: { en: "Next" },
+  previous: { en: "Previous" },
+  yes: { en: "Yes" },
+  no: { en: "No" },
+  ok: { en: "OK" },
+  loading: { en: "Loading…" },
+  search: { en: "Search" },
+  no_results: { en: "No results" },
+  required: { en: "Required" },
+  retry: { en: "Retry" },
+  add: { en: "Add" },
+  remove: { en: "Remove" },
+});
+
+// True when `key` is one of the predefined shared keys — the discriminator
+// `useI18n` uses to decide whether to try the `shared.<key>` namespace. A key
+// the author invents is NOT shared (it stays per-widget) so authors can't
+// accidentally collide with another widget by reusing a bare name.
+function isSharedTranslationKey(key) {
+  return (
+    typeof key === "string" &&
+    Object.prototype.hasOwnProperty.call(SHARED_TRANSLATION_KEYS, key)
+  );
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -1459,7 +1532,36 @@ const CONTRACT = deepFreeze({
   //    `users.write:*`. New linter rule `scope-required-for-user-delete`
   //    flags a widget that calls `.remove()` without declaring the scope.
   //    No hook signature changed; `useUsers().remove` is unchanged.
-  version: "1.26.0",
+  //
+  // 1.27.0: additive — the vetted import allowlist gains `react/jsx-runtime`
+  //    and `react/jsx-dev-runtime`. These are subpaths of the already-vetted
+  //    `react`, injected automatically by the JSX transform when a bundle is
+  //    compiled with the automatic JSX runtime (Vite/esbuild's default). The
+  //    runtime already treats them as host-provided (the web loader shims both
+  //    in widgetLoader.js, the AI-agent sandbox stubs them, and the Developer
+  //    guide documents them as externalized), but the linter's vetted list did
+  //    not list them — so a first-party/marketplace bundle built with the
+  //    automatic runtime failed publish static analysis with `import-not-vetted`
+  //    on `react/jsx-runtime`. Adding them converges the linter onto the same
+  //    contract every other surface already honoured (CLAUDE.md §3). No
+  //    existing entry changed shape — minor bump on the pre-1.0 channel.
+  //
+  // 1.28.0: additive (REQ-L10N-SHARED) — predefined SHARED translation keys.
+  //    A new tenant-wide namespace `shared.<key>` carries the standard strings
+  //    the default widgets repeat ("Submit", "Cancel", "Loading…", …) so an
+  //    identical string is translated ONCE and every widget that calls
+  //    `t("<sharedKey>")` inherits it. New contract field
+  //    `sharedTranslationKeys` (the predefined map, the single source the
+  //    backend seeder reads) + new exported helpers `sharedTranslationPrefix()`
+  //    / `sharedTranslationKey(key)` / `isSharedTranslationKey(key)`.
+  //    `useI18n().t(key)` now resolves the per-widget key first, THEN the
+  //    shared key (when `key` is one of the predefined shared keys), then the
+  //    raw key — so a default widget picks up the shared translation with no
+  //    manual key entry, and a `widget.<id>.<key>` override still wins per
+  //    instance. No existing hook, primitive, manifest field, or token changed
+  //    shape — minor bump on the pre-1.0 channel.
+  version: "1.28.0",
+  sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
@@ -1497,4 +1599,8 @@ export {
   requiredContextKeys,
   widgetTranslationPrefix,
   widgetTranslationKey,
+  sharedTranslationPrefix,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+  SHARED_TRANSLATION_KEYS,
 };

package/dist/hooks.js

@@ -26,10 +26,18 @@ import React, {
   useRef,
   useState,
 } from "react";
-// REQ-L10N-WIDGET: the per-widget translation key format lives in ONE place
-// (contract.js). useI18n (lookup) and the backend seeder (write) both call it
-// so the namespaced key can never drift between the two sides.
-import { widgetTranslationKey } from "./contract.js";
+// REQ-L10N-WIDGET / REQ-L10N-SHARED: the translation key formats live in ONE
+// place (contract.js). useI18n (lookup) and the backend seeder (write) both
+// call them so the namespaced keys can never drift between the two sides.
+// `widgetTranslationKey` builds the per-widget key (`widget.<id>.<key>`);
+// `sharedTranslationKey` builds the tenant-wide predefined key
+// (`shared.<key>`); `isSharedTranslationKey` tells the hook whether a bare key
+// is one of the predefined shared keys and so should try the shared namespace.
+import {
+  widgetTranslationKey,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+} from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
@@ -240,7 +248,27 @@ export function useI18n() {
             return scoped;
           }
         }
-        // 2) Fall back to the raw key (shared app keys + widgets with no
+        // 2) REQ-L10N-SHARED: for a predefined SHARED key, try the tenant-wide
+        //    `shared.<key>` namespace next. This is what lets identical
+        //    default-widget strings ("Submit", "Cancel", …) translate ONCE: a
+        //    widget that has no per-instance `widget.<id>.<key>` override
+        //    inherits the shared value. The per-widget step above runs FIRST,
+        //    so an author override of a single instance still wins for that
+        //    instance. Only the predefined keys are tried here — an
+        //    author-invented bare key is never silently shared.
+        if (isSharedTranslationKey(key)) {
+          const shared = sharedTranslationKey(key);
+          const scoped = hostT(shared);
+          if (
+            typeof scoped === "string" &&
+            scoped.length > 0 &&
+            scoped !== shared &&
+            !scoped.startsWith("{{t:")
+          ) {
+            return scoped;
+          }
+        }
+        // 3) Fall back to the raw key (shared app keys + widgets with no
         //    manifest translations — unchanged from pre-1.10 behaviour).
         const out = hostT(key, fallback);
         if (typeof out === "string" && out.length > 0 && out !== key) {

package/dist/linter.cjs

@@ -54,6 +54,149 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
   _ruleForIdentifier(b.identifier, b.reason),
 );
 
+// Replace the *content* of comments and string / template literals with
+// spaces so the banned-identifier scan only ever sees executable code. A
+// banned host-escape identifier (`window`, `document`, `eval`, `process`, …)
+// is only dangerous as a real identifier reference — never as prose in a
+// `//` comment or as character data inside a string — so matching the bare
+// word there is a false positive that blocks an otherwise-clean widget (a
+// comment that reads "the hour window the grid renders" must not trip
+// `no-window`).
+//
+// Newlines are preserved verbatim so reported line numbers still line up
+// with the original source. Template-literal `${ … }` expression holes are
+// left intact: real code lives there and must still be scanned (`${window}`
+// is a genuine escape). Backslash escapes inside strings/templates are
+// consumed so an escaped quote (`"\""`) doesn't end the literal early.
+function _stripNonCode(source) {
+  let out = "";
+  const n = source.length;
+  let mode = "code"; // code | line | block | sq | dq | tmpl
+  // Brace depth, plus a stack of the depths at which an enclosing template
+  // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
+  // strings, or nested templates) be told apart from the literal text.
+  let braceDepth = 0;
+  const tmplStack = [];
+  const keep = (ch) => {
+    out += ch;
+  };
+  const blank = (ch) => {
+    out += ch === "\n" || ch === "\r" ? ch : " ";
+  };
+  let i = 0;
+  while (i < n) {
+    const ch = source[i];
+    const nx = source[i + 1];
+    if (mode === "code") {
+      if (ch === "/" && nx === "/") {
+        mode = "line";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "/" && nx === "*") {
+        mode = "block";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "'") {
+        mode = "sq";
+        blank(ch);
+        i += 1;
+      } else if (ch === '"') {
+        mode = "dq";
+        blank(ch);
+        i += 1;
+      } else if (ch === "`") {
+        mode = "tmpl";
+        blank(ch);
+        i += 1;
+      } else if (ch === "{") {
+        braceDepth += 1;
+        keep(ch);
+        i += 1;
+      } else if (ch === "}") {
+        braceDepth -= 1;
+        if (
+          tmplStack.length > 0 &&
+          tmplStack[tmplStack.length - 1] === braceDepth
+        ) {
+          tmplStack.pop();
+          mode = "tmpl";
+          blank(ch);
+        } else {
+          keep(ch);
+        }
+        i += 1;
+      } else {
+        keep(ch);
+        i += 1;
+      }
+    } else if (mode === "line") {
+      if (ch === "\n") {
+        mode = "code";
+        keep(ch);
+      } else {
+        blank(ch);
+      }
+      i += 1;
+    } else if (mode === "block") {
+      if (ch === "*" && nx === "/") {
+        mode = "code";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    } else if (mode === "sq" || mode === "dq") {
+      const quote = mode === "sq" ? "'" : '"';
+      if (ch === "\\") {
+        blank(ch);
+        if (i + 1 < n) blank(nx);
+        i += 2;
+      } else if (ch === quote) {
+        mode = "code";
+        blank(ch);
+        i += 1;
+      } else if (ch === "\n") {
+        // A bare newline terminates an unterminated string in JS; bail back
+        // to code so malformed input can't blank the rest of the file.
+        mode = "code";
+        keep(ch);
+        i += 1;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    } else {
+      // mode === "tmpl"
+      if (ch === "\\") {
+        blank(ch);
+        if (i + 1 < n) blank(nx);
+        i += 2;
+      } else if (ch === "`") {
+        mode = "code";
+        blank(ch);
+        i += 1;
+      } else if (ch === "$" && nx === "{") {
+        // Enter an expression hole. Remember the brace depth the template
+        // resumes at, then count the `{` so its matching `}` is recognised.
+        tmplStack.push(braceDepth);
+        braceDepth += 1;
+        mode = "code";
+        keep(ch);
+        keep(nx);
+        i += 2;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    }
+  }
+  return out;
+}
+
 // REQ-WSDK-PLATFORM: `no-axios-import` is GONE. axios is on the vetted
 // import list now (`CONTRACT.vettedImports`). See linter.js for the
 // source-of-truth comment.
@@ -387,16 +530,22 @@ function lintSource(source, options) {
   }
   const findings = [];
   const lines = source.split(/\r?\n/);
+  // Scan code with comments + string/template text blanked out so a banned
+  // identifier only fires on an actual code reference, not on the same word
+  // appearing in prose or string data. `codeLines` lines up 1:1 with `lines`
+  // (masking preserves newlines), so the reported snippet still comes from
+  // the original source.
+  const codeLines = _stripNonCode(source).split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
+    const codeLine = codeLines[i];
     for (const rule of RULES) {
-      if (rule.pattern.test(line)) {
+      if (rule.pattern.test(codeLine)) {
         findings.push({
           rule: rule.id,
           severity: "error",
           label: rule.label,
           line: i + 1,
-          snippet: line.trim().slice(0, 200),
+          snippet: lines[i].trim().slice(0, 200),
         });
       }
     }

package/dist/linter.js

@@ -55,6 +55,149 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
   _ruleForIdentifier(b.identifier, b.reason),
 );
 
+// Replace the *content* of comments and string / template literals with
+// spaces so the banned-identifier scan only ever sees executable code. A
+// banned host-escape identifier (`window`, `document`, `eval`, `process`, …)
+// is only dangerous as a real identifier reference — never as prose in a
+// `//` comment or as character data inside a string — so matching the bare
+// word there is a false positive that blocks an otherwise-clean widget (a
+// comment that reads "the hour window the grid renders" must not trip
+// `no-window`).
+//
+// Newlines are preserved verbatim so reported line numbers still line up
+// with the original source. Template-literal `${ … }` expression holes are
+// left intact: real code lives there and must still be scanned (`${window}`
+// is a genuine escape). Backslash escapes inside strings/templates are
+// consumed so an escaped quote (`"\""`) doesn't end the literal early.
+function _stripNonCode(source) {
+  let out = "";
+  const n = source.length;
+  let mode = "code"; // code | line | block | sq | dq | tmpl
+  // Brace depth, plus a stack of the depths at which an enclosing template
+  // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
+  // strings, or nested templates) be told apart from the literal text.
+  let braceDepth = 0;
+  const tmplStack = [];
+  const keep = (ch) => {
+    out += ch;
+  };
+  const blank = (ch) => {
+    out += ch === "\n" || ch === "\r" ? ch : " ";
+  };
+  let i = 0;
+  while (i < n) {
+    const ch = source[i];
+    const nx = source[i + 1];
+    if (mode === "code") {
+      if (ch === "/" && nx === "/") {
+        mode = "line";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "/" && nx === "*") {
+        mode = "block";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "'") {
+        mode = "sq";
+        blank(ch);
+        i += 1;
+      } else if (ch === '"') {
+        mode = "dq";
+        blank(ch);
+        i += 1;
+      } else if (ch === "`") {
+        mode = "tmpl";
+        blank(ch);
+        i += 1;
+      } else if (ch === "{") {
+        braceDepth += 1;
+        keep(ch);
+        i += 1;
+      } else if (ch === "}") {
+        braceDepth -= 1;
+        if (
+          tmplStack.length > 0 &&
+          tmplStack[tmplStack.length - 1] === braceDepth
+        ) {
+          tmplStack.pop();
+          mode = "tmpl";
+          blank(ch);
+        } else {
+          keep(ch);
+        }
+        i += 1;
+      } else {
+        keep(ch);
+        i += 1;
+      }
+    } else if (mode === "line") {
+      if (ch === "\n") {
+        mode = "code";
+        keep(ch);
+      } else {
+        blank(ch);
+      }
+      i += 1;
+    } else if (mode === "block") {
+      if (ch === "*" && nx === "/") {
+        mode = "code";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    } else if (mode === "sq" || mode === "dq") {
+      const quote = mode === "sq" ? "'" : '"';
+      if (ch === "\\") {
+        blank(ch);
+        if (i + 1 < n) blank(nx);
+        i += 2;
+      } else if (ch === quote) {
+        mode = "code";
+        blank(ch);
+        i += 1;
+      } else if (ch === "\n") {
+        // A bare newline terminates an unterminated string in JS; bail back
+        // to code so malformed input can't blank the rest of the file.
+        mode = "code";
+        keep(ch);
+        i += 1;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    } else {
+      // mode === "tmpl"
+      if (ch === "\\") {
+        blank(ch);
+        if (i + 1 < n) blank(nx);
+        i += 2;
+      } else if (ch === "`") {
+        mode = "code";
+        blank(ch);
+        i += 1;
+      } else if (ch === "$" && nx === "{") {
+        // Enter an expression hole. Remember the brace depth the template
+        // resumes at, then count the `{` so its matching `}` is recognised.
+        tmplStack.push(braceDepth);
+        braceDepth += 1;
+        mode = "code";
+        keep(ch);
+        keep(nx);
+        i += 2;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    }
+  }
+  return out;
+}
+
 // Extra rules that don't map 1:1 to a banned identifier in the contract:
 // host-internal imports that widgets must never touch.
 //
@@ -124,9 +267,7 @@ function _classifySpecifier(spec) {
 
 function _importRules(source, manifest) {
   const findings = [];
-  const allowed = new Map(
-    CONTRACT.vettedImports.map((v) => [v.specifier, v]),
-  );
+  const allowed = new Map(CONTRACT.vettedImports.map((v) => [v.specifier, v]));
   // Track declared `supportedPlatforms` so a widget that claims "web only"
   // doesn't import a native-only package (and vice versa) without the
   // marketplace listing being honest about which platforms ship.
@@ -258,7 +399,12 @@ const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate"];
 // useUsers().remove() must declare `users.delete:*` so the static contract
 // matches the backend gate on DELETE /api/v1/app/users/:userId.
 const USER_DELETE_METHODS = ["remove"];
-const GROUP_MUTATION_METHODS = ["create", "remove", "addMember", "removeMember"];
+const GROUP_MUTATION_METHODS = [
+  "create",
+  "remove",
+  "addMember",
+  "removeMember",
+];
 const SKIP_COMMENT = /\/\/[^\n]*@appstudio-skip-scope-check/;
 
 function _scopeRules(source, manifest) {
@@ -277,8 +423,7 @@ function _scopeRules(source, manifest) {
     if (!reads) {
       findings.push({
         rule: "scope-required-for-useUsers",
-        label:
-          "useUsers() requires `users.read:*` in manifest.requestedScopes",
+        label: "useUsers() requires `users.read:*` in manifest.requestedScopes",
         line: 0,
         snippet: "",
       });
@@ -308,10 +453,7 @@ function _scopeRules(source, manifest) {
       for (const m of USER_MUTATION_METHODS) {
         const re = new RegExp(`\\.${m}\\s*\\(`);
         if (re.test(line)) {
-          if (
-            !declared.has("users.write:*") &&
-            !declared.has("users.write")
-          ) {
+          if (!declared.has("users.write:*") && !declared.has("users.write")) {
             findings.push({
               rule: "scope-required-for-user-mutation",
               label: `useUsers().${m}() requires \`users.write:*\` in manifest.requestedScopes`,
@@ -400,7 +542,13 @@ function _manifestActionRules(manifest) {
   const validTriggers = new Set(CONTRACT.actionTriggerTypes);
   const maxBytes = CONTRACT.actionScriptMaxBytes;
   const push = (label) =>
-    findings.push({ rule: "manifest-action", severity: "error", label, line: 0, snippet: "" });
+    findings.push({
+      rule: "manifest-action",
+      severity: "error",
+      label,
+      line: 0,
+      snippet: "",
+    });
   if (!Array.isArray(manifest.actions)) {
     push("manifest.actions must be an array (omit it or use [] for none)");
     return findings;
@@ -422,9 +570,16 @@ function _manifestActionRules(manifest) {
       push("manifest.actions[].name must be a non-empty string");
     }
     if (!validTriggers.has(a.triggerType)) {
-      push(`manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`);
-    } else if (a.triggerType === "schedule" && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
-      push("manifest.actions[].scheduleCron is required when triggerType is 'schedule'");
+      push(
+        `manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`,
+      );
+    } else if (
+      a.triggerType === "schedule" &&
+      (typeof a.scheduleCron !== "string" || !a.scheduleCron)
+    ) {
+      push(
+        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+      );
     }
     if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
       push("manifest.actions[].scriptSource must be a non-empty string");
@@ -438,7 +593,9 @@ function _manifestActionRules(manifest) {
       }
     }
     if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
-      push("manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install");
+      push(
+        "manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install",
+      );
     }
   }
   return findings;
@@ -461,16 +618,22 @@ export function lintSource(source, options) {
   }
   const findings = [];
   const lines = source.split(/\r?\n/);
+  // Scan code with comments + string/template text blanked out so a banned
+  // identifier only fires on an actual code reference, not on the same word
+  // appearing in prose or string data. `codeLines` lines up 1:1 with `lines`
+  // (masking preserves newlines), so the reported snippet still comes from
+  // the original source.
+  const codeLines = _stripNonCode(source).split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
+    const codeLine = codeLines[i];
     for (const rule of RULES) {
-      if (rule.pattern.test(line)) {
+      if (rule.pattern.test(codeLine)) {
         findings.push({
           rule: rule.id,
           severity: "error",
           label: rule.label,
           line: i + 1,
-          snippet: line.trim().slice(0, 200),
+          snippet: lines[i].trim().slice(0, 200),
         });
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js"
   },
   "engines": {
     "node": ">=18"