@nika-js/onlymap 0.7.6 → 0.8.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.7.6",
-  "description": "Declarative deck.gl maps for HTML and React — interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
+  "version": "0.8.1",
+  "description": "Declarative deck.gl maps for HTML and React \u2014 interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
     "access": "public"
@@ -74,6 +74,17 @@
       "import": "./dist/onlymap.standalone.js",
       "default": "./dist/onlymap.standalone.js"
     },
+    "./cartograph": {
+      "types": "./dist/cartograph/index.d.ts",
+      "import": "./dist/cartograph.js",
+      "default": "./dist/cartograph.js"
+    },
+    "./cartograph/standalone": {
+      "types": "./dist/cartograph/standalone.d.ts",
+      "import": "./dist/cartograph.standalone.js",
+      "default": "./dist/cartograph.standalone.js"
+    },
+    "./cartograph.css": "./dist/cartograph.css",
     "./onlymapjs.css": "./dist/onlymapjs.css",
     "./style.css": "./dist/style.css",
     "./onlymapjs.html-data.json": "./onlymapjs.html-data.json",
@@ -108,11 +119,11 @@
   ],
   "scripts": {
     "dev": "vite",
-    "build": "npm run typecheck && npm run gen:licenses && vite build && vite build --config vite.react.config.ts && vite build --config vite.deck.config.ts && vite build --config vite.standalone.config.ts && node dev/assert-bundle-cdn-safe.mjs && npm run build:types",
+    "build": "npm run typecheck && npm run gen:licenses && vite build && vite build --config vite.react.config.ts && vite build --config vite.deck.config.ts && vite build --config vite.standalone.config.ts && vite build --config vite.cartograph.config.ts && vite build --config vite.cartograph-standalone.config.ts && node dev/assert-bundle-cdn-safe.mjs && npm run build:types",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.e2e.json --noEmit && tsc -p cloud/workers/telemetry/tsconfig.json && tsc -p cloud/workers/examples/tsconfig.json",
     "test": "vitest run",
-    "comment:e2e-smoke": "Release gate for rendered-pixel guarantees the unit suite can't see: the license-condition badge chrome (a red badge e2e shipped across 0.6.24 AND 0.6.25 because only vitest gated publish) and frame determinism. Deliberately tiny — the full e2e suite stays a manual/CI concern.",
+    "comment:e2e-smoke": "Release gate for rendered-pixel guarantees the unit suite can't see: the license-condition badge chrome (a red badge e2e shipped across 0.6.24 AND 0.6.25 because only vitest gated publish) and frame determinism. Deliberately tiny \u2014 the full e2e suite stays a manual/CI concern.",
     "test:e2e:smoke": "playwright test e2e/deterministic-frames.spec.ts && playwright test e2e/examples.spec.ts -g \"attribution badge\"",
     "prepublishOnly": "node dev/tools/announce-release.mjs --check && npm run build && npm run test:e2e:smoke",
     "postpublish": "node dev/tools/announce-release.mjs",
@@ -131,7 +142,7 @@
     "dev:examples": "wrangler dev --config cloud/workers/examples/wrangler.toml",
     "gen:licenses": "node dev/gen-third-party-licenses.mjs"
   },
-  "comment:deps": "This library ships a fully self-contained bundle in dist/ (verified: zero external bare imports), so it has NO runtime dependencies — deck.gl, loaders.gl, MapLibre, Arrow, d3, acorn, etc. are build-time-only and get bundled by Vite. Keeping them here (not in dependencies) is what stops every consumer install from pulling ~250 MB it never uses.",
+  "comment:deps": "This library ships a fully self-contained bundle in dist/ (verified: zero external bare imports), so it has NO runtime dependencies \u2014 deck.gl, loaders.gl, MapLibre, Arrow, d3, acorn, etc. are build-time-only and get bundled by Vite. Keeping them here (not in dependencies) is what stops every consumer install from pulling ~250 MB it never uses.",
   "devDependencies": {
     "@deck.gl/aggregation-layers": "9.3.5",
     "@deck.gl/core": "9.3.5",
@@ -184,5 +195,5 @@
     "ws": "^8.21.0",
     "zustand": "^5.0.14"
   },
-  "comment:deck-pin": "deck.gl/luma.gl devDeps are EXACT pins: they get BUNDLED into dist, and both libraries hard-throw on duplicate-version detection — consumers that also ship their own deck.gl (nika-agent) must match these versions exactly. CONTRACT: the bundled deck.gl/luma.gl version is part of the release surface and only changes at the SemVer boundary a caret does NOT cross — a MAJOR onlymap release (a 0.x MINOR while pre-1.0). Anything a caret floats (minor+patch once >=1.0; patch while 0.x) must NEVER move deck.gl, so a consumer can caret onlymap safely. Bumping deck is a breaking-coordination event, never a side effect of a minor/patch release or a reinstall."
+  "comment:deck-pin": "deck.gl/luma.gl devDeps are EXACT pins: they get BUNDLED into dist, and both libraries hard-throw on duplicate-version detection \u2014 consumers that also ship their own deck.gl (nika-agent) must match these versions exactly. CONTRACT: the bundled deck.gl/luma.gl version is part of the release surface and only changes at the SemVer boundary a caret does NOT cross \u2014 a MAJOR onlymap release (a 0.x MINOR while pre-1.0). Anything a caret floats (minor+patch once >=1.0; patch while 0.x) must NEVER move deck.gl, so a consumer can caret onlymap safely. Bumping deck is a breaking-coordination event, never a side effect of a minor/patch release or a reinstall."
 }

package/skills/onlymapjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onlymapjs
-description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards, or React maps via the @nika-js/onlymap/react adapter. Use when a user asks for an interactive map, deck.gl-style visualization, geospatial dashboard, live fleet/telemetry map, choropleth, popup/tooltip map, map story/tour, manual drawing/sketch map, 3D map assets, a React map component, a map page shared as a single HTML file (incl. no-JS fallbacks for chat/email previews), a responsive/mobile map whose controls auto-fold on narrow screens, auditing a map's widget layout with the check-layout tool, syncing OnlyMapJS map/camera state into an app state store (Redux, MobX, Zustand, Jotai — the getStore contract), BIM/IFC models (loading .ifc files in the browser, 3D Tiles per-element picking, isolate/hide/ghost, clash detection, model federation), routes and directions (a styled A-to-B route line, OSRM or another routing engine, click-to-route), live vehicle/rider/delivery tracking (a moving marker gliding between GPS fixes with a follow camera), a React Native or Expo mobile map (route to the separate @nika-js/onlymap-native package), a Remotion map video or programmatic map flyover with overlays (route to the separate @nika-js/onlymap-remotion package), or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
+description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards, or React maps via the @nika-js/onlymap/react adapter. Use when a user asks for an interactive map, deck.gl-style visualization, geospatial dashboard, live fleet/telemetry map, choropleth, popup/tooltip map, map story/tour, manual drawing/sketch map, 3D map assets, a React map component, a map page shared as a single HTML file (incl. no-JS fallbacks for chat/email previews), a print-ready map sheet / PDF map / atlas (the cartograph entry: mm-based pages, frames, derived legends, scale bars, graticules), a responsive/mobile map whose controls auto-fold on narrow screens, auditing a map's widget layout with the check-layout tool, syncing OnlyMapJS map/camera state into an app state store (Redux, MobX, Zustand, Jotai — the getStore contract), BIM/IFC models (loading .ifc files in the browser, 3D Tiles per-element picking, isolate/hide/ghost, clash detection, model federation), routes and directions (a styled A-to-B route line, OSRM or another routing engine, click-to-route), live vehicle/rider/delivery tracking (a moving marker gliding between GPS fixes with a follow camera), a Remotion map video or programmatic map flyover with overlays (route to the separate @nika-js/onlymap-remotion package), a React Native or Expo mobile map (route to the separate @nika-js/onlymap-native package), or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
 ---
 
 # OnlyMapJS
@@ -23,7 +23,7 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 </script>
 ```
 
-For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.7.5` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.5/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
+For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.8.0` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.8.0/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
 
 ## React Projects
 

package/skills/onlymapjs/references/syntax.md

@@ -16,8 +16,8 @@ Vite/npm project:
 Static CDN page (raw-file CDNs only — unpkg/jsDelivr; never esm.sh or another rebundling CDN, which duplicates the WebGL runtime and breaks layer shaders):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.5/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.7.5"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.8.0/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.8.0"></script>
 ```
 
 Always include `onlymapjs.css` — it carries the MapLibre basemap styles and the no-JS fallback rules (`<om-fallback>` / default banner). For the fallback to work in script-disabled previews it must load without JavaScript: a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages (a bundler-emitted stylesheet is fine in npm projects).
@@ -622,6 +622,31 @@ Example:
 
 
 
+### Cartographs (`@nika-js/onlymap/cartograph` — print layouts)
+
+A separate lazy entry (`import "@nika-js/onlymap/cartograph"`; CDN: `https://unpkg.com/@nika-js/onlymap/dist/cartograph.standalone.js`). Pages are measured in millimetres and print at true size.
+
+```html
+<om-cartograph size="A3" orientation="landscape" title="Parcel survey" dpi="300">
+  <om-text kind="title" x="10" y="8" w="250" h="12">{{title}}</om-text>
+  <om-frame id="main" x="24" y="28" w="236" h="196" center="[103.81, 1.31]" zoom="14.4">
+    <om-map basemap="none">…layers…</om-map>
+  </om-frame>
+  <om-legend for="main" x="270" y="84" w="60" h="62" title="Legend"></om-legend>
+  <om-scalebar for="main" x="10" y="230" w="72" h="10" units="metric"></om-scalebar>
+  <om-north for="main" x="238" y="226" w="16" h="18" kind="rose"></om-north>
+  <om-graticule for="main" x="24" y="28" w="236" h="196" interval="0.005" labels="outside"></om-graticule>
+</om-cartograph>
+```
+
+- Frames: live (`<om-map>` child, the FRAME's camera attributes win) or `mode="static"` with `crs` + `corners` for a georeferenced raster. `overview-of="<frame-id>"` draws a locator footprint.
+- A live frame caps its map's tilt at the steepest pitch the frame's own box can still georeference (past it the top edge reaches the horizon and the frame loses its scale bar, north, graticule and export). The limit rises with zoom and with a wider box; `max-pitch` on `<om-map>` is the same control, settable by hand for a kiosk map.
+- `<om-legend for>` derives rows from the live map's own symbology (classified breaks included); literal rows via `derived="false"` + `<om-legend-row>` children.
+- `<om-atlas for="<frame-id>" layer="<layer-id>">` renders one page per feature sequentially and exports a ZIP.
+- Output: `page.print()` / `?print=1` (PDF at page size), `renderCartograph(page, {dpi})` / `?export=png&dpi=300` (PNG). Press attributes: `bleed`, `crop-marks`, `safe-zone` (screen-only), `flatten`. `cvd="deuteranopia|…"` simulates colour-vision deficiency; `lintLegendColours()` flags collapsing palettes.
+- Free plan injects a small foot credit — suppressed by an authored `om-text` crediting OnlyMap or a paid key on a live frame's map.
+- Deep reference: `docs/cartograph.md`.
+
 ### `<om-fallback>`
 
 Static content shown only where scripts never run — chat-app/email file previews (iOS QuickLook), file managers, sandboxed webviews. Hidden automatically once the map boots. Good practice on every complete page, especially one that may be shared as a file.