@nika-js/onlymap 0.2.3 → 0.3.1

package/dist/scene-lighting.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Scene lighting (spec: "Scene Lighting") — the manifest surface over
+ * deck.gl's LightingEffect, resolving the backlog TODO ("Lighting/effects
+ * manifest surface"). Attributes on <om-map>, the basemap= precedent:
+ * singleton scene state as attributes gets undo/redo for free (attribute
+ * history) and live switching through the same MutationObserver path.
+ *
+ *   <om-map lighting="daylight">
+ *   <om-map lighting="custom" lighting-ambient="0.6" lighting-sun="1.5"
+ *           lighting-sun-azimuth="135" lighting-sun-elevation="45">
+ *   <om-map lighting="daylight" lighting-sun-date="2026-07-15T14:00:00Z">
+ *
+ * The sun is ALWAYS a DirectionalLight driven by azimuth/elevation;
+ * `lighting-sun-date` is sugar that computes az/el from solar position at
+ * the map center when lighting is applied (deliberately NOT deck's
+ * experimental `_SunLight`, which recomputes per frame from the viewport —
+ * an attribute-declared scene should be deterministic, and the underscore
+ * API is upgrade churn). Absent `lighting` = deck's default lights —
+ * today's behavior, so the whole surface is additive.
+ */
+import { AmbientLight, _CameraLight as CameraLight, DirectionalLight, LightingEffect } from "@deck.gl/core";
+export interface LightingIR {
+    /** Preset the values were seeded from (validation/UI echo; "custom" for a fully hand-tuned scene). */
+    preset: LightingPresetName;
+    /** Ambient intensity — always-on fill. */
+    ambient: number;
+    /** Sun (directional) intensity; 0 omits the sun light entirely. */
+    sun: number;
+    /** Sun compass bearing, ° clockwise from north. */
+    sunAzimuth: number;
+    /** Sun height above the horizon, ° (0 = horizon, 90 = zenith). */
+    sunElevation: number;
+    /** Camera-following fill intensity (model inspection); 0 omits it. */
+    camera: number;
+    /** Epoch ms — when set, az/el are recomputed from solar position at apply time. */
+    sunDate?: number;
+}
+export type LightingPresetName = "daylight" | "studio" | "flat" | "custom";
+export declare const LIGHTING_PRESET_NAMES: readonly ["daylight", "studio", "flat", "custom"];
+export declare function isLightingPreset(name: string): name is LightingPresetName;
+/** Programmatic twin of the lighting-* attributes (MapControllerOptions.lighting / setLighting). */
+export interface LightingOptions {
+    preset?: LightingPresetName;
+    ambient?: number;
+    sun?: number;
+    sunAzimuth?: number;
+    sunElevation?: number;
+    camera?: number;
+    /** Epoch ms or ISO 8601 — the lighting-sun-date twin. */
+    sunDate?: number | string;
+}
+/** Preset seeds values; explicit fields override individual seeds; sunDate (resolved at apply time) wins over az/el. */
+export declare function resolveLighting(options: LightingOptions): LightingIR;
+/**
+ * `lighting*` attributes → IR. Returns null when `lighting` itself is
+ * absent (deck default lights; stray lighting-* overrides without it are
+ * inert — validation warns). Malformed numbers fall back to the preset seed
+ * (validation flags them; the live path must still render something).
+ */
+export declare function parseLightingAttrs(getAttr: (name: string) => string | null): LightingIR | null;
+/**
+ * Solar azimuth/elevation at a timestamp + location, in the manual-sun
+ * convention (azimuth ° CW from north, elevation ° above horizon). The
+ * standard suncalc derivation (the same math deck's `_SunLight` uses via
+ * @math.gl/sun): solar azimuth measured south→west, so matching the
+ * DirectionalLight convention is `azimuth = solar + 180°`. Below-horizon
+ * sun clamps to the horizon — a flat scene can't render a sun beneath it.
+ */
+export declare function solarAzElDegrees(timestamp: number, latitude: number, longitude: number): {
+    azimuth: number;
+    elevation: number;
+};
+/**
+ * IR → the named lights map a LightingEffect is constructed from —
+ * separated so tests can assert composition without reaching into
+ * LightingEffect's private fields. The ambient light is always present;
+ * sun and camera lights only at intensity > 0 (deck renders a 0-intensity
+ * light as subtle noise, not nothing). `center` (current map center) feeds
+ * the sunDate → az/el resolution.
+ */
+export declare function buildLights(ir: LightingIR, center?: [longitude: number, latitude: number]): Record<string, AmbientLight | DirectionalLight | CameraLight>;
+/** IR → deck.gl LightingEffect (see buildLights for the composition rules). */
+export declare function buildLightingEffect(ir: LightingIR, center?: [longitude: number, latitude: number]): LightingEffect;

package/dist/selection.d.ts

@@ -27,5 +27,5 @@ interface PickingInfoLike {
     x: number;
     y: number;
 }
-export declare function toSelection(info: PickingInfoLike, type: "hover" | "click"): Selection | null;
+export declare function toSelection(info: PickingInfoLike, type: "hover" | "click", resolveLayerId?: (renderedId: string) => string): Selection | null;
 export {};

package/dist/snapshot.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Snapshot serialization (spec: "Snapshot API") — shared by OmMapElement
+ * and MapController: the composite canvas RuntimeCore.snapshot() produces,
+ * serialized to the consumer's preferred shape.
+ */
+export interface SnapshotOptions {
+    /** Image MIME type — default "image/png". */
+    type?: "image/png" | "image/jpeg" | "image/webp";
+    /** Lossy-format quality 0–1 (jpeg/webp). */
+    quality?: number;
+    /** Output shape — default "dataURL" (what print/export pipelines embed directly); "blob" for uploads/files. */
+    as?: "dataURL" | "blob";
+}
+export declare function serializeSnapshot(canvas: HTMLCanvasElement, opts: SnapshotOptions): Promise<string | Blob>;

package/dist/{table-accessors-DBjWgN0C.js → table-accessors-CYWTzpQI.js}

@@ -1,6 +1,5 @@
-function w(e) {
-  var a;
-  switch (typeof e == "object" && (e == null ? void 0 : e.shape)) {
+function d(e) {
+  switch (typeof e == "object" && e?.shape) {
     case "array-row-table":
     case "object-row-table":
       return Array.isArray(e.data);
@@ -9,12 +8,12 @@ function w(e) {
     case "columnar-table":
       return e.data && typeof e.data == "object";
     case "arrow-table":
-      return ((a = e == null ? void 0 : e.data) == null ? void 0 : a.numRows) !== void 0;
+      return e?.data?.numRows !== void 0;
     default:
       return !1;
   }
 }
-function l(e) {
+function i(e) {
   switch (e.shape) {
     case "array-row-table":
     case "object-row-table":
@@ -24,8 +23,8 @@ function l(e) {
     case "arrow-table":
       return e.data.numRows;
     case "columnar-table":
-      for (const a of Object.values(e.data))
-        return a.length || 0;
+      for (const t of Object.values(e.data))
+        return t.length || 0;
       return 0;
     default:
       throw new Error("table");
@@ -34,7 +33,7 @@ function l(e) {
 function g(e) {
   if (e.schema)
     return e.schema.fields.length;
-  if (l(e) === 0)
+  if (i(e) === 0)
     throw new Error("empty table");
   switch (e.shape) {
     case "array-row-table":
@@ -51,154 +50,150 @@ function g(e) {
       throw new Error("table");
   }
 }
-function j(e, r, a) {
-  var o;
+function j(e, r, t) {
   switch (e.shape) {
     case "array-row-table":
-      const n = m(e, a);
-      return e.data[r][n];
+      const o = m(e, t);
+      return e.data[r][o];
     case "object-row-table":
-      return e.data[r][a];
+      return e.data[r][t];
     case "geojson-table":
-      return e.features[r][a];
+      return e.features[r][t];
     case "columnar-table":
-      return e.data[a][r];
+      return e.data[t][r];
     case "arrow-table":
-      const c = e.data, u = c.schema.fields.findIndex((s) => s.name === a);
-      return (o = c.getChildAt(u)) == null ? void 0 : o.get(r);
+      const n = e.data, f = n.schema.fields.findIndex((c) => c.name === t);
+      return n.getChildAt(f)?.get(r);
     default:
       throw new Error("todo");
   }
 }
-function y(e, r, a) {
-  var o;
+function y(e, r, t) {
   switch (e.shape) {
     case "array-row-table":
-      return e.data[r][a];
+      return e.data[r][t];
     case "object-row-table":
-      const n = i(e, a);
-      return e.data[r][n];
+      const o = l(e, t);
+      return e.data[r][o];
     case "geojson-table":
-      const f = i(e, a);
-      return e.features[r][f];
+      const u = l(e, t);
+      return e.features[r][u];
     case "columnar-table":
-      const c = i(e, a);
-      return e.data[c][r];
+      const n = l(e, t);
+      return e.data[n][r];
     case "arrow-table":
-      return (o = e.data.getChildAt(a)) == null ? void 0 : o.get(r);
+      return e.data.getChildAt(t)?.get(r);
     default:
       throw new Error("todo");
   }
 }
 function m(e, r) {
-  var o;
-  const a = (o = e.schema) == null ? void 0 : o.fields.findIndex((n) => n.name === r);
-  if (a === void 0)
+  const t = e.schema?.fields.findIndex((o) => o.name === r);
+  if (t === void 0)
     throw new Error(r);
-  return a;
+  return t;
 }
-function i(e, r) {
-  var o, n;
-  const a = (n = (o = e.schema) == null ? void 0 : o.fields[r]) == null ? void 0 : n.name;
-  if (!a)
+function l(e, r) {
+  const t = e.schema?.fields[r]?.name;
+  if (!t)
     throw new Error(`${r}`);
-  return a;
+  return t;
 }
-function T(e, r, a, o) {
+function T(e, r, t, o) {
   switch (e.shape) {
     case "object-row-table":
       return o ? Object.fromEntries(Object.entries(e.data[r])) : e.data[r];
     case "array-row-table":
       if (e.schema) {
-        const s = a || {};
-        for (let t = 0; t < e.schema.fields.length; t++)
-          s[e.schema.fields[t].name] = e.data[r][t];
+        const s = t || {};
+        for (let a = 0; a < e.schema.fields.length; a++)
+          s[e.schema.fields[a].name] = e.data[r][a];
         return s;
       }
       throw new Error("no schema");
     case "geojson-table":
       if (e.schema) {
-        const s = a || {};
-        for (let t = 0; t < e.schema.fields.length; t++)
-          s[e.schema.fields[t].name] = e.features[r][t];
+        const s = t || {};
+        for (let a = 0; a < e.schema.fields.length; a++)
+          s[e.schema.fields[a].name] = e.features[r][a];
         return s;
       }
       throw new Error("no schema");
     case "columnar-table":
       if (e.schema) {
-        const s = a || {};
-        for (let t = 0; t < e.schema.fields.length; t++)
-          s[e.schema.fields[t].name] = e.data[e.schema.fields[t].name][r];
+        const s = t || {};
+        for (let a = 0; a < e.schema.fields.length; a++)
+          s[e.schema.fields[a].name] = e.data[e.schema.fields[a].name][r];
         return s;
       } else {
-        const s = a || {};
-        for (const [t, h] of Object.entries(e.data))
-          s[t] = h[r];
+        const s = t || {};
+        for (const [a, h] of Object.entries(e.data))
+          s[a] = h[r];
         return s;
       }
     case "arrow-table":
-      const n = e.data, f = a || {}, c = n.get(r), u = n.schema;
-      for (let s = 0; s < u.fields.length; s++)
-        f[u.fields[s].name] = c == null ? void 0 : c[u.fields[s].name];
-      return f;
+      const u = e.data, n = t || {}, f = u.get(r), c = u.schema;
+      for (let s = 0; s < c.fields.length; s++)
+        n[c.fields[s].name] = f?.[c.fields[s].name];
+      return n;
     default:
       throw new Error("shape");
   }
 }
-function d(e, r, a, o) {
+function w(e, r, t, o) {
   switch (e.shape) {
     case "array-row-table":
       return o ? Array.from(e.data[r]) : e.data[r];
     case "object-row-table":
       if (e.schema) {
-        const s = a || [];
-        for (let t = 0; t < e.schema.fields.length; t++)
-          s[t] = e.data[r][e.schema.fields[t].name];
+        const s = t || [];
+        for (let a = 0; a < e.schema.fields.length; a++)
+          s[a] = e.data[r][e.schema.fields[a].name];
         return s;
       }
       return Object.values(e.data[r]);
     case "geojson-table":
       if (e.schema) {
-        const s = a || [];
-        for (let t = 0; t < e.schema.fields.length; t++)
-          s[t] = e.features[r][e.schema.fields[t].name];
+        const s = t || [];
+        for (let a = 0; a < e.schema.fields.length; a++)
+          s[a] = e.features[r][e.schema.fields[a].name];
         return s;
       }
       return Object.values(e.features[r]);
     case "columnar-table":
       if (e.schema) {
-        const s = a || [];
-        for (let t = 0; t < e.schema.fields.length; t++)
-          s[t] = e.data[e.schema.fields[t].name][r];
+        const s = t || [];
+        for (let a = 0; a < e.schema.fields.length; a++)
+          s[a] = e.data[e.schema.fields[a].name][r];
         return s;
       } else {
-        const s = a || [];
-        let t = 0;
+        const s = t || [];
+        let a = 0;
         for (const h of Object.values(e.data))
-          s[t] = h[r], t++;
+          s[a] = h[r], a++;
         return s;
       }
     case "arrow-table":
-      const n = e.data, f = a || [], c = n.get(r), u = n.schema;
-      for (let s = 0; s < u.fields.length; s++)
-        f[s] = c == null ? void 0 : c[u.fields[s].name];
-      return f;
+      const u = e.data, n = t || [], f = u.get(r), c = u.schema;
+      for (let s = 0; s < c.fields.length; s++)
+        n[s] = f?.[c.fields[s].name];
+      return n;
     default:
       throw new Error("shape");
   }
 }
 function* p(e, r = []) {
-  const a = l(e);
-  for (let o = 0; o < a; o++)
-    yield d(e, o, r);
+  const t = i(e);
+  for (let o = 0; o < t; o++)
+    yield w(e, o, r);
 }
 export {
   g as a,
   y as b,
   j as c,
-  d,
+  w as d,
   T as e,
-  l as g,
-  w as i,
+  i as g,
+  d as i,
   p as m
 };

package/dist/terrain.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Terrain (spec: "Terrain") — 3D elevation surface + per-layer draping,
+ * declared as `terrain*` attributes on <om-map> (the basemap=/lighting=
+ * scene-attribute precedent: free undo/redo, live MutationObserver
+ * switching).
+ *
+ *   <om-map terrain="terrarium" terrain-exaggeration="1.5" pitch="55">
+ *   <om-map terrain="https://tiles.example.com/dem/{z}/{x}/{y}.png"
+ *           terrain-decoder="terrarium" terrain-max-zoom="14"
+ *           terrain-texture="https://…/satellite/{z}/{x}/{y}.jpg">
+ *
+ * The seventh plugin registry (`OmMap.registerTerrain`) resolves preset
+ * names; a `{z}/{x}/{y}` URL is bring-your-own DEM (requires
+ * terrain-decoder). Geographic layers DRAPE onto the surface by default;
+ * a per-layer `terrain="drape|offset|off"` attribute overrides (3D-model
+ * layers default to `offset` — models sit ON terrain, not painted onto
+ * it).
+ *
+ * Terrain REPLACES an active basemap: a flat MapLibre canvas sits at sea
+ * level and visibly desyncs from a raised surface (true coexistence is
+ * the interleaved-compositing TODO). RuntimeCore suppresses the basemap
+ * while terrain is active and restores it when terrain turns off.
+ *
+ * `applyTerrain` is PURE (unit-testable without a GPU — headless never
+ * reaches the deck handoff): it computes each layer's terrain patches and
+ * the terrain-surface layer props; RuntimeCore feeds them to buildLayers.
+ */
+import type { Layer } from "@deck.gl/core";
+import type { LayerIR } from "./ir";
+/** RGB DEM decoder: height = offset + R·rScaler + G·gScaler + B·bScaler. */
+export interface ElevationDecoder {
+    rScaler: number;
+    gScaler: number;
+    bScaler: number;
+    offset: number;
+}
+export declare const DECODERS: Readonly<Record<string, ElevationDecoder>>;
+export interface TerrainPreset {
+    /** `{z}/{x}/{y}` DEM tile URL template (may carry a `{key}` placeholder for keyed providers). */
+    elevationData: string;
+    /** Decoder name ("terrarium" / "mapbox-rgb") or explicit scalers. */
+    decoder: keyof typeof DECODERS | ElevationDecoder;
+    /**
+     * The provider's REAL tileset cap — deck over-samples past it for closer
+     * cameras; a too-high cap requests tiles that 404 and blanks the terrain.
+     */
+    maxZoom: number;
+    /** Optional draped imagery `{z}/{x}/{y}` URL template. */
+    texture?: string;
+    /** Display name (switcher UIs). */
+    label?: string;
+    /** Which key `{key}` substitutes — the basemap-registry convention. */
+    requiresKey?: "maptiler";
+}
+export declare function registerTerrain(name: string, preset: TerrainPreset): void;
+export declare function getTerrain(name: string): TerrainPreset | undefined;
+export declare function getAllTerrains(): ReadonlyMap<string, TerrainPreset>;
+export interface TerrainIR {
+    elevationData: string;
+    elevationDecoder: ElevationDecoder;
+    maxZoom: number;
+    /** Multiplies decoded DEM heights (1 = true relief). */
+    exaggeration: number;
+    texture?: string;
+}
+export interface ResolvedTerrain {
+    ir: TerrainIR | null;
+    /** Resolution problem (unknown preset / missing key / missing decoder) — the caller decides how loudly to fail; `ir` is null when unresolvable. */
+    error?: string;
+}
+/** Is this `terrain` value a bring-your-own DEM URL rather than a preset name? (The basemap isStyleUrl convention.) */
+export declare function isDemUrl(raw: string): boolean;
+/**
+ * `terrain*` attributes → TerrainIR. Returns `{ir: null}` when `terrain`
+ * is absent/"off"; `{ir: null, error}` when set but unresolvable (unknown
+ * preset, keyless keyed preset, raw URL without a decoder) — terrain
+ * renders NOTHING in that case rather than a wrong surface, and validation
+ * carries the loud version of the same message.
+ */
+export declare function parseTerrainAttrs(getAttr: (name: string) => string | null, maptilerKey?: string): ResolvedTerrain;
+export declare const TERRAIN_LAYER_ID = "__onlymapjs-terrain";
+export type LayerTerrainMode = "drape" | "offset" | "off";
+export declare const LAYER_TERRAIN_MODES: readonly ["drape", "offset", "off"];
+export declare function defaultTerrainMode(type: string): LayerTerrainMode;
+export interface TerrainLayerPatch {
+    /**
+     * The deck-layer id to construct with. Suffixed `#t<generation>` while
+     * terrain is active: adding/removing an extension on a LIVE layer
+     * recompiles shaders and corrupts attribute state (the DataFilterExtension
+     * birth-mount rule), and a stale TerrainExtension vertical offset survives
+     * a terrain toggle on a stable id — a fresh id forces clean teardown +
+     * rebuild. RuntimeCore maps these generated ids back to authored ids for
+     * picks without guessing from the string shape.
+     */
+    deckId: string;
+    /** Extra constructor props: extensions (APPENDED to existing — DataFilterExtension stays mounted) + terrainDrawMode. Empty for mode "off". */
+    extraProps: Record<string, unknown>;
+}
+/**
+ * Per-layer terrain patches, PURE. `terrainActive` false → identity patches
+ * (stable ids, no props). Runtime-internal layers (trace temps, draw
+ * preview, tooltip plumbing) never drape — they're screen-space/transient.
+ */
+export declare function applyTerrain(irs: readonly LayerIR[], terrainActive: boolean, generation: number): Map<string, TerrainLayerPatch>;
+/**
+ * The terrain-surface layer itself. `operation: "terrain+draw"` makes it
+ * double as the elevation surface extension-carrying layers drape onto;
+ * `pickable: "3d"` runs the depth pick pass so click/hover coordinates
+ * unproject at the SURFACE's depth instead of z=0 sea level (without it,
+ * tilted-view picks/drawn vertices land behind the cursor). Exempt from
+ * license gates by the `__onlymapjs-` prefix.
+ */
+export declare function buildTerrainLayer(ir: TerrainIR): Layer;

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * the build rootDir, and a `define` would need repeating across vite/vitest/
  * vite-node configs.
  */
-export declare const LIBRARY_VERSION = "0.2.3";
+export declare const LIBRARY_VERSION = "0.3.1";

package/dist/zstd-jXobGRcq.js

@@ -0,0 +1,14 @@
+import { decompress as r } from "./index-2v2NXF_n.js";
+async function o(t) {
+  const e = r(new Uint8Array(t));
+  return n(e);
+}
+function n(t) {
+  if (t.byteOffset === 0 && t.byteLength === t.buffer.byteLength)
+    return t.buffer;
+  const e = new Uint8Array(t.byteLength);
+  return e.set(t), e.buffer;
+}
+export {
+  o as decode
+};

package/docs/custom-layers.md

@@ -0,0 +1,99 @@
+# Registering an external layer class
+
+`OmMap.registerLayer` makes any deck.gl layer class a first-class manifest
+type: validation, IntelliSense generation, and attribute resolution all read
+the same schema the built-ins use. This page is the recipe for bringing a
+layer class the library doesn't bundle — a community layer, a company shim, a
+composite that wraps a whole data pipeline.
+
+## Rule 1: build on `@nika-js/onlymap/deck`, never on your own deck.gl
+
+OnlyMapJS bundles deck.gl (it has zero runtime dependencies). If your class
+extends a `@deck.gl/*` copy you installed yourself, it belongs to a
+**different class hierarchy** — two `Layer` base classes, two luma.gl
+runtimes — and fails inside the bundled renderer. The `deck` subpath
+re-exports the bundled classes, so your shim extends the exact objects the
+core renders with:
+
+```js
+import { CompositeLayer, TileLayer, BitmapLayer } from "@nika-js/onlymap/deck";
+```
+
+Available: `Layer`, `CompositeLayer`, `LayerExtension`, `WebMercatorViewport`,
+`COORDINATE_SYSTEM`, `GeoJsonLayer`, `ScatterplotLayer`, `IconLayer`,
+`BitmapLayer`, `TileLayer`, `Tile3DLayer`, `SimpleMeshLayer`,
+`ScenegraphLayer` — plus authoring types (`LayerProps`, `DefaultProps`,
+`UpdateParameters`, `PickingInfo`, `LayersList`; typechecking against them
+needs `@deck.gl/core` as a dev dependency).
+
+## Rule 2: functions ride `static defaultProps`, not attributes
+
+HTML attributes are strings — function-valued props (`renderSubLayers`,
+`getTileData`, load callbacks) are inexpressible by design. Put them on a
+thin subclass; deck.gl's own defaultProps merge delivers them to every
+instance:
+
+```js
+class CogLayer extends CompositeLayer {
+  static layerName = "CogLayer";
+  static defaultProps = {
+    renderTile: { type: "function", value: renderTile },
+    onRasterLoad: { type: "function", value: () => {} },
+  };
+  renderLayers() {
+    /* compose TileLayer/BitmapLayer from the subpath here */
+  }
+}
+```
+
+## Rule 3: the schema wires attributes to deck props
+
+```js
+import { OmMap } from "@nika-js/onlymap";
+
+OmMap.registerLayer({
+  type: "CogLayer",
+  deckClass: CogLayer,
+  props: [
+    // deck's URL prop is `data`, but OnlyMapJS reserves the `data` attribute
+    // for its own loader — alias it, and the layer class fetches for itself
+    // (the built-in Tile3DLayer `tileset` attribute uses the same trick).
+    { attr: "src", kind: "scalar", deckProp: "data", type: "string", required: true },
+    // JSON attributes and dot-path descriptors compose: the JSON sets the
+    // object, later dot-paths merge into it.
+    { attr: "load-options", kind: "scalar", deckProp: "loadOptions", type: "json" },
+    { attr: "max-error", kind: "scalar", deckProp: "loadOptions.cog.maxError", type: "number" },
+    { attr: "opacity", kind: "scalar", deckProp: "opacity", type: "number", default: 1 },
+    { attr: "visible", kind: "scalar", deckProp: "visible", type: "boolean", default: true },
+    // accessor-kind props get the full expression language:
+    // { attr: "get-color", kind: "accessor", deckProp: "getColor" },
+  ],
+});
+```
+
+Then the manifest just works:
+
+```html
+<om-layer id="rast" type="CogLayer" src="https://example.com/landcover.tif"
+          max-error="16" opacity="0.9"></om-layer>
+```
+
+## Rule 4: register before the manifest mounts
+
+Registration after mount does not retrigger reconciles — an unknown-type
+layer is warn-skipped until the next DOM mutation. Call `registerLayer` at
+module top level (the `registerSource`/`registerFormat` convention), before
+the `<om-map>` connects.
+
+## Verifying without a GPU
+
+`OmMap.snapshotIR(html)` resolves your registered type through the same
+pipeline the live reconciler runs — assert the aliased URL lands on
+`props.data`, dot-paths nest, functions appear as `[function]` — in plain
+jsdom/happy-dom, no WebGL.
+
+## The programmatic alternative
+
+On the `MapController` front-end (and the React adapter), `props` passes
+function values directly — no subclass needed. The subclass recipe exists so
+the **manifest** front-end can express what attributes can't.