@colixsystems/widget-sdk 0.36.0 → 0.37.0

package/README.md

@@ -47,7 +47,11 @@ 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.37.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.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"],
@@ -1459,7 +1473,20 @@ 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.
+  version: "1.27.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

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"],
@@ -1459,7 +1473,20 @@ 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.
+  version: "1.27.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

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.37.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"