@nika-js/onlymap 0.7.6 → 0.8.0

package/dist/cartograph/georef.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Frame georeferencing — the ONE interface every piece of furniture consumes
+ * (scale bar, north indicator, graticule, locator inset, tokens), so nothing
+ * else has to know whether a frame is a live map or a static raster.
+ *
+ * THE LOAD-BEARING DECISION: the projective homography is fitted in the
+ * frame's CRS PLANE, never in raw lon/lat.
+ *
+ * A map image is a projective (perspective) transform of its own projection
+ * plane — that is exactly what a pitched camera does to flat map coordinates,
+ * and what a north-up crop does trivially. It is NOT a projective transform of
+ * longitude/latitude: Web Mercator's y = R·ln(tan(π/4+φ/2)) is nonlinear in
+ * latitude, so a homography fitted to four lon/lat corners reproduces those
+ * four corners exactly and misplaces every interior point, with error growing
+ * with the frame's latitude span (a 40°-span frame is off by millimetres at
+ * the centre — a visibly wrong graticule). Fitting in the CRS plane makes the
+ * corner fit exact AND the interior correct:
+ *
+ *     project(lngLat) = H · crsForward(lngLat)
+ *
+ * `crsForward` is closed-form for the two CRSs that need no dependency —
+ * EPSG:3857 (spherical Mercator) and EPSG:4326 (plate carrée, where the
+ * forward IS identity, which is why a naive lon/lat fit happens to be right
+ * for equirectangular rasters and wrong for everything else). Any other
+ * projected CRS resolves through the core's lazy proj4 (src/crs.ts) — the
+ * only reason this module ever awaits anything.
+ */
+import type { LngLat } from "../geodesy";
+/** A planar coordinate in a CRS (metres for projected CRSs, degrees for geographic). */
+export type PlaneXY = [number, number];
+/** Forward/inverse pair for a frame's CRS — the plane the homography is fitted in. */
+export interface CrsForward {
+    code: string;
+    forward(lngLat: LngLat): PlaneXY;
+    inverse(xy: PlaneXY): LngLat;
+}
+export declare function mercatorForward([lng, lat]: LngLat): PlaneXY;
+export declare function mercatorInverse([x, y]: PlaneXY): LngLat;
+/** Normalize "3857" / "epsg:3857" / "EPSG::3857" to "EPSG:3857"; null when unparseable. */
+export declare function normalizeCrs(raw: string | null | undefined): string | null;
+/** The CRSs this module handles with no proj4 load. */
+export declare function builtinCrsForward(crs: string | null | undefined): CrsForward | null;
+/**
+ * Resolve any CRS to a forward/inverse pair, loading proj4 (lazily, through
+ * the core's own module) only for codes without a closed form. `crsDef` is an
+ * authored "+proj=…" string for CRSs the library does not bundle.
+ */
+export declare function resolveCrsForward(crs: string | null | undefined, crsDef?: string | null): Promise<CrsForward | null>;
+/** Formulaic UTM definition — the zones no regional table can enumerate. */
+export declare function utmDef(zone: number, hemisphere: "N" | "S"): string | null;
+/** Row-major 3×3: [a,b,c, d,e,f, g,h,i] mapping [x,y,1] → [u,v,w]. */
+export type Mat3 = readonly [number, number, number, number, number, number, number, number, number];
+/**
+ * The homography taking four source points to four destination points.
+ * Sources are normalized (centroid-shifted, isotropically scaled) before the
+ * fit — CRS-plane coordinates run to ±20 000 000 m, and an unnormalized 8×8
+ * DLT on those loses most of its precision.
+ */
+export declare function homographyFromQuad(src: readonly PlaneXY[], dst: readonly PlaneXY[]): {
+    matrix: Mat3;
+    normalize: (p: PlaneXY) => PlaneXY;
+    denormalize: (p: PlaneXY) => PlaneXY;
+} | null;
+export declare function applyMat3(m: Mat3, [x, y]: PlaneXY): PlaneXY | null;
+export declare function invertMat3(m: Mat3): Mat3 | null;
+export interface FrameGeoref {
+    /** The frame's CRS, normalized (e.g. "EPSG:3857"). */
+    readonly crs: string;
+    /** The frame's four corners in lon/lat, order tl, tr, br, bl. */
+    readonly corners: readonly [LngLat, LngLat, LngLat, LngLat];
+    readonly widthMm: number;
+    readonly heightMm: number;
+    /**
+     * True when the corner quad could not produce a usable mapping (collinear
+     * corners, a near-horizon capture). Furniture must refuse to draw rather
+     * than draw something wrong; the validator surfaces it.
+     */
+    readonly degenerate: boolean;
+    /** Lon/lat → millimetres from the FRAME's top-left. Null when off the projective horizon. */
+    project(lngLat: LngLat): {
+        xMm: number;
+        yMm: number;
+    } | null;
+    /** Millimetres from the frame's top-left → lon/lat. Null when unmappable. */
+    unproject(xMm: number, yMm: number): LngLat | null;
+    /** Ground metres per page millimetre along the frame's horizontal centre line. */
+    groundMetersPerMm(): number;
+}
+export interface CreateGeorefOptions {
+    corners: readonly [LngLat, LngLat, LngLat, LngLat];
+    widthMm: number;
+    heightMm: number;
+    /** Resolved CRS plane; defaults to Web Mercator (what live frames always are). */
+    crsForward?: CrsForward | null;
+}
+export declare function createFrameGeoref({ corners, widthMm, heightMm, crsForward }: CreateGeorefOptions): FrameGeoref;
+/**
+ * Parse a `corners=` attribute: JSON `[[lng,lat],[lng,lat],[lng,lat],[lng,lat]]`
+ * (tl, tr, br, bl) or a flat list of eight numbers in the same order. Returns
+ * null for anything else — the validator turns that into an error, because a
+ * frame placed from bad corners looks exactly like one placed from good ones.
+ */
+export declare function parseCorners(raw: string | null | undefined): [LngLat, LngLat, LngLat, LngLat] | null;
+/**
+ * Which way is north, in degrees clockwise from the frame's "up".
+ *
+ * Derived from the georeference rather than from a `bearing` attribute, so it
+ * is correct for every frame kind — a rotated capture, a projected static
+ * raster whose grid north differs from true north, a pitched view. Null when
+ * the frame has no usable mapping.
+ */
+export declare function northBearingDegrees(georef: FrameGeoref): number | null;
+/**
+ * Relative scale variation across a frame's width, as a fraction (0.02 = 2%).
+ *
+ * The quantity a scale bar's honesty depends on: in Mercator the ground
+ * distance per page millimetre changes with sec(latitude), so a bar is only
+ * true near its anchor. Measuring the actual variation is the right test —
+ * a 5° span at the equator is harmless (~0.4%) while 3° at 60°N is not (~9%).
+ */
+export declare function scaleVariation(georef: FrameGeoref): number | null;
+/**
+ * Corners for a north-up frame from a lon/lat bounding box — the shape a
+ * producer has when it exported a plain map view rather than a pitched one.
+ */
+export declare function cornersFromBounds(west: number, south: number, east: number, north: number): [LngLat, LngLat, LngLat, LngLat];

package/dist/cartograph/graticule.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Graticule generation — coordinate grid lines over a frame.
+ *
+ * Two grids, one algorithm. A GEOGRAPHIC graticule draws meridians and
+ * parallels at whole degrees; a PROJECTED grid (a UTM sheet's 1 km squares)
+ * draws lines at whole eastings and northings in the frame's projected CRS.
+ * Both are "walk a regular lattice in some coordinate system, project each
+ * point through the frame's georeference, clip to the frame" — so both come
+ * out of `buildGraticule` with the grid CRS supplying the lattice.
+ *
+ * Lines are DENSIFIED rather than drawn corner to corner: a straight line in
+ * one coordinate system is a curve in another, and a two-point meridian would
+ * visibly bow away from the truth on a wide or rotated frame.
+ */
+import type { LngLat } from "../geodesy";
+import type { FrameGeoref } from "./georef";
+export interface GraticuleLine {
+    /** Points in frame millimetres. */
+    points: {
+        xMm: number;
+        yMm: number;
+    }[];
+    /** The coordinate value this line marks (degrees, or projected metres). */
+    value: number;
+    axis: "x" | "y";
+}
+export interface GraticuleLabel {
+    text: string;
+    xMm: number;
+    yMm: number;
+    /** Which frame edge the label hangs off. */
+    edge: "top" | "bottom" | "left" | "right";
+    axis: "x" | "y";
+}
+export interface Graticule {
+    lines: GraticuleLine[];
+    labels: GraticuleLabel[];
+    /** The interval actually used, after any automatic choice. */
+    intervalX: number;
+    intervalY: number;
+}
+/** A plane the lattice is walked in: identity for geographic, proj4 for projected. */
+export interface GridPlane {
+    /** Grid coordinates → lon/lat, so the georeference can place them. */
+    toLngLat(x: number, y: number): LngLat;
+    /** Lon/lat → grid coordinates, for working out which lines are in view. */
+    fromLngLat(lngLat: LngLat): [number, number];
+}
+/** The geographic plane: grid coordinates ARE lon/lat. */
+export declare const GEOGRAPHIC_PLANE: GridPlane;
+/** A "nice" interval (1-2-5 × 10ⁿ) giving roughly `target` divisions across a span. */
+export declare function niceInterval(span: number, target?: number): number;
+export interface BuildGraticuleOptions {
+    georef: FrameGeoref;
+    plane?: GridPlane;
+    /** Grid spacing in the plane's units; omitted, a nice interval is chosen. */
+    interval?: number | null;
+    intervalX?: number | null;
+    intervalY?: number | null;
+    labels?: "none" | "inside" | "outside";
+    /** Formats a coordinate value for its label. */
+    format?: (value: number, axis: "x" | "y") => string;
+}
+/**
+ * Build the grid for a frame. Returns null when the frame has no usable
+ * georeference — furniture must then refuse to draw rather than guess.
+ */
+export declare function buildGraticule({ georef, plane, interval, intervalX, intervalY, labels, format }: BuildGraticuleOptions): Graticule | null;
+/** Degrees-minutes-seconds, for a geographic graticule that wants it. */
+export declare function formatDms(value: number, axis: "x" | "y"): string;

package/dist/cartograph/html-data.d.ts

@@ -0,0 +1,27 @@
+export interface CartographAttrData {
+    name: string;
+    description: string;
+    values?: {
+        name: string;
+    }[];
+}
+export interface CartographTagData {
+    name: string;
+    description: string;
+    attributes: CartographAttrData[];
+    references?: {
+        name: string;
+        url: string;
+    }[];
+}
+/**
+ * Descriptions for the placement attributes every placed element carries
+ * (schema.ts PLACED_ATTR_NAMES). Millimetres from the page top-left.
+ */
+export declare const PLACED_COMMON: CartographAttrData[];
+/**
+ * The cartograph tags for `onlymapjs.html-data.json` — merged into
+ * buildHtmlCustomData()'s output by src/html-data.ts so ONE custom-data
+ * file ships for the whole package.
+ */
+export declare function buildCartographHtmlData(): CartographTagData[];

package/dist/cartograph/index.d.ts

@@ -0,0 +1 @@
+export * from "./api";

package/dist/cartograph/layout.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Page geometry — the one place millimetres meet pixels.
+ *
+ * CSS defines 1mm ≡ 96/25.4 px, so elements positioned with mm CSS units
+ * agree between screen preview and print BY CONSTRUCTION; this constant
+ * exists only for canvas compositing (renderCartograph) and tests. Nothing
+ * else in src/cartograph/ multiplies by 3.78.
+ */
+export declare const PX_PER_MM: number;
+export interface PageSizeMm {
+    widthMm: number;
+    heightMm: number;
+}
+/** Page presets in PORTRAIT mm — orientation="landscape" swaps them. */
+export declare const PAGE_PRESETS: Readonly<Record<string, PageSizeMm>>;
+export declare const DEFAULT_PAGE_SIZE = "A4";
+/**
+ * Resolve the page box from the authored attributes. Explicit width+height
+ * (custom size) win over the preset; an unknown preset falls back to A4 so
+ * the page still renders (the validator flags it — Phase 1). Orientation
+ * applies to presets only: custom dimensions are already oriented.
+ */
+export declare function resolvePageSize(size: string | null, width: string | null, height: string | null, orientation: string | null): PageSizeMm;

package/dist/cartograph/legend.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Legend derivation.
+ *
+ * THE INVARIANT: a cartograph legend is never stored. Its rows are computed
+ * from the frame's map at render time, so the legend cannot drift out of
+ * agreement with the map it describes — the failure class that makes printed
+ * cartography untrustworthy, and the one QGIS still has.
+ *
+ * The source of truth is the mounted map's own IR (`getLayers()` →
+ * `meta.legend`, `meta.label`, `meta.color`), NOT a re-parse of the authored
+ * colour attributes. That matters: `meta.legend` is also populated by the
+ * `classify=` family (class breaks computed from the DATA, which no static
+ * read of the attributes could reproduce) and by rasters resolving their
+ * domain at load. Re-deriving from source would silently disagree with the
+ * map for exactly the layers whose symbology was computed rather than
+ * authored.
+ */
+import type { LegendSpec } from "../legend-spec";
+/** The swatch a row draws — the geometry a reader expects for that layer kind. */
+export type SwatchShape = "polygon" | "line" | "point" | "ramp";
+export interface LegendRow {
+    layerId: string;
+    label: string;
+    /** Primary colour for the row's swatch. */
+    color: string;
+    shape: SwatchShape;
+    /** Full symbology detail (ramp stops, class or category entries), when the layer has one. */
+    legend?: LegendSpec;
+    /** Sort key from an `order=` override; rows without one keep map order. */
+    order?: number;
+}
+/** The subset of a layer's IR the legend needs — structurally what `getLayers()` returns. */
+export interface LegendLayerInput {
+    id: string;
+    type?: string;
+    meta?: {
+        label?: string;
+        color?: string;
+        legend?: LegendSpec;
+    };
+    props?: {
+        visible?: boolean;
+        [key: string]: unknown;
+    };
+}
+export declare function swatchShapeFor(layer: LegendLayerInput): SwatchShape;
+/** The row swatch, matching the core legend widget's own rule exactly. */
+export declare function rowColorFor(layer: LegendLayerInput): string;
+/** Categories beyond this many collapse into a "+N more" row — a printed legend has finite space. */
+export declare const MAX_CATEGORY_ENTRIES = 12;
+export interface LegendRowOverride {
+    layer: string;
+    /** Which derived row to target: a category value or class label. Absent targets the layer's row. */
+    match?: string;
+    label?: string;
+    hide?: boolean;
+    order?: number;
+    color?: string;
+    shape?: SwatchShape;
+}
+/**
+ * Derive the rows for a legend from a frame's layers, applying overrides.
+ *
+ * Hidden layers are omitted (the core legend widget shows the layer row but
+ * not its symbology; on paper an invisible layer has no business appearing at
+ * all).
+ */
+export declare function deriveLegendRows(layers: readonly LegendLayerInput[], overrides?: readonly LegendRowOverride[]): LegendRow[];
+/** Read `<om-legend-row>` children into override records. */
+export declare function readOverrides(legendEl: Element): LegendRowOverride[];
+/**
+ * Literal rows for a legend that cannot derive — a static frame has no layers,
+ * so the producer writes the rows and marks the legend `derived="false"`.
+ */
+export declare function readLiteralRows(legendEl: Element): LegendRow[];

package/dist/cartograph/live-frame.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Mounting a live map inside a frame, and turning its camera into a
+ * georeference.
+ *
+ * Two jobs the frame element delegates here so its own file stays about
+ * placement and rendering:
+ *
+ *  1. SANITIZED ADOPTION of a map manifest fetched from `src=`. A cartograph
+ *     may reference a map document from anywhere, and the fetched HTML is
+ *     rebuilt element by element rather than assigned through innerHTML:
+ *     scripts are dropped except the inert `application/json` blocks that
+ *     carry inline layer data, and `on*` handler attributes never survive.
+ *     An inline `<om-map>` CHILD is not sanitized — the author already owns
+ *     that document.
+ *  2. CORNERS FROM THE CAMERA. A live frame's georeference comes from its own
+ *     `center/zoom/bearing/pitch` and its pixel box, through the core's
+ *     WebMercatorViewport — the same viewport class the renderer uses, so the
+ *     furniture agrees with the pixels.
+ */
+import type { LngLat } from "../geodesy";
+import { type CoreModule } from "./core-loader";
+export type Corners = [LngLat, LngLat, LngLat, LngLat];
+/**
+ * Rebuild a fetched subtree as fresh elements, keeping only inert content.
+ * Returns null if the source has nothing to adopt.
+ */
+export declare function sanitizeAdoptedMap(source: Element, doc: Document): Element | null;
+/** Fetch a map document and return its `<om-map>`, sanitized and ready to mount. */
+export declare function fetchMapElement(src: string, doc?: Document): Promise<Element>;
+export interface FrameCamera {
+    center: LngLat;
+    zoom: number;
+    bearing: number;
+    pitch: number;
+}
+/** Read the frame's own camera; null when it has not authored one. */
+export declare function readCamera(el: Element): FrameCamera | null;
+/**
+ * The four ground corners a camera sees in a `widthPx × heightPx` box, in
+ * tl, tr, br, bl order.
+ *
+ * Null when the view cannot be georeferenced as a quad: past roughly 60° of
+ * pitch the top edge unprojects at or beyond the horizon, where "the ground
+ * under this pixel" has no finite answer. Returning null there — rather than
+ * a huge number that looks like a coordinate — is what lets the frame mark
+ * itself degenerate and the furniture refuse to draw.
+ */
+export declare function cornersFromCamera(core: CoreModule, camera: FrameCamera, widthPx: number, heightPx: number): Corners | null;
+/** Load the core and build an `<om-map>` for a frame, from `src=` or an inline child. */
+export declare function buildLiveMap(frame: Element): Promise<{
+    core: CoreModule;
+    map: Element;
+}>;
+/**
+ * Stamp the FRAME's camera onto the map. The frame's camera is authoritative
+ * by design: the same map document can appear twice on one page at different
+ * extents (the locator-inset pattern), so the document's own center/zoom are
+ * deliberately ignored.
+ *
+ * TWO steps, and the second is not optional. `<om-map>` reads center/zoom ONCE,
+ * as its initial view — its attribute observer deliberately does not watch the
+ * camera, so that a manifest edit never fights a user's pan. An inline
+ * `<om-map>` child has therefore already booted at ITS OWN camera by the time a
+ * frame mounts it, and writing the attributes alone leaves the map sitting
+ * wherever the document said (for a fresh document, [0,0] at zoom 1 — an empty
+ * ocean). So the attributes are written for the DOM's sake (serialization,
+ * agents, re-mounts) and the live camera is driven through the runtime.
+ */
+export declare function applyCamera(map: Element, camera: FrameCamera): void;

package/dist/cartograph/paint.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The canvas paint contract used by `renderCartograph`.
+ *
+ * Every placed element knows how to draw itself onto a 2D context at an
+ * arbitrary scale, so export is a walk over the page's own children rather
+ * than a second, drifting description of the page. Painters read their
+ * COMPUTED style — the browser has already resolved theme custom properties,
+ * attribute overrides and inherited values, so the exported pixels use exactly
+ * the values the screen and the printed page use.
+ */
+export interface PaintEnv {
+    /** Canvas pixels per CSS pixel — dpi / 96. */
+    scale: number;
+    /** Canvas pixels per millimetre — dpi / 25.4. */
+    pxPerMm: number;
+}
+export declare function paintEnvForDpi(dpi: number): PaintEnv;
+export interface CartographPainter {
+    /**
+     * Draw this element. The context is pre-translated to the element's own
+     * top-left corner and rotated by its `rotation`, so painters draw in their
+     * own local box starting at (0, 0), in CANVAS pixels.
+     */
+    paintCartograph(ctx: CanvasRenderingContext2D, env: PaintEnv): void;
+    /**
+     * Optional async pre-pass, awaited before ANY element paints. A live frame
+     * uses it to re-render its map at the export resolution; painting itself
+     * stays synchronous so the composite order is trivially deterministic.
+     */
+    prepareCartograph?(env: PaintEnv): Promise<void>;
+    /**
+     * Drop anything `prepareCartograph` produced, so a failed pre-pass paints
+     * nothing rather than the previous page's stale capture.
+     */
+    discardCartograph?(): void;
+}
+export declare function isPainter(node: unknown): node is Element & CartographPainter;
+export interface BoxMm {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rotation: number;
+    z: number | null;
+}
+/** An element's authored box in millimetres — the placement source of truth. */
+export declare function boxMm(el: Element): BoxMm;
+/**
+ * Resolve a computed-style length (e.g. "12.5px") to a number, with a
+ * fallback for the values happy-dom and other partial DOMs leave empty.
+ */
+export declare function styleLength(value: string | null | undefined, fallback?: number): number;
+/** A CSS colour that actually paints — treats empty/transparent as "skip". */
+export declare function paintableColor(value: string | null | undefined): string | null;

package/dist/cartograph/refs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cross-element references (`for=`, `overview-of=`, atlas `for=`) and the
+ * shared "this reference goes nowhere" rendering.
+ *
+ * A dangling reference is a validation ERROR and renders a visible inline
+ * placeholder, never nothing: a scale bar that silently vanishes because its
+ * frame id has a typo is indistinguishable, on a printed page, from a scale
+ * bar the author chose not to include.
+ */
+import type { OmFrameElement } from "./elements/om-frame";
+/** The `<om-cartograph>` an element belongs to. */
+export declare function ownerCartograph(el: Element): Element | null;
+/** Resolve a frame id within the same cartograph. */
+export declare function findFrame(el: Element, id: string | null | undefined): OmFrameElement | null;
+/** Every frame on the page, in document order. */
+export declare function allFrames(root: Element): OmFrameElement[];
+/** The frame a `for=`-less furniture element implicitly binds to (only when there is exactly one). */
+export declare function soleFrame(el: Element): OmFrameElement | null;
+/**
+ * Resolve the frame this element draws for: an explicit `for=`, or the page's
+ * only frame when `for=` is absent.
+ */
+export declare function referencedFrame(el: Element): OmFrameElement | null;
+/** Show the inline "unlinked" note, replacing whatever the element rendered. */
+export declare function showUnlinked(el: HTMLElement, message: string): void;
+/**
+ * Drop the "unlinked" note once the element can render for real. Elements that
+ * rebuild their whole subtree get this for free; one that APPENDS its output
+ * (om-legend, which must preserve its authored config children) has to say so,
+ * or the page keeps a stale "waiting for its frame" line above a legend that
+ * is already showing rows.
+ */
+export declare function clearUnlinked(el: Element): void;

package/dist/cartograph/render.d.ts

@@ -0,0 +1,64 @@
+import type { OmCartographElement } from "./elements/om-cartograph";
+/**
+ * Conservative canvas ceilings. Browsers differ (Chrome allows ~2^28 px of
+ * area, iOS Safari far less), and exceeding them fails SILENTLY — a blank or
+ * null-blob export. Clamping to a documented budget and REPORTING the dpi
+ * actually delivered beats handing back an empty page.
+ */
+export declare const MAX_CANVAS_DIMENSION = 16384;
+export declare const MAX_CANVAS_AREA = 134217728;
+export interface RenderCartographOptions {
+    /** Target resolution; defaults to the page's dpi= attribute, else 300. */
+    dpi?: number;
+    format?: "png" | "jpeg";
+    /** JPEG quality 0–1 (ignored for PNG). */
+    quality?: number;
+    /** Override the canvas ceilings (tests, hosts that know their environment). */
+    maxDimension?: number;
+    maxArea?: number;
+    /**
+     * Simulate a colour-vision deficiency in the exported raster
+     * (NikaGeospatial/onlymap-js#42). Default
+     * NONE — even when the page is being previewed under `cvd=`, because an
+     * export is a deliverable and a simulated deliverable helps nobody. Pass
+     * `"page"` to honour the page's own `cvd=`, or a type to force one.
+     */
+    cvd?: string | null;
+}
+export interface RenderCartographResult {
+    blob: Blob;
+    widthPx: number;
+    heightPx: number;
+    /** The resolution actually delivered — lower than requested when clamped. */
+    dpi: number;
+    /** Non-fatal problems worth surfacing to the user (clamping, skipped frames). */
+    warnings: string[];
+}
+export declare function renderCartograph(page?: OmCartographElement | null, options?: RenderCartographOptions): Promise<RenderCartographResult>;
+export interface RenderAtlasOptions extends RenderCartographOptions {
+    /** Render only this page (0-based) — the host contract for `?export=&page=i`. */
+    page?: number;
+    /** Called after each page, for progress reporting on a long run. */
+    onPage?: (index: number, count: number) => void;
+}
+export interface RenderAtlasResult {
+    /** One ZIP of every page, or the single page's own image when `page` was given. */
+    blob: Blob;
+    filenames: string[];
+    pages: number;
+    dpi: number;
+    warnings: string[];
+}
+/**
+ * Render every page of an atlas.
+ *
+ * SEQUENTIALLY, and reusing the one live map: seeking moves the existing
+ * frames rather than cloning the page. Cloning would mount a fresh WebGL
+ * context per page, and browsers cap live contexts at roughly 8–16 — an atlas
+ * of any useful size would silently start printing blank pages. This way the
+ * ceiling is one map, whatever N is.
+ *
+ * The result is a single ZIP because browsers block or prompt on a loop of N
+ * downloads; a host wanting one page at a time passes `page`.
+ */
+export declare function renderCartographAtlas(page?: OmCartographElement | null, options?: RenderAtlasOptions): Promise<RenderAtlasResult>;

package/dist/cartograph/scalebar.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Scale-bar maths — ground distance per page millimetre, and the "nice"
+ * segment lengths a printed bar is allowed to use.
+ *
+ * A scale bar whose segments read "0 · 347 · 694 m" is useless to the person
+ * holding a ruler over the page, so segment lengths snap to a 1-2-5 series
+ * (1, 2, 5, 10, 20, 50, …) in the bar's own unit system, and the bar's drawn
+ * width follows from that choice rather than the other way round.
+ */
+import { type UnitSystem } from "../units";
+export type ScalebarUnits = UnitSystem;
+export { niceNumberBelow } from "../units";
+export interface ScalebarSpec {
+    /** Ground metres spanned by ONE segment. */
+    segmentMeters: number;
+    /** Page millimetres spanned by one segment. */
+    segmentMm: number;
+    segments: number;
+    /** Total drawn width, mm (segments × segmentMm). */
+    totalMm: number;
+    /** Tick labels, one per boundary (segments + 1 of them), in `unitLabel` units. */
+    labels: string[];
+    unitLabel: string;
+    /** The representative fraction denominator — the "1:25 000" number. */
+    scaleDenominator: number;
+}
+export interface ScalebarOptions {
+    groundMetersPerMm: number;
+    /** The bar's authored box width in mm — the bar is drawn at or below this. */
+    maxWidthMm: number;
+    segments?: number;
+    units?: ScalebarUnits;
+    /** Ground metres per segment, overriding the automatic 1-2-5 choice. */
+    segmentLengthMeters?: number | null;
+}
+/**
+ * Build the bar. Null when there is no usable scale (a degenerate georef, a
+ * zero-width box) — furniture must render an inline "no scale" placeholder
+ * rather than a bar that lies.
+ */
+export declare function buildScalebar({ groundMetersPerMm, maxWidthMm, segments, units, segmentLengthMeters }: ScalebarOptions): ScalebarSpec | null;
+export type ScalebarStyle = "single" | "double" | "line" | "ticks";
+export interface ScalebarDrawing {
+    /** Filled/hollow segment rectangles, in mm relative to the element's box. */
+    bars: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        filled: boolean;
+    }[];
+    /** Rules and ticks, in mm. */
+    strokes: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    }[];
+    /** Tick labels — `y` is the text BASELINE, in mm. */
+    labels: {
+        text: string;
+        x: number;
+        y: number;
+        anchor: "start" | "middle" | "end";
+    }[];
+    fontMm: number;
+    strokeMm: number;
+    /** Ground metres one segment spans — carried here so a host drawing the bar needs nothing else. */
+    segmentMeters: number;
+    /** Unit the labels are in ("m", "km", "mi", "nmi"). */
+    unitLabel: string;
+    /** Representative-fraction denominator at this scale. */
+    scaleDenominator: number;
+}
+/**
+ * Turn a computed bar into geometry, ONCE. The SVG renderer and the canvas
+ * exporter both consume this, so an exported PNG and the printed page cannot
+ * disagree about where the ticks are.
+ */
+export declare function buildScalebarDrawing(spec: ScalebarSpec, style: ScalebarStyle, boxHeightMm: number): ScalebarDrawing;
+/**
+ * Digit-group separator for printed scale text: U+202F NARROW NO-BREAK SPACE.
+ * ISO 31-0 / SI group digits with a thin space rather than a comma or point
+ * (which mean different things either side of the Atlantic), and the NO-BREAK
+ * variant is the one a printed page needs — "1:25 000" must never wrap across
+ * a line. Pinned by codepoint in the tests so it cannot drift to an ASCII
+ * space during a copy-edit.
+ */
+export declare const SCALE_GROUP_SEPARATOR = "\u202F";
+/** "1:25 000" — the representative fraction, grouped for print. */
+export declare function formatScaleDenominator(denominator: number): string;