@colixsystems/widget-sdk 0.187.0 → 0.188.0

package/README.md

@@ -75,7 +75,32 @@ 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.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**.
+
+### 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/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",
@@ -4864,7 +4867,11 @@ 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`.
+  version: "1.149.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

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",
@@ -4860,7 +4863,11 @@ 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`.
+  version: "1.149.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/linter.cjs

@@ -252,7 +252,9 @@ 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];
 }
 
@@ -336,6 +338,87 @@ 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*=)/;
+
+function _lineAt(code, index) {
+  return code.slice(0, index).split(/\r?\n/).length;
+}
+
+function _leafletRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  let firstLeafletLine = 0;
+  let importsCss = false;
+  let importsReactLeaflet = false;
+  // 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 = _lineAt(code, 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;
+  }
+  _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);
+    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 +1936,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));

package/dist/linter.js

@@ -135,7 +135,9 @@ 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];
 }
 
@@ -229,6 +231,87 @@ 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*=)/;
+
+function _lineAt(code, index) {
+  return code.slice(0, index).split(/\r?\n/).length;
+}
+
+function _leafletRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  let firstLeafletLine = 0;
+  let importsCss = false;
+  let importsReactLeaflet = false;
+  // 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 = _lineAt(code, 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;
+  }
+  _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);
+    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 +2008,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.188.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",