@nika-js/onlymap 0.7.5 → 0.8.0

package/dist/basemap.d.ts

@@ -103,6 +103,21 @@ export declare class MapLibreBasemapAdapter {
      * fire without one. The ecosystem's standard user-vs-programmatic signal.
      */
     onMove(cb: (origin: ViewOrigin) => void): void;
+    /** Set while a capture-resolution override resizes the canvases — see onMove. */
+    private moveSuppressed;
+    /**
+     * Re-rasterize both canvases at `ratio` captured pixels per CSS pixel, or
+     * restore the display default with null (spec: "Snapshot API" — the
+     * `snapshot({scale})` seam). MapLibre's own `setPixelRatio` drives the
+     * basemap canvas; the overlay's deck takes the same number through
+     * `useDevicePixels`, which luma applies to the drawing buffer immediately.
+     *
+     * The idle latch is cleared deliberately: the caller must re-await
+     * `whenSettled()` before capturing, because a re-rasterized basemap has
+     * tiles and glyphs to redraw and `map.once("render")` alone would capture
+     * the first, unconverged frame.
+     */
+    setCapturePixelRatio(ratio: number | null): void;
     setLayers(layers: DeckProps["layers"]): void;
     /**
      * Scene lighting (spec: "Scene Lighting") — MapboxOverlay accepts full

package/dist/cartograph/api.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The cartograph API surface — elements, geometry, validation, export.
+ *
+ * Shared by BOTH build entries. Deliberately contains no core-loader
+ * registration: the import expression that reaches the map runtime differs
+ * per entry (package name vs relative URL) and lives in index.ts /
+ * standalone.ts. Importing this module registers the elements and pulls the
+ * stylesheet.
+ */
+import "./cartograph.css";
+export { OmCartographElement } from "./elements/om-cartograph";
+export { OmTextElement } from "./elements/om-text";
+export { OmFrameElement, type FrameMode, type FrameErrorReason } from "./elements/om-frame";
+export { OmScalebarElement } from "./elements/om-scalebar";
+export { OmNorthElement } from "./elements/om-north";
+export { OmShapeElement, type ShapeKind } from "./elements/om-shape";
+export { OmImageElement } from "./elements/om-image";
+export { OmLegendElement } from "./elements/om-legend";
+export { OmGraticuleElement } from "./elements/om-graticule";
+export { OmAtlasElement } from "./elements/om-atlas";
+export { CARTOGRAPH_FORMAT, CARTOGRAPH_THEMES, CARTOGRAPH_TAG_NAMES, CARTOGRAPH_ELEMENT_ATTRS, INERT_RESERVED_CARTOGRAPH_ATTRS, PAGE_SIZE_NAMES, PLACED_ATTR_NAMES, } from "./schema";
+export { PAGE_PRESETS, PX_PER_MM, resolvePageSize, type PageSizeMm } from "./layout";
+export { createFrameGeoref, cornersFromBounds, parseCorners, normalizeCrs, builtinCrsForward, resolveCrsForward, northBearingDegrees, scaleVariation, utmDef, mercatorForward, mercatorInverse, type FrameGeoref, type CrsForward, } from "./georef";
+export { buildScalebar, buildScalebarDrawing, niceNumberBelow, formatScaleDenominator, SCALE_GROUP_SEPARATOR, type ScalebarSpec, type ScalebarDrawing, type ScalebarStyle, type ScalebarUnits, } from "./scalebar";
+export { resolveTokens, resolveToken, tokensIn, applyTokens, isoDate, type TokenContext, type FrameTokenValues } from "./tokens";
+export { layoutText, canvasMeasurer, alignOffset, type TextLayout, type TextLine } from "./textlayout";
+export { validateCartograph, validateCartographString, validateCartographDeep } from "./validate";
+export { deriveLegendRows, readOverrides, readLiteralRows, swatchShapeFor, rowColorFor, MAX_CATEGORY_ENTRIES, type LegendRow, type LegendRowOverride, type SwatchShape, } from "./legend";
+export { buildGraticule, niceInterval, formatDms, GEOGRAPHIC_PLANE, type Graticule, type GridPlane } from "./graticule";
+export { lintLegendColours, simulate, deltaE00, parseColor, ensureCvdFilters, applyCvdToCanvas, resolveCvdType, CVD_TYPES, CVD_VALUES, CVD_MATRICES, COLLAPSE_THRESHOLD, type CvdType, type LegendColourLint, type ColourCollapse, } from "./cvd";
+export { loadCore, setCoreLoader, peekCore, isCoreLoaded, type CoreModule } from "./core-loader";
+export { cornersFromCamera, readCamera, sanitizeAdoptedMap, type FrameCamera, type Corners } from "./live-frame";
+export { renderCartograph, renderCartographAtlas, MAX_CANVAS_AREA, MAX_CANVAS_DIMENSION, type RenderCartographOptions, type RenderCartographResult, type RenderAtlasOptions, type RenderAtlasResult, } from "./render";
+export { buildPages, featureBounds, padBounds, boundsArea, atlasFields, fieldOf, parseSort, sanitizeFilename, resolveFilenames, rejectionFor, type AtlasFeature, type AtlasRejection, } from "./atlas";
+export { createZip, type ZipFile } from "./zip";
+export { applyUrlActions, whenPageReady, installUrlActions, URL_ACTION_TIMEOUT_MS } from "./url-actions";
+export { boxMm, paintEnvForDpi, type PaintEnv, type CartographPainter } from "./paint";
+export { findFrame, allFrames, referencedFrame, ownerCartograph, clearUnlinked } from "./refs";
+/**
+ * Explicit registration — importing the entry already registers everything
+ * (defineElement is idempotent and a no-op outside a browser); this exists
+ * for hosts that tree-shake side effects or want registration at a chosen
+ * time.
+ */
+export declare function defineCartographElements(): void;

package/dist/cartograph/atlas.d.ts

@@ -0,0 +1,50 @@
+/** A row as the atlas sees it — flat object, GeoJSON feature, or columnar slice. */
+export type AtlasFeature = Record<string, unknown>;
+export interface AtlasLayerInput {
+    id: string;
+    type?: string;
+    data?: unknown;
+    tileData?: unknown;
+    asset?: unknown;
+    live?: boolean;
+    filter?: unknown;
+    categoryFilter?: unknown;
+    props?: Record<string, unknown>;
+}
+/** Why a layer cannot drive an atlas — each maps to a validator message. */
+export type AtlasRejection = "tiled" | "asset" | "empty";
+export declare function rejectionFor(layer: AtlasLayerInput | undefined): AtlasRejection | null;
+/** Read a field from a row, looking inside GeoJSON `properties` when present. */
+export declare function fieldOf(feature: AtlasFeature, name: string): unknown;
+/** Every field a page's `{{atlas.<field>}}` tokens can resolve, flattened. */
+export declare function atlasFields(feature: AtlasFeature): Record<string, string>;
+export type Bounds = [number, number, number, number];
+/**
+ * A feature's lon/lat bounding box, walking whatever geometry it carries.
+ * Null when the feature has no coordinates to fit to.
+ */
+export declare function featureBounds(feature: AtlasFeature): Bounds | null;
+/** Grow a box by a fraction of its own size, so a fitted feature is not flush to the frame edge. */
+export declare function padBounds(bounds: Bounds, margin: number): Bounds;
+/** Bounding-box area — the tie-break for "the largest feature" in overlap checks. */
+export declare const boundsArea: ([west, south, east, north]: Bounds) => number;
+export interface BuildPagesOptions {
+    features: readonly AtlasFeature[];
+    /** Compiled predicate from the `filter=` expression; absent keeps everything. */
+    filter?: (feature: AtlasFeature) => boolean;
+    /** `sort="field"` / `"-field"`, comma-separated for several keys. */
+    sort?: string | null;
+}
+/** Apply filter and sort to produce the page order. */
+export declare function buildPages({ features, filter, sort }: BuildPagesOptions): AtlasFeature[];
+export declare function parseSort(sort: string | null | undefined): {
+    field: string;
+    descending: boolean;
+}[];
+/** Strip everything a filesystem (or a zip reader) would object to. */
+export declare function sanitizeFilename(name: string): string;
+/**
+ * Resolve one filename per page from a token pattern, suffixing duplicates so
+ * two features with the same name cannot silently overwrite each other.
+ */
+export declare function resolveFilenames(pattern: string | null | undefined, pages: readonly AtlasFeature[], extension: string): string[];

package/dist/cartograph/core-loader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The one place the cartograph reaches the map runtime.
+ *
+ * THE LAZY-CORE RULE: `src/cartograph/` never imports the core entry at module
+ * scope, so a static-only cartograph — the qgis2carto output, a survey sheet
+ * in a mail preview — loads no deck.gl, no MapLibre, nothing. The core arrives
+ * only when a live `<om-frame>` actually mounts. `dev/assert-bundle-cdn-safe.mjs`
+ * fails the build if that ever regresses.
+ *
+ * The import EXPRESSION differs per build entry and cannot be written here:
+ *   - the bundler entry imports the package by name ("@nika-js/onlymap"),
+ *     which its Vite config marks external so consumers share one core
+ *     instance (the deck.gl class-identity rule);
+ *   - the standalone entry imports a sibling file by relative URL, because a
+ *     CDN-hosted single file has no package resolution.
+ * So each entry injects its own loader and this module owns the caching,
+ * the in-flight de-duplication, and the "you forgot" error.
+ */
+/** The slice of the core the cartograph uses. Type-only — erased at compile time. */
+export type CoreModule = typeof import("../index");
+type CoreLoader = () => Promise<unknown>;
+/** Called once by each entry (index.ts / standalone.ts) at import time. */
+export declare function setCoreLoader(fn: CoreLoader): void;
+/** True once the core has finished loading — lets callers stay synchronous. */
+export declare function isCoreLoaded(): boolean;
+/** The loaded core, or null if it has not been loaded yet. */
+export declare function peekCore(): CoreModule | null;
+/**
+ * Load the map runtime. Concurrent callers share one import; repeat callers
+ * get the cached module.
+ */
+export declare function loadCore(): Promise<CoreModule>;
+/** Test seam: forget the cached core so a suite can install a different loader. */
+export declare function resetCoreLoaderForTest(): void;
+export {};

package/dist/cartograph/cvd.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Colour-vision-deficiency simulation and legend colour linting
+ * (NikaGeospatial/onlymap-js#42).
+ *
+ * Two jobs, one set of matrices:
+ *   - `cvd=` / `?cvd=` renders the whole page as a viewer with that condition
+ *     would see it — a review aid, applied to the live document and never
+ *     persisted by an editor.
+ *   - `lintLegendColours()` answers the question that actually matters before
+ *     printing: would any two legend entries become indistinguishable? A map
+ *     whose categories collapse under deuteranopia is unreadable to roughly
+ *     1 in 12 men, and paper offers no way to toggle it back.
+ *
+ * Matrices are Viénot, Brettel & Mollon (1999), applied in LINEAR RGB.
+ *
+ * That combination is load-bearing and was got wrong once: the widely-copied
+ * "colour blindness matrices" that operate on sRGB directly are INVERTIBLE —
+ * their red/green block has a non-zero determinant — so no two distinct
+ * colours ever map to the same output and a lint built on them can never
+ * report a collapse. The Viénot matrices project onto the dichromat's own
+ * two-dimensional colour plane, so rows 1 and 2 (protan/deutan) or 2 and 3
+ * (tritan) are IDENTICAL by construction: the confusion axis genuinely
+ * disappears, which is the whole point of asking the question.
+ */
+export type CvdType = "protanopia" | "deuteranopia" | "tritanopia" | "achromatopsia";
+export declare const CVD_TYPES: readonly CvdType[];
+/** The simulation an authored `cvd=` / `?cvd=` value asks for; null for "none" or a typo. */
+export declare function resolveCvdType(raw: string | null | undefined): CvdType | null;
+/** Every accepted `cvd=` spelling, for validator messages and IntelliSense. */
+export declare const CVD_VALUES: readonly string[];
+/**
+ * Row-major 3×3 transforms in LINEAR RGB (not sRGB — see the module comment).
+ * Note the repeated rows: that singularity IS the simulation.
+ */
+export declare const CVD_MATRICES: Record<CvdType, readonly number[]>;
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Parse `#rgb`, `#rrggbb`, or `rgb()/rgba()`. Null for anything else (a gradient, a keyword we do not resolve). */
+export declare function parseColor(input: string): Rgb | null;
+/**
+ * Apply a CVD matrix to a colour. The transform happens in LINEAR light,
+ * because that is the space the matrices were derived in — running them on
+ * gamma-encoded sRGB gives visibly wrong results and, worse, a model that
+ * never collapses anything.
+ */
+export declare function simulate(color: Rgb, type: CvdType): Rgb;
+/**
+ * CIEDE2000 colour difference. Below ~10 two colours are hard to tell apart
+ * at legend-swatch size; below ~2.3 they are a "just noticeable difference".
+ */
+export declare function deltaE00(a: Rgb, b: Rgb): number;
+/** Colours that collapse under a CVD type are indistinguishable below this ΔE00. */
+export declare const COLLAPSE_THRESHOLD = 10;
+export interface LegendColourEntry {
+    label: string;
+    color: string;
+    /**
+     * The layer this row came from. Rows are only compared WITHIN a layer
+     * (NikaGeospatial/onlymap-js#42 §3): two layers may legitimately share a colour — a reader
+     * tells their swatches apart by which block of the legend they sit in, not
+     * by hue — so pairing across them reports collapses nobody can act on.
+     * Literal rows carry no layer and are compared as one group.
+     */
+    layer?: string;
+}
+export interface ColourCollapse {
+    type: CvdType;
+    a: LegendColourEntry;
+    b: LegendColourEntry;
+    /** ΔE00 after simulation — smaller is worse. */
+    distance: number;
+}
+export interface LegendColourLint {
+    collapses: ColourCollapse[];
+    /** The CVD type that damages this palette most, if any. */
+    worstType: CvdType | null;
+}
+/**
+ * Find legend entries that become indistinguishable under colour-vision
+ * deficiency. Pairs that are ALREADY indistinguishable to normal vision are
+ * skipped — that is a palette bug of a different kind, not a CVD finding.
+ */
+export declare function lintLegendColours(entries: readonly LegendColourEntry[], threshold?: number): LegendColourLint;
+/**
+ * Apply a CVD simulation to a 2D canvas in place — the EXPORT half of `cvd=`
+ * (NikaGeospatial/onlymap-js#42). The screen and print paths use the SVG filter above; a raster export
+ * has no filter stage, so the same matrices are run over the pixels here,
+ * which is what keeps "what I reviewed" and "what I sent" the same image.
+ *
+ * Returns false when the pixels cannot be read — a cross-origin raster taints
+ * the canvas, and an unfiltered export is a better answer than a thrown one,
+ * as long as the caller says so.
+ */
+export declare function applyCvdToCanvas(ctx: CanvasRenderingContext2D, width: number, height: number, type: CvdType): boolean;
+/** The `filter` value applied to a page under `cvd=` — an SVG filter this module injects. */
+export declare const CVD_FILTER_ID: (type: CvdType) => string;
+/**
+ * Ensure the SVG colour-matrix filters exist in the document, once. CSS
+ * cannot express a colour matrix, so simulation needs a real filter element;
+ * it is injected next to the page rather than shipped in the stylesheet
+ * because a document with no `cvd=` should carry none of it.
+ */
+export declare function ensureCvdFilters(doc: Document): void;

package/dist/cartograph/element-base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared base for the cartograph elements: attribute reflection with
+ * microtask-coalesced re-render (the om-widget observedAttributes pattern,
+ * batched — an editor writing x, y, w, h in one gesture triggers ONE
+ * render), and placement application.
+ *
+ * Placement contract (design §3.1): the ATTRIBUTES (`x y w h rotation z`,
+ * mm) are the single authored source of truth; the runtime re-asserts the
+ * equivalent inline mm styles from them on every change. Producers also
+ * write those inline styles at export time so the no-JS fallback positions
+ * exactly; the validator (Phase 1) errors when authored styles disagree
+ * with the attributes.
+ */
+import { HTMLElementBase } from "../env";
+export declare abstract class CartographElementBase extends HTMLElementBase {
+    private renderQueued;
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** Ask for a re-render — used when something this element DEPENDS on changed. */
+    requestCartographRender(): void;
+    protected scheduleRender(): void;
+    /** One coalesced render per microtask — subclasses re-read their attributes here. */
+    protected abstract renderNow(): void;
+    /** Write the placed-element inline styles from the mm placement attributes. */
+    protected applyPlacement(): void;
+}

package/dist/cartograph/elements/om-atlas.d.ts

@@ -0,0 +1,47 @@
+import { CartographElementBase } from "../element-base";
+import { type AtlasFeature, type AtlasRejection } from "../atlas";
+import type { OmFrameElement } from "./om-frame";
+export declare class OmAtlasElement extends CartographElementBase {
+    static readonly observedAttributes: string[];
+    /**
+     * Pages are SNAPSHOTTED when iteration first starts. A streaming or polling
+     * layer would otherwise change the page count halfway through an export,
+     * producing an archive whose contents do not match its own index.
+     */
+    private pages;
+    private currentIndex;
+    private rejection;
+    /** The frame whose layer drives the iteration — the same `for=` rule every furniture element follows. */
+    get frame(): OmFrameElement | null;
+    get count(): number;
+    get index(): number;
+    get current(): AtlasFeature | null;
+    /** Why this atlas cannot run, if it cannot. */
+    get problem(): AtlasRejection | null;
+    /** Export filenames, one per page, already de-duplicated. */
+    filenames(extension?: string): string[];
+    /** Human page labels, for an editor's stepper and PDF bookmarks. */
+    pageName(index: number): string;
+    /**
+     * Recompute the page list from the layer as it stands now, and apply the
+     * current page. Applying is part of refreshing because the page list first
+     * becomes non-empty when the frame mounts its map: without it, page 1 would
+     * never be applied and a cartograph would print `{{atlas.*}}` literally with
+     * the authored camera, until something else happened to seek.
+     */
+    refresh(): void;
+    private ensurePages;
+    /**
+     * Rows from the layer, with the layer's OWN declarative filters applied —
+     * the coherence rule. An atlas that paged over unfiltered rows would print
+     * sheets for features the map itself is hiding.
+     */
+    private materialize;
+    /** `filter=` uses the CORE expression language — the syntax authors already know from om-layer. */
+    private compileFilter;
+    /** Move to a page: refit the following frames, re-resolve tokens, announce it. */
+    seek(index: number): void;
+    next(): void;
+    private applyPage;
+    protected renderNow(): void;
+}

package/dist/cartograph/elements/om-cartograph.d.ts

@@ -0,0 +1,76 @@
+import { CartographElementBase } from "../element-base";
+import { type PageSizeMm } from "../layout";
+import { type TokenContext } from "../tokens";
+import type { OmAtlasElement } from "./om-atlas";
+export declare class OmCartographElement extends CartographElementBase {
+    static readonly observedAttributes: string[];
+    private frameListenerBound;
+    /** Fields of the atlas page currently displayed, for {{atlas.<field>}}. */
+    private atlasFields;
+    private creditObserver;
+    private unsubscribeLicense;
+    /** The resolved page box, mm — furniture and export read this, never the attributes. */
+    get pageSize(): PageSizeMm;
+    /** Bleed in mm (0 when unset) — extends the printed sheet past the trim. */
+    get bleedMm(): number;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * The free-tier credit (issue #41 §6, decided 2026-09-11): a cartograph is
+     * a print/export artifact, and `snapshot()` deliberately excludes the map
+     * badge — so without this line a free-plan sheet would ship credit-free.
+     * Suppressed when the author placed their OWN OnlyMap credit in any
+     * `om-text` (the licensing condition is the credit, not this element), or
+     * when a loaded core reports a paid plan (`hideBadge`). A static-only page
+     * never loads the core and keeps the credit — key verification is the map
+     * runtime's job (issue #41 §9: the om-map carries the key).
+     */
+    private renderCredit;
+    /** Give the runtime-owned DOM credit the same canvas paint contract as authored furniture. */
+    private armCreditPainter;
+    /**
+     * Print this page at `dpi`.
+     *
+     * A live map is a WebGL canvas, and WebGL canvases print blank or at screen
+     * resolution — the drawing buffer is not preserved, and the print rasterizer
+     * never re-renders it. So every live frame is swapped for a print-resolution
+     * capture first, and restored on `afterprint`. This is also why an
+     * unassisted Ctrl+P cannot produce a high-DPI page: the print dialog opens
+     * synchronously and captures are asynchronous.
+     */
+    print(options?: {
+        dpi?: number;
+    }): Promise<void>;
+    /** Render the whole page to one image, for `flatten`. */
+    private buildFlattenedImage;
+    /** The page's atlas controller, if it has one. */
+    get atlas(): OmAtlasElement | null;
+    /** Called by the atlas when it seeks — the source for {{atlas.<field>}}. */
+    setAtlasFields(fields: Record<string, string> | undefined): void;
+    /** Re-render every furniture element — called when a frame's georeference appears. */
+    refreshFurniture(): void;
+    /** Values every `{{token}}` on this page resolves against. */
+    tokenContext(): TokenContext;
+    /** Re-resolve `{{tokens}}` in every text block on the page. */
+    refreshTokens(): void;
+    protected renderNow(): void;
+    /**
+     * Crop marks and the safe-zone guide.
+     *
+     * Crop marks tell a trimmer where the sheet is cut, so they live OUTSIDE the
+     * trim box, in the bleed. The safe zone is the opposite: an on-screen guide
+     * showing where content is at risk of being trimmed off, and it must never
+     * reach paper or an exported image — a guide printed on the deliverable is
+     * worse than no guide.
+     */
+    private renderPrintMarks;
+    /**
+     * Colour-vision simulation over the whole page — a review aid, so an author
+     * can see what a red/green categorical scheme does to roughly 1 in 12 male
+     * readers BEFORE it is printed, when nothing can be toggled back.
+     *
+     * CSS cannot express a colour matrix, so the filters are real SVG elements,
+     * injected only when a page actually asks for one.
+     */
+    private applyCvd;
+}

package/dist/cartograph/elements/om-frame.d.ts

@@ -0,0 +1,111 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+import { type FrameGeoref } from "../georef";
+export type FrameMode = "live" | "static";
+export type FrameErrorReason = "no-raster" | "bad-corners" | "unknown-crs" | "raster-decode" | "no-source" | "load-failed" | "no-camera" | "degenerate-view";
+export declare class OmFrameElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    /** Resolved non-builtin CRS planes, so a re-render does not re-await proj4. */
+    private resolvedForward;
+    private resolvedForwardKey;
+    private resolveToken;
+    private lastError;
+    private readyFired;
+    private readySettled;
+    private readyPromise;
+    private readyResolve;
+    /**
+     * Settles when the frame has either rendered its map or given up on it —
+     * mirroring `<om-map>`'s own `ready`. It RESOLVES on error rather than
+     * rejecting, because every caller (export, print, the URL triggers) wants
+     * "stop waiting", and a frame that failed still shows a visible placeholder
+     * that belongs on the page.
+     */
+    get ready(): Promise<void>;
+    private settleReady;
+    /** Live-mode state. */
+    private liveMap;
+    private liveCorners;
+    private mountToken;
+    private mounting;
+    private mountingSource;
+    private mountedSource;
+    private liveMapOwned;
+    /** A capture standing in for the live map during export/print. */
+    private captureImage;
+    private printing;
+    get mode(): FrameMode;
+    /** The mounted `<om-map>`, once a live frame has one. */
+    get mapElement(): HTMLElement | null;
+    /**
+     * The frame's georeference, or null when it has none yet (malformed corners,
+     * a CRS still resolving, a live map not yet mounted, a view too pitched to
+     * georeference). Recomputed on demand — the fit is an 8×8 solve, far cheaper
+     * than caching it correctly.
+     */
+    get georef(): FrameGeoref | null;
+    /** The raster a static frame draws — its first <img> child, if any. */
+    get raster(): HTMLImageElement | null;
+    disconnectedCallback(): void;
+    /**
+     * Bump the generation token so a mount already in flight cannot adopt its
+     * map into this frame when it lands. The token is the whole cancellation
+     * protocol, so it lives in one place — three copies of it is three chances
+     * for a stale map to arrive after a src= change.
+     */
+    private abandonMount;
+    protected renderNow(): void;
+    private renderStatic;
+    private renderLive;
+    /** Inline maps are identified by node identity; fetched maps by their src=. */
+    private liveSource;
+    /** Leave live mode without deleting an authored inline map. */
+    private suspendLiveMode;
+    private releaseLiveMap;
+    private updateLiveCorners;
+    private mountLive;
+    private sizeLiveMap;
+    /**
+     * Draw another frame's footprint on this one. The outline is DENSIFIED —
+     * sampled along each edge and projected point by point — because a
+     * rectangle in one projection is a curve in another, and four straight
+     * segments would visibly cut the corners on a wide-extent inset.
+     */
+    private renderOverview;
+    private signalStaticReady;
+    private signalReady;
+    /**
+     * Frames fail loudly and visibly. A silent empty box on a printed page is
+     * the worst outcome — it looks like a design choice.
+     */
+    private showPlaceholder;
+    private clearPlaceholder;
+    /**
+     * Capture this frame's map at `scale` captured pixels per CSS pixel.
+     * Static frames need no capture (their raster IS the picture); a live frame
+     * re-renders at the requested resolution through the core.
+     */
+    captureAt(scale: number): Promise<HTMLImageElement | null>;
+    /**
+     * Point this frame's camera at a lon/lat box — the atlas's per-page refit.
+     * Solves for the zoom that fits the box in the frame's own pixel size, in
+     * the Mercator plane (where the projection is linear), then writes the
+     * camera attributes so everything downstream — corners, scale bar, tokens —
+     * follows from the same source as any authored camera.
+     */
+    fitBounds(bounds: [number, number, number, number]): void;
+    /** Export hook: capture before the page paints (see render.ts). */
+    prepareCartograph(env: PaintEnv): Promise<void>;
+    /** Export hook: forget the capture, so a failed pre-pass never reuses it. */
+    discardCartograph(): void;
+    /**
+     * Swap the live canvas for a print-resolution bitmap. A WebGL canvas prints
+     * blank or at screen resolution — the drawing buffer is not preserved and
+     * the print rasterizer does not re-render it — so the printed page shows a
+     * captured `<img>` instead, restored afterwards.
+     */
+    enterPrintMode(dpi: number): Promise<void>;
+    exitPrintMode(): void;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+    private paintOverview;
+}

package/dist/cartograph/elements/om-graticule.d.ts

@@ -0,0 +1,24 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+import { type Graticule } from "../graticule";
+export declare class OmGraticuleElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    private resolvedPlane;
+    private resolvedPlaneKey;
+    private resolveToken;
+    private get kind();
+    private get labelPlacement();
+    /** The grid this element currently draws, or null when it cannot yet. */
+    get graticule(): Graticule | null;
+    /**
+     * The coordinate system the lattice is walked in. Geographic needs nothing;
+     * a projected grid needs proj4, which resolves asynchronously and triggers
+     * a re-render when it lands.
+     */
+    private gridPlane;
+    protected renderNow(): void;
+    private renderSvg;
+    /** Intersections of this line with the perpendicular family. */
+    private tickPoints;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}

package/dist/cartograph/elements/om-image.d.ts

@@ -0,0 +1,12 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+declare const FITS: readonly ["contain", "cover", "fill"];
+type Fit = (typeof FITS)[number];
+export declare class OmImageElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    get fit(): Fit;
+    get image(): HTMLImageElement | null;
+    protected renderNow(): void;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}
+export {};

package/dist/cartograph/elements/om-legend.d.ts

@@ -0,0 +1,16 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+import { type LegendRow } from "../legend";
+export declare class OmLegendElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    get derived(): boolean;
+    /** The rows this legend currently shows — recomputed on demand, never stored. */
+    get rows(): LegendRow[];
+    protected renderNow(): void;
+    private renderRows;
+    private buildRow;
+    /** The swatch geometry carries meaning: an area, a line and a point read differently. */
+    private buildSwatch;
+    private buildSymbology;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}

package/dist/cartograph/elements/om-north.d.ts

@@ -0,0 +1,11 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+export declare class OmNorthElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    /** Degrees clockwise from the page's "up", or null when unknowable. */
+    get bearing(): number | null;
+    private get indicatorKind();
+    protected renderNow(): void;
+    private buildGeometry;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}

package/dist/cartograph/elements/om-scalebar.d.ts

@@ -0,0 +1,13 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+import { type ScalebarDrawing } from "../scalebar";
+export declare class OmScalebarElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    /** The geometry currently drawn — reused by the canvas exporter. */
+    get drawing(): ScalebarDrawing | null;
+    private get barStyle();
+    private get unitSystem();
+    protected renderNow(): void;
+    private renderSvg;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}

package/dist/cartograph/elements/om-shape.d.ts

@@ -0,0 +1,16 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+export type ShapeKind = "rect" | "ellipse" | "line" | "arrow";
+export declare class OmShapeElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    get kind(): ShapeKind;
+    private get fill();
+    private get stroke();
+    private get strokeWidthMm();
+    private get fillOpacity();
+    private get radiusMm();
+    protected renderNow(): void;
+    /** A line from the box's top-left to its bottom-right, with a solid head. */
+    private arrowPath;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}

package/dist/cartograph/elements/om-text.d.ts

@@ -0,0 +1,9 @@
+import { CartographElementBase } from "../element-base";
+import { type CartographPainter, type PaintEnv } from "../paint";
+export declare class OmTextElement extends CartographElementBase implements CartographPainter {
+    static readonly observedAttributes: string[];
+    protected renderNow(): void;
+    /** Re-run token substitution from the authored templates. */
+    resolveTokens(): void;
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+}