@colixsystems/widget-sdk 0.187.0 → 0.189.0

package/README.md

@@ -75,7 +75,43 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.187.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.189.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.189.0 (contract 1.150.0)
+
+**The import check now catches two shapes that passed lint and then failed to load in the web Player.** This narrows `import-not-vetted`:
+
+- **Imports wrapped over several lines.** The check read one line at a time, so a Prettier-wrapped import of a package that is not on the vetted list was never seen. It now reads the whole file and reports the finding on the `from` line. `export { … } from "pkg"` and `export * from "pkg"` are checked too, and so are forms written without spaces (`import{a}from"pkg"`) or inside an expression (`x = require("pkg")`).
+- **Subpaths of packages the web Player provides.** The web Player supplies some packages itself and loads them by their exact name only. `CONTRACT.hostExternalSpecifiers` lists them; today they are `react` (and its JSX runtimes), `react-dom`, `react-native`, `@colixsystems/widget-sdk`, `lucide-react-native`, `react-native-svg`, `react-native-qrcode-svg`, `date-fns`, `decimal.js`, `d3-scale`, `d3-shape`, `d3-array` and `simple-statistics`. A subpath of one of them, such as `date-fns/format` or `react-native/Libraries/…`, cannot load on web. It is now `import-not-vetted` in any file that ships to web. Import from the package itself: `import { format } from "date-fns"`.
+
+A subpath of a package your bundle includes is still allowed, for example `leaflet/dist/leaflet.css`, a Leaflet marker image or `react-native-vector-icons/MaterialIcons`. A file that ships only to native (`widget.native.jsx`, or a manifest whose `supportedPlatforms` is `["native"]`) keeps every vetted subpath, because the native build resolves them.
+
+`CONTRACT.subpathImportRoots` lists the vetted packages whose subpaths load on web, and the new `subpathImportRootsFor(manifest)` export of `@colixsystems/widget-sdk/linter` returns the roots that load for a file with that manifest. `appstudio-widget lint --manifest` now checks `widget.web.jsx` and `widget.native.jsx` against the platform each one ships to, as the submission check already did.
+
+### What's new in 0.188.0 (contract 1.149.0)
+
+**New linter rules for Leaflet maps: `leaflet-css-missing` and `leaflet-default-marker-icon`.** A widget's web entry is bundled with its own copy of Leaflet, and nothing else loads Leaflet's stylesheet. A map that skipped `import "leaflet/dist/leaflet.css"` drew a small patch of tiles inside an otherwise empty box, with its panes out of place and its markers invisible. Even with the stylesheet, Leaflet looks up its default marker image relative to the page, which 404s inside a widget, so a `<Marker>` with no `icon` showed no pin.
+
+- **`leaflet-css-missing` (severity `error`).** A file that imports `leaflet` or `react-leaflet` code (an image-only import does not count) must also import `"leaflet/dist/leaflet.css"`. The bundler turns that import into an injected `<style>`. Import it in every file that uses Leaflet; the bundler includes it once.
+- **`leaflet-default-marker-icon` (severity `warning`).** A react-leaflet `<Marker>` with no `icon` prop. Import the marker PNGs (the bundler inlines them as data URLs), build the icon once at module scope and pass it in:
+
+```jsx
+import L from "leaflet";
+import "leaflet/dist/leaflet.css";
+import markerIcon from "leaflet/dist/images/marker-icon.png";
+import markerIcon2x from "leaflet/dist/images/marker-icon-2x.png";
+import markerShadow from "leaflet/dist/images/marker-shadow.png";
+
+const pin = L.icon({
+  iconUrl: markerIcon, iconRetinaUrl: markerIcon2x, shadowUrl: markerShadow,
+  iconSize: [25, 41], iconAnchor: [12, 41], popupAnchor: [1, -34], shadowSize: [41, 41],
+});
+// <Marker position={[lat, lng]} icon={pin} />
+```
+
+  It is a warning because a widget that configures `L.Icon.Default` itself is fine, and is not flagged. `<CircleMarker>` needs no icon.
+
+The `leaflet` and `react-leaflet` entries in `CONTRACT.vettedImports` now say the same. Comments are not scanned, so documenting the pattern is safe.
 
 ### What's new in 0.187.0 (contract 1.148.0)
 

package/dist/cli.js

@@ -5,10 +5,15 @@
 //                                                          — REQ-WSDK-DEVKIT local dev server
 
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { argv, exit, stderr, stdout } from "node:process";
-import { lintSource, lintStyleWiring, lintEditability } from "./linter.js";
+import {
+  lintSource,
+  lintStyleWiring,
+  lintEditability,
+  narrowManifestForFile,
+} from "./linter.js";
 import { startDevServer } from "./devserver.js";
 
 function usage() {
@@ -99,9 +104,15 @@ async function runLint(rest) {
     }
   }
   const label = positionals.join(", ");
+  // Narrow per split-impl file, as the submission gate does.
   const perFile = Object.entries(files).map(([filePath, source]) => [
     filePath,
-    lintSource(source, manifest ? { manifest } : undefined),
+    lintSource(
+      source,
+      manifest
+        ? { manifest: narrowManifestForFile(manifest, basename(filePath)) }
+        : undefined,
+    ),
   ]);
   const wiring = manifest
     ? lintStyleWiring(manifest, files)

package/dist/contract.cjs

@@ -3296,13 +3296,16 @@ const VETTED_IMPORTS = [
     platforms: ["web"],
     category: "geo",
     description:
-      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps.",
+      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps. " +
+      'Every file that imports it must also `import "leaflet/dist/leaflet.css"` (the linter enforces it), and a marker needs an ' +
+      "explicit `L.icon` built from the imported `leaflet/dist/images/*.png`: Leaflet's default icon cannot resolve its image inside a bundle.",
   },
   {
     specifier: "react-leaflet",
     platforms: ["web"],
     category: "geo",
-    description: "React bindings for leaflet. Web-only.",
+    description:
+      'React bindings for leaflet. Web-only. Import "leaflet/dist/leaflet.css" alongside it and pass `icon` to every <Marker>.',
   },
   {
     specifier: "expo-audio",
@@ -3502,6 +3505,49 @@ const ALLOWED_BARE_IMPORTS = [
   ...CORE_INFRA_BARE_IMPORTS,
 ];
 
+// sc-10502: the bare specifiers the web host RESOLVES for a loaded widget
+// instead of letting its bundle inline a copy. The web-entry bundler marks
+// exactly these `external` and the Studio loader shims each by EXACT name, so
+// a subpath of one (`date-fns/format`) cannot load in the web Player.
+// `dev-shims.hostExternalSpecifiers()` returns this list; the loader's
+// module-load guard (frontend widgetLoader.js) throws if its shims drift.
+//
+// Why each entry is host-resolved, not bundled:
+//   * react + its JSX runtimes: one React instance (hooks, context).
+//   * react-dom, react-dom/client: react-leaflet portals through react-dom;
+//     a second renderer beside the host's React crashes (sc-1064).
+//   * @colixsystems/widget-sdk: the host-built SDK carries datastore, theme
+//     and navigation.
+//   * react-native, lucide-react-native, react-native-svg,
+//     react-native-qrcode-svg: share the host's react-native-web instance
+//     (sc-1265, sc-6105).
+//   * date-fns and the maths set: an agent widget is transpiled, not
+//     bundled, so the host must resolve its bare imports (sc-7191).
+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",
+  "react-native-qrcode-svg",
+  "react-native",
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
+];
+
+// Vetted roots whose subpaths load on web (`leaflet/dist/leaflet.css`): the
+// bundle inlines them, so no exact-name host shim stands in the way.
+const SUBPATH_IMPORT_ROOTS = ALLOWED_BARE_IMPORTS.filter(
+  (spec) => !HOST_EXTERNAL_SPECIFIERS.includes(spec),
+);
+
 // REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
 // soft warning. None of these block the lint by themselves — they prompt
 // the marketplace reviewer to spot-check, and they help authors learn the
@@ -4864,7 +4910,20 @@ const CONTRACT = deepFreeze({
   //    New `useUserPhoto()` changes it through the new OPTIONAL context
   //    slice `account` ({ setPhoto, removePhoto }); a host without it reads
   //    `canEdit: false`.
-  version: "1.148.0",
+  // 1.149.0: narrowing (sc-10466) — new linter rule `leaflet-css-missing`
+  //    (error): a file importing leaflet / react-leaflet must import
+  //    "leaflet/dist/leaflet.css". `leaflet-default-marker-icon` (warning)
+  //    flags a react-leaflet <Marker> with no `icon`.
+  // 1.150.0: narrowing (sc-10502) — the linter scans imports across the whole
+  //    file, so a wrapped `import { … } from` (or an `export … from`) of an
+  //    unvetted package is `import-not-vetted` on its `from` line. A file
+  //    that ships to web may import a SUBPATH only of a bundled vetted
+  //    package (`subpathImportRoots`, e.g. "leaflet/dist/leaflet.css"); a
+  //    host-provided package's subpath ("date-fns/format") is flagged. A
+  //    native-only file keeps every vetted subpath (Metro resolves them).
+  //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
+  //    linter export `subpathImportRootsFor(manifest)`.
+  version: "1.150.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4891,6 +4950,8 @@ const CONTRACT = deepFreeze({
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
+  hostExternalSpecifiers: HOST_EXTERNAL_SPECIFIERS,
+  subpathImportRoots: SUBPATH_IMPORT_ROOTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
   payloadValueTypes: PAYLOAD_VALUE_TYPES,
   chargeCurrency: CHARGE_CURRENCY,

package/dist/contract.js

@@ -3292,13 +3292,16 @@ const VETTED_IMPORTS = [
     platforms: ["web"],
     category: "geo",
     description:
-      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps.",
+      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps. " +
+      'Every file that imports it must also `import "leaflet/dist/leaflet.css"` (the linter enforces it), and a marker needs an ' +
+      "explicit `L.icon` built from the imported `leaflet/dist/images/*.png`: Leaflet's default icon cannot resolve its image inside a bundle.",
   },
   {
     specifier: "react-leaflet",
     platforms: ["web"],
     category: "geo",
-    description: "React bindings for leaflet. Web-only.",
+    description:
+      'React bindings for leaflet. Web-only. Import "leaflet/dist/leaflet.css" alongside it and pass `icon` to every <Marker>.',
   },
   {
     specifier: "expo-audio",
@@ -3498,6 +3501,49 @@ const ALLOWED_BARE_IMPORTS = [
   ...CORE_INFRA_BARE_IMPORTS,
 ];
 
+// sc-10502: the bare specifiers the web host RESOLVES for a loaded widget
+// instead of letting its bundle inline a copy. The web-entry bundler marks
+// exactly these `external` and the Studio loader shims each by EXACT name, so
+// a subpath of one (`date-fns/format`) cannot load in the web Player.
+// `dev-shims.hostExternalSpecifiers()` returns this list; the loader's
+// module-load guard (frontend widgetLoader.js) throws if its shims drift.
+//
+// Why each entry is host-resolved, not bundled:
+//   * react + its JSX runtimes: one React instance (hooks, context).
+//   * react-dom, react-dom/client: react-leaflet portals through react-dom;
+//     a second renderer beside the host's React crashes (sc-1064).
+//   * @colixsystems/widget-sdk: the host-built SDK carries datastore, theme
+//     and navigation.
+//   * react-native, lucide-react-native, react-native-svg,
+//     react-native-qrcode-svg: share the host's react-native-web instance
+//     (sc-1265, sc-6105).
+//   * date-fns and the maths set: an agent widget is transpiled, not
+//     bundled, so the host must resolve its bare imports (sc-7191).
+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",
+  "react-native-qrcode-svg",
+  "react-native",
+  "decimal.js",
+  "d3-scale",
+  "d3-shape",
+  "d3-array",
+  "simple-statistics",
+];
+
+// Vetted roots whose subpaths load on web (`leaflet/dist/leaflet.css`): the
+// bundle inlines them, so no exact-name host shim stands in the way.
+const SUBPATH_IMPORT_ROOTS = ALLOWED_BARE_IMPORTS.filter(
+  (spec) => !HOST_EXTERNAL_SPECIFIERS.includes(spec),
+);
+
 // REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
 // soft warning. None of these block the lint by themselves — they prompt
 // the marketplace reviewer to spot-check, and they help authors learn the
@@ -4860,7 +4906,20 @@ const CONTRACT = deepFreeze({
   //    New `useUserPhoto()` changes it through the new OPTIONAL context
   //    slice `account` ({ setPhoto, removePhoto }); a host without it reads
   //    `canEdit: false`.
-  version: "1.148.0",
+  // 1.149.0: narrowing (sc-10466) — new linter rule `leaflet-css-missing`
+  //    (error): a file importing leaflet / react-leaflet must import
+  //    "leaflet/dist/leaflet.css". `leaflet-default-marker-icon` (warning)
+  //    flags a react-leaflet <Marker> with no `icon`.
+  // 1.150.0: narrowing (sc-10502) — the linter scans imports across the whole
+  //    file, so a wrapped `import { … } from` (or an `export … from`) of an
+  //    unvetted package is `import-not-vetted` on its `from` line. A file
+  //    that ships to web may import a SUBPATH only of a bundled vetted
+  //    package (`subpathImportRoots`, e.g. "leaflet/dist/leaflet.css"); a
+  //    host-provided package's subpath ("date-fns/format") is flagged. A
+  //    native-only file keeps every vetted subpath (Metro resolves them).
+  //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
+  //    linter export `subpathImportRootsFor(manifest)`.
+  version: "1.150.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4887,6 +4946,8 @@ const CONTRACT = deepFreeze({
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
+  hostExternalSpecifiers: HOST_EXTERNAL_SPECIFIERS,
+  subpathImportRoots: SUBPATH_IMPORT_ROOTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
   payloadValueTypes: PAYLOAD_VALUE_TYPES,
   chargeCurrency: CHARGE_CURRENCY,

package/dist/dev-shims.js

@@ -19,6 +19,8 @@
 // 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.
 
+import { CONTRACT } from "./contract.js";
+
 // 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.
@@ -61,81 +63,16 @@ export const REACT_NAMED_EXPORTS = [
 // 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`,
-//     `react-native-qrcode-svg` — vetted packages the host already bundles +
-//     shims (`_hostVettedModules`); sharing the host copy keeps icons/SVG on
-//     the host's react-native-web instance. qrcode-svg draws through
-//     react-native-svg, so externalising it keeps the QR on that same
-//     instance instead of a bundle inlining a second one (sc-6105).
-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",
-  "react-native-qrcode-svg",
-  // 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",
-  // sc-7191: the vetted pure-JS maths set. Externalised for the same reason as
-  // date-fns — an AI-agent widget is transpiled, never bundled, so the host
-  // must resolve the bare import at runtime.
-  "decimal.js",
-  "d3-scale",
-  "d3-shape",
-  "d3-array",
-  "simple-statistics",
-];
-
 /**
  * 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.
+ * the web-entry bundler must NOT inline. Sourced from
+ * `CONTRACT.hostExternalSpecifiers`, which documents each entry. 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];
+  return [...CONTRACT.hostExternalSpecifiers];
 }
 
 function reactShimSrc() {

package/dist/index.d.ts

@@ -3380,6 +3380,10 @@ export interface AiWidgetContract {
   readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
   readonly bannedApis: ReadonlyArray<ContractBannedApi>;
   readonly allowedBareImports: ReadonlyArray<string>;
+  /** Bare specifiers the web host provides by exact name; a widget bundle never inlines them. */
+  readonly hostExternalSpecifiers: ReadonlyArray<string>;
+  /** Bundled vetted package roots: the only roots whose subpaths load in the web Player. */
+  readonly subpathImportRoots: ReadonlyArray<string>;
   /** sc-4686 — the render-time fallback currency when the host supplies none. */
   readonly chargeCurrency: string;
   /** sc-4686 — how each currency is written; read by `formatMoney`, never Intl. */