@nika-js/onlymap 0.4.6 → 0.5.1

package/README.md

@@ -46,7 +46,7 @@ deck.gl is the best WebGL data-visualization engine there is — and OnlyMapJS i
 |---|---|---|
 | Setup | `new Deck({...})`, canvas + basemap sync wiring | one `<om-map>` element (or `<OmMap>` in React) |
 | State | your reducers/stores drive `setProps` | the manifest **is** the state — edit an attribute, the map reconciles; undo/redo built in |
-| Data loading | fetch + parse + reload yourself | `data="…"` — GeoJSON, CSV, Arrow/GeoArrow, Shapefile, KML, WebSocket streams, polled REST; GeoTIFF/COG rasters via `type="COGLayer"` |
+| Data loading | fetch + parse + reload yourself | `data="…"` — GeoJSON, CSV, Arrow/GeoArrow, Shapefile, KML, CityJSON, WebSocket streams, polled REST, tiled XYZ/vector (`TileLayer`/`MVTLayer`); GeoTIFF/COG rasters via `type="COGLayer"` |
 | Accessors | JS functions + `updateTriggers` bookkeeping | `get-*` expressions; update triggers derived automatically |
 | UI | build legends/popups/filters from scratch | built-in widgets, overlays, behaviors — declarative |
 | Testing | mock WebGL or ship untested | `OmMap.validate`, IR snapshots, headless behavioral harness |
@@ -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 540 unit/behavioral tests and 53 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 595 unit/behavioral tests and 58 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.
 
@@ -79,7 +79,7 @@ A handful of elements, one rule: **attributes are kebab-case versions of deck.gl
 
 | Element | Role |
 |---|---|
-| `<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-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. Give it a height: a custom element is `display:inline` by default, so the library injects a `display:block` default (fills a sized parent, else a 400px floor) to keep a bare map visible, but set an explicit height (`om-map { height: 100vh }`) for real layout — any height you set wins outright, including one below the floor. A map that still collapses warns in the console; `hidden` and `display:none` maps stay hidden and stay quiet. |
 | `<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 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. |
@@ -111,9 +111,11 @@ Built-ins: `scale()` (types: `sequential`, `diverging`, `threshold`, `sqrt`, `lo
 | **CSV / TSV** | `data="./quakes.csv"` | parsed to typed columns (lazy ~48 KB chunk); numbers auto-typed, quoted fields intact |
 | **Shapefile** | `data="./countries.shp"` | geometry + `.dbf` attributes joined into GeoJSON features (sidecars fetched with your auth config) |
 | **KML** | `data="./tour.kml"` | placemarks → GeoJSON features; other formats plug in via `OmMap.registerFormat` |
+| **CityJSON / CityJSONSeq** | `data="./tile.city.json"` + `extruded get-elevation="$roof_height"` | semantic 3D city models (3DBAG, PLATEAU) → extruded footprints with derived `roof_height`/`eaves_height`/`ridge_height`/`roof_area`; national grids reprojected automatically (NL/CH/DE/JP/AT/SG); `.city.jsonl` streams in as it downloads; lazy chunk — see [docs/3d-assets.md](docs/3d-assets.md#semantic-city-models-cityjson) |
 | **GeoTIFF / COG raster** | `<om-layer type="COGLayer" src="./dem.tif" min="0" max="1900" colormap="viridis">` | Cloud-Optimized GeoTIFFs stream tiles by Range request (lazy chunk); min/max restretch + colormap swaps are GPU uniforms, nodata → transparent, legend ramp derives automatically; plain 8-bit RGB COGs need no attributes at all |
 | **WebSocket stream** | `data="wss://feed" key="id" flush="250ms" source="myFormat"` | upsert-by-key, burst coalescing, auto-reconnect; decode any format via `OmMap.registerSource` |
 | **Polled REST snapshot** | `data="/api/fleet.json" refresh="5s"` | full-snapshot replace per poll; outages keep the last good data |
+| **Tiled layer (XYZ / vector)** | `<om-layer type="TileLayer" data="…/{z}/{x}/{y}.png">` or `type="MVTLayer"` | a `{z}/{x}/{y}` `data` template is deck's tile URL — passed through, never fetched as rows; raster `TileLayer` gets a built-in `BitmapLayer` renderer, `MVTLayer` self-renders vector tiles (`get-*` accessors apply to tile features) |
 | **Draw store** | `data="draw:sketch"` | live in-memory GeoJSON feature store written by `<om-widget type="draw" target="sketch">` |
 
 Private endpoints: `OmMap.configureData({ headers, credentials, fetch })` — applied to every fetch including refreshes. Credentials stay out of markup by design. Full guide: [docs/live-data.md](docs/live-data.md).
@@ -263,7 +265,7 @@ Plus `OmMap.snapshotIR(html)` to lock down what a manifest *means* in a snapshot
 
 ## Free tier & licensing
 
-**Non-commercial use is free with attribution** (LICENSE.md §3); commercial use requires a license. Without a license key, maps run on the **free plan**: up to **5 layers** and **25,000 rows per layer** (20 MB per data fetch), with a small "OnlyMap by NIKA. Free for non-commercial use." badge in the corner. Exceeding a limit never breaks the map — the offending layer simply doesn't render, and the validation stream/error panel tells you exactly which limit, why, and how to lift it. Limits apply identically everywhere (including localhost — no dev/prod surprises).
+**Non-commercial use is free with attribution** (LICENSE.md §3); commercial use requires a license. Without a license key, maps run on the **free plan**: up to **5 layers** and **25,000 rows per layer** (20 MB per data fetch), with a small "OnlyMap by NIKA. Free for non-commercial use." badge in the corner. Exceeding a limit never breaks the map. Past the **layer** cap the extra layer simply doesn't render; past the **row** cap the layer renders its first 25,000 rows (an arbitrary subset, in source order) rather than nothing, with a dismissible on-map notice saying the data is partial — so a capped map is still useful to look at without ever pretending it's complete. Either way the validation stream/error panel tells you exactly which limit, why, and how to lift it. Limits apply identically everywhere (including localhost — no dev/prod surprises).
 
 A license key lifts all limits and removes the badge:
 

package/THIRD-PARTY-LICENSES.md

@@ -168,7 +168,7 @@ hand.
 | pbf | 3.3.0 | BSD-3-Clause |
 | potpack | 2.1.0 | ISC |
 | process-nextick-args | 2.0.1 | MIT |
-| proj4 | 2.6.2 | MIT |
+| proj4 | 2.20.9 | MIT |
 | protocol-buffers-schema | 3.6.1 | MIT |
 | quickselect | 3.0.0 | ISC |
 | readable-stream | 2.3.8 | MIT |
@@ -7210,7 +7210,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.**
 ```
 
-## proj4@2.6.2 (MIT)
+## proj4@2.20.9 (MIT)
 
 ```
 ## Proj4js -- Javascript reprojection library. 

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

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

package/dist/{basemap-nJ_ODY7r.js → basemap-7GQL0KSL.js}

@@ -1,4 +1,4 @@
-import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-DSkgI4Oc.js";
+import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-ppCRU8Eb.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, Q = 0) {
   const me = Math.min(180, Pe) * Cd;

package/dist/cityjson-urQeujQv.js

@@ -0,0 +1,407 @@
+function P(t, e) {
+  if (!Array.isArray(t)) return [];
+  const n = e?.scale?.[0] ?? 1, o = e?.scale?.[1] ?? 1, s = e?.scale?.[2] ?? 1, a = e?.translate?.[0] ?? 0, i = e?.translate?.[1] ?? 0, c = e?.translate?.[2] ?? 0, r = new Array(t.length);
+  for (let f = 0; f < t.length; f++) {
+    const l = t[f];
+    r[f] = [l[0] * n + a, l[1] * o + i, (l[2] ?? 0) * s + c];
+  }
+  return r;
+}
+const T = {
+  MultiPoint: 1,
+  MultiLineString: 2,
+  MultiSurface: 3,
+  CompositeSurface: 3,
+  Solid: 4,
+  MultiSolid: 5,
+  CompositeSolid: 5
+};
+function J(t, e) {
+  let n = t;
+  for (let o = 0; o < e; o++) n = n.flat();
+  return n;
+}
+function A(t) {
+  const e = T[t.type ?? ""];
+  return !e || e < 3 || !Array.isArray(t.boundaries) ? [] : J(t.boundaries, e - 3);
+}
+function X(t, e) {
+  const n = new Array(e).fill(void 0), o = T[t.type ?? ""], s = t.semantics?.surfaces, a = t.semantics?.values;
+  if (!o || !Array.isArray(s) || !Array.isArray(a)) return n;
+  const i = J(a, o - 3);
+  for (let c = 0; c < e; c++) {
+    const r = i[c];
+    typeof r == "number" && (n[c] = s[r]?.type);
+  }
+  return n;
+}
+function L(t) {
+  const e = typeof t == "number" ? t : Number.parseFloat(String(t ?? ""));
+  return Number.isFinite(e) ? e : -1;
+}
+function q(t, e) {
+  if (!Array.isArray(t)) return;
+  const n = t.filter((o) => A(o).length > 0);
+  if (n.length !== 0) {
+    if (e !== void 0) {
+      const o = n.find((s) => L(s.lod) === e);
+      if (o) return o;
+    }
+    return n.reduce((o, s) => L(s.lod) > L(o.lod) ? s : o);
+  }
+}
+const K = {
+  7415: 28992,
+  // Amersfoort / RD New + NAP height — the 3DBAG default
+  6697: 6668,
+  // JGD2011 geographic 3D + height — the PLATEAU default
+  5555: 25832,
+  // ETRS89 / UTM 32N + DHHN92 height
+  5556: 25833
+  // ETRS89 / UTM 33N + DHHN92 height
+}, G = [
+  [33, 129.5],
+  [33, 131],
+  [36, 132.166666666667],
+  [33, 133.5],
+  [36, 134.333333333333],
+  [36, 136],
+  [36, 137.166666666667],
+  [36, 138.5],
+  [36, 139.833333333333],
+  [40, 140.833333333333],
+  [44, 140.25],
+  [44, 142.25],
+  [44, 144.25],
+  [26, 142],
+  [26, 127.5],
+  [26, 124],
+  [26, 131],
+  [20, 136],
+  [26, 154]
+], j = {
+  // Netherlands — Amersfoort / RD New (3DBAG).
+  28992: {
+    def: "+proj=sterea +lat_0=52.1561605555556 +lon_0=5.38763888888889 +k=0.9999079 +x_0=155000 +y_0=463000 +ellps=bessel +towgs84=565.4171,50.3319,465.5524,-0.398957,0.343988,-1.8774,4.0725 +units=m +no_defs"
+  },
+  // Switzerland — CH1903+ / LV95.
+  2056: {
+    def: "+proj=somerc +lat_0=46.9524055555556 +lon_0=7.43958333333333 +k_0=1 +x_0=2600000 +y_0=1200000 +ellps=bessel +towgs84=674.374,15.056,405.346,0,0,0,0 +units=m +no_defs"
+  },
+  // Germany — ETRS89 / UTM zones 32N and 33N.
+  25832: { def: "+proj=utm +zone=32 +ellps=GRS80 +units=m +no_defs" },
+  25833: { def: "+proj=utm +zone=33 +ellps=GRS80 +units=m +no_defs" },
+  // Plain WGS84 UTM zones 32N/33N (EPSG:326xx) — the generic, non-European-specific
+  // code many CityJSON files declare instead of the ETRS89 pair above (e.g.
+  // Ingolstadt's own open-data LoD3 export). Numerically near-identical to
+  // 25832/25833 at map-rendering precision (WGS84 vs. ETRS89 differ by ~cm in
+  // Europe), so no +towgs84 shift is needed — same bare projection string.
+  32632: { def: "+proj=utm +zone=32 +datum=WGS84 +units=m +no_defs" },
+  32633: { def: "+proj=utm +zone=33 +datum=WGS84 +units=m +no_defs" },
+  // Austria — MGI / Austria GK West/Central/East (the national cadastral
+  // system's three meridian-strip zones; Vienna sits in GK East). Same
+  // Bessel ellipsoid + towgs84 shift and y_0=-5,000,000 false-northing
+  // convention across all three — proj4 strings verified against epsg.io,
+  // not hand-derived, and cross-checked by reprojecting a real Vienna
+  // open-data file's own extent and confirming it lands in Vienna.
+  31254: { def: "+proj=tmerc +lat_0=0 +lon_0=10.3333333333333 +k=1 +x_0=0 +y_0=-5000000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232 +units=m +no_defs" },
+  31255: { def: "+proj=tmerc +lat_0=0 +lon_0=13.3333333333333 +k=1 +x_0=0 +y_0=-5000000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232 +units=m +no_defs" },
+  31256: { def: "+proj=tmerc +lat_0=0 +lon_0=16.3333333333333 +k=1 +x_0=0 +y_0=-5000000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232 +units=m +no_defs" },
+  // Singapore — SVY21 / Singapore TM (the national grid; NUS's own Singapore
+  // HDB buildings dataset declares this via metadata.referenceSystem
+  // directly, unlike the Austria/3DBAG files, which had none). proj4 string
+  // verified against epsg.io, cross-checked by reprojecting a real dataset's
+  // own extent and confirming it lands in Singapore (103.68-103.99°E,
+  // 1.27-1.46°N — matches).
+  3414: { def: "+proj=tmerc +lat_0=1.36666666666667 +lon_0=103.833333333333 +k=1 +x_0=28001.642 +y_0=38744.572 +ellps=WGS84 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs" },
+  // Japan — JGD2011 geographic 2D. EPSG axis order is (lat, lon).
+  6668: { def: "+proj=longlat +ellps=GRS80 +no_defs", geographic: !0, swapXY: !0 },
+  // WGS 84. Files in the wild store lon/lat despite EPSG's formal (lat, lon).
+  4326: { def: "+proj=longlat +datum=WGS84 +no_defs", geographic: !0 },
+  3857: { def: "+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +y_0=0 +k=1 +units=m +nadgrids=@null +no_defs" }
+};
+for (let t = 0; t < G.length; t++) {
+  const [e, n] = G[t];
+  j[6669 + t] = {
+    def: `+proj=tmerc +lat_0=${e} +lon_0=${n} +k=0.9999 +x_0=0 +y_0=0 +ellps=GRS80 +units=m +no_defs`,
+    swapXY: !0
+  };
+}
+const Q = /EPSG.*?(\d{4,6})\D*$/i;
+function ee(t) {
+  if (!t) return;
+  const e = Number(Q.exec(t)?.[1]);
+  return Number.isFinite(e) ? e : void 0;
+}
+let x = !1;
+async function k(t, e) {
+  const n = { toLngLat: (r, f) => [r, f], projected: !1 }, o = ee(t);
+  if (o === void 0)
+    return x || (x = !0, console.warn(
+      `[onlymapjs] data="${e}": CityJSON has no metadata.referenceSystem — assuming coordinates are already WGS84 lon/lat. Add a referenceSystem to the file if they are not.`
+    )), n;
+  const s = K[o] ?? o, a = j[s];
+  if (!a)
+    throw new Error(
+      `CityJSON declares EPSG:${o}${s === o ? "" : ` (horizontal component EPSG:${s})`}, which is not one of the bundled coordinate systems (${Object.keys(j).join(", ")}). Reproject the file to EPSG:4326 server-side (cjio --reproject 4326), or claim the URL with OmMap.registerFormat() and supply your own projection.`
+    );
+  if (a.geographic)
+    return a.swapXY ? { toLngLat: (r, f) => [f, r], projected: !1 } : n;
+  const i = (await import("./index-CW1n5LdO.js")).default, c = i(a.def, "+proj=longlat +datum=WGS84 +no_defs");
+  return {
+    toLngLat: (r, f) => {
+      const [l, p] = c.forward(a.swapXY ? [f, r] : [r, f]);
+      return [l, p];
+    },
+    projected: !0
+  };
+}
+function F(t) {
+  let e = 0, n = 0, o = 0;
+  for (let s = 0; s < t.length; s++) {
+    const a = t[s], i = t[(s + 1) % t.length];
+    e += (a[1] - i[1]) * (a[2] + i[2]), n += (a[2] - i[2]) * (a[0] + i[0]), o += (a[0] - i[0]) * (a[1] + i[1]);
+  }
+  return Math.hypot(e, n, o) / 2;
+}
+function te(t) {
+  const e = t.slice().sort((o, s) => o - s), n = e.length >> 1;
+  return e.length % 2 ? e[n] : (e[n - 1] + e[n]) / 2;
+}
+function U(t, e, n, o, s) {
+  const a = q(e.geometry, s);
+  if (!a) return;
+  const i = A(a);
+  if (i.length === 0) return;
+  const c = X(a, i.length), r = i.map(
+    (d) => d.map((m) => m.map((u) => n[u]).filter((u) => u !== void 0))
+  );
+  let f = 1 / 0, l = -1 / 0;
+  for (const d of r)
+    for (const m of d)
+      for (const [, , u] of m)
+        u < f && (f = u), u > l && (l = u);
+  if (!Number.isFinite(f)) return;
+  const p = f, g = c.some((d) => d === "RoofSurface"), y = [];
+  let _ = 1 / 0, h = -1 / 0;
+  for (let d = 0; d < r.length; d++)
+    if (!(g && c[d] !== "RoofSurface"))
+      for (const m of r[d])
+        for (const [, , u] of m)
+          (g || u > p + 0.5) && (y.push(u), u < _ && (_ = u), u > h && (h = u));
+  y.length === 0 && (y.push(l), _ = l, h = l);
+  let S = c.indexOf("GroundSurface");
+  if (S < 0) {
+    let d = -1;
+    for (let m = 0; m < r.length; m++) {
+      const u = r[m][0];
+      if (!u || u.length < 3) continue;
+      const b = u.every(([, , v]) => v <= p + 0.5), w = F(u) * (b ? 1e3 : 1);
+      w > d && (d = w, S = m);
+    }
+  }
+  if (S < 0) return;
+  const O = r[S];
+  if (!O[0] || O[0].length < 3) return;
+  const [, B] = o.toLngLat(O[0][0][0], O[0][0][1]), Z = 111320 * Math.cos(B * Math.PI / 180), W = 110540, Y = (d) => o.projected ? d : d.map(([m, u, b]) => {
+    const [w, v] = o.toLngLat(m, u);
+    return [w * Z, v * W, b];
+  });
+  let R = 0, E = 0;
+  for (let d = 0; d < r.length; d++) {
+    if (g && c[d] !== "RoofSurface") continue;
+    const m = r[d][0];
+    if (!m || m.length < 3) continue;
+    const u = F(Y(m));
+    R += u, E += u * (m.reduce((b, [, , w]) => b + w, 0) / m.length);
+  }
+  const V = R > 0 ? E / R : te(y), H = {
+    cityobject_id: t,
+    cityobject_type: e.type ?? "Unknown",
+    ...e.parents?.[0] !== void 0 ? { parent_id: e.parents[0] } : {},
+    ...a.lod !== void 0 ? { lod: String(a.lod) } : {},
+    ground_height: C(p),
+    roof_height: C(V - p),
+    eaves_height: C(_ - p),
+    ridge_height: C(h - p),
+    roof_area: C(R),
+    surface_count: i.length
+  };
+  return { faceRings: r, semantics: c, footprintIndex: S, derived: H };
+}
+function ne(t, e, n, o, s, a) {
+  const i = U(t, e, n, o, a);
+  if (!i) return;
+  const r = i.faceRings[i.footprintIndex].filter((f) => f.length >= 3).map((f) => {
+    const l = f.map(([p, g]) => o.toLngLat(p, g));
+    return l.push(l[0]), l;
+  });
+  return {
+    type: "Feature",
+    id: t,
+    geometry: { type: "Polygon", coordinates: r },
+    // Source attributes first: the derived names are the ones manifests bind
+    // to, so they must be deterministic even against a same-named source field.
+    properties: { ...s, ...e.attributes, ...i.derived }
+  };
+}
+const I = {
+  GroundSurface: "#999999",
+  WallSurface: "#ffffff",
+  RoofSurface: "#ff0000",
+  TrafficArea: "#6e6e6e",
+  AuxiliaryTrafficArea: "#2c8200",
+  Window: "#0059ff",
+  Door: "#640000"
+}, M = {
+  Building: "#7497df",
+  BuildingPart: "#7497df",
+  BuildingInstallation: "#7497df",
+  Bridge: "#999999",
+  BridgePart: "#999999",
+  BridgeInstallation: "#999999",
+  BridgeConstructiveElement: "#999999",
+  CityObjectGroup: "#ffffb3",
+  LandUse: "#ffffb3",
+  CityFurniture: "#cc0000",
+  GenericCityObject: "#cc0000",
+  PlantCover: "#39ac39",
+  SolitaryVegetationObject: "#39ac39",
+  Railway: "#000000",
+  Road: "#999999",
+  TransportSquare: "#999999",
+  TINRelief: "#ffdb99",
+  Tunnel: "#999999",
+  TunnelPart: "#999999",
+  TunnelInstallation: "#999999",
+  WaterBody: "#4da6ff"
+}, oe = "#b0b0b0";
+function re(t, e) {
+  return t && I[t] ? I[t] : e && M[e] ? M[e] : oe;
+}
+function ie(t, e, n, o, s, a) {
+  const i = U(t, e, n, o, a);
+  if (!i) return [];
+  const c = [];
+  for (let r = 0; r < i.faceRings.length; r++) {
+    const f = i.faceRings[r], l = f[0];
+    if (!l || l.length < 3) continue;
+    const p = f.filter((y) => y.length >= 3).map((y) => y.map(([_, h, S]) => [...o.toLngLat(_, h), S])), g = p[0];
+    c.push({
+      ...s,
+      ...e.attributes,
+      ...i.derived,
+      surface_type: i.semantics[r],
+      fill_color: re(i.semantics[r], e.type),
+      polygon: p,
+      outline: [...g, g[0]]
+    });
+  }
+  return c;
+}
+function C(t) {
+  return Number.isFinite(t) ? Math.round(t * 1e3) / 1e3 : 0;
+}
+function D(t, e, n, o, s = "footprint") {
+  if (!t) return [];
+  const a = (c) => Array.isArray(c.children) && c.children.some((r) => {
+    const f = t[r];
+    return f?.type === `${c.type}Part` && (f.geometry?.some((l) => A(l).length > 0) ?? !1);
+  }), i = [];
+  for (const [c, r] of Object.entries(t)) {
+    if (!r || typeof r != "object" || a(r)) continue;
+    const l = (r.parents?.[0] ? t[r.parents[0]] : void 0)?.attributes ?? {};
+    if (s === "surfaces")
+      i.push(...ie(c, r, e, n, l, o));
+    else {
+      const p = ne(c, r, e, n, l, o);
+      p && i.push(p);
+    }
+  }
+  return i;
+}
+function N(t, e, n) {
+  if (t?.type !== n)
+    throw new Error(
+      `expected a ${n} object but found type="${t?.type ?? "undefined"}" — this does not look like CityJSON. If it is a different newline-delimited format, claim the URL with OmMap.registerFormat().`
+    );
+}
+function $(t) {
+  const e = /[?&]om-lod=([^&#]+)/.exec(t)?.[1];
+  if (e === void 0) return;
+  const n = Number.parseFloat(decodeURIComponent(e));
+  if (!Number.isFinite(n)) {
+    console.warn(`[onlymapjs] om-lod="${e}" is not a number — ignoring and using the highest available LoD.`);
+    return;
+  }
+  return n;
+}
+function z(t) {
+  const e = /[?&]om-surfaces=([^&#]+)/.exec(t)?.[1];
+  if (e === void 0) return !1;
+  const n = decodeURIComponent(e).toLowerCase();
+  return n === "1" || n === "true";
+}
+async function ce(t, e) {
+  const n = await t.json();
+  N(n, e, "CityJSON");
+  const o = await k(n.metadata?.referenceSystem, e), s = P(n.vertices, n.transform), a = z(e) ? "surfaces" : "footprint";
+  return D(n.CityObjects, s, o, $(e), a);
+}
+const se = 250, ae = 512;
+async function* fe(t) {
+  if (!t.body) {
+    for (const s of (await t.text()).split(`
+`)) yield s;
+    return;
+  }
+  const e = t.body.getReader(), n = new TextDecoder();
+  let o = "";
+  for (; ; ) {
+    const { done: s, value: a } = await e.read();
+    if (s) break;
+    o += n.decode(a, { stream: !0 });
+    let i;
+    for (; (i = o.indexOf(`
+`)) >= 0; )
+      yield o.slice(0, i), o = o.slice(i + 1);
+  }
+  o += n.decode(), o.length > 0 && (yield o);
+}
+async function le(t, e, n) {
+  const o = $(e), s = z(e) ? "surfaces" : "footprint";
+  let a, i, c = !1;
+  const r = [];
+  let f = 0, l = 0;
+  for await (const p of fe(t)) {
+    const g = p.trim();
+    if (g.length === 0) continue;
+    const y = JSON.parse(g);
+    if (c)
+      N(y, e, "CityJSONFeature");
+    else if (N(y, e, "CityJSON"), i = y.transform, a = await k(y.metadata?.referenceSystem, e), c = !0, y.CityObjects && Object.keys(y.CityObjects).length === 0) continue;
+    const _ = P(y.vertices, i);
+    r.push(...D(y.CityObjects, _, a, o, s)), f++;
+    const h = performance.now();
+    (f >= ae || h - l >= se) && (f = 0, l = h, n(r.slice()));
+  }
+  if (!c)
+    throw new Error(
+      'CityJSONSeq file is empty or has no header line — the first line must be a CityJSON object carrying "transform" and "metadata", followed by one CityJSONFeature per line.'
+    );
+  return r;
+}
+export {
+  q as chooseGeometry,
+  D as decodeCityObjects,
+  P as decompressVertices,
+  re as defaultFillColor,
+  X as faceSemantics,
+  A as flattenToFaces,
+  ce as parseCityJsonDocument,
+  le as parseCityJsonSeq,
+  ee as parseEpsgCode,
+  $ as parseLodPin,
+  z as parseSurfacesFlag,
+  k as resolveCrs
+};

package/dist/cityjson.d.ts

@@ -0,0 +1,138 @@
+/**
+ * CityJSON / CityJSONSeq ingestion (spec: "CityJSON ingestion"; issue #25).
+ *
+ * A LAZY chunk — reached only through `CITYJSON_FORMAT`'s dynamic import in
+ * data-layer.ts, so neither this decoder nor proj4 weighs on the eager
+ * bundle (the src/raster.ts precedent). proj4 itself is imported lazily
+ * AGAIN inside `resolveCrs`, so a file already in lon/lat never pays for it.
+ *
+ * Two output shapes share one geometry computation (`computeCityObjectGeometry`):
+ *
+ *  - DEFAULT — one GeoJSON `Feature` per CityObject: a 2D footprint polygon
+ *    plus DERIVED height properties, rendered through GeoJsonLayer's
+ *    `extruded` + `get-elevation`. Lit, pickable, GPU-filterable,
+ *    terrain-aware — and, because extrusion is a flat-topped prism, it
+ *    cannot draw the actual shape of a pitched/hipped LoD2.2 roof no matter
+ *    how accurate the derived height is.
+ *  - `?om-surfaces=1` — one flat row PER FACE (wall, roof, ground), each
+ *    carrying its real 3D ring coordinates (real per-vertex height, not a
+ *    uniform extrusion) for `SolidPolygonLayer` with `extruded="false"` and
+ *    `full3d`. This draws the true reconstructed shape. The tradeoff: deck's
+ *    solid-polygon vertex shader computes lighting only inside its
+ *    `if (solidPolygon.extruded)` branch (verified against
+ *    solid-polygon-layer-vertex-main.glsl.js), so this path is unavoidably
+ *    unlit — flat per-face fill color, no shading from surface orientation.
+ *    `_full3d` is what makes near-vertical wall polygons triangulate at all:
+ *    without it earcut works in the flat xy plane, where a wall's projected
+ *    area is ~zero and the face silently vanishes.
+ *
+ * Semantics are not discarded in either mode: they drive which vertices
+ * count as roof (so the derived heights are real roof heights, not
+ * bounding-box heights) and survive as a `surface_type` per-face property in
+ * surfaces mode.
+ */
+/** [x, y, z] in the source CRS — decompressed, not yet reprojected. */
+type Vec3 = [number, number, number];
+/** A face is a list of rings; ring[0] is the outer boundary, the rest are holes. */
+type Face = number[][];
+interface CityJsonTransform {
+    scale?: number[];
+    translate?: number[];
+}
+interface CityJsonSemantics {
+    surfaces?: {
+        type?: string;
+    }[];
+    values?: unknown;
+}
+interface CityJsonGeometry {
+    type?: string;
+    lod?: string | number;
+    boundaries?: unknown;
+    semantics?: CityJsonSemantics;
+}
+interface CityObject {
+    type?: string;
+    attributes?: Record<string, unknown>;
+    geometry?: CityJsonGeometry[];
+    parents?: string[];
+    children?: string[];
+}
+export declare function decompressVertices(vertices: number[][] | undefined, transform: CityJsonTransform | undefined): Vec3[];
+/**
+ * Geometry → flat face list. Surface-less geometry types (points, lines) and
+ * anything unrecognized yield no faces, so the CityObject is skipped rather
+ * than emitted with a broken footprint.
+ */
+export declare function flattenToFaces(geometry: CityJsonGeometry): Face[];
+/** One semantic surface type per face (`"RoofSurface"`, …), aligned by index. */
+export declare function faceSemantics(geometry: CityJsonGeometry, faceCount: number): (string | undefined)[];
+/**
+ * Highest-LoD geometry that actually has surfaces. Higher LoD wins even though
+ * the output is an extrusion: an LoD2 solid carries real roof vertices and
+ * semantics, so its derived heights beat LoD1's single stated height.
+ * `?om-lod=` pins a specific one (see `parseCityJsonDocument`).
+ */
+export declare function chooseGeometry(geometries: CityJsonGeometry[] | undefined, lodPin?: number): CityJsonGeometry | undefined;
+/** `"https://www.opengis.net/def/crs/EPSG/0/7415"` / `"urn:ogc:def:crs:EPSG::7415"` / `"EPSG:7415"` → 7415. */
+export declare function parseEpsgCode(referenceSystem: string | undefined): number | undefined;
+/** Source [x, y] → WGS84 [lon, lat]. */
+export interface CrsAdapter {
+    toLngLat(x: number, y: number): [number, number];
+    /**
+     * True when source coordinates are already metres (a projected grid), so
+     * horizontal areas can be measured on them directly. Geographic sources are
+     * in degrees and need a local metric frame first — see `buildFeature`.
+     */
+    projected: boolean;
+}
+/**
+ * Build the reprojection adapter for a document. An unsupported EPSG code
+ * throws rather than silently misplacing a whole city — the failure surfaces
+ * through the Data Layer's own `Failed to fetch data="…"` path, the same as
+ * any other format error.
+ */
+export declare function resolveCrs(referenceSystem: string | undefined, url: string): Promise<CrsAdapter>;
+/** Derived property names. Documented as reserved — they win over same-named source attributes. */
+export interface DerivedProperties {
+    cityobject_id: string;
+    cityobject_type: string;
+    parent_id?: string;
+    lod?: string;
+    ground_height: number;
+    roof_height: number;
+    eaves_height: number;
+    ridge_height: number;
+    roof_area: number;
+    surface_count: number;
+}
+export declare function defaultFillColor(surfaceType: string | undefined, cityObjectType: string | undefined): string;
+/**
+ * CityObjects → features (default) or per-face surface rows (`mode:
+ * "surfaces"`, see `parseSurfacesFlag`). Geometry usually hangs off child
+ * objects (`BuildingPart`, `BridgePart`), so a parent's attributes are
+ * inherited by its children — the child's own values win, and `parent_id`
+ * keeps the hierarchy walkable for selection.
+ */
+export declare function decodeCityObjects(cityObjects: Record<string, CityObject> | undefined, vertices: Vec3[], crs: CrsAdapter, lodPin: number | undefined, mode?: "footprint" | "surfaces"): unknown[];
+/** `?om-lod=1.2` → 1.2. The DataFormat contract sees only the URL, so this is the option channel. */
+export declare function parseLodPin(url: string): number | undefined;
+/**
+ * `?om-surfaces=1` → per-face `SolidPolygonLayer` rows instead of the default
+ * footprint-extrusion `GeoJsonLayer` Features. Same option-channel idiom as
+ * `om-lod` — and the same URL-keyed cache benefit: a plain URL and its
+ * `?om-surfaces=1` counterpart parse and cache independently, so one manifest
+ * can point a `GeoJsonLayer` at one and a `SolidPolygonLayer` at the other.
+ */
+export declare function parseSurfacesFlag(url: string): boolean;
+/** A whole `.city.json` document. One JSON parse — a single JSON value has no incremental path. */
+export declare function parseCityJsonDocument(res: Response, url: string): Promise<unknown[]>;
+/**
+ * Streaming `.city.jsonl`. `push` hands the Data Layer a fresh array reference
+ * every batch so deck.gl's shallow `data` diff fires and the city fills in as
+ * it downloads; the returned array is the complete set.
+ */
+export declare function parseCityJsonSeq(res: Response, url: string, push: (features: unknown[]) => void): Promise<unknown[]>;
+/** Test hook — resets the once-per-page missing-CRS warning. */
+export declare function resetCityJsonWarningsForTests(): void;
+export {};

package/dist/data-layer.d.ts

@@ -70,6 +70,16 @@ export interface DataFormat {
     match(url: string, contentType?: string): boolean;
     /** Parse the claimed response. The parser module should be lazy-imported here (HU1 — the apache-arrow precedent). `url` is the requested URL (res.url is empty on constructed Responses — test fetches, service workers). */
     parse(res: Response, url: string): Promise<LayerData>;
+    /**
+     * Optional progressive variant for record-per-line formats (CityJSONSeq):
+     * `push` publishes a partial snapshot mid-download, taking the same
+     * cache-swap + notify path a stream flush takes, so the map fills in as
+     * bytes arrive instead of staying empty until EOF. Pass a FRESH array
+     * reference each time — deck.gl diffs `data` by identity. When present this
+     * is used instead of `parse`; the returned value is the complete dataset.
+     * `push` is a no-op during a `refresh` re-fetch — see getData for why.
+     */
+    parseIncremental?(res: Response, url: string, push: (partial: LayerData) => void): Promise<LayerData>;
 }
 /**
  * Row objects → ColumnarData (the memory-efficient shape: one array per
@@ -119,6 +129,17 @@ export interface DataRequestConfig {
 export declare function configureData(config: DataRequestConfig): void;
 /** `data="draw:sketch"` — the reserved scheme for a widget-fed sketch layer (never collides with http/ws/inline). */
 export declare function isDrawUrl(url: string): boolean;
+/**
+ * A tile URL template (spec: "Tiled layers"). deck's `TileLayer`/`MVTLayer`
+ * (and any `TileLayer` subclass) take their `data` prop as a `{z}/{x}/{y}`
+ * template STRING — a template deck expands per tile, NOT a document to fetch
+ * and parse into rows. OnlyMapJS otherwise routes every `data` attribute
+ * through getData() (fetch → parse), so a template would be fetched literally
+ * (`…/{z}/{x}/{y}.png`) and 404; this classifier lets the parser pass it
+ * through to deck untouched instead. Same `{z}/{x}/{y}` convention terrain and
+ * basemap tile URLs already use.
+ */
+export declare function isTileTemplateUrl(url: string): boolean;
 /**
  * Push a new sketch snapshot into a `draw:<name>` store (the draw widget's
  * DrawSession.onChange calls this). A FRESH array reference is stored so