@orbat-mapper/tactical-map-sheet 0.1.2 → 0.2.0

package/README.md

@@ -5,9 +5,9 @@ Public package for deterministic, scale-accurate tactical map sheets.
 The package creates transparent or explicitly backed, grid-north-up UTM/UPS SVG and PDF
 sheets from physical page data, a geographic center, nominal true-ground scale, and normalized authored layers.
 It supports automatic or explicit projection selection, deterministic UTM/UPS MGRS grids, control
-measures, renderer-neutral point symbols, custom vector symbols, and complete configurable
-marginalia. One center-selected CRS is retained across zone and polar transitions and any usable
-distortion or fallback is reported through structured warnings.
+measures, renderer-neutral point symbols, custom vector symbols, physically registered overlays,
+and complete configurable marginalia. One center-selected CRS is retained across zone and polar
+transitions and any usable distortion or fallback is reported through structured warnings.
 
 ## Install and entry points
 
@@ -74,9 +74,61 @@ Regular/Caps, Italic, and Light semantic text use complete package-owned Open Sa
 one final-size metrics service. Their license, immutable provenance, and SHA-256 identities live
 under `src/assets/`.
 
-Projection and grid primitives remain private. The `geographiclib-mgrs` backend is qualified against
-GeographicLib/GEOTRANS vectors, Norway/Svalbard zone rules, explicit-zone and round-trip behavior,
-UTM/UPS transitions, poles, MGRS precision boundaries, TypeScript/ESM, Node, and browser bundling.
+The package owns public MGRS utilities for parsing, normalization, conversion, formatting, and
+snapping. MGRS text accepts case and whitespace variations and normalizes to compact uppercase.
+Finite-precision references identify the southwest intersection of their grid cell, never its
+center. Geographic positions use GeoJSON order (`[longitude, latitude]`); projected results carry an
+explicit UTM or UPS `crs` alongside metre `easting` and `northing` values. The
+`geographiclib-mgrs` backend is qualified against GeographicLib/GEOTRANS vectors, Norway/Svalbard
+zone rules, explicit-zone and round-trip behavior, UTM/UPS transitions, poles, MGRS precision
+boundaries, TypeScript/ESM, Node, and browser bundling.
+
+## Registered physical overlays
+
+Add `registration` to turn a normal sheet into a registered overlay. The page, map frame,
+geographic center, projection, and nominal scale remain authoritative: registration validates the
+chosen sheet and never fits, rotates, resizes, or relocates it.
+
+```ts
+const registered = createTacticalMapSheet({
+  page: { widthMm: 297, heightMm: 210, marginMm: 10 },
+  center: [-2.5, 49.2],
+  scaleDenominator: 25_000,
+  registration: {
+    marks: [
+      { id: "southwest", mgrs: "30u wv 33924 48309", label: "SW" },
+      { id: "northeast", mgrs: "30UWV3892451309" },
+    ],
+    snapIntervalMeters: 1_000,
+  },
+  marginalia: { showFrameCornerMarks: false, showCalibrationMarks: false },
+  printerCalibration: {},
+});
+```
+
+Registration requires at least two marks with unique non-empty IDs. Every MGRS reference is
+normalized and resolves to its southwest grid intersection, then optionally snaps at 100 m, 1 km,
+10 km, or 100 km. A mark must use the sheet's UTM zone and hemisphere, or the same UPS hemisphere.
+Its complete fixed 8 mm black crosshair and labels must fit inside the printable frame. A non-empty
+authored label is placed inward from the crosshair. Otherwise, the MGRS easting is placed to its left
+and the northing below it in the conventional abbreviated arrangement. At 100 km precision, the
+grid-square column and row letters take those positions. At least one pair must span 50% of the frame
+diagonal and 25% of both frame axes. Any invalid mark rejects the complete request; marks are never
+omitted or moved.
+
+Registered overlays are transparent. An explicit non-transparent `page.background` is rejected.
+SVG and PDF results expose the same ordered `registrationMarks`, each containing the authored ID,
+normalized `mgrs`, GeoJSON-order `position`, and derived `sheetPositionMm`. The optional full MGRS
+grid, tactical layers, and marginalia remain independent.
+
+`printerCalibration: {}` adds a 100 mm diagnostic line, endpoint ticks, and length label centered
+in the bottom page margin. Set a positive `lengthMm` to choose another length. The request fails if
+the complete calibration artwork does not fit; calibration never changes sheet geometry, coverage,
+scale, or mark positions.
+
+Print registered SVG or PDF output at **100% / Actual Size** with **Fit to page disabled**. If the
+calibration line measures incorrectly, correct the printer settings and reprint; do not compensate
+by resizing the overlay.
 
 Point-symbol renderers enter through a capability that returns complete SVG, bounds, doctrinal and
 octagon anchors. Point and custom symbols then use the same conservative vector subset. Raster,
@@ -142,6 +194,9 @@ Application stores and map-engine output are not part of the public request cont
   matching precision 3, 2, 1, or 0; plus color, line width, and label size).
 - `layers`: ordered `TacticalMapSheetLayer[]`; `pointSymbols`: the optional renderer capability;
   `marginalia`: `false` or display options; `metadata`: optional document text.
+- `registration`: optional grouped MGRS marks and `snapIntervalMeters`; its presence activates
+  strict transparent registered-overlay validation.
+- `printerCalibration`: optional bottom-margin diagnostic line; `lengthMm` defaults to 100.
 
 Each layer has a stable `id`, ordered `{ graphic }[]`, and optional shared portrayal defaults for
 color, line/dash/cap/join, and label size/clamp. A graphic is a control-measure `ControlMeasure`, a
@@ -153,9 +208,37 @@ must return a `ControlledVectorSymbol`: stable resource ID, controlled-subset SV
 height, octagon size, placement anchor, octagon anchor, and optional validation state. Custom symbols
 carry that same vector record directly. Metre sizes may specify pixel clamps.
 
+### Paper presets
+
+`PAPER_SIZES` contains exact portrait millimetre dimensions for `a0` through `a4`, `letter`, `legal`,
+`tabloid`, `ansi-c`, `ansi-d`, `ansi-e`, and `arch-d`. `ledger` aliases `tabloid`; `ansi-a` aliases
+`letter`; and `ansi-b` aliases `tabloid`, so aliases share one physical definition. ANSI D is
+558.8 × 863.6 mm and remains distinct from 609.6 × 914.4 mm ARCH D.
+
+`resolvePaperSize(name, orientation)` returns `{ widthMm, heightMm }` for direct use as a page input.
+Portrait is the default and landscape swaps the axes. Presets are optional conveniences: callers can
+continue supplying arbitrary positive `widthMm` and `heightMm`, which remain authoritative during
+rendering.
+
+### MGRS utilities
+
+- `parseMgrsReference` validates a complete UTM or UPS reference and returns its compact-uppercase
+  form, precision, explicit grid CRS, projected metre coordinates, and GeoJSON-order position.
+- `normalizeMgrsReference`, `mgrsToProjected`, and `mgrsToGeographic` expose focused forms of that
+  parsed result. Geographic conversion always returns the southwest grid-cell intersection.
+- `geographicToMgrs` and `projectedToMgrs` format coordinates at precision 0 through 5 (100 km
+  through 1 m). Projected input includes its explicit UTM zone/hemisphere or UPS hemisphere.
+- `snapGeographicToMgrs` and `snapProjectedToMgrs` accept 100 m, 1 km, 10 km, or 100 km. Already
+  aligned intersections stay fixed; exact halfway ties move toward increasing easting and northing.
+
 `MapSheetMarginaliaOptions` controls color and visibility of declared scale, scale bar, grid/north,
-registration marks, calibration marks, and footprint. `MapSheetMetadata` supplies optional title,
-subtitle, classification, and preparer text.
+frame-corner marks, legacy calibration marks, and footprint. Grid/north marginalia includes the
+MGRS grid-zone designation for the sheet center. Use `showFrameCornerMarks` for the
+canonical ungeoreferenced corner crosses. Deprecated `showRegistrationMarks` remains an alias; when
+both are supplied, `showFrameCornerMarks` takes precedence. Deprecated `showCalibrationMarks`
+continues to control the existing pair of 10 mm legacy marks and is independent of
+`printerCalibration`. `MapSheetMetadata` supplies optional title, subtitle, classification, and
+preparer text.
 
 ### Results and resolved metadata
 
@@ -168,9 +251,12 @@ subtitle, classification, and preparer text.
   hemisphere, EPSG, center point scale, center convergence in degrees, and maximum frame scale
   deviation).
 - `resources`: identities for embedded Open Sans fonts and deterministic pattern resources.
+- `registrationMarks`: when registered, the ordered resolved IDs, normalized MGRS references,
+  longitude/latitude positions, and physical sheet positions in millimetres.
 
 `renderMapSheetPdf(request)` accepts the identical request and returns `TacticalMapSheetPdfResult`:
-`pdf: Uint8Array` plus the same footprint, warnings, metadata, and resources as the SVG result.
+`pdf: Uint8Array` plus the same footprint, warnings, metadata, resources, and resolved registration
+marks as the SVG result.
 
 ### Warning union
 

package/dist/{create-tactical-map-sheet-Wpo49_IR.mjs → create-tactical-map-sheet-DSmO71Oa.mjs}

@@ -5,7 +5,7 @@ import { DEFAULT_LABEL_HEIGHT_CSS_PIXELS, DEFAULT_LABEL_SIZE_CLAMP_CSS_PIXELS, D
 import { SaxesParser } from "saxes";
 //#region src/projection/geographic-lib.ts
 const backend = GeographicLibMgrs.UTMUPS;
-const mgrsBackend = GeographicLibMgrs.MGRS;
+const mgrsBackend$1 = GeographicLibMgrs.MGRS;
 const FORCE_UTM_ZONE_SELECTION = -2;
 const UPS_FALSE_ORIGIN_METERS = 2e6;
 const polarBackend = PolarStereographic.UPS();
@@ -106,7 +106,7 @@ const geographicLibGridProjection = {
 		assertGridCrs(crs);
 		if (!Number.isInteger(precision) || precision < 0 || precision > 5) throw new RangeError("MGRS precision must be an integer from 0 through 5");
 		if (!Number.isFinite(point.easting) || !Number.isFinite(point.northing)) throw new RangeError("Projected coordinates must be finite");
-		return mgrsBackend.forward(crs.kind === "utm" ? crs.zone : 0, crs.hemisphere === "north", point.easting, point.northing, precision);
+		return mgrsBackend$1.forward(crs.kind === "utm" ? crs.zone : 0, crs.hemisphere === "north", point.easting, point.northing, precision);
 	}
 };
 //#endregion
@@ -255,6 +255,23 @@ function createRegularSceneText(input) {
 	};
 }
 //#endregion
+//#region src/scene-line.ts
+/** Stroke width shared by marginalia, registration, and calibration line work. */
+const DEFAULT_LINE_STROKE_WIDTH_MM = .2;
+/** Build a plain solid scene line: butt caps, mitre joins, no dashes. */
+function createSceneLine(points, color, options = {}) {
+	return {
+		kind: "path",
+		points,
+		strokeColor: color,
+		strokeWidthMm: options.strokeWidthMm ?? .2,
+		strokeDashMm: [],
+		lineCap: "butt",
+		lineJoin: "miter",
+		...options.attributes ? { attributes: options.attributes } : {}
+	};
+}
+//#endregion
 //#region src/validation.ts
 function requirePositiveFinite(value, name) {
 	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a positive finite number`);
@@ -277,18 +294,24 @@ function projectedToScenePoint(projected, context) {
 	};
 }
 //#endregion
-//#region src/mgrs-grid.ts
-const SUPPORTED_INTERVALS = [
+//#region src/mgrs-domain.ts
+const MGRS_SNAP_INTERVALS = [
 	100,
 	1e3,
 	1e4,
 	1e5
 ];
+function mgrsPrecisionForInterval(interval) {
+	if (!MGRS_SNAP_INTERVALS.includes(interval)) throw new RangeError("MGRS interval must be 100, 1000, 10000, or 100000 metres");
+	return Math.round(Math.log10(1e5 / interval));
+}
+//#endregion
+//#region src/mgrs-grid.ts
 function resolveGrid(options, context) {
-	const automatic = SUPPORTED_INTERVALS.find((candidate) => candidate / context.projectedMetresPerMillimetre >= 10);
+	const automatic = MGRS_SNAP_INTERVALS.find((candidate) => candidate / context.projectedMetresPerMillimetre >= 10);
 	const intervalMeters = options.intervalMeters ?? automatic ?? 1e5;
-	if (!SUPPORTED_INTERVALS.includes(intervalMeters)) throw new RangeError("MGRS interval must be 100, 1000, 10000, or 100000 metres");
-	const expectedPrecision = Math.round(Math.log10(1e5 / intervalMeters));
+	if (!MGRS_SNAP_INTERVALS.includes(intervalMeters)) throw new RangeError("MGRS interval must be 100, 1000, 10000, or 100000 metres");
+	const expectedPrecision = mgrsPrecisionForInterval(intervalMeters);
 	const precision = options.precision ?? expectedPrecision;
 	if (precision !== expectedPrecision) throw new RangeError("MGRS precision must match the selected grid interval");
 	const lineWidthCssPixels = options.lineWidthCssPixels ?? .75;
@@ -339,15 +362,7 @@ function renderMgrsGrid(options, context) {
 	const xMm = (easting) => eastingToMillimetres(easting, context);
 	const yMm = (northing) => northingToMillimetres(northing, context);
 	const strokeWidthMm = resolved.lineWidthCssPixels * MILLIMETRES_PER_CSS_PIXEL;
-	const gridLine = (points) => ({
-		kind: "path",
-		points,
-		strokeColor: resolved.color,
-		strokeWidthMm,
-		strokeDashMm: [],
-		lineCap: "butt",
-		lineJoin: "miter"
-	});
+	const gridLine = (points) => createSceneLine(points, resolved.color, { strokeWidthMm });
 	const elements = [...eastings.flatMap((easting) => {
 		const gridLabel = label(geographicLibGridProjection.formatMgrs(context.crs, {
 			easting,
@@ -401,17 +416,8 @@ function text(value, xMm, yMm, sizeCssPixels, color, anchor = "middle") {
 		anchor
 	});
 }
-function line(points, color, attributes) {
-	return {
-		kind: "path",
-		points,
-		strokeColor: color,
-		strokeWidthMm: .2,
-		strokeDashMm: [],
-		lineCap: "butt",
-		lineJoin: "miter",
-		...attributes ? { attributes } : {}
-	};
+function line$1(points, color, attributes) {
+	return createSceneLine(points, color, { attributes });
 }
 function formatScale(scaleDenominator) {
 	return Math.round(scaleDenominator).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
@@ -445,7 +451,7 @@ function renderMarginalia(options, context) {
 		const barX = context.frame.xMm;
 		const barY = bottomY;
 		const representedMeters = barWidthMm * context.scaleDenominator / 1e3;
-		elements.push(line([{
+		elements.push(line$1([{
 			xMm: barX,
 			yMm: barY
 		}, {
@@ -454,7 +460,7 @@ function renderMarginalia(options, context) {
 		}], color, { "data-scale-bar-m": representedMeters }));
 		for (let step = 0; step <= 4; step += 1) {
 			const xMm = barX + barWidthMm * step / 4;
-			elements.push(line([{
+			elements.push(line$1([{
 				xMm,
 				yMm: barY - 1
 			}, {
@@ -467,21 +473,21 @@ function renderMarginalia(options, context) {
 	if (options.showGridAndNorth !== false) {
 		const gridName = context.crs.kind === "utm" ? `UTM ${context.crs.zone}${context.crs.hemisphere === "north" ? "N" : "S"}` : `UPS ${context.crs.hemisphere === "north" ? "NORTH" : "SOUTH"}`;
 		const rightX = context.frame.xMm + context.frame.widthMm;
-		elements.push(text(`${gridName} / EPSG:${context.epsg}`, rightX, bottomY - 1.5, 6, color, "end"));
+		elements.push(text(`MGRS GRID ZONE ${context.mgrsGridZone} · ${gridName} / EPSG:${context.epsg}`, rightX, bottomY - 1.5, 6, color, "end"));
 		elements.push(text(`GRID NORTH · TRUE NORTH · CONVERGENCE ${context.convergenceDegrees.toFixed(3)}°`, rightX, bottomY + 1.5, 5, color, "end"));
 	}
-	if (options.showRegistrationMarks !== false) for (const [index, [xMm, yMm]] of [
+	if (options.showFrameCornerMarks ?? options.showRegistrationMarks ?? true) for (const [index, [xMm, yMm]] of [
 		[context.frame.xMm, context.frame.yMm],
 		[context.frame.xMm + context.frame.widthMm, context.frame.yMm],
 		[context.frame.xMm + context.frame.widthMm, context.frame.yMm + context.frame.heightMm],
 		[context.frame.xMm, context.frame.yMm + context.frame.heightMm]
-	].entries()) elements.push(line([{
+	].entries()) elements.push(line$1([{
 		xMm: xMm - 2,
 		yMm
 	}, {
 		xMm: xMm + 2,
 		yMm
-	}], color, { "data-registration-mark": index }), line([{
+	}], color, { "data-registration-mark": index }), line$1([{
 		xMm,
 		yMm: yMm - 2
 	}, {
@@ -502,7 +508,7 @@ function renderMarginalia(options, context) {
 		}, {
 			xMm: centerX + calibrationLengthMm / 2,
 			yMm: context.frame.yMm + context.frame.heightMm + 1
-		}]].entries()) elements.push(line([start, end], color, {
+		}]].entries()) elements.push(line$1([start, end], color, {
 			"data-calibration-mark": index,
 			"data-calibration-length-mm": calibrationLengthMm
 		}));
@@ -1616,6 +1622,329 @@ function assertNever(value) {
 	throw new Error(`Unsupported geometry: ${String(value)}`);
 }
 //#endregion
+//#region src/mgrs.ts
+const mgrsBackend = GeographicLibMgrs.MGRS;
+function invalidReference(reference, cause) {
+	const detail = cause instanceof Error ? cause.message : String(cause);
+	return /* @__PURE__ */ new RangeError(`Invalid MGRS reference ${JSON.stringify(reference)}: ${detail}`);
+}
+function compactReference(reference) {
+	if (typeof reference !== "string") throw invalidReference(String(reference), "expected a string");
+	const normalized = reference.replace(/\s/g, "").toUpperCase();
+	const match = /^(?:0[1-9]|[1-9]|[1-5][0-9]|60)[C-HJ-NP-X][A-HJ-NP-Z]{2}(\d*)$/.exec(normalized) ?? /^[ABYZ][A-HJ-NP-Z]{2}(\d*)$/.exec(normalized);
+	if (!match) throw invalidReference(reference, "expected a complete UTM or UPS grid reference");
+	if (match[1].length % 2 !== 0) throw invalidReference(reference, "easting and northing must have equal precision");
+	if (match[1].length > 10) throw invalidReference(reference, "precision cannot exceed 5 digits per axis");
+	return normalized;
+}
+function assertPrecision(precision) {
+	if (!Number.isInteger(precision) || precision < 0 || precision > 5) throw new RangeError("MGRS precision must be an integer from 0 through 5");
+}
+function pointForMgrsFormatting(coordinate, precision) {
+	if (coordinate.crs.kind !== "ups") return coordinate;
+	const cellSizeMeters = 1e5 / 10 ** precision;
+	if (coordinate.northing % cellSizeMeters !== 0) return coordinate;
+	return {
+		easting: coordinate.easting,
+		northing: coordinate.northing + 1e-6
+	};
+}
+/** Parse a complete MGRS cell and resolve its southwest grid intersection. */
+function parseMgrsReference(reference) {
+	const normalized = compactReference(reference);
+	try {
+		const result = mgrsBackend.reverse(normalized, false);
+		assertPrecision(result.prec);
+		const crs = result.zone === 0 ? {
+			kind: "ups",
+			hemisphere: result.northp ? "north" : "south"
+		} : {
+			kind: "utm",
+			zone: result.zone,
+			hemisphere: result.northp ? "north" : "south"
+		};
+		const position = geographicLibGridProjection.reverse(crs, {
+			easting: result.x,
+			northing: result.y
+		});
+		return {
+			normalized: projectedToMgrs({
+				crs,
+				easting: result.x,
+				northing: result.y
+			}, result.prec),
+			precision: result.prec,
+			crs,
+			easting: result.x,
+			northing: result.y,
+			position
+		};
+	} catch (error) {
+		if (error instanceof RangeError && error.message.startsWith("Invalid MGRS reference")) throw error;
+		throw invalidReference(reference, error);
+	}
+}
+function normalizeMgrsReference(reference) {
+	return parseMgrsReference(reference).normalized;
+}
+/** Convert an MGRS cell to its southwest intersection in its native grid CRS. */
+function mgrsToProjected(reference) {
+	const { crs, easting, northing } = parseMgrsReference(reference);
+	return {
+		crs,
+		easting,
+		northing
+	};
+}
+/** Convert an MGRS cell to its southwest intersection in GeoJSON coordinate order. */
+function mgrsToGeographic(reference) {
+	return parseMgrsReference(reference).position;
+}
+function projectedToMgrs(coordinate, precision = 5) {
+	assertPrecision(precision);
+	return geographicLibGridProjection.formatMgrs(coordinate.crs, pointForMgrsFormatting(coordinate, precision), precision);
+}
+function geographicToMgrs(position, precision = 5) {
+	assertPrecision(precision);
+	const crs = geographicLibGridProjection.selectStandard(position);
+	return projectedToMgrs({
+		crs,
+		...geographicLibGridProjection.forward(crs, position)
+	}, precision);
+}
+function snapUpOnHalf(value, interval) {
+	return Math.floor(value / interval + .5) * interval;
+}
+function snapProjectedToMgrs(coordinate, interval) {
+	const precision = mgrsPrecisionForInterval(interval);
+	const easting = snapUpOnHalf(coordinate.easting, interval);
+	const northing = snapUpOnHalf(coordinate.northing, interval);
+	return parseMgrsReference(projectedToMgrs({
+		crs: coordinate.crs,
+		easting,
+		northing
+	}, precision));
+}
+function snapGeographicToMgrs(position, interval) {
+	const crs = geographicLibGridProjection.selectStandard(position);
+	return snapProjectedToMgrs({
+		crs,
+		...geographicLibGridProjection.forward(crs, position)
+	}, interval);
+}
+//#endregion
+//#region src/registration.ts
+const CROSSHAIR_HALF_SIZE_MM = 4;
+const CROSSHAIR_STROKE_WIDTH_MM = DEFAULT_LINE_STROKE_WIDTH_MM;
+const LABEL_GAP_MM = 1;
+const LABEL_SIZE_CSS_PIXELS = 7;
+function sameCrs(left, right) {
+	return left.kind === right.kind && left.hemisphere === right.hemisphere && (left.kind === "ups" || right.kind === "utm" && left.zone === right.zone);
+}
+function createCrosshairAxis(points, id, axis) {
+	return createSceneLine(points, "#000000", {
+		strokeWidthMm: CROSSHAIR_STROKE_WIDTH_MM,
+		attributes: {
+			"data-registration-id": id,
+			"data-registration-axis": axis,
+			"data-registration-size-mm": CROSSHAIR_HALF_SIZE_MM * 2
+		}
+	});
+}
+function textBounds(text) {
+	const left = text.anchor === "start" ? text.position.xMm : text.anchor === "end" ? text.position.xMm - text.widthMm : text.position.xMm - text.widthMm / 2;
+	return {
+		left,
+		right: left + text.widthMm,
+		top: text.position.yMm - text.heightMm / 2,
+		bottom: text.position.yMm + text.heightMm / 2
+	};
+}
+function contains(frame, bounds) {
+	return bounds.left >= frame.xMm && bounds.right <= frame.xMm + frame.widthMm && bounds.top >= frame.yMm && bounds.bottom <= frame.yMm + frame.heightMm;
+}
+function createCustomLabel(value, point, frame, id) {
+	const towardRight = point.xMm <= frame.xMm + frame.widthMm / 2;
+	return createRegularSceneText({
+		text: value,
+		xMm: point.xMm + (towardRight ? 1 : -1) * 5,
+		yMm: point.yMm,
+		sizeCssPixels: LABEL_SIZE_CSS_PIXELS,
+		color: "#000000",
+		anchor: towardRight ? "start" : "end",
+		attributes: {
+			"data-registration-id": id,
+			"data-registration-label": value
+		}
+	});
+}
+function splitGridCoordinates(reference) {
+	if (reference.precision === 0) return [reference.normalized.at(-2), reference.normalized.at(-1)];
+	const coordinates = reference.normalized.slice(-2 * reference.precision);
+	return [coordinates.slice(0, reference.precision), coordinates.slice(reference.precision)];
+}
+function createCoordinateLabels(reference, point, id) {
+	const [easting, northing] = splitGridCoordinates(reference);
+	return [createRegularSceneText({
+		text: easting,
+		xMm: point.xMm - CROSSHAIR_HALF_SIZE_MM - LABEL_GAP_MM,
+		yMm: point.yMm,
+		sizeCssPixels: LABEL_SIZE_CSS_PIXELS,
+		color: "#000000",
+		anchor: "end",
+		attributes: {
+			"data-registration-id": id,
+			"data-registration-label": easting,
+			"data-registration-coordinate": "easting"
+		}
+	}), createRegularSceneText({
+		text: northing,
+		xMm: point.xMm,
+		yMm: point.yMm + CROSSHAIR_HALF_SIZE_MM + LABEL_GAP_MM,
+		sizeCssPixels: LABEL_SIZE_CSS_PIXELS,
+		color: "#000000",
+		attributes: {
+			"data-registration-id": id,
+			"data-registration-label": northing,
+			"data-registration-coordinate": "northing"
+		}
+	})];
+}
+function assertMarkFits(point, labels, frame, id) {
+	const strokeEdge = 4.1;
+	if (!(point.xMm - strokeEdge >= frame.xMm && point.xMm + strokeEdge <= frame.xMm + frame.widthMm && point.yMm - strokeEdge >= frame.yMm && point.yMm + strokeEdge <= frame.yMm + frame.heightMm) || labels.some((label) => !contains(frame, textBounds(label)))) throw new RangeError(`Registration mark ${JSON.stringify(id)} and its label must fit within the printable map frame`);
+}
+function hasUsablePair(marks, frame) {
+	const minimumX = frame.widthMm * .25;
+	const minimumY = frame.heightMm * .25;
+	const minimumDiagonal = Math.hypot(frame.widthMm, frame.heightMm) * .5;
+	for (let left = 0; left < marks.length; left += 1) for (let right = left + 1; right < marks.length; right += 1) {
+		const first = marks[left].sheetPositionMm;
+		const second = marks[right].sheetPositionMm;
+		const x = Math.abs(first.xMm - second.xMm);
+		const y = Math.abs(first.yMm - second.yMm);
+		if (x >= minimumX && y >= minimumY && Math.hypot(x, y) >= minimumDiagonal) return true;
+	}
+	return false;
+}
+function renderRegistration(request, context) {
+	if (!Array.isArray(request.marks) || request.marks.length < 2) throw new RangeError("Registration requires at least two authored marks");
+	const ids = /* @__PURE__ */ new Set();
+	const graphics = [];
+	const marks = [];
+	for (const authored of request.marks) {
+		if (typeof authored.id !== "string" || authored.id.trim() === "") throw new RangeError("Every registration mark requires a non-empty ID");
+		const idKey = authored.id.trim();
+		if (ids.has(idKey)) throw new RangeError(`Registration mark ID ${JSON.stringify(authored.id)} must be unique`);
+		ids.add(idKey);
+		const parsed = parseMgrsReference(authored.mgrs);
+		const resolved = request.snapIntervalMeters !== void 0 ? snapProjectedToMgrs(parsed, request.snapIntervalMeters) : parsed;
+		if (!sameCrs(resolved.crs, context.crs)) throw new RangeError(`Registration mark ${JSON.stringify(authored.id)} must use the sheet grid coordinate reference system`);
+		const sheetPositionMm = projectedToScenePoint(resolved, context);
+		const labels = authored.label && authored.label.trim() !== "" ? [createCustomLabel(authored.label, sheetPositionMm, context.frame, authored.id)] : createCoordinateLabels(resolved, sheetPositionMm, authored.id);
+		assertMarkFits(sheetPositionMm, labels, context.frame, authored.id);
+		marks.push({
+			id: authored.id,
+			mgrs: resolved.normalized,
+			position: [resolved.position[0], resolved.position[1]],
+			sheetPositionMm
+		});
+		const elements = [
+			createCrosshairAxis([{
+				xMm: sheetPositionMm.xMm - CROSSHAIR_HALF_SIZE_MM,
+				yMm: sheetPositionMm.yMm
+			}, {
+				xMm: sheetPositionMm.xMm + CROSSHAIR_HALF_SIZE_MM,
+				yMm: sheetPositionMm.yMm
+			}], authored.id, "horizontal"),
+			createCrosshairAxis([{
+				xMm: sheetPositionMm.xMm,
+				yMm: sheetPositionMm.yMm - CROSSHAIR_HALF_SIZE_MM
+			}, {
+				xMm: sheetPositionMm.xMm,
+				yMm: sheetPositionMm.yMm + CROSSHAIR_HALF_SIZE_MM
+			}], authored.id, "vertical"),
+			...labels
+		];
+		graphics.push({
+			id: authored.id,
+			elements
+		});
+	}
+	if (!hasUsablePair(marks, context.frame)) throw new RangeError("Registration requires a pair spanning 50% of the printable diagonal and 25% of both frame axes");
+	return {
+		layer: {
+			id: "registration-marks-0",
+			graphics,
+			attributes: { "data-registration-marks": marks.length }
+		},
+		marks
+	};
+}
+//#endregion
+//#region src/printer-calibration.ts
+const DEFAULT_LENGTH_MM = 100;
+const TICK_HALF_HEIGHT_MM = 2;
+const LABEL_OFFSET_MM = 2.5;
+const STROKE_WIDTH_MM = DEFAULT_LINE_STROKE_WIDTH_MM;
+function line(points, attributes) {
+	return createSceneLine(points, "#000000", { attributes });
+}
+function renderPrinterCalibration(request, page, frame) {
+	const lengthMm = request.lengthMm ?? DEFAULT_LENGTH_MM;
+	requirePositiveFinite(lengthMm, "Printer-calibration length");
+	const centerX = page.widthMm / 2;
+	const frameBottom = frame.yMm + frame.heightMm;
+	const yMm = frameBottom + (page.heightMm - frameBottom) / 2;
+	const startX = centerX - lengthMm / 2;
+	const endX = centerX + lengthMm / 2;
+	const label = createRegularSceneText({
+		text: `${lengthMm} mm`,
+		xMm: centerX,
+		yMm: yMm - LABEL_OFFSET_MM,
+		sizeCssPixels: 6,
+		color: "#000000",
+		attributes: { "data-printer-calibration-label": lengthMm }
+	});
+	const strokeEdge = STROKE_WIDTH_MM / 2;
+	const fitsHorizontally = startX - strokeEdge >= 0 && endX + strokeEdge <= page.widthMm;
+	const labelLeft = label.position.xMm - label.widthMm / 2;
+	const labelRight = label.position.xMm + label.widthMm / 2;
+	const contentTop = Math.min(label.position.yMm - label.heightMm / 2, yMm - TICK_HALF_HEIGHT_MM - strokeEdge);
+	const contentBottom = Math.max(label.position.yMm + label.heightMm / 2, yMm + TICK_HALF_HEIGHT_MM + strokeEdge);
+	if (!fitsHorizontally || labelLeft < 0 || labelRight > page.widthMm || contentTop < frameBottom || contentBottom > page.heightMm) throw new RangeError("The bottom page margin must fit the complete printer-calibration line, ticks, and label");
+	return {
+		id: "printer-calibration-0",
+		graphics: [{
+			id: "printer-calibration",
+			elements: [
+				line([{
+					xMm: startX,
+					yMm
+				}, {
+					xMm: endX,
+					yMm
+				}], { "data-printer-calibration-length-mm": lengthMm }),
+				line([{
+					xMm: startX,
+					yMm: yMm - TICK_HALF_HEIGHT_MM
+				}, {
+					xMm: startX,
+					yMm: yMm + TICK_HALF_HEIGHT_MM
+				}], { "data-printer-calibration-tick": "start" }),
+				line([{
+					xMm: endX,
+					yMm: yMm - TICK_HALF_HEIGHT_MM
+				}, {
+					xMm: endX,
+					yMm: yMm + TICK_HALF_HEIGHT_MM
+				}], { "data-printer-calibration-tick": "end" }),
+				label
+			]
+		}]
+	};
+}
+//#endregion
 //#region src/create-tactical-map-sheet.ts
 const FOOTPRINT_SEGMENTS_PER_EDGE = 16;
 const SCALE_SEARCH_BOUNDARY_DIVISIONS = 256;
@@ -1737,6 +2066,17 @@ function epsgFor(crs) {
 	if (crs.kind === "ups") return crs.hemisphere === "north" ? 32661 : 32761;
 	return (crs.hemisphere === "north" ? 32600 : 32700) + crs.zone;
 }
+function mgrsGridZoneFor(crs, center) {
+	const longitude = center[0];
+	if (crs.kind === "ups") {
+		if (crs.hemisphere === "north") return longitude < 0 ? "Y" : "Z";
+		return longitude < 0 ? "A" : "B";
+	}
+	const latitude = center[1];
+	const bands = "CDEFGHJKLMNPQRSTUVWX";
+	const bandIndex = Math.min(19, Math.max(0, Math.floor((latitude + 80) / 8)));
+	return `${crs.zone}${bands[bandIndex]}`;
+}
 function scaleDeviationWarning(maximumRelativeDeviation) {
 	return maximumRelativeDeviation >= .001 ? [{
 		code: "scale-deviation",
@@ -1771,6 +2111,13 @@ function createTacticalMapSheetDocument(request) {
 		projectedMetresPerMillimetre,
 		frame: mapFrame
 	});
+	if (request.registration && request.page.background !== void 0 && request.page.background !== "transparent") throw new RangeError("Registered overlays require a transparent page background");
+	const renderedRegistration = request.registration && renderRegistration(request.registration, {
+		crs,
+		center,
+		projectedMetresPerMillimetre,
+		frame: mapFrame
+	});
 	const epsg = epsgFor(crs);
 	const renderedMarginalia = request.marginalia && renderMarginalia(request.marginalia, {
 		page,
@@ -1778,17 +2125,23 @@ function createTacticalMapSheetDocument(request) {
 		scaleDenominator: request.scaleDenominator,
 		crs,
 		epsg,
+		mgrsGridZone: mgrsGridZoneFor(crs, request.center),
 		convergenceDegrees: center.convergenceDegrees,
 		footprintRing,
 		metadata: request.metadata
 	});
-	const fontStyles = [...renderedGrid || renderedMarginalia ? ["Regular"] : [], ...renderedLayers.fontStyles];
+	const renderedPrinterCalibration = request.printerCalibration && renderPrinterCalibration(request.printerCalibration, page, mapFrame);
+	const fontStyles = [...renderedGrid || renderedMarginalia || renderedRegistration || renderedPrinterCalibration ? ["Regular"] : [], ...renderedLayers.fontStyles];
 	const scene = {
 		page,
 		mapFrame,
 		...request.page.background && request.page.background !== "transparent" ? { backgroundColor: request.page.background } : {},
-		layers: [...renderedGrid ? [renderedGrid.layer] : [], ...renderedLayers.layers],
-		...renderedMarginalia ? { marginalia: [renderedMarginalia] } : {},
+		layers: [
+			...renderedGrid ? [renderedGrid.layer] : [],
+			...renderedLayers.layers,
+			...renderedRegistration ? [renderedRegistration.layer] : []
+		],
+		...renderedMarginalia || renderedPrinterCalibration ? { marginalia: [...renderedMarginalia ? [renderedMarginalia] : [], ...renderedPrinterCalibration ? [renderedPrinterCalibration] : []] } : {},
 		fonts: openSansResources(fontStyles),
 		patterns: renderedLayers.patterns
 	};
@@ -1809,6 +2162,7 @@ function createTacticalMapSheetDocument(request) {
 				fonts: openSansIdentities(fontStyles),
 				patterns: renderedLayers.patterns.map((pattern) => pattern.identity)
 			},
+			...renderedRegistration ? { registrationMarks: renderedRegistration.marks } : {},
 			metadata: {
 				center: [request.center[0], request.center[1]],
 				scaleDenominator: request.scaleDenominator,
@@ -1831,4 +2185,4 @@ function createTacticalMapSheet(request) {
 	return createTacticalMapSheetDocument(request).result;
 }
 //#endregion
-export { POINTS_PER_MILLIMETRE as a, MILLIMETRES_PER_CSS_PIXEL as i, createTacticalMapSheetDocument as n, openSansCentralBaselineOffset as o, formatDecimal as r, createTacticalMapSheet as t };
+export { mgrsToProjected as a, projectedToMgrs as c, formatDecimal as d, MILLIMETRES_PER_CSS_PIXEL as f, mgrsToGeographic as i, snapGeographicToMgrs as l, openSansCentralBaselineOffset as m, createTacticalMapSheetDocument as n, normalizeMgrsReference as o, POINTS_PER_MILLIMETRE as p, geographicToMgrs as r, parseMgrsReference as s, createTacticalMapSheet as t, snapProjectedToMgrs as u };

package/dist/{create-tactical-map-sheet-DAKVJ3Bx.d.mts → create-tactical-map-sheet-T2q1nHWO.d.mts}

@@ -200,6 +200,10 @@ interface PhysicalPageSize {
   readonly widthMm: number;
   readonly heightMm: number;
 }
+interface ScenePoint {
+  readonly xMm: number;
+  readonly yMm: number;
+}
 interface MapSheetPatternIdentity {
   readonly id: string;
   readonly pattern: PatternId;
@@ -210,10 +214,14 @@ interface MapSheetPatternIdentity {
   readonly phaseYMm: number;
 }
 //#endregion
+//#region src/mgrs-domain.d.ts
+declare const MGRS_SNAP_INTERVALS: readonly [100, 1000, 10000, 100000];
+type MgrsPrecision = 0 | 1 | 2 | 3 | 4 | 5;
+type MgrsSnapInterval = (typeof MGRS_SNAP_INTERVALS)[number];
+//#endregion
 //#region src/mgrs-grid.d.ts
-declare const SUPPORTED_INTERVALS: readonly [100, 1000, 10000, 100000];
 interface MgrsGridOptions {
-  readonly intervalMeters?: (typeof SUPPORTED_INTERVALS)[number];
+  readonly intervalMeters?: MgrsSnapInterval;
   readonly precision?: 0 | 1 | 2 | 3;
   readonly color?: string;
   readonly lineWidthCssPixels?: number;
@@ -237,7 +245,10 @@ interface MapSheetMarginaliaOptions {
   readonly showScale?: boolean;
   readonly showScaleBar?: boolean;
   readonly showGridAndNorth?: boolean;
+  readonly showFrameCornerMarks?: boolean;
+  /** @deprecated Use showFrameCornerMarks. The canonical option takes precedence. */
   readonly showRegistrationMarks?: boolean;
+  /** @deprecated Legacy 10 mm marks. Use the printerCalibration request instead. */
   readonly showCalibrationMarks?: boolean;
   readonly showFootprint?: boolean;
 }
@@ -351,11 +362,42 @@ interface PointSymbolFallbackWarning extends IdentifiedGraphicWarning {
 type GraphicVisibilityWarning = GraphicClippedWarning | GraphicOutsideFrameWarning | GraphicHiddenWarning;
 type GraphicRenderWarning = GraphicVisibilityWarning | PointSymbolFallbackWarning;
 //#endregion
+//#region src/paper.d.ts
+type PaperOrientation = "portrait" | "landscape";
+type PaperSizeName = "a0" | "a1" | "a2" | "a3" | "a4" | "letter" | "legal" | "tabloid" | "ledger" | "ansi-a" | "ansi-b" | "ansi-c" | "ansi-d" | "ansi-e" | "arch-d";
+/** Exact physical paper dimensions in their portrait orientation. */
+declare const PAPER_SIZES: Readonly<Record<PaperSizeName, PhysicalPageSize>>;
+/** Resolve a named paper size into values accepted by `MapSheetPageInput`. */
+declare function resolvePaperSize(name: PaperSizeName, orientation?: PaperOrientation): PhysicalPageSize;
+//#endregion
+//#region src/registration.d.ts
+interface AuthoredRegistrationMark {
+  readonly id: string;
+  readonly mgrs: string;
+  readonly label?: string;
+}
+interface MapSheetRegistrationRequest {
+  readonly marks: readonly AuthoredRegistrationMark[];
+  readonly snapIntervalMeters?: MgrsSnapInterval;
+}
+interface ResolvedRegistrationMark {
+  readonly id: string;
+  readonly mgrs: string;
+  /** GeoJSON coordinate order: longitude, then latitude. */
+  readonly position: Position;
+  readonly sheetPositionMm: ScenePoint;
+}
+//#endregion
+//#region src/printer-calibration.d.ts
+interface PrinterCalibrationRequest {
+  readonly lengthMm?: number;
+}
+//#endregion
 //#region src/create-tactical-map-sheet.d.ts
 interface MapSheetPageInput extends PhysicalPageSize {
   readonly marginMm?: number;
   readonly background?: string | "transparent";
-  readonly orientation?: "portrait" | "landscape";
+  readonly orientation?: PaperOrientation;
 }
 interface TacticalMapSheetRequest {
   readonly page: MapSheetPageInput;
@@ -368,6 +410,8 @@ interface TacticalMapSheetRequest {
   readonly pointSymbols?: MapSheetPointSymbolCapability;
   readonly marginalia?: MapSheetMarginaliaOptions | false;
   readonly metadata?: MapSheetMetadata;
+  readonly registration?: MapSheetRegistrationRequest;
+  readonly printerCalibration?: PrinterCalibrationRequest;
 }
 type UtmProjection = UtmCrs;
 type UpsProjection = UpsCrs;
@@ -419,7 +463,8 @@ interface TacticalMapSheetResult {
   readonly warnings: readonly TacticalMapSheetWarning[];
   readonly metadata: ResolvedMapSheetMetadata;
   readonly resources: TacticalMapSheetResources;
+  readonly registrationMarks?: readonly ResolvedRegistrationMark[];
 }
 declare function createTacticalMapSheet(request: TacticalMapSheetRequest): TacticalMapSheetResult;
 //#endregion
-export { MgrsGridOptions as A, MapSheetCustomSymbol as C, VectorSymbolAnchor as D, MapSheetSymbolSize as E, MapSheetPatternIdentity as M, Polygon as N, MapSheetMarginaliaOptions as O, ControlledVectorSymbol as S, MapSheetPointSymbolCapability as T, GraphicOutsideFrameWarning as _, ResolvedMapSheetMetadata as a, PointSymbolFallbackWarning as b, TacticalMapSheetResources as c, UpsProjection as d, UtmProjection as f, GraphicHiddenWarning as g, GraphicClippedWarning as h, MapSheetPageInput as i, ResolvedMgrsGridMetadata as j, MapSheetMetadata as k, TacticalMapSheetResult as l, AuthoredMapSheetGraphic as m, CrossZoneFootprintWarning as n, ScaleDeviationWarning as o, createTacticalMapSheet as p, MapSheetFontIdentity as r, TacticalMapSheetRequest as s, CrossProjectionFootprintWarning as t, TacticalMapSheetWarning as u, GraphicRenderWarning as v, MapSheetPointSymbol as w, TacticalMapSheetLayer as x, MapSheetPortrayalDefaults as y };
+export { ControlledVectorSymbol as A, MgrsPrecision as B, GraphicClippedWarning as C, MapSheetPortrayalDefaults as D, GraphicRenderWarning as E, VectorSymbolAnchor as F, UpsCrs as G, MapSheetPatternIdentity as H, MapSheetMarginaliaOptions as I, Position as J, UtmCrs as K, MapSheetMetadata as L, MapSheetPointSymbol as M, MapSheetPointSymbolCapability as N, PointSymbolFallbackWarning as O, MapSheetSymbolSize as P, MgrsGridOptions as R, AuthoredMapSheetGraphic as S, GraphicOutsideFrameWarning as T, GeographicPosition as U, MgrsSnapInterval as V, GridCrs as W, ResolvedRegistrationMark as _, ResolvedMapSheetMetadata as a, PaperSizeName as b, TacticalMapSheetResources as c, UpsProjection as d, UtmProjection as f, MapSheetRegistrationRequest as g, AuthoredRegistrationMark as h, MapSheetPageInput as i, MapSheetCustomSymbol as j, TacticalMapSheetLayer as k, TacticalMapSheetResult as l, PrinterCalibrationRequest as m, CrossZoneFootprintWarning as n, ScaleDeviationWarning as o, createTacticalMapSheet as p, Polygon as q, MapSheetFontIdentity as r, TacticalMapSheetRequest as s, CrossProjectionFootprintWarning as t, TacticalMapSheetWarning as u, PAPER_SIZES as v, GraphicHiddenWarning as w, resolvePaperSize as x, PaperOrientation as y, ResolvedMgrsGridMetadata as z };

package/dist/index.d.mts

@@ -1,2 +1,27 @@
-import { A as MgrsGridOptions, C as MapSheetCustomSymbol, D as VectorSymbolAnchor, E as MapSheetSymbolSize, M as MapSheetPatternIdentity, O as MapSheetMarginaliaOptions, S as ControlledVectorSymbol, T as MapSheetPointSymbolCapability, _ as GraphicOutsideFrameWarning, a as ResolvedMapSheetMetadata, b as PointSymbolFallbackWarning, c as TacticalMapSheetResources, d as UpsProjection, f as UtmProjection, g as GraphicHiddenWarning, h as GraphicClippedWarning, i as MapSheetPageInput, j as ResolvedMgrsGridMetadata, k as MapSheetMetadata, l as TacticalMapSheetResult, m as AuthoredMapSheetGraphic, n as CrossZoneFootprintWarning, o as ScaleDeviationWarning, p as createTacticalMapSheet, r as MapSheetFontIdentity, s as TacticalMapSheetRequest, t as CrossProjectionFootprintWarning, u as TacticalMapSheetWarning, v as GraphicRenderWarning, w as MapSheetPointSymbol, x as TacticalMapSheetLayer, y as MapSheetPortrayalDefaults } from "./create-tactical-map-sheet-DAKVJ3Bx.mjs";
-export { type AuthoredMapSheetGraphic, type ControlledVectorSymbol, type CrossProjectionFootprintWarning, type CrossZoneFootprintWarning, type GraphicClippedWarning, type GraphicHiddenWarning, type GraphicOutsideFrameWarning, type GraphicRenderWarning, type MapSheetCustomSymbol, type MapSheetFontIdentity, type MapSheetMarginaliaOptions, type MapSheetMetadata, type MapSheetPageInput, type MapSheetPatternIdentity, type MapSheetPointSymbol, type MapSheetPointSymbolCapability, type MapSheetPortrayalDefaults, type MapSheetSymbolSize, type MgrsGridOptions, type PointSymbolFallbackWarning, type ResolvedMapSheetMetadata, type ResolvedMgrsGridMetadata, type ScaleDeviationWarning, type TacticalMapSheetLayer, type TacticalMapSheetRequest, type TacticalMapSheetResources, type TacticalMapSheetResult, type TacticalMapSheetWarning, type UpsProjection, type UtmProjection, type VectorSymbolAnchor, createTacticalMapSheet };
+import { A as ControlledVectorSymbol, B as MgrsPrecision, C as GraphicClippedWarning, D as MapSheetPortrayalDefaults, E as GraphicRenderWarning, F as VectorSymbolAnchor, G as UpsCrs, H as MapSheetPatternIdentity, I as MapSheetMarginaliaOptions, J as Position, K as UtmCrs, L as MapSheetMetadata, M as MapSheetPointSymbol, N as MapSheetPointSymbolCapability, O as PointSymbolFallbackWarning, P as MapSheetSymbolSize, R as MgrsGridOptions, S as AuthoredMapSheetGraphic, T as GraphicOutsideFrameWarning, U as GeographicPosition, V as MgrsSnapInterval, W as GridCrs, _ as ResolvedRegistrationMark, a as ResolvedMapSheetMetadata, b as PaperSizeName, c as TacticalMapSheetResources, d as UpsProjection, f as UtmProjection, g as MapSheetRegistrationRequest, h as AuthoredRegistrationMark, i as MapSheetPageInput, j as MapSheetCustomSymbol, k as TacticalMapSheetLayer, l as TacticalMapSheetResult, m as PrinterCalibrationRequest, n as CrossZoneFootprintWarning, o as ScaleDeviationWarning, p as createTacticalMapSheet, r as MapSheetFontIdentity, s as TacticalMapSheetRequest, t as CrossProjectionFootprintWarning, u as TacticalMapSheetWarning, v as PAPER_SIZES, w as GraphicHiddenWarning, x as resolvePaperSize, y as PaperOrientation, z as ResolvedMgrsGridMetadata } from "./create-tactical-map-sheet-T2q1nHWO.mjs";
+
+//#region src/mgrs.d.ts
+interface ProjectedGridCoordinate {
+  readonly crs: GridCrs;
+  readonly easting: number;
+  readonly northing: number;
+}
+interface ResolvedMgrsReference extends ProjectedGridCoordinate {
+  readonly normalized: string;
+  readonly precision: MgrsPrecision;
+  /** GeoJSON coordinate order: longitude, then latitude. */
+  readonly position: Position;
+}
+/** Parse a complete MGRS cell and resolve its southwest grid intersection. */
+declare function parseMgrsReference(reference: string): ResolvedMgrsReference;
+declare function normalizeMgrsReference(reference: string): string;
+/** Convert an MGRS cell to its southwest intersection in its native grid CRS. */
+declare function mgrsToProjected(reference: string): ProjectedGridCoordinate;
+/** Convert an MGRS cell to its southwest intersection in GeoJSON coordinate order. */
+declare function mgrsToGeographic(reference: string): Position;
+declare function projectedToMgrs(coordinate: ProjectedGridCoordinate, precision?: MgrsPrecision): string;
+declare function geographicToMgrs(position: GeographicPosition, precision?: MgrsPrecision): string;
+declare function snapProjectedToMgrs(coordinate: ProjectedGridCoordinate, interval: MgrsSnapInterval): ResolvedMgrsReference;
+declare function snapGeographicToMgrs(position: GeographicPosition, interval: MgrsSnapInterval): ResolvedMgrsReference;
+//#endregion
+export { type AuthoredMapSheetGraphic, type AuthoredRegistrationMark, type ControlledVectorSymbol, type CrossProjectionFootprintWarning, type CrossZoneFootprintWarning, type GraphicClippedWarning, type GraphicHiddenWarning, type GraphicOutsideFrameWarning, type GraphicRenderWarning, type GridCrs, type MapSheetCustomSymbol, type MapSheetFontIdentity, type MapSheetMarginaliaOptions, type MapSheetMetadata, type MapSheetPageInput, type MapSheetPatternIdentity, type MapSheetPointSymbol, type MapSheetPointSymbolCapability, type MapSheetPortrayalDefaults, type MapSheetRegistrationRequest, type MapSheetSymbolSize, type MgrsGridOptions, type MgrsPrecision, type MgrsSnapInterval, PAPER_SIZES, type PaperOrientation, type PaperSizeName, type PointSymbolFallbackWarning, type PrinterCalibrationRequest, type ProjectedGridCoordinate, type ResolvedMapSheetMetadata, type ResolvedMgrsGridMetadata, type ResolvedMgrsReference, type ResolvedRegistrationMark, type ScaleDeviationWarning, type TacticalMapSheetLayer, type TacticalMapSheetRequest, type TacticalMapSheetResources, type TacticalMapSheetResult, type TacticalMapSheetWarning, type UpsCrs, type UpsProjection, type UtmCrs, type UtmProjection, type VectorSymbolAnchor, createTacticalMapSheet, geographicToMgrs, mgrsToGeographic, mgrsToProjected, normalizeMgrsReference, parseMgrsReference, projectedToMgrs, resolvePaperSize, snapGeographicToMgrs, snapProjectedToMgrs };

package/dist/index.mjs

@@ -1,2 +1,83 @@
-import { t as createTacticalMapSheet } from "./create-tactical-map-sheet-Wpo49_IR.mjs";
-export { createTacticalMapSheet };
+import { a as mgrsToProjected, c as projectedToMgrs, i as mgrsToGeographic, l as snapGeographicToMgrs, o as normalizeMgrsReference, r as geographicToMgrs, s as parseMgrsReference, t as createTacticalMapSheet, u as snapProjectedToMgrs } from "./create-tactical-map-sheet-DSmO71Oa.mjs";
+//#region src/paper.ts
+const A0 = Object.freeze({
+	widthMm: 841,
+	heightMm: 1189
+});
+const A1 = Object.freeze({
+	widthMm: 594,
+	heightMm: 841
+});
+const A2 = Object.freeze({
+	widthMm: 420,
+	heightMm: 594
+});
+const A3 = Object.freeze({
+	widthMm: 297,
+	heightMm: 420
+});
+const A4 = Object.freeze({
+	widthMm: 210,
+	heightMm: 297
+});
+const LETTER = Object.freeze({
+	widthMm: 215.9,
+	heightMm: 279.4
+});
+const LEGAL = Object.freeze({
+	widthMm: 215.9,
+	heightMm: 355.6
+});
+const TABLOID = Object.freeze({
+	widthMm: 279.4,
+	heightMm: 431.8
+});
+const ANSI_C = Object.freeze({
+	widthMm: 431.8,
+	heightMm: 558.8
+});
+const ANSI_D = Object.freeze({
+	widthMm: 558.8,
+	heightMm: 863.6
+});
+const ANSI_E = Object.freeze({
+	widthMm: 863.6,
+	heightMm: 1117.6
+});
+const ARCH_D = Object.freeze({
+	widthMm: 609.6,
+	heightMm: 914.4
+});
+/** Exact physical paper dimensions in their portrait orientation. */
+const PAPER_SIZES = Object.freeze({
+	a0: A0,
+	a1: A1,
+	a2: A2,
+	a3: A3,
+	a4: A4,
+	letter: LETTER,
+	legal: LEGAL,
+	tabloid: TABLOID,
+	ledger: TABLOID,
+	"ansi-a": LETTER,
+	"ansi-b": TABLOID,
+	"ansi-c": ANSI_C,
+	"ansi-d": ANSI_D,
+	"ansi-e": ANSI_E,
+	"arch-d": ARCH_D
+});
+/** Resolve a named paper size into values accepted by `MapSheetPageInput`. */
+function resolvePaperSize(name, orientation = "portrait") {
+	const size = PAPER_SIZES[name];
+	if (!size) throw new RangeError(`Unknown paper size: ${String(name)}`);
+	if (orientation !== "portrait" && orientation !== "landscape") throw new RangeError("Paper orientation must be portrait or landscape");
+	return orientation === "portrait" ? {
+		widthMm: size.widthMm,
+		heightMm: size.heightMm
+	} : {
+		widthMm: size.heightMm,
+		heightMm: size.widthMm
+	};
+}
+//#endregion
+export { PAPER_SIZES, createTacticalMapSheet, geographicToMgrs, mgrsToGeographic, mgrsToProjected, normalizeMgrsReference, parseMgrsReference, projectedToMgrs, resolvePaperSize, snapGeographicToMgrs, snapProjectedToMgrs };

package/dist/pdf.d.mts

@@ -1,4 +1,4 @@
-import { N as Polygon, a as ResolvedMapSheetMetadata, c as TacticalMapSheetResources, s as TacticalMapSheetRequest, u as TacticalMapSheetWarning } from "./create-tactical-map-sheet-DAKVJ3Bx.mjs";
+import { a as ResolvedMapSheetMetadata, c as TacticalMapSheetResources, l as TacticalMapSheetResult, q as Polygon, s as TacticalMapSheetRequest, u as TacticalMapSheetWarning } from "./create-tactical-map-sheet-T2q1nHWO.mjs";
 
 //#region src/pdf.d.ts
 interface TacticalMapSheetPdfResult {
@@ -7,6 +7,7 @@ interface TacticalMapSheetPdfResult {
   readonly warnings: readonly TacticalMapSheetWarning[];
   readonly metadata: ResolvedMapSheetMetadata;
   readonly resources: TacticalMapSheetResources;
+  readonly registrationMarks?: TacticalMapSheetResult["registrationMarks"];
 }
 declare function renderMapSheetPdf(request: TacticalMapSheetRequest): TacticalMapSheetPdfResult;
 //#endregion

package/dist/pdf.mjs

@@ -1,4 +1,4 @@
-import { a as POINTS_PER_MILLIMETRE, i as MILLIMETRES_PER_CSS_PIXEL, n as createTacticalMapSheetDocument, o as openSansCentralBaselineOffset, r as formatDecimal } from "./create-tactical-map-sheet-Wpo49_IR.mjs";
+import { d as formatDecimal, f as MILLIMETRES_PER_CSS_PIXEL, m as openSansCentralBaselineOffset, n as createTacticalMapSheetDocument, p as POINTS_PER_MILLIMETRE } from "./create-tactical-map-sheet-DSmO71Oa.mjs";
 import { jsPDF } from "jspdf";
 //#region src/pdf-transparency.ts
 const FORM_DICTIONARY_MARKER = new TextEncoder().encode("/Subtype /Form\n/BBox");
@@ -676,7 +676,8 @@ function renderMapSheetPdf(request) {
 		footprint: result.footprint,
 		warnings: result.warnings,
 		metadata: result.metadata,
-		resources: result.resources
+		resources: result.resources,
+		...result.registrationMarks ? { registrationMarks: result.registrationMarks } : {}
 	};
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbat-mapper/tactical-map-sheet",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Scale-accurate projected vector tactical map-sheet renderer.",
   "license": "MIT",
   "author": "Orbat Mapper",