@nika-js/onlymap 0.4.3 → 0.4.6

package/README.md

@@ -69,7 +69,7 @@ Or with no build step at all, straight from a CDN:
 
 The bare package URL serves `dist/onlymap.standalone.js`, a single-file bundle built for exactly this (jsDelivr too). Use a CDN that serves the package's raw files — **not** a rebundling CDN like esm.sh, which re-splits the bundle into duplicate copies of the deck.gl/luma.gl runtime and breaks every layer's shader compilation.
 
-Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 528 unit/behavioral tests and 45 Playwright GPU tests.
+Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 540 unit/behavioral tests and 53 Playwright GPU tests.
 
 The [examples](https://github.com/NikaGeospatial/onlymapjs/tree/main/examples) are the best tour: widgets, behaviors & overlays, basemaps, columnar/Arrow data, manual drawing, 3D models, scene lighting (with the native lighting widget), DEM terrain, a live WebSocket ship feed, and a polled driver fleet.
 
@@ -81,7 +81,7 @@ A handful of elements, one rule: **attributes are kebab-case versions of deck.gl
 |---|---|
 | `<om-map>` | The map. `center`, `zoom`, `pitch`, `bearing`; `basemap` takes a free preset (`positron`, `liberty`, `dark-matter`, `osm`, …), a style URL, or `"none"` (standalone canvas) — and switches **live**; `validate` for a live on-page error panel. |
 | `<om-layer>` | Any of **34 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale and the native `COGLayer` for GeoTIFF rasters. `id` required; `label`/`color` feed the legend. |
-| `<om-widget>` | UI panels. Built-ins: `legend` (symbology-aware: color scales render as gradient ramps or class ranges, categorical ternaries as discrete palettes), `layer-switcher`, `basemap-switcher`, `lighting`, `zoom-controls`, `undo-redo`, `scale-bar`, `attribution`, `filter`, `draw`, `vega-lite` (live charts). Or write your own inline with HTML + a `<script type="om/widget">`. Adjacent compact button widgets (`zoom-controls`, `undo-redo`, `widgets-toggle`) **auto-cluster** into one control group (opt out per widget with `cluster="false"`), and `<om-map widgets-hidden>` / the `set-widgets-visible` action / `<om-widget type="widgets-toggle">` hide all chrome without destroying it — attribution never hides. **Placement is managed**: `position` takes one of 8 logical, RTL-aware slots (`top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`; legacy corner names alias) — same-slot widgets stack with flush edges and a shared gap, `order` sets in-slot ordering, and `position="manual"` opts out entirely (a plain block you style yourself, even outside the map). A slot dims automatically while an open popup covers it (`widgets-dim="off"` to disable). Themeable from plain page CSS via custom properties: `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` (also `-muted`, `-border`, `-hover-bg`, `-accent`), plus layout tokens (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) or the no-CSS sugar `<om-map widget-style="gap:10 opacity:0.9">`. |
+| `<om-widget>` | UI panels. Built-ins: `legend` (symbology-aware: color scales render as gradient ramps or class ranges, categorical ternaries as discrete palettes), `layer-switcher`, `basemap-switcher`, `lighting`, `zoom-controls`, `undo-redo`, `scale-bar`, `attribution`, `filter`, `draw`, `vega-lite` (live charts). Or write your own inline with HTML + a `<script type="om/widget">`. Adjacent compact button widgets (`zoom-controls`, `undo-redo`, `widgets-toggle`) **auto-cluster** into one control group (opt out per widget with `cluster="false"`), and `<om-map widgets-hidden>` / the `set-widgets-visible` action / `<om-widget type="widgets-toggle">` hide all authored chrome without destroying it — provider attribution and the license badge never hide. **Placement is managed**: `position` takes one of 8 logical, RTL-aware slots (`top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`; legacy corner names alias) — same-slot widgets stack with flush edges and a shared gap, `order` sets in-slot ordering, and `position="manual"` opts out entirely (a plain block you style yourself, even outside the map). At map widths ≤640px, managed widgets automatically move into accessible top/end/bottom/start drawers; `fold="never"` keeps an essential control out, `widgets-fold="off"` disables folding, and `--om-widget-fold-breakpoint` changes the map-width threshold. Provider attribution is an in-flow member of `bottom-end` and the license badge of `bottom-start`, so neither covers a widget. A slot dims automatically while an open popup covers it (`widgets-dim="off"` to disable), except slots containing required chrome. Themeable from plain page CSS via custom properties: `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` (also `-muted`, `-border`, `-hover-bg`, `-accent`), plus layout tokens (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) or the no-CSS sugar `<om-map widget-style="gap:10 opacity:0.9">`. |
 | `<om-overlay>` | Rich HTML anchored to a map location — a static `anchor="[lng, lat]"`, the current selection, or a feature's own geometry via `anchor-layer`/`anchor-feature-id`. `{{field}}` interpolates the picked feature, HTML-escaped by default. |
 | `<om-behavior>` | Declarative interactions: `on="click|hover|drag|load|data-loaded"` → a named action. |
 | `<om-story>` | A storyboard: `<om-step>` children fire actions on a timeline. Controlled by the `player` widget, behaviors, or `storyEl.play()/pause()/seek()`. |
@@ -172,23 +172,54 @@ That opt-in command updates `.vscode/settings.json` and copies the `!`-prefixed
 
 The package also ships `!`-prefixed manifest snippets (`node_modules/@nika-js/onlymap/.vscode/onlymap.code-snippets`) — type `!starter`, `!map`, `!layer`, `!draw`, etc. to scaffold a well-formed element.
 
-## LLM Skill
+## Quick-start guide
 
-The npm package and public mirror include a portable Skill at `skills/onlymapjs`. Skill-aware agents can install that folder to learn the OnlyMapJS manifest syntax, authoring patterns, and validation workflow instead of treating the library like raw deck.gl.
+### Use OnlyMapJS with Claude Code and Codex
 
-With the Vercel Labs `skills` CLI, install it from the public GitHub repo:
+The public repo includes a portable `onlymapjs` Skill that teaches coding agents the manifest syntax, React adapter, common map patterns, and validation/testing workflow. Install the library in the app you want to map:
 
 ```bash
+npm install @nika-js/onlymap
+```
+
+Then, from that app's repository root, install the Skill for your agent:
+
+```bash
+# Claude Code
+npx -y skills add NikaGeospatial/onlymapjs --skill onlymapjs --agent claude-code
+
+# Codex
 npx -y skills add NikaGeospatial/onlymapjs --skill onlymapjs --agent codex
 ```
 
-Or install globally for Codex:
+Using both agents in the same repository? Install it for both in one command:
 
 ```bash
-npx -y skills add NikaGeospatial/onlymapjs --skill onlymapjs --agent codex --global
+npx -y skills add NikaGeospatial/onlymapjs \
+  --skill onlymapjs \
+  --agent claude-code \
+  --agent codex
+```
+
+Start or restart Claude Code or Codex in that repository, then describe the map you want. Mention the installed Skill explicitly when you want to guarantee it is used:
+
+```text
+Use the installed OnlyMapJS skill to build a full-screen map in this project.
+Inspect my data before choosing accessors. Add a legend and click details,
+include a no-JavaScript fallback, validate the result, and run the relevant tests.
 ```
 
-To inspect it without installing:
+For an existing React app:
+
+```text
+Use the installed OnlyMapJS skill to add this map to my React app. Use the
+@nika-js/onlymap/react adapter, preserve the app's existing state patterns,
+and verify the result with the library's headless testing tools.
+```
+
+The Skill steers HTML projects toward declarative `om-*` manifests and React projects toward the first-party adapter. It also tells the agent to use `OmMap.validate()`, `OmMap.snapshotIR()`, and the headless harness rather than guessing whether the generated map works.
+
+To inspect the Skill before installing it:
 
 ```bash
 npx -y skills add NikaGeospatial/onlymapjs --list
@@ -213,7 +244,9 @@ await h.pick({ layer: "quakes", featureId: "q1" }); // same code path as a real
 expect(overlay.shadowRoot.textContent).toContain("M 6.5");
 ```
 
-Plus `OmMap.snapshotIR(html)` to lock down what a manifest *means* in a snapshot test, and `await mapEl.ready` / the `om-map-ready` event to de-flake browser e2e tests. Full guide: [docs/testing.md](docs/testing.md).
+Plus `OmMap.snapshotIR(html)` to lock down what a manifest *means* in a snapshot test, and `await mapEl.ready` / the `om-map-ready` event to de-flake browser e2e tests.
+
+**Layout, checked like types.** `npx @nika-js/onlymap check-layout <manifest.html>` audits a page's real rendered widget layout in headless Chromium — no screenshots, no eyeballing: it asserts no widgets overlap, each is hit-testable (not painted under the canvas), each sits in its slot, and same-slot edges are flush, across a viewport-width sweep, emitting structured `{severity, element, message, fix}` diagnostics and exiting 0/1. The same audit is importable as `auditLayout(page)` for your own Playwright suite. Full guide: [docs/testing.md](docs/testing.md).
 
 ## 3D
 
@@ -223,8 +256,8 @@ Plus `OmMap.snapshotIR(html)` to lock down what a manifest *means* in a snapshot
 
 - **`OmMap.*`** — `validate`, `snapshotIR`, `registerLayer`, `registerWidget`, `registerAction`, `registerSource`, `registerFormat`, `registerBasemap`, `configureBasemap`, `configureData`, `configureTelemetry`, `configureLicense`, `getLayerSchema`
 - **`@nika-js/onlymap/deck`** — the bundled deck.gl classes (`CompositeLayer`, `TileLayer`, …) for building custom layer types: shims must extend the same class hierarchy the core renders with, not a second installed deck.gl copy. Recipe: [docs/custom-layers.md](docs/custom-layers.md)
-- **On a `<om-map>` element** — `ready` (promise), `flyTo(coords, zoom?)`, `setLayerVisible(id, bool)`, `getLayers()`, `emit(action, payload)`, `snapshot(opts?)` (canvas-only PNG of basemap + layers at device pixels — DOM widgets/overlays and provider attribution are NOT captured, so exports must render credits themselves; `{as: "blob"}` for files, default dataURL); the `om-view-changed` event fires once the camera settles (debounced; `detail` = `{longitude, latitude, zoom, pitch, bearing, origin}`, where `origin` is `"user"` for gesture-driven bursts vs `"programmatic"` for API/story moves — the echo-suppression signal for state sync) — the camera-persistence hook; `document.querySelector("om-map")` is fully typed
-- **`MapController`** — the framework-grade programmatic front-end (typed `LayerDescriptor`s → the same reconcile core, no DOM manifest): `setLayers`, `watch`, `emit`, camera methods, `injectPick`, `ready`, `snapshot`, an `onViewChange(view, origin)` option (the `om-view-changed` twin). The React adapter rides it; usable directly from vanilla TS or other frameworks
+- **On a `<om-map>` element** — `ready` (promise), `flyTo(coords, zoom?)`, `setLayerVisible(id, bool)`, `getLayers()`, `emit(action, payload)`, `snapshot(opts?)` (canvas-only PNG of basemap + layers at device pixels — DOM widgets/overlays and provider attribution are NOT captured, so exports must render credits themselves; `{as: "blob"}` for files, default dataURL); the `om-view-changed` event fires once the camera settles (debounced; `detail` = `{longitude, latitude, zoom, pitch, bearing, origin}`, where `origin` is `"user"` for gesture-driven bursts vs `"programmatic"` for API/story moves — the echo-suppression signal for state sync) — the camera-persistence hook; the `om-map-point` event (`detail = {coordinate: [lng,lat]|null, kind: "click"|"hover"}`) fires on every click/hover with the map coordinate, including empty-map clicks picks discard — the hook for custom capture tools the built-in draw widget doesn't cover; the `om-tileset-load` event (`detail = {layerId, tileset}`) surfaces a `Tile3DLayer`'s live deck `Tileset3D` for tools that need the real tileset (e.g. region export), not the IR; `document.querySelector("om-map")` is fully typed
+- **`MapController`** — the framework-grade programmatic front-end (typed `LayerDescriptor`s → the same reconcile core, no DOM manifest): `setLayers`, `watch`, `emit`, camera methods, `injectPick`, `ready`, `snapshot`, an `onViewChange(view, origin)` option (the `om-view-changed` twin), plus `onMapPoint` / `onTilesetLoad` options (the `om-map-point` / `om-tileset-load` twins). The React adapter rides it; usable directly from vanilla TS or other frameworks
 - **`getStore(token)`** — the external-store contract: per-token `{subscribe, getSnapshot}` stores (`viewport`/`selection`/`layers`/`data:<id>`) with cached immutable plain-data snapshots and `origin` tagging — directly consumable by `useSyncExternalStore` (the React adapter's own hooks ride it), MobX autoruns, Redux listeners, Zustand mirrors. ~20-line integration-tested recipes for Redux Toolkit, MobX/mobx-keystone, Zustand, and Jotai: [docs/external-stores.md](docs/external-stores.md)
 - **Testing** — `mountForTest`, and imports are SSR-safe (importing in Node/jsdom never touches browser globals)
 

package/bin/onlymapjs.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { dirname, extname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const CUSTOM_DATA = "./node_modules/@nika-js/onlymap/onlymapjs.html-data.json";
@@ -9,16 +10,161 @@ const SNIPPET_FILE = "onlymap.code-snippets";
 function usage() {
   console.log(`Usage:
   onlymapjs init [--force]
+  onlymapjs check-layout <manifest.html>
   onlymapjs --help
 
 Commands:
   init       Configure the current project for OnlyMapJS authoring in VS Code.
+  check-layout
+             Load a browser-runnable manifest in isolated headless Chromium,
+             audit real widget geometry at 360/640/768/1024px, and exit 0/1.
 
 Options:
   --force    Overwrite .vscode/${SNIPPET_FILE} if it already exists.
 `);
 }
 
+const MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".geojson": "application/geo+json; charset=utf-8",
+  ".csv": "text/csv; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".wasm": "application/wasm",
+};
+
+function isInside(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${sep}`);
+}
+
+function browserManifestHtml(text) {
+  // A plain static server cannot resolve package bare specifiers. Rewrite
+  // the root OnlyMapJS entry only in the ephemeral response; relative data
+  // and all authored source files keep their original URLs.
+  return text
+    .replaceAll('"@nika-js/onlymap"', '"/__onlymapjs__/dist/onlymapjs.js"')
+    .replaceAll("'@nika-js/onlymap'", "'/__onlymapjs__/dist/onlymapjs.js'")
+    .replaceAll('"@nika-js/onlymap/onlymapjs.css"', '"/__onlymapjs__/dist/onlymapjs.css"')
+    .replaceAll("'@nika-js/onlymap/onlymapjs.css'", "'/__onlymapjs__/dist/onlymapjs.css'");
+}
+
+async function startStaticServer(manifestPath, packageRoot) {
+  const manifestRoot = dirname(manifestPath);
+  const server = createServer((req, res) => {
+    try {
+      const pathname = decodeURIComponent(new URL(req.url ?? "/", "http://127.0.0.1").pathname);
+      let target;
+      let root;
+      let isManifest = false;
+      if (pathname === "/") {
+        target = manifestPath;
+        root = manifestRoot;
+        isManifest = true;
+      } else if (pathname.startsWith("/__onlymapjs__/")) {
+        root = packageRoot;
+        target = resolve(root, pathname.slice("/__onlymapjs__/".length));
+      } else {
+        root = manifestRoot;
+        target = resolve(root, pathname.slice(1));
+      }
+      if (!isInside(root, target) || !existsSync(target) || !statSync(target).isFile()) {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Not found");
+        return;
+      }
+      const type = MIME_TYPES[extname(target).toLowerCase()] ?? "application/octet-stream";
+      const content = readFileSync(target);
+      res.writeHead(200, { "content-type": type, "cache-control": "no-store" });
+      res.end(isManifest ? browserManifestHtml(content.toString("utf8")) : content);
+    } catch (error) {
+      res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+      res.end(error instanceof Error ? error.message : String(error));
+    }
+  });
+  await new Promise((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolveListen);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Could not allocate the local layout-audit server.");
+  return { server, url: `http://127.0.0.1:${address.port}/` };
+}
+
+async function checkLayout(manifestArg) {
+  if (!manifestArg) throw new Error("check-layout needs a manifest HTML path.\nUsage: onlymapjs check-layout <manifest.html>");
+  const manifestPath = resolve(process.cwd(), manifestArg);
+  if (!existsSync(manifestPath) || !statSync(manifestPath).isFile()) {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  if (extname(manifestPath).toLowerCase() !== ".html") {
+    throw new Error(`check-layout expects an .html manifest, received: ${manifestPath}`);
+  }
+
+  let playwright;
+  try {
+    playwright = await import("playwright");
+  } catch (error) {
+    if (error?.code === "ERR_MODULE_NOT_FOUND" || String(error).includes("Cannot find package 'playwright'")) {
+      throw new Error(
+        "check-layout needs Playwright in this project.\n" +
+          "Install it with:\n  npm install --save-dev playwright\n  npx playwright install chromium",
+      );
+    }
+    throw error;
+  }
+
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const { auditLayout } = await import(new URL("../dist/onlymapjs.js", import.meta.url));
+  const { server, url } = await startStaticServer(manifestPath, packageRoot);
+  let browser;
+  try {
+    console.log(`Auditing ${manifestPath}`);
+    console.log("Note: check-layout executes this page's scripts inside an isolated headless Chromium context.");
+    try {
+      browser = await playwright.chromium.launch({ headless: true });
+    } catch (error) {
+      if (String(error).includes("Executable doesn't exist") || String(error).includes("browserType.launch")) {
+        throw new Error(`Chromium is not installed for Playwright.\nRun:\n  npx playwright install chromium\n\n${String(error)}`);
+      }
+      throw error;
+    }
+    const context = await browser.newContext({ serviceWorkers: "block" });
+    const page = await context.newPage();
+    const pageErrors = [];
+    page.on("pageerror", (error) => pageErrors.push(String(error).split("\n")[0]));
+    page.on("console", (msg) => {
+      if (msg.type() === "error") pageErrors.push(msg.text().split("\n")[0]);
+    });
+    await page.goto(url, { waitUntil: "domcontentloaded" });
+    let diagnostics;
+    try {
+      diagnostics = await auditLayout(page);
+    } catch (error) {
+      // The page never produced a map. Its own console/pageerror output is the
+      // real cause — surface it so the failure is self-explaining.
+      const detail = pageErrors.length ? `\nPage errors:\n  ${pageErrors.slice(0, 3).join("\n  ")}` : "";
+      throw new Error(`${error instanceof Error ? error.message : String(error)}${detail}`);
+    }
+    if (diagnostics.length === 0) {
+      console.log("CLEAN: no widget layout problems at 360, 640, 768, or 1024px.");
+      return 0;
+    }
+    for (const diagnostic of diagnostics) console.error(JSON.stringify(diagnostic));
+    console.error(`FAILED: ${diagnostics.length} layout diagnostic(s).`);
+    return diagnostics.some((diagnostic) => diagnostic.severity === "error") ? 1 : 0;
+  } finally {
+    await browser?.close();
+    await new Promise((resolveClose) => server.close(resolveClose));
+  }
+}
+
 function parseJsonc(text) {
   let out = "";
   let inString = false;
@@ -167,16 +313,19 @@ if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   process.exit(0);
 }
 
-const [command, ...rest] = args;
-if (command !== "init") {
-  console.error(`Unknown command: ${command}\n`);
-  usage();
-  process.exit(1);
-}
-
 try {
-  init({ force: rest.includes("--force") });
+  const [command, ...rest] = args;
+  if (command === "init") {
+    init({ force: rest.includes("--force") });
+  } else if (command === "check-layout") {
+    if (rest.length !== 1) throw new Error("Usage: onlymapjs check-layout <manifest.html>");
+    process.exitCode = await checkLayout(rest[0]);
+  } else {
+    console.error(`Unknown command: ${command}\n`);
+    usage();
+    process.exitCode = 1;
+  }
 } catch (err) {
   console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
+  process.exitCode = 1;
 }

package/dist/{LercDecode.es-peqB7bxk.js → LercDecode.es-B49qauXg.js}

@@ -19,7 +19,7 @@ async function v(N = {}) {
   if (n) {
     const { createRequire: I } = await import(
       /*webpackIgnore:true*/
-      "./lerc-DEpGyngt.js"
+      "./lerc-CaQOmDCP.js"
     ).then((g) => g._);
     var O = I(import.meta.url);
   }