@colixsystems/widget-sdk 0.44.0 → 0.45.0

package/dist/webbundle.js

@@ -108,7 +108,30 @@ export async function bundleWebEntry({
     jsx: "automatic",
     // Leave the host-resolved set as bare `import`s; the Studio loader rewrites
     // them to blob shims at runtime (and Metro resolves them in the export).
+    // `react-native` is in that set (hostExternalSpecifiers): a vetted RN
+    // package (react-native-gesture-handler, react-native-reanimated, …) is
+    // INLINED, but its internal `import "react-native"` is left bare and
+    // resolves to the host's single react-native-web instance — the same
+    // shared-instance model as react/react-dom, far smaller than inlining a
+    // second copy of react-native-web into every bundle.
     external,
+    // sc-1265: resolve the WEB build of cross-platform packages. RN packages
+    // ship `.web.js` platform variants and lean on the `browser` field /
+    // export condition; without these esbuild would pull their native entry and
+    // bundle React Native internals that break in the browser.
+    resolveExtensions: [
+      ".web.js",
+      ".web.jsx",
+      ".web.ts",
+      ".web.tsx",
+      ".js",
+      ".jsx",
+      ".ts",
+      ".tsx",
+      ".json",
+    ],
+    mainFields: ["browser", "module", "main"],
+    conditions: ["browser"],
     loader: { ".png": "dataurl", ".jpg": "dataurl", ".gif": "dataurl" },
     plugins: [cssInjectPlugin()],
     // esbuild walks up from the entry for node_modules by default; `nodePaths`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,8 @@
       "require": "./dist/contract.cjs",
       "import": "./dist/contract.js",
       "default": "./dist/contract.cjs"
-    }
+    },
+    "./src/webbundle.js": "./src/webbundle.js"
   },
   "bin": {
     "appstudio-widget": "./dist/cli.js"
@@ -35,11 +36,13 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src/webbundle.js",
+    "src/dev-shims.js"
   ],
   "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-assets-by-tag.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 src/__tests__/host-externals.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-assets-by-tag.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__/lucide-icon-names.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js"
   },
   "engines": {
     "node": ">=18"

package/src/dev-shims.js

@@ -0,0 +1,261 @@
+// REQ-WSDK-DEVKIT v2 (sc-1027): shared shim-source generator used by BOTH
+// `widgetLoader.buildShims()` (Studio runtime, blob URLs) AND the dev server's
+// `/shim/<spec>` endpoint (when serving siblings of a multi-file widget).
+//
+// Both code paths produce ESM that re-exports the matching key out of
+// `globalThis.__appstudioWidgetHost__` — populated by the Studio's `buildShims`
+// before any widget bundle is evaluated. Keeping the shim sources in one place
+// means a vetted-package addition lands once and both paths see it.
+//
+// Pure JS, no runtime deps — safe to import from the SDK dev server (Node)
+// and from the Studio loader (browser).
+//
+// LIMITATION (v1): for SIBLING files served by the dev server's `/file/<rel>`
+// endpoint, only the specifiers with a statically-known named-export list are
+// shimmable through `/shim/<spec>`: `react`, `react/jsx-runtime`,
+// `react/jsx-dev-runtime`, and `@colixsystems/widget-sdk`. Any other vetted
+// package (`lucide-react-native`, `react-native-svg`, `date-fns`, ...) must be
+// imported from the widget's ENTRY (where the Studio's blob-shim path
+// runtime-enumerates the host's namespace). Imports of these packages from a
+// sibling .jsx file return `422` from the dev server with a clear message.
+
+// React named exports the Studio re-exposes through the shim. Mirrors the
+// browser's `react` named-export surface. Adding a new hook in a React minor
+// release means appending it here.
+export const REACT_NAMED_EXPORTS = [
+  "Children",
+  "Component",
+  "Fragment",
+  "Profiler",
+  "PureComponent",
+  "StrictMode",
+  "Suspense",
+  "cloneElement",
+  "createContext",
+  "createElement",
+  "createFactory",
+  "createRef",
+  "forwardRef",
+  "isValidElement",
+  "lazy",
+  "memo",
+  "startTransition",
+  "useCallback",
+  "useContext",
+  "useDebugValue",
+  "useDeferredValue",
+  "useEffect",
+  "useId",
+  "useImperativeHandle",
+  "useInsertionEffect",
+  "useLayoutEffect",
+  "useMemo",
+  "useReducer",
+  "useRef",
+  "useState",
+  "useSyncExternalStore",
+  "useTransition",
+  "version",
+];
+
+// React's automatic JSX runtime: jsx / jsxs / Fragment, plus the dev variant.
+export const REACT_JSX_RUNTIME_EXPORTS = ["jsx", "jsxs", "Fragment", "jsxDEV"];
+
+// REQ-WSDK-PLATFORM bundle (sc-1064): the canonical list of bare specifiers the
+// runtime web host RESOLVES for a loaded widget — i.e. the ones the Studio's
+// `widgetLoader.buildShims()` re-exports from `globalThis.__appstudioWidgetHost__`
+// rather than letting a bundle inline a second copy. The web-entry bundler
+// (`webbundle.bundleWebEntry`, used by both the publish packer and the dev
+// server) marks EXACTLY these `external`, so everything else the entry imports
+// (`react-leaflet`, `leaflet`, CSS, PNG assets, …) gets inlined.
+//
+// This is the SINGLE source of truth (CLAUDE.md §3). It MUST stay in lockstep
+// with the frontend's `widgetLoader._hostVettedModules()` + the core React/SDK
+// shims it builds. Two backstops enforce the equality: (1) this list's
+// contents are pinned by the SDK-side importable test
+// (`packages/widget-sdk/src/__tests__/host-externals.test.js`), and (2) the
+// loader's own module-load guard in `frontend/src/services/widgetLoader.js`
+// throws at import time if `hostShimmedSpecifiers()` drifts from
+// `hostExternalSpecifiers()` — the loader's shimmed set can't be asserted from
+// a Node test (it imports `react-dom` etc.), so that equality is enforced by
+// the load-time guard rather than a separate frontend test.
+//
+// Why each entry is host-resolved (NOT bundled):
+//   * `react`, `react/jsx-runtime`, `react/jsx-dev-runtime` — the widget MUST
+//     share the host's ONE React instance (hooks + context); a bundled second
+//     React breaks both.
+//   * `react-dom`, `react-dom/client` — `react-leaflet`'s Popup/Pane render
+//     through `createPortal` from `react-dom`. A bundled second react-dom
+//     paired with the host's external React is a mismatched renderer and
+//     crashes. The Studio is a React-DOM app, so it shims its own react-dom.
+//     On React 19 the two specifiers expose DIFFERENT surfaces — createPortal /
+//     flushSync / version live on `react-dom`, createRoot / hydrateRoot on
+//     `react-dom/client` — so the loader stashes + shims each from its own real
+//     host namespace (sc-1064).
+//   * `@colixsystems/widget-sdk` — the widget must route hooks through the SAME
+//     SDK instance the host built (datastore/theme/navigation live there).
+//   * `lucide-react-native`, `react-native-svg`, `date-fns` — vetted packages
+//     the host already bundles + shims (`_hostVettedModules`); sharing the
+//     host copy keeps icons/SVG on the host's react-native-web instance.
+const HOST_EXTERNAL_SPECIFIERS = [
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "react-dom",
+  "react-dom/client",
+  "@colixsystems/widget-sdk",
+  "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",
+];
+
+/**
+ * The canonical "host-resolved at runtime" bare-specifier set — the externals
+ * the web-entry bundler must NOT inline. Returns a fresh array each call so a
+ * caller can't mutate the source of truth.
+ *
+ * @returns {string[]}
+ */
+export function hostExternalSpecifiers() {
+  return [...HOST_EXTERNAL_SPECIFIERS];
+}
+
+function reactShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.React";
+  const named = REACT_NAMED_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+function reactJsxRuntimeShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.ReactJSXRuntime";
+  const named = REACT_JSX_RUNTIME_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return named;
+}
+
+// react-dom named exports a bundled widget might reach through the host shim.
+// `react-leaflet`'s Popup/Pane/SVGOverlay use `createPortal`; `flushSync`
+// rounds out the surface react-leaflet may touch. These are the names that
+// genuinely EXIST on the `react-dom` namespace in React 19 — `createRoot` /
+// `hydrateRoot` moved to `react-dom/client`, and `render` /
+// `unmountComponentAtNode` / `findDOMNode` were removed entirely, so listing
+// them here would re-export `undefined` (sc-1064). `version` is always present.
+// Mirrors REACT_NAMED_EXPORTS' hand-list-of-the-named-surface approach (a blob
+// module can't `export *`).
+export const REACT_DOM_NAMED_EXPORTS = ["createPortal", "flushSync", "version"];
+
+// React 19: `createRoot` / `hydrateRoot` live ONLY on `react-dom/client`. The
+// `react-dom/client` shim sources these from the host's REAL `react-dom/client`
+// namespace (stashed as `ReactDOMClient`), NOT from the `react-dom` namespace
+// where they are `undefined` on v19. `version` is present on both.
+export const REACT_DOM_CLIENT_NAMED_EXPORTS = [
+  "createRoot",
+  "hydrateRoot",
+  "version",
+];
+
+function reactDomShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.ReactDOM";
+  const named = REACT_DOM_NAMED_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+function reactDomClientShimSrc() {
+  const host = "globalThis.__appstudioWidgetHost__.ReactDOMClient";
+  const named = REACT_DOM_CLIENT_NAMED_EXPORTS.map(
+    (n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`,
+  ).join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+function sdkShimSrc(sdkNamedExports) {
+  const host = "globalThis.__appstudioWidgetHost__.sdk";
+  const names = (Array.isArray(sdkNamedExports) ? sdkNamedExports : []).filter(
+    (n) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(n),
+  );
+  const named = names
+    .map((n) => `export const ${n} = (${host})[${JSON.stringify(n)}];`)
+    .join("\n");
+  return `const __host = ${host};\nexport default __host;\n${named}\n`;
+}
+
+/**
+ * Build a shim ESM source for a vetted bare specifier with a statically-known
+ * named-export shape. Returns null when the specifier isn't shimmable from a
+ * sibling file — the caller surfaces this as a clear error.
+ *
+ * @param {string} specifier  bare import specifier (e.g. "react")
+ * @param {object} [opts]
+ * @param {string[]} [opts.sdkExports]  named-export list for
+ *   "@colixsystems/widget-sdk" — caller passes this since the dev server
+ *   doesn't statically load the SDK.
+ * @returns {string | null}
+ */
+export function getShimSource(specifier, opts = {}) {
+  switch (specifier) {
+    case "react":
+      return reactShimSrc();
+    case "react/jsx-runtime":
+    case "react/jsx-dev-runtime":
+      return reactJsxRuntimeShimSrc();
+    case "react-dom":
+      return reactDomShimSrc();
+    case "react-dom/client":
+      return reactDomClientShimSrc();
+    case "@colixsystems/widget-sdk":
+      return sdkShimSrc(opts.sdkExports);
+    default:
+      return null;
+  }
+}
+
+/**
+ * The set of bare specifiers a SIBLING file may import — i.e. the keys
+ * `getShimSource` recognises. Anything outside this set must move to the
+ * entry, where the Studio's runtime blob-shim path enumerates the full
+ * `CONTRACT.allowedBareImports` surface (REQ-WSDK-PLATFORM §3.4).
+ *
+ * @returns {string[]}
+ */
+export function shimmableSpecifiersForSiblings() {
+  return [
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "@colixsystems/widget-sdk",
+  ];
+}
+
+/**
+ * Stable URL-safe slug for a bare specifier — used as the path segment under
+ * `/shim/` so a specifier like `react/jsx-runtime` doesn't need URL encoding
+ * on the wire. Reversed by `shimSpecifierFromSlug` on the server.
+ *
+ * @param {string} specifier
+ * @returns {string}
+ */
+export function shimSlugFor(specifier) {
+  return specifier.replace(/\//g, "__").replace(/@/g, "_at_");
+}
+
+/**
+ * Reverse of `shimSlugFor`. Returns the bare specifier; the caller validates
+ * it against `shimmableSpecifiersForSiblings()` before serving.
+ *
+ * @param {string} slug
+ * @returns {string}
+ */
+export function shimSpecifierFromSlug(slug) {
+  return slug.replace(/_at_/g, "@").replace(/__/g, "/");
+}

package/src/webbundle.js

@@ -0,0 +1,148 @@
+// REQ-WSDK-PLATFORM bundle (sc-1064): the SINGLE web-entry bundler shared by the
+// publish packer (`scripts/pack-first-party-widget.mjs`) and the dev server
+// (`devserver.js`). Both paths feed a widget's WEB entry through this so what
+// you `dev` is byte-shape-identical to what ships (CLAUDE.md §3, one source).
+//
+// Why a bundler at all (vs. the sucrase transpile the native entry still uses):
+// the Studio's runtime loader resolves bare specifiers only for the host's OWN
+// shimmed set (`dev-shims.hostExternalSpecifiers()` — react family, react-dom,
+// the SDK, and a few vetted packages). A transpile-only web entry leaves
+// `import … from "react-leaflet"` / `"leaflet"` / `"leaflet/dist/leaflet.css"`
+// / the marker PNGs bare, and the loader's `findUnresolvedBareImports` guard
+// rejects the bundle ("unresolvable bare imports: react-leaflet, leaflet, …").
+// esbuild inlines all of those while leaving the host-resolved set external.
+//
+// What's externalised vs. inlined:
+//   * external = `hostExternalSpecifiers()` — the host injects its OWN React,
+//     react-dom, SDK, and vetted packages at runtime; inlining a second copy of
+//     React/react-dom would break the shared-instance invariant (mismatched
+//     renderer). These stay as bare `import`s the loader rewrites to blob shims.
+//   * inlined  = everything else: `react-leaflet`, `leaflet`, the marker PNGs
+//     (→ data URLs), the `leaflet/dist/leaflet.css` side-effect import (→ a JS
+//     module that injects a <style> at runtime).
+//
+// esbuild is a LAZY, optional dependency — imported only when this module's
+// `bundleWebEntry` runs (the `dev`/pack paths), never by the published SDK
+// runtime. Same pattern as `loadTransform()`'s `sucrase` import in devserver.js.
+
+import { hostExternalSpecifiers } from "./dev-shims.js";
+
+/**
+ * Lazily resolve esbuild's `build`. Kept out of the module's static imports so
+ * the published SDK runtime never forces the dependency — only the dev/pack
+ * bundle paths reach it. Throws a friendly install hint when it's absent
+ * (mirrors `loadTransform`'s sucrase handling).
+ *
+ * @returns {Promise<typeof import("esbuild")>}
+ */
+export async function loadEsbuild() {
+  try {
+    return await import("esbuild");
+  } catch {
+    throw new Error(
+      "Bundling a widget's web entry needs the optional `esbuild` dependency.\n" +
+        "Install it in your widget project:\n" +
+        "  npm install --save-dev esbuild",
+    );
+  }
+}
+
+// esbuild plugin: resolve `import "….css"` (a side-effect import) to a tiny JS
+// module that injects the CSS through a runtime <style> element. The output
+// bundle then carries NO `.css` import, and the styling still applies the
+// moment the module is evaluated in the browser. Guarded by
+// `typeof document !== "undefined"` so the same module is a no-op under SSR /
+// the native runtime (which never loads the web entry, but belt-and-braces).
+function cssInjectPlugin() {
+  return {
+    name: "appstudio-css-inject",
+    setup(build) {
+      build.onLoad({ filter: /\.css$/ }, async (args) => {
+        const { readFile } = await import("node:fs/promises");
+        const css = await readFile(args.path, "utf8");
+        const contents =
+          "if (typeof document !== \"undefined\") {\n" +
+          "  const __s = document.createElement(\"style\");\n" +
+          "  __s.setAttribute(\"data-appstudio-widget-css\", \"1\");\n" +
+          `  __s.textContent = ${JSON.stringify(css)};\n` +
+          "  document.head.appendChild(__s);\n" +
+          "}\n" +
+          "export default undefined;\n";
+        return { contents, loader: "js" };
+      });
+    },
+  };
+}
+
+/**
+ * Bundle a widget's WEB entry into a single ESM string with the host-resolved
+ * specifiers left external. JSX is transformed with the automatic runtime (so
+ * the loader's react/jsx-runtime shims resolve it), `.png` assets become data
+ * URLs, and `.css` side-effect imports become runtime <style> injectors.
+ *
+ * @param {object} opts
+ * @param {string} opts.entryPath  absolute path to the web entry (e.g. the
+ *   resolved `MapWidget.web.jsx`).
+ * @param {string[]} [opts.external]  bare specifiers to leave external. Defaults
+ *   to `hostExternalSpecifiers()` — the canonical host-resolved set.
+ * @param {string[]} [opts.nodePaths]  extra `node_modules` roots esbuild should
+ *   search when resolving the inlined deps (`react-leaflet`, `leaflet`, …). The
+ *   packer passes the frontend's `node_modules` (where the vetted web packages
+ *   are installed per the adding-vetted-packages skill) so the bundle resolves
+ *   them no matter the invoking CWD.
+ * @returns {Promise<string>} the bundled ESM source.
+ */
+export async function bundleWebEntry({
+  entryPath,
+  external = hostExternalSpecifiers(),
+  nodePaths = [],
+}) {
+  const esbuild = await loadEsbuild();
+  const result = await esbuild.build({
+    entryPoints: [entryPath],
+    bundle: true,
+    write: false,
+    format: "esm",
+    platform: "browser",
+    target: ["es2020"],
+    jsx: "automatic",
+    // Leave the host-resolved set as bare `import`s; the Studio loader rewrites
+    // them to blob shims at runtime (and Metro resolves them in the export).
+    // `react-native` is in that set (hostExternalSpecifiers): a vetted RN
+    // package (react-native-gesture-handler, react-native-reanimated, …) is
+    // INLINED, but its internal `import "react-native"` is left bare and
+    // resolves to the host's single react-native-web instance — the same
+    // shared-instance model as react/react-dom, far smaller than inlining a
+    // second copy of react-native-web into every bundle.
+    external,
+    // sc-1265: resolve the WEB build of cross-platform packages. RN packages
+    // ship `.web.js` platform variants and lean on the `browser` field /
+    // export condition; without these esbuild would pull their native entry and
+    // bundle React Native internals that break in the browser.
+    resolveExtensions: [
+      ".web.js",
+      ".web.jsx",
+      ".web.ts",
+      ".web.tsx",
+      ".js",
+      ".jsx",
+      ".ts",
+      ".tsx",
+      ".json",
+    ],
+    mainFields: ["browser", "module", "main"],
+    conditions: ["browser"],
+    loader: { ".png": "dataurl", ".jpg": "dataurl", ".gif": "dataurl" },
+    plugins: [cssInjectPlugin()],
+    // esbuild walks up from the entry for node_modules by default; `nodePaths`
+    // adds extra roots so a packer invoked from the repo root still resolves the
+    // vetted web packages installed under frontend/node_modules.
+    nodePaths,
+    logLevel: "silent",
+  });
+  const out = result.outputFiles?.[0];
+  if (!out) {
+    throw new Error(`esbuild produced no output for ${entryPath}`);
+  }
+  return out.text;
+}