@colixsystems/widget-sdk 0.187.0 → 0.189.0

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 (
@@ -252,10 +269,30 @@ function _packageRoot(spec) {
   const parts = spec.split("/");
   // A traversal / empty segment is a non-canonical specifier — never resolve it
   // to a vetted root, or "leaflet/../evil" would pass the gate as "leaflet".
-  if (parts.some((p) => p === "" || p === "." || p === "..")) return null;
+  if (parts.some((p) => p === "" || p === "." || p === ".." || p.includes("\\"))) {
+    return null;
+  }
   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(
@@ -275,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,
+          });
         }
       }
     }
@@ -336,6 +399,97 @@ function _importRules(source, manifest) {
   return findings;
 }
 
+// sc-10466 — Leaflet is bundled per widget; no host supplies its stylesheet.
+// Without `leaflet/dist/leaflet.css` the tiles, panes and markers are
+// unpositioned: a patch of map in an empty box, and no visible pin. And once
+// the CSS is injected inline its default marker image resolves against the
+// page URL and 404s, so a `<Marker>` needs an explicit `icon`.
+const _LEAFLET_ROOTS = new Set(["leaflet", "react-leaflet"]);
+const _LEAFLET_CSS = "leaflet/dist/leaflet.css";
+const _MARKER_TAG_RE = /<Marker\b/g;
+
+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*=)/;
+
+// 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) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  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;
+  while ((m = IMPORT_SPECIFIER_RE.exec(code))) {
+    const spec = m[1];
+    if (spec === _LEAFLET_CSS) importsCss = true;
+    const root = _packageRoot(spec);
+    if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
+    if (root === "react-leaflet") importsReactLeaflet = true;
+    if (!firstLeafletLine) firstLeafletLine = importLineAt(m.index + m[0].length);
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  if (!firstLeafletLine) return [];
+  const findings = [];
+  if (!importsCss) {
+    findings.push({
+      rule: "leaflet-css-missing",
+      severity: "error",
+      label:
+        `this file uses Leaflet but never imports its stylesheet — without ` +
+        `it the map draws a partial patch of tiles inside an empty box and ` +
+        `markers are invisible. Add \`import "${_LEAFLET_CSS}";\` to this file.`,
+      line: firstLeafletLine,
+      snippet: (sourceLines[firstLeafletLine - 1] || "").trim().slice(0, 200),
+    });
+  }
+  if (
+    !importsReactLeaflet ||
+    _ICON_DEFAULT_CONFIGURED_RE.test(_stripNonCode(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 = markerLineAt(tag.index);
+    findings.push({
+      rule: "leaflet-default-marker-icon",
+      severity: "warning",
+      label:
+        `<Marker> uses Leaflet's default icon, whose image path cannot ` +
+        `resolve inside a widget bundle, so the pin does not show. Import the ` +
+        `images (\`import markerIcon from "leaflet/dist/images/marker-icon.png"\`, ` +
+        `plus marker-icon-2x.png and marker-shadow.png), build ` +
+        `\`L.icon({ iconUrl, iconRetinaUrl, shadowUrl, iconSize: [25, 41], ` +
+        `iconAnchor: [12, 41] })\` once at module scope, and pass it as ` +
+        `\`icon={…}\`. Warning only — a widget that sets \`L.Icon.Default\` ` +
+        `itself (\`mergeOptions\` / \`imagePath\`) is not flagged.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+    _MARKER_TAG_RE.lastIndex = end;
+  }
+  return findings;
+}
+
 // Explicit opt-out. A widget legitimately calling a THIRD-PARTY API with a
 // relative path against an `axios` baseURL cannot avoid the substring match,
 // and post-sc-3589 an unavoidable finding burns AI repair turns on correct
@@ -1853,6 +2007,7 @@ function lintSource(source, options) {
       severity: f.severity || "error",
     })),
   );
+  findings.push(..._leafletRules(source));
   findings.push(..._hostApiUrlRules(source));
   // sc-6970 — soft warning: HTML markup spliced into a content string.
   findings.push(..._htmlInContentRules(source));
@@ -1896,4 +2051,5 @@ module.exports = {
   lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,
+  subpathImportRootsFor,
 };

package/dist/linter.js

@@ -94,9 +94,10 @@ export function bannedIdentifiers() {
 //
 // Recognised forms (string-level, no AST):
 //   import X from "spec"
-//   import { … } from "spec"
+//   import { … } from "spec"   (also wrapped over several lines)
 //   import * as X from "spec"
 //   import "spec"
+//   export { … } from "spec" / export * from "spec"
 //   const X = require("spec")  // CJS — for completeness
 //
 // Relative imports within the bundle (`./foo.js`, `./shared/util.js`) are
@@ -104,8 +105,25 @@ export function bannedIdentifiers() {
 // between `widget.web.jsx` and `widget.native.jsx`. Parent-directory
 // (`../`) and absolute (`/`, `http(s):`) paths are rejected to keep the
 // bundle scope sealed.
-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 (
@@ -135,10 +153,30 @@ function _packageRoot(spec) {
   const parts = spec.split("/");
   // A traversal / empty segment is a non-canonical specifier — never resolve it
   // to a vetted root, or "leaflet/../evil" would pass the gate as "leaflet".
-  if (parts.some((p) => p === "" || p === "." || p === "..")) return null;
+  if (parts.some((p) => p === "" || p === "." || p === ".." || p.includes("\\"))) {
+    return null;
+  }
   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.
+ */
+export 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(CONTRACT.vettedImports.map((v) => [v.specifier, v]));
@@ -159,69 +197,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];
-    // Reset lastIndex — the regex is /g and shared across lines.
+  // 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;
-      }
-      // Bare specifier — validate against the vetted list. A subpath/asset
-      // import (leaflet/dist/leaflet.css) resolves to its vetted package root.
-      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 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: 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,
+          });
         }
       }
     }
@@ -229,6 +284,97 @@ function _importRules(source, manifest) {
   return findings;
 }
 
+// sc-10466 — Leaflet is bundled per widget; no host supplies its stylesheet.
+// Without `leaflet/dist/leaflet.css` the tiles, panes and markers are
+// unpositioned: a patch of map in an empty box, and no visible pin. And once
+// the CSS is injected inline its default marker image resolves against the
+// page URL and 404s, so a `<Marker>` needs an explicit `icon`.
+const _LEAFLET_ROOTS = new Set(["leaflet", "react-leaflet"]);
+const _LEAFLET_CSS = "leaflet/dist/leaflet.css";
+const _MARKER_TAG_RE = /<Marker\b/g;
+
+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*=)/;
+
+// 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) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  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;
+  while ((m = IMPORT_SPECIFIER_RE.exec(code))) {
+    const spec = m[1];
+    if (spec === _LEAFLET_CSS) importsCss = true;
+    const root = _packageRoot(spec);
+    if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
+    if (root === "react-leaflet") importsReactLeaflet = true;
+    if (!firstLeafletLine) firstLeafletLine = importLineAt(m.index + m[0].length);
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  if (!firstLeafletLine) return [];
+  const findings = [];
+  if (!importsCss) {
+    findings.push({
+      rule: "leaflet-css-missing",
+      severity: "error",
+      label:
+        `this file uses Leaflet but never imports its stylesheet — without ` +
+        `it the map draws a partial patch of tiles inside an empty box and ` +
+        `markers are invisible. Add \`import "${_LEAFLET_CSS}";\` to this file.`,
+      line: firstLeafletLine,
+      snippet: (sourceLines[firstLeafletLine - 1] || "").trim().slice(0, 200),
+    });
+  }
+  if (
+    !importsReactLeaflet ||
+    _ICON_DEFAULT_CONFIGURED_RE.test(_stripNonCode(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 = markerLineAt(tag.index);
+    findings.push({
+      rule: "leaflet-default-marker-icon",
+      severity: "warning",
+      label:
+        `<Marker> uses Leaflet's default icon, whose image path cannot ` +
+        `resolve inside a widget bundle, so the pin does not show. Import the ` +
+        `images (\`import markerIcon from "leaflet/dist/images/marker-icon.png"\`, ` +
+        `plus marker-icon-2x.png and marker-shadow.png), build ` +
+        `\`L.icon({ iconUrl, iconRetinaUrl, shadowUrl, iconSize: [25, 41], ` +
+        `iconAnchor: [12, 41] })\` once at module scope, and pass it as ` +
+        `\`icon={…}\`. Warning only — a widget that sets \`L.Icon.Default\` ` +
+        `itself (\`mergeOptions\` / \`imagePath\`) is not flagged.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+    _MARKER_TAG_RE.lastIndex = end;
+  }
+  return findings;
+}
+
 // REQ-WSDK-PLATFORM §3.5: soft warning when source contains host-API URL
 // substrings. `severity: "warning"` so a HUMAN-authored submission still
 // publishes and the marketplace review queue flags it for a human pass.
@@ -1925,6 +2071,7 @@ export function lintSource(source, options) {
       severity: f.severity || "error",
     })),
   );
+  findings.push(..._leafletRules(source));
   // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
   // sc-6970 — soft warning: HTML markup spliced into a content string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.187.0",
+  "version": "0.189.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -45,7 +45,8 @@
     "README.md",
     "LICENSE",
     "src/webbundle.js",
-    "src/dev-shims.js"
+    "src/dev-shims.js",
+    "src/contract.js"
   ],
   "scripts": {
     "build": "node scripts/build.js",