@colixsystems/widget-sdk 0.37.0 → 0.39.0

package/dist/dev-shims.js

@@ -0,0 +1,255 @@
+// 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",
+];
+
+/**
+ * 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, "/");
+}