@orbat-mapper/tactical-map-sheet 0.1.0

package/COMPATIBILITY.md

@@ -0,0 +1,25 @@
+# Public compatibility audit
+
+This audit records the publication gate for the product contract in
+[tactical-graphics#394](https://github.com/orbat-mapper/tactical-graphics/issues/394).
+
+| Completion criterion | Evidence |
+| --- | --- |
+| Package remains private until completion | Privacy is removed only by the #415 release change; `publication.spec.ts` verifies the public package metadata and entry points. |
+| Deterministic SVG and PDF, independent of viewport/DPR | Canonical byte fixtures and repeated-render assertions live in `product-contract.spec.ts`, `normandy-conformance.spec.ts`, and `pdf.spec.ts`. Rendering accepts no viewport or DPR input. |
+| Exact page dimensions, center scale, and reported scale factors | `create-tactical-map-sheet.spec.ts` verifies physical dimensions, center compensation, footprint, center point scale, and maximum deviation; `pdf.spec.ts` verifies the PDF MediaBox. |
+| UTM, UPS, MGRS, exceptions, transitions, and polar cases | `projection.spec.ts` qualifies GeographicLib/GEOTRANS vectors, hemisphere behavior, Norway/Svalbard rules, explicit zones, transitions, poles, round trips, and MGRS precision; sheet tests cover UTM and UPS grids. |
+| Cross-zone and polar behavior is documented and warning-driven | The README documents `cross-zone-footprint`, `cross-projection-footprint`, and `scale-deviation`; sheet and PDF tests assert compatible structured warnings. |
+| Portable control-measure portrayal and ordering | Normandy and product-contract fixtures cover ground-scale portrayal, canonical defaults/order, patterns, clipping, label clearance, and injected Open Sans metrics. |
+| Vector point and custom symbols preserve their contract | Sheet tests cover bounds, anchors, size, rotation, colors, opacity, amplifiers, fallback warnings, and rejected unsupported SVG; PDF tests cover vector composition. |
+| Complete marginalia | Sheet and product-contract fixtures cover metadata, declared scale, scale bar, CRS/zone, grid and true north, convergence, registration marks, and printable-footprint information. |
+| No rasterized requested graphics | Controlled vector import rejects raster/linked/scripted content; SVG/PDF structural tests assert vector paths, patterns, symbols, and text. |
+| PDF vector parity and exact dimensions | `pdf.spec.ts` checks MediaBox, clipping, patterns, ordering, embedded searchable fonts, deterministic bytes, vector structure, and visual parity with sibling SVG fixtures. |
+| Main SVG entry does not load PDF | `node-packaging.spec.ts` and `browser-packaging.spec.ts` build both exports and verify that the root module graph contains neither jsPDF nor the PDF renderer. |
+| Invalid input throws; all usable loss is identified | Public-boundary tests cover invalid geometry, projection failure, missing capabilities, unsupported vectors, clipping, off-frame and hidden graphics, fallback symbols, zone/projection crossings, and scale deviation. |
+| Independent application adaptation | Closed issue #414 proves TacTrace adapts representative UTM/UPS requests without leaking application, framework, or map-engine types or runtime dependencies into this package. The deferred ORBAT Mapper integration is explicitly excluded from this publication gate by the current #415 product scope. |
+| Required semantic, byte, structural, packaging, and visual coverage | The package suite contains semantic contract tests, checked SVG/PDF bytes, PDF/vector structure assertions, Node/browser packaging qualification, and pinned rendered goldens with explicit tolerances. |
+
+The public compatibility boundary is normalized authored layers in and deterministic vector document
+results out. Application stores, engine-rendered features, export UI, authorization, preview, and file
+saving remain application responsibilities.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orbat Mapper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# Tactical map sheet
+
+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.
+
+## Install and entry points
+
+```bash
+pnpm add @orbat-mapper/tactical-map-sheet
+```
+
+The root entry point exports `createTacticalMapSheet` and all request, result, warning, metadata,
+layer, MGRS, marginalia, and vector-symbol capability types. The optional PDF implementation is
+only exported from `@orbat-mapper/tactical-map-sheet/pdf`, keeping PDF code and dependencies out of
+the main SVG module graph.
+
+```ts
+import {
+  createTacticalMapSheet,
+  type TacticalMapSheetRequest,
+} from "@orbat-mapper/tactical-map-sheet";
+
+const request: TacticalMapSheetRequest = {
+  page: { widthMm: 297, heightMm: 210, marginMm: 10, orientation: "landscape" },
+  center: [-2.5, 49.2],
+  scaleDenominator: 25_000,
+  grid: { intervalMeters: 1_000 },
+  layers: [],
+  marginalia: {},
+};
+
+const { svg, footprint, warnings, metadata, resources } = createTacticalMapSheet(request);
+```
+
+`TacticalMapSheetResult` contains deterministic SVG bytes, the densified geographic printable
+footprint, structured warnings, resolved projection/page/grid metadata, and the font and pattern
+resources used by the document. Identical requests produce identical results independently of a
+browser viewport or device-pixel ratio.
+
+## Contract and failure behavior
+
+The page and map frame use millimetres. The package derives one printable footprint from the page,
+center, and scale; it does not accept a competing extent. `projection: "auto"` selects one UTM or
+UPS CRS from the center and retains it for the whole sheet. Layers render bottom-to-top in request
+order, and each layer preserves authored graphic order. Requested control measures and symbols stay
+vector in both output formats.
+
+Invalid coordinates, contradictory page geometry, unavailable point-symbol capabilities,
+projection failures, and SVG content outside the controlled vector subset throw. A usable but lossy
+result is returned only with an identifying warning; requested content is never silently omitted or
+rasterized.
+
+Warnings are deterministic records with these public codes and payloads:
+
+- `cross-zone-footprint` reports the center-selected UTM `selectedZone` and all
+  `intersectedZones` when the printable footprint enters another UTM zone.
+- `cross-projection-footprint` reports the `selectedProjection` and the ordered
+  `intersectedProjections` (`ups`, `utm`) when the footprint crosses the UTM/UPS boundary. A UTM
+  footprint crossing that boundary and another UTM zone reports both warnings.
+- `scale-deviation` reports `maximumRelativeDeviation` when frame scale differs from center scale
+  by at least `0.001` (0.1%). Smaller usable distortion remains available in result metadata.
+- `graphic-clipped`, `graphic-outside-frame`, and `graphic-hidden` identify the affected `layerId`
+  and `graphicId`.
+- `point-symbol-fallback` identifies a `layerId` and `graphicId` whose point-symbol capability
+  returned visible fallback vector content.
+
+Regular/Caps, Italic, and Light semantic text use complete package-owned Open Sans static TTFs and
+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.
+
+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,
+linked, scripted, malformed, or otherwise unsupported SVG throws instead of being omitted or
+rasterized.
+
+The checked conformance assets live beside `normandy-conformance.spec.ts`. Update both the canonical
+SVG bytes and the 1188-pixel-wide PNG rendered by the exactly pinned `@resvg/resvg-js` dependency
+with:
+
+```bash
+pnpm --filter @orbat-mapper/tactical-map-sheet fixtures:update
+```
+
+Review the SVG and PNG visually before committing an update. The visual comparison permits at most
+0.01% of pixels to differ by more than 8 in any RGBA channel; semantic assertions remain exact.
+
+The optional direct PDF backend is a separate entry point, so SVG consumers never load jsPDF or its
+dependencies:
+
+```ts
+import { renderMapSheetPdf } from "@orbat-mapper/tactical-map-sheet/pdf";
+
+const result = renderMapSheetPdf(request);
+const pdfBytes = result.pdf;
+```
+
+PDF is serialized directly from the same private millimetre scene as SVG. It retains vector paths,
+tiling patterns, map-frame clipping, opacity, symbol transforms, embedded searchable Open Sans text,
+canonical ordering, warnings, resources, footprint, and resolved metadata. The serializer fixes the
+document timestamp and identifier, disables variable compression, and normalizes geometry through
+the shared six-decimal formatter so identical requests produce identical bytes. Update the ordinary,
+patterned, cross-zone, and polar canonical PDF and rendered PNG fixtures with:
+
+```bash
+pnpm --filter @orbat-mapper/tactical-map-sheet fixtures:update:pdf
+```
+
+The PDF fixtures are rendered by pinned PDF.js and `@napi-rs/canvas`, then compared both byte-for-byte
+with their checked PNGs and visually with the sibling SVG render. The cross-renderer comparison allows
+at most 2% of pixels to differ by more than 24 in one RGBA channel, or 10% for one-pixel repeating
+hatching where the two vector rasterizers cover opposite edge pixels.
+
+Application code remains responsible for content selection, authorization, export preferences,
+footprint preview, displaying warnings and validation failures, and saving the returned bytes.
+Application stores and map-engine output are not part of the public request contract.
+
+## API reference
+
+### Request
+
+`TacticalMapSheetRequest` has these fields:
+
+- `page`: required physical `widthMm` and `heightMm`, with optional non-negative `marginMm`,
+  `orientation`, and CSS `background` (or `"transparent"`).
+- `center`: required GeoJSON longitude/latitude position; `scaleDenominator`: required positive
+  nominal true-ground scale at that center.
+- `mapFrame`: optional `{ xMm, yMm, widthMm, heightMm }` inside the page. It is mutually exclusive
+  with `page.marginMm`.
+- `projection`: `"auto"` (default), `{ kind: "utm", zone, hemisphere }`, or
+  `{ kind: "ups", hemisphere }`.
+- `grid`: `false` or `MgrsGridOptions` (`intervalMeters` of 100, 1,000, 10,000, or 100,000;
+  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.
+
+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
+`MapSheetPointSymbol`, or a `MapSheetCustomSymbol`.
+
+Point symbols carry `id`, `sidc`, position, rotation in radians, pixel- or metre-based size, optional
+amplifiers/modifiers, and renderer style/options. `MapSheetPointSymbolCapability.render(symbol)`
+must return a `ControlledVectorSymbol`: stable resource ID, controlled-subset SVG, complete width and
+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.
+
+`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.
+
+### Results and resolved metadata
+
+`createTacticalMapSheet(request)` returns `TacticalMapSheetResult`:
+
+- `svg`: complete deterministic SVG; `footprint`: densified GeoJSON polygon.
+- `warnings`: ordered structured warnings described below.
+- `metadata`: resolved center, scale denominator, physical page and map frame, optional source
+  document metadata, optional resolved MGRS interval/precision, and resolved CRS (`kind`, zone or
+  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.
+
+`renderMapSheetPdf(request)` accepts the identical request and returns `TacticalMapSheetPdfResult`:
+`pdf: Uint8Array` plus the same footprint, warnings, metadata, and resources as the SVG result.
+
+### Warning union
+
+`TacticalMapSheetWarning` is a discriminated union on `code`. Zone, projection, and scale warnings
+carry the payloads documented earlier. `graphic-clipped`, `graphic-outside-frame`, `graphic-hidden`,
+and `point-symbol-fallback` carry both `layerId` and `graphicId`. Warning order is deterministic.