@colixsystems/widget-sdk 0.188.0 → 0.189.0

package/README.md

@@ -75,7 +75,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.188.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)
 

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

@@ -3505,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
@@ -4871,7 +4914,16 @@ const CONTRACT = deepFreeze({
   //    (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`.
-  version: "1.149.0",
+  // 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,
@@ -4898,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

@@ -3501,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
@@ -4867,7 +4910,16 @@ const CONTRACT = deepFreeze({
   //    (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`.
-  version: "1.149.0",
+  // 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,
@@ -4894,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. */

package/dist/linter.cjs

@@ -221,8 +221,25 @@ function bannedIdentifiers() {
 
 // REQ-WSDK-PLATFORM §3.4, §8: import-specifier validation. See linter.js
 // for the source-of-truth comment.
-const IMPORT_SPECIFIER_RE =
-  /(?:^|[\s;])(?:import(?:\s+[^"';]+from)?|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+// The import clause follows the grammar (default, `* as ns`, `{ … }`), so
+// prose that merely says "import … from" rarely matches. A brace list stops
+// at the next import/export keyword and no two quantifiers share whitespace,
+// keeping the whole-source scan linear on hostile input.
+const _ID_CHAR = "[\\p{ID_Continue}$\\\\]";
+const _NAMED = `\\{(?:(?!\\b(?:import|export)\\b)(?:[^}"';]|"[^"\\n]*"|'[^'\\n]*'))*\\}`;
+const _NAMESPACE = `\\*\\s*as\\s+${_ID_CHAR}+`;
+const _IMPORT_CLAUSE =
+  `(?:${_ID_CHAR}+(?:\\s*,\\s*(?:${_NAMESPACE}|${_NAMED}))?` +
+  `|${_NAMESPACE}|${_NAMED})`;
+const IMPORT_SPECIFIER_RE = new RegExp(
+  // Not part of an identifier, a member access, CSS `@import` or JSX text.
+  `(?<![\\p{ID_Continue}$.@#'"\`>])` +
+    `(?:import(?!${_ID_CHAR})\\s*(?:${_IMPORT_CLAUSE}\\s*from\\s*)?(?:\\(\\s*)?` +
+    `|export(?!${_ID_CHAR})\\s*(?:\\*(?:\\s*as\\s+${_ID_CHAR}+)?|${_NAMED})\\s*from\\s*` +
+    `|require(?!${_ID_CHAR})\\s*\\(\\s*)` +
+    `['"]([^'"\\s]+)['"]`,
+  "gu",
+);
 
 function _classifySpecifier(spec) {
   if (
@@ -258,6 +275,24 @@ function _packageRoot(spec) {
   return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 
+/**
+ * The package roots whose SUBPATH imports load in a file whose manifest is
+ * narrowed to it (`narrowManifestForFile`). The web loader shims the packages
+ * the host provides by exact name, so a file that ships to web may import a
+ * subpath only of a bundled vetted package; Metro, on native, resolves any
+ * real subpath of a vetted package. Shared with the agent render sandbox.
+ */
+function subpathImportRootsFor(manifest) {
+  const platforms =
+    manifest && Array.isArray(manifest.supportedPlatforms)
+      ? manifest.supportedPlatforms
+      : [];
+  const nativeOnly = platforms.length > 0 && !platforms.includes("web");
+  return nativeOnly
+    ? [...CONTRACT.allowedBareImports]
+    : [...CONTRACT.subpathImportRoots];
+}
+
 function _importRules(source, manifest) {
   const findings = [];
   const allowed = new Map(
@@ -277,60 +312,86 @@ function _importRules(source, manifest) {
     manifest.supportedPlatforms.length > 0
       ? new Set(manifest.supportedPlatforms)
       : null;
+  const subpathRoots = new Set(subpathImportRootsFor(manifest));
 
-  const lines = source.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
+  // Whole-source scan: a Prettier-wrapped import spans several lines. Both
+  // the raw and the comment-masked text are read, because the masker cannot
+  // see regex literals and a `/"/` would blank a real import out of it.
+  const specifiersByEnd = new Map();
+  for (const text of [source, _stripNonCode(source, { keepStrings: true })]) {
     IMPORT_SPECIFIER_RE.lastIndex = 0;
     let m;
-    while ((m = IMPORT_SPECIFIER_RE.exec(line))) {
-      const spec = m[1];
-      const kind = _classifySpecifier(spec);
-      if (kind === "relative-ok") continue;
-      if (kind === "relative-escape") {
-        findings.push({
-          rule: "no-parent-relative-import",
-          label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      if (kind === "absolute") {
-        findings.push({
-          rule: "no-absolute-import",
-          label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      const entry = allowed.get(spec) || allowed.get(_packageRoot(spec));
-      if (!entry) {
-        findings.push({
-          rule: "import-not-vetted",
-          label:
-            `import "${spec}" is not on the vetted package list — see ` +
-            `CONTRACT.vettedImports for the current set or open a request to add it`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      if (declaredPlatforms) {
-        for (const wanted of declaredPlatforms) {
-          if (!entry.platforms.includes(wanted)) {
-            findings.push({
-              rule: "import-platform-mismatch",
-              label:
-                `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
-                `manifest claims supportedPlatforms includes "${wanted}". ` +
-                `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
-                `or drop "${wanted}" from manifest.supportedPlatforms.`,
-              line: i + 1,
-              snippet: line.trim().slice(0, 200),
-            });
-          }
+    while ((m = IMPORT_SPECIFIER_RE.exec(text))) {
+      specifiersByEnd.set(m.index + m[0].length, m[1]);
+    }
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(source);
+  const ordered = [...specifiersByEnd].sort((a, b) => a[0] - b[0]);
+  for (const [end, spec] of ordered) {
+    const line = lineAt(end);
+    const snippet = (sourceLines[line - 1] || "").trim().slice(0, 200);
+    const kind = _classifySpecifier(spec);
+    if (kind === "relative-ok") continue;
+    if (kind === "relative-escape") {
+      findings.push({
+        rule: "no-parent-relative-import",
+        label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    if (kind === "absolute") {
+      findings.push({
+        rule: "no-absolute-import",
+        label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    // Bare specifier — validate against the vetted list. A subpath/asset
+    // import (leaflet/dist/leaflet.css) resolves to its vetted package root.
+    let entry = allowed.get(spec);
+    const root = entry ? null : _packageRoot(spec);
+    if (root && subpathRoots.has(root)) entry = allowed.get(root);
+    if (!entry) {
+      findings.push({
+        rule: "import-not-vetted",
+        label:
+          root && allowed.has(root)
+            ? `import "${spec}" is a subpath of "${root}", which the web ` +
+              `host provides by its exact name only, so it cannot load in ` +
+              `the web Player — import from "${root}" itself (a file that ` +
+              `ships only to native may keep the subpath)`
+            : `import "${spec}" is not on the vetted package list — see ` +
+              `CONTRACT.vettedImports for the current set or open a request to add it`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    // If the manifest declares supportedPlatforms, every imported
+    // specifier must support every declared platform. A widget that
+    // imports react-native-maps (native-only) cannot honestly claim
+    // supportedPlatforms: ["web", "native"] from a single source file —
+    // it must either drop "web" from the manifest, OR move that import
+    // into widget.native.jsx so the web bundle doesn't see it.
+    if (declaredPlatforms) {
+      for (const wanted of declaredPlatforms) {
+        if (!entry.platforms.includes(wanted)) {
+          findings.push({
+            rule: "import-platform-mismatch",
+            label:
+              `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
+              `manifest claims supportedPlatforms includes "${wanted}". ` +
+              `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
+              `or drop "${wanted}" from manifest.supportedPlatforms.`,
+            line,
+            snippet,
+          });
         }
       }
     }
@@ -351,8 +412,16 @@ const _ASSET_SPECIFIER_RE = /\.(css|png|jpe?g|gif)$/i;
 const _ICON_DEFAULT_CONFIGURED_RE =
   /\bIcon\s*\.\s*Default\s*(\.\s*mergeOptions\s*\(|\.\s*imagePath\s*=)/;
 
-function _lineAt(code, index) {
-  return code.slice(0, index).split(/\r?\n/).length;
+// Line of an index in `code`, counted forward: indexes must not decrease.
+function _lineCounter(code) {
+  let line = 1;
+  let at = 0;
+  return (index) => {
+    for (; at < index; at += 1) {
+      if (code.charCodeAt(at) === 10) line += 1;
+    }
+    return line;
+  };
 }
 
 function _leafletRules(source) {
@@ -361,6 +430,7 @@ function _leafletRules(source) {
   let firstLeafletLine = 0;
   let importsCss = false;
   let importsReactLeaflet = false;
+  const importLineAt = _lineCounter(code);
   // Whole-source scan: a Prettier-wrapped import spans several lines.
   IMPORT_SPECIFIER_RE.lastIndex = 0;
   let m;
@@ -370,7 +440,7 @@ function _leafletRules(source) {
     const root = _packageRoot(spec);
     if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
     if (root === "react-leaflet") importsReactLeaflet = true;
-    if (!firstLeafletLine) firstLeafletLine = _lineAt(code, m.index + m[0].length);
+    if (!firstLeafletLine) firstLeafletLine = importLineAt(m.index + m[0].length);
   }
   IMPORT_SPECIFIER_RE.lastIndex = 0;
   if (!firstLeafletLine) return [];
@@ -393,12 +463,13 @@ function _leafletRules(source) {
   ) {
     return findings;
   }
+  const markerLineAt = _lineCounter(code);
   _MARKER_TAG_RE.lastIndex = 0;
   let tag;
   while ((tag = _MARKER_TAG_RE.exec(code))) {
     const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
     if (/(^|\s)icon\s*=/.test(code.slice(tag.index, end))) continue;
-    const line = _lineAt(code, tag.index);
+    const line = markerLineAt(tag.index);
     findings.push({
       rule: "leaflet-default-marker-icon",
       severity: "warning",
@@ -1980,4 +2051,5 @@ module.exports = {
   lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,
+  subpathImportRootsFor,
 };