@colixsystems/widget-sdk 0.44.0 → 0.45.0

package/README.md

@@ -49,10 +49,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.44.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.45.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.45.0
+
+**New linter rule `lucide-unknown-icon` (sc-1366).** `lucide-react-native` is a vetted import the bundler **externalises**, so esbuild never checks the *named* imports — a widget that imports an icon name absent from the pinned `lucide-react-native@0.368.0` (e.g. `import { House } from "lucide-react-native"`, when that version only ships `Home` — `House` was added to lucide later) bundles and publishes cleanly, then fails only at **runtime load** ("does not provide an export named 'House'") and renders blank. The linter now rejects such imports at publish so the failure becomes a repair-loop finding instead of a broken shipped widget. The valid set is committed data (`src/lucideIconNames.{cjs,js}` — the 1451 base export names + the generated-from `LUCIDE_VERSION`) because the linter runs in zero-dependency contexts where `lucide-react-native` (and its `react-native` peer) is not installed; alias forms (`<Name>Icon`, `Lucide<Name>`) are normalised. Regenerate after a lucide bump with `node scripts/generate-lucide-icon-names.cjs`; a test asserts `LUCIDE_VERSION` matches the frontend pin so the set can't go stale. The `CONTRACT` object is unchanged (no new field), so `CONTRACT.version` stays at `1.32.0`. The author/agent-facing mirror of this rule is the "Icons" note in the AI agent's `DEFAULT_SYSTEM_PROMPT` (shipped in the companion sc-1273/sc-1362 prompt PR).
 
 ### What's new in 0.44.0
 
+**AI-generated widgets are bundled at publish (sc-1265).** Until this release the AI agent's publish path served the validated LLM source **verbatim** (transpiled, not bundled), which meant an AI widget could only import the host-shimmed specifiers — a draft that imported, say, `react-native-gesture-handler` published cleanly but threw "unresolvable bare imports" at load. Marketplace widgets, in contrast, are esbuild-**bundled** by the publish packer and get the full vetted-import surface. This release closes that gap: every AI publish now ships through the **`@appstudio/widget-bundler`** sidecar (`services/widget-bundler` — internal HTTP service that wraps the SAME `bundleWebEntry` the marketplace packer uses), so the bundled output is byte-shape identical regardless of who published.
+
+- **`react-native` is now host-resolved on web.** A bundled widget — AI or marketplace — that imports `react-native` (directly, or via a vetted RN package like `react-native-gesture-handler` that imports it internally) leaves the specifier as a bare import; the Studio loader shims it to the host's **single** `react-native-web` instance. That keeps the bundle small (gesture-handler probes dropped from 762 KB to ~248 KB) and avoids two RN-web copies in the same page (`StyleSheet` + context conflicts).
+- **`hostExternalSpecifiers()` grew `react-native`.** The canonical "host-resolved at runtime" set the bundler externalises now lists react family + `react-dom` + `react-dom/client` + `@colixsystems/widget-sdk` + the vetted shimmed packages (lucide / svg / date-fns) + `react-native`.
+- **`bundleWebEntry` resolves RN web builds.** `resolveExtensions` is `.web.js`-first, `mainFields` is `[browser, module, main]`, and the `browser` export condition is active — so esbuild picks the web build of an RN-shape package automatically. No alias step; `react-native` stays external.
+- **Contract description fix.** The vetted-imports entry for `react-native` previously claimed "the host bundler aliases this to react-native-web" — that was never true and the misclaim leaked into the AI system prompt. The description now reads: "`react-native` is host-resolved to the host's single react-native-web instance (external, shimmed) — NOT aliased at bundle time".
+- **AI publish storage shape.** Every AI publish now writes the `bundleFiles` JSONB column with the bundled web entry under `widget.web.jsx` and the transpiled RN source under `widget.native.jsx`. `bundleSource` (the legacy single-file column) stays NULL on AI rows; `resolveWebBundleSource` / `resolveNativeBundleSource` pick the right file at load time.
+- **Bundle failure → repair loop.** A bundler error is now a `bundle.web` finding the existing publish repair loop folds into the next attempt's prompt, so the model can self-correct a draft whose imports the bundler refused.
+- **`CONTRACT.version` → `1.32.0`** (additive: the `react-native` host-resolution behaviour + a corrected vetted-imports description; the SET of vetted imports is unchanged).
+
 **Vetted `@shopify/react-native-skia` for canvas-style graphics & games (sc-1270).** Widgets that need true 2D/GPU canvas drawing (games, custom visualisations) can now `import` Skia. It is **native-only** (`platforms: ["native"]`, like `react-native-maps` / `lottie-react-native`): author it in `widget.native.jsx` and pair it with a web variant in `widget.web.jsx` — a browser `<canvas>` or `react-native-svg`. This closes the gap where a raw `<canvas>` rendered in the web Player but crashed the Expo export ("View config getter callback for component `canvas` … received undefined") because React Native has no `<canvas>`. The compiler pins `@shopify/react-native-skia` in the exported app's `package.json`; no host shim is added (native-only packages are never shimmed, and there is no Skia web build wired into the Player). Unified Skia-on-web (CanvasKit/WASM) is a documented follow-up. Additive — `CONTRACT.version` bumped to 1.31.0.
 
 ### What's new in 0.43.0
@@ -488,6 +502,46 @@ The manifest declares the matching scope:
 
 The server-side gate is `canGrant` on the target record — Studio owners pass automatically; an APP_USER holds `canGrant` as the record's creator or via a delegated grant. A caller without `canGrant` receives `PermissionError { code: "FORBIDDEN" }`. The hook collapses to a stable no-op when `tableId` or `recordId` is null/empty — so a widget can render its picker first, then bind to the picked record without conditional hook tricks.
 
+## Cross-platform widgets (single-file vs split)
+
+Every widget runs in **both** the web Player and the exported native (Expo) app.
+There are two ways to author one, and the **file set you ship decides
+`supportedPlatforms`** — you don't hand-declare it, the platform derives it.
+
+**1. Single file — `widget.jsx` (the default).** Works on web AND native. Pick
+this when the widget needs only the SDK primitives + hooks, or only packages
+that support both platforms (every `["web", "native"]` entry in
+`CONTRACT.vettedImports` — `react-native`, `react-native-svg`, `date-fns`,
+`react-native-paper`, `@shopify/flash-list`, `react-native-reanimated`,
+`react-native-gesture-handler`, `expo-linear-gradient`, …). Most widgets land
+here. Derives `supportedPlatforms: ["web", "native"]`.
+
+**2. Split implementation — `widget.web.jsx` + `widget.native.jsx`.** Pick this
+when the widget needs a package that only runs on ONE platform. Each file
+targets its platform and imports the package that works there; shared logic
+lives in a sibling `./helper.js` both files import. This is the **canonical
+pattern** for graphics, media, and any platform-divergent library:
+
+| Capability | `widget.native.jsx` | `widget.web.jsx` |
+| ---------- | ------------------- | ---------------- |
+| Maps | `react-native-maps` | `react-leaflet` / `leaflet` |
+| Canvas / 2D-GPU drawing | `@shopify/react-native-skia` | `<canvas>` or `react-native-svg` |
+| Video | `expo-video` | the browser `<video>` element |
+| Audio | `expo-audio` | the browser `<audio>` element |
+| Lottie animation | `lottie-react-native` | `lottie-react` |
+| Embedded web content | `react-native-webview` | an `<iframe>` |
+
+A few native-only packages (`@react-native-community/datetimepicker`,
+`expo-clipboard`) are already wrapped by an SDK primitive/hook
+(`<DateTimePicker>`, `useClipboard()`) that resolves the right implementation on
+each platform — reach for those first and you stay single-file.
+
+**The linter enforces honesty at publish.** A single-file widget that imports a
+native-only package while claiming web (or vice-versa) fails the
+`import-platform-mismatch` rule — move the import into the file that targets its
+platform, or ship the split pair. So you can't accidentally publish a widget
+that renders on one platform and blanks on the other.
+
 ## Linter
 
 ```sh

package/dist/contract.cjs

@@ -1140,7 +1140,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "primitive",
     description:
-      "Direct RN imports for APIs the SDK hasn't re-exported yet. On web the host bundler aliases this to react-native-web; on native Metro resolves the real library.",
+      "Direct RN imports for APIs the SDK hasn't re-exported yet. On web `react-native` is host-resolved to the host's single react-native-web instance (external, shimmed) — NOT aliased at bundle time — so a bundled widget shares the host's RN-web (one StyleSheet/context, no double-instance conflicts). On native Metro resolves the real library.",
   },
   {
     specifier: "axios",
@@ -1672,7 +1672,16 @@ const CONTRACT = deepFreeze({
   //    variant in widget.web.jsx. Pinned in the compiler's export
   //    package.json; no host shim (native-only is never shimmed). No hook,
   //    primitive, manifest field, or token changed shape — minor bump.
-  version: "1.31.0",
+  //
+  // 1.32.0: behaviour (sc-1265) — `react-native` is now host-resolved on web
+  //    as an EXTERNAL, loader-shimmed to the host's single react-native-web
+  //    instance, instead of being aliased at bundle time. AI publishes now
+  //    bundle through the widget-bundler sidecar (byte-shape identical to the
+  //    marketplace packer), so a bundled widget shares the host's one RN-web
+  //    instance — one StyleSheet/context, no double-instance conflicts. The
+  //    vetted-import SET is unchanged (react-native was already vetted); only
+  //    its web resolution + description changed — minor bump.
+  version: "1.32.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1140,7 +1140,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "primitive",
     description:
-      "Direct RN imports for APIs the SDK hasn't re-exported yet. On web the host bundler aliases this to react-native-web; on native Metro resolves the real library.",
+      "Direct RN imports for APIs the SDK hasn't re-exported yet. On web `react-native` is host-resolved to the host's single react-native-web instance (external, shimmed) — NOT aliased at bundle time — so a bundled widget shares the host's RN-web (one StyleSheet/context, no double-instance conflicts). On native Metro resolves the real library.",
   },
   {
     specifier: "axios",
@@ -1672,7 +1672,16 @@ const CONTRACT = deepFreeze({
   //    variant in widget.web.jsx. Pinned in the compiler's export
   //    package.json; no host shim (native-only is never shimmed). No hook,
   //    primitive, manifest field, or token changed shape — minor bump.
-  version: "1.31.0",
+  //
+  // 1.32.0: behaviour (sc-1265) — `react-native` is now host-resolved on web
+  //    as an EXTERNAL, loader-shimmed to the host's single react-native-web
+  //    instance, instead of being aliased at bundle time. AI publishes now
+  //    bundle through the widget-bundler sidecar (byte-shape identical to the
+  //    marketplace packer), so a bundled widget shares the host's one RN-web
+  //    instance — one StyleSheet/context, no double-instance conflicts. The
+  //    vetted-import SET is unchanged (react-native was already vetted); only
+  //    its web resolution + description changed — minor bump.
+  version: "1.32.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/dev-shims.js

@@ -107,6 +107,12 @@ const HOST_EXTERNAL_SPECIFIERS = [
   "lucide-react-native",
   "react-native-svg",
   "date-fns",
+  // sc-1265: a bundled widget (and any vetted RN package it inlines, e.g.
+  // react-native-gesture-handler) imports `react-native`; the host resolves it
+  // to its OWN single react-native-web instance through a blob shim, so the
+  // bundle shares one RN-web (StyleSheet/context) instead of inlining a second
+  // copy. On native, Metro resolves the real react-native in the export.
+  "react-native",
 ];
 
 /**

package/dist/linter.cjs

@@ -11,6 +11,7 @@
 "use strict";
 
 const { CONTRACT } = require("./contract.cjs");
+const { LUCIDE_ICON_NAMES, LUCIDE_VERSION } = require("./lucideIconNames.cjs");
 
 function _ruleForIdentifier(identifier, reason) {
   const id = identifier;
@@ -513,6 +514,63 @@ function _manifestActionRules(manifest) {
   return findings;
 }
 
+// sc-1366 — invalid lucide icon import gate. lucide-react-native is a vetted
+// import that the bundler EXTERNALISES, so esbuild never checks the named
+// imports; a name that does not exist in the pinned version (`House` was added
+// to lucide AFTER the pinned 0.368.0, which only has `Home`) bundles + publishes
+// cleanly and fails only at runtime load ("does not provide an export named
+// 'House'"), leaving the widget blank. This rule rejects such imports at publish
+// so the agent's repair loop fixes them. The valid set is committed data
+// (lucideIconNames.cjs) because the linter runs where lucide is not installed.
+const LUCIDE_NAME_SET = new Set(LUCIDE_ICON_NAMES);
+const LUCIDE_IMPORT_RE =
+  /import\s+(?:[A-Za-z0-9_$]+\s*,\s*)?\{([\s\S]*?)\}\s*from\s*["']lucide-react-native["']/g;
+
+// lucide re-exports each base icon as `<Name>`, `<Name>Icon`, and `Lucide<Name>`;
+// the committed set holds only the base names, so normalise the alias forms
+// before the membership check. No base name ends in "Icon" or starts with
+// "Lucide" (asserted by lucide-icon-names.test.js), so stripping is unambiguous.
+function _isValidLucideName(name) {
+  if (LUCIDE_NAME_SET.has(name)) return true;
+  if (name.endsWith("Icon") && LUCIDE_NAME_SET.has(name.slice(0, -4))) return true;
+  if (name.startsWith("Lucide") && LUCIDE_NAME_SET.has(name.slice(6))) return true;
+  return false;
+}
+
+function _lucideIconRules(source) {
+  const findings = [];
+  const sourceLines = source.split(/\r?\n/);
+  LUCIDE_IMPORT_RE.lastIndex = 0;
+  let m;
+  while ((m = LUCIDE_IMPORT_RE.exec(source))) {
+    const line = source.slice(0, m.index).split(/\r?\n/).length;
+    for (const raw of (m[1] || "").split(",")) {
+      // Strip any inline comment from the specifier token so a `{ Home, // x`
+      // comment can't glue onto and hide the next specifier (e.g. `House`).
+      const cleaned = raw
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/\/\/[^\n]*/g, "");
+      const imported = cleaned.trim().split(/\s+as\s+/)[0].trim();
+      if (!imported || imported === "type") continue;
+      if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(imported)) continue;
+      if (_isValidLucideName(imported)) continue;
+      findings.push({
+        rule: "lucide-unknown-icon",
+        severity: "error",
+        label:
+          `lucide-react-native has no export "${imported}" in the pinned ` +
+          `lucide-react-native@${LUCIDE_VERSION}. The widget bundles cleanly but FAILS at ` +
+          `runtime load ("does not provide an export named '${imported}'") and never ` +
+          `renders — replace it with an icon name that exists in that version (lucide ` +
+          `adds and renames icons across releases, so a newer name may not exist here).`,
+        line,
+        snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+      });
+    }
+  }
+  return findings;
+}
+
 function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -557,6 +615,7 @@ function lintSource(source, options) {
     })),
   );
   findings.push(..._hostApiUrlRules(source));
+  findings.push(..._lucideIconRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -7,6 +7,7 @@
 // system prompt, the linter, and the runtime allowlist agree.
 
 import { CONTRACT } from "./contract.js";
+import { LUCIDE_ICON_NAMES, LUCIDE_VERSION } from "./lucideIconNames.js";
 
 // Per-identifier match rule. Most banned identifiers compile to a
 // whole-word match; a few have special syntax (`Function(`, `new Function`,
@@ -601,6 +602,63 @@ function _manifestActionRules(manifest) {
   return findings;
 }
 
+// sc-1366 — invalid lucide icon import gate. lucide-react-native is a vetted
+// import that the bundler EXTERNALISES, so esbuild never checks the named
+// imports; a name that does not exist in the pinned version (`House` was added
+// to lucide AFTER the pinned 0.368.0, which only has `Home`) bundles + publishes
+// cleanly and fails only at runtime load ("does not provide an export named
+// 'House'"), leaving the widget blank. This rule rejects such imports at publish
+// so the agent's repair loop fixes them. The valid set is committed data
+// (lucideIconNames.js) because the linter runs where lucide is not installed.
+const LUCIDE_NAME_SET = new Set(LUCIDE_ICON_NAMES);
+const LUCIDE_IMPORT_RE =
+  /import\s+(?:[A-Za-z0-9_$]+\s*,\s*)?\{([\s\S]*?)\}\s*from\s*["']lucide-react-native["']/g;
+
+// lucide re-exports each base icon as `<Name>`, `<Name>Icon`, and `Lucide<Name>`;
+// the committed set holds only the base names, so normalise the alias forms
+// before the membership check. No base name ends in "Icon" or starts with
+// "Lucide" (asserted by lucide-icon-names.test.js), so stripping is unambiguous.
+function _isValidLucideName(name) {
+  if (LUCIDE_NAME_SET.has(name)) return true;
+  if (name.endsWith("Icon") && LUCIDE_NAME_SET.has(name.slice(0, -4))) return true;
+  if (name.startsWith("Lucide") && LUCIDE_NAME_SET.has(name.slice(6))) return true;
+  return false;
+}
+
+function _lucideIconRules(source) {
+  const findings = [];
+  const sourceLines = source.split(/\r?\n/);
+  LUCIDE_IMPORT_RE.lastIndex = 0;
+  let m;
+  while ((m = LUCIDE_IMPORT_RE.exec(source))) {
+    const line = source.slice(0, m.index).split(/\r?\n/).length;
+    for (const raw of (m[1] || "").split(",")) {
+      // Strip any inline comment from the specifier token so a `{ Home, // x`
+      // comment can't glue onto and hide the next specifier (e.g. `House`).
+      const cleaned = raw
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/\/\/[^\n]*/g, "");
+      const imported = cleaned.trim().split(/\s+as\s+/)[0].trim();
+      if (!imported || imported === "type") continue;
+      if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(imported)) continue;
+      if (_isValidLucideName(imported)) continue;
+      findings.push({
+        rule: "lucide-unknown-icon",
+        severity: "error",
+        label:
+          `lucide-react-native has no export "${imported}" in the pinned ` +
+          `lucide-react-native@${LUCIDE_VERSION}. The widget bundles cleanly but FAILS at ` +
+          `runtime load ("does not provide an export named '${imported}'") and never ` +
+          `renders — replace it with an icon name that exists in that version (lucide ` +
+          `adds and renames icons across releases, so a newer name may not exist here).`,
+        line,
+        snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+      });
+    }
+  }
+  return findings;
+}
+
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -647,6 +705,7 @@ export function lintSource(source, options) {
   );
   // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
+  findings.push(..._lucideIconRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.