@diagrammo/dgmo 0.22.0 → 0.24.0

package/dist/advanced.d.cts

@@ -236,6 +236,28 @@ interface ParsedMap {
     readonly diagnostics: readonly DgmoError[];
     readonly error: string | null;
 }
+/** Legend descriptor for a rendered map (a layout-stage output, re-exported from
+ *  `layout.ts`). It lives here so the `legend-band` helper can consume it without
+ *  importing `layout` — `layout` already value-imports `mapLegendBand`, so the
+ *  reverse type import would form a layout↔legend-band cycle. */
+interface MapLayoutLegend {
+    readonly tagGroups: ReadonlyArray<{
+        name: string;
+        entries: ReadonlyArray<{
+            value: string;
+            color: string;
+        }>;
+    }>;
+    readonly activeGroup: string | null;
+    readonly ramp?: {
+        metric?: string;
+        min: number;
+        max: number;
+        hue: string;
+        /** Low end of the ramp gradient (the land colour the fills blend from). */
+        base: string;
+    };
+}
 
 /** A TopoJSON topology (world-coarse/world-detail keyed by ISO 3166-1 alpha-2;
  *  us-states keyed by ISO 3166-2). Geometry feature `id` is the ISO code;
@@ -1568,6 +1590,7 @@ declare function renderForExport(content: string, theme: 'light' | 'dark' | 'tra
     tagGroup?: string;
     exportMode?: boolean;
     mapData?: MapData;
+    mapAspect?: number;
 }): Promise<string>;
 
 /**
@@ -2500,6 +2523,9 @@ interface BLNode {
     readonly lineNumber: number;
     readonly metadata: Readonly<Record<string, string>>;
     readonly description?: readonly string[];
+    /** Numeric measure lifted from `value: X` metadata (mirror of map's
+     *  `region.value`). Drives the value ramp / choropleth tinting. */
+    readonly value?: number;
 }
 interface BLEdge {
     readonly source: string;
@@ -2527,6 +2553,12 @@ interface ParsedBoxesAndLines {
     readonly options: Readonly<Record<string, string>>;
     readonly initialHiddenTagValues: ReadonlyMap<string, ReadonlySet<string>>;
     readonly direction: 'LR' | 'TB';
+    /** `box-metric <label> [color]` — names the value-ramp dimension and
+     *  optionally sets its hue. Mirror of map's `region-metric`. */
+    readonly boxMetric?: string;
+    readonly boxMetricColor?: string;
+    /** `show-values` — print each box's numeric value as text (opt-in). */
+    readonly showValues?: boolean;
     readonly diagnostics: readonly DgmoError[];
     readonly error: string | null;
 }
@@ -4672,6 +4704,14 @@ interface MapLayoutRegion {
     /** The region's tag values keyed by group (lowercased) — emitted as
      *  `data-tag-<group>` so the app can highlight on legend-entry hover. */
     readonly tags?: Readonly<Record<string, string>>;
+    /** Area-weighted screen centroid (px) of the DRAWN geometry — emitted as
+     *  `data-label-x`/`data-label-y` so the app can anchor the hover label here
+     *  instead of the path's bounding-box centre. The bbox centre breaks for
+     *  antimeridian crossers (Russia's wrapped Chukotka sliver pins the box's left
+     *  edge to the far side of the map, dropping the centre into the Atlantic); the
+     *  area-weighted centroid stays on the body. Honours WORLD_LABEL_ANCHORS. */
+    readonly labelX?: number;
+    readonly labelY?: number;
 }
 /** A framed inset "cutout" (albers-usa AK/HI), in screen px. The frame is a
  *  quad whose TOP edge is angled to ride just under the conus southern coast,
@@ -4822,24 +4862,7 @@ interface PlacedLabel {
     readonly clusterMember?: string;
     readonly lineNumber: number;
 }
-interface MapLayoutLegend {
-    readonly tagGroups: ReadonlyArray<{
-        name: string;
-        entries: ReadonlyArray<{
-            value: string;
-            color: string;
-        }>;
-    }>;
-    readonly activeGroup: string | null;
-    readonly ramp?: {
-        metric?: string;
-        min: number;
-        max: number;
-        hue: string;
-        /** Low end of the ramp gradient (the land colour the fills blend from). */
-        base: string;
-    };
-}
+
 /** A drawn river centerline — an open stroked path (no fill). */
 interface MapLayoutRiver {
     readonly d: string;
@@ -4938,6 +4961,10 @@ interface LayoutOptions {
      *  canvas away from the content aspect, so the off-aspect canvas doesn't
      *  re-distort. The in-app preview pane leaves this unset (keeps stretch-fill). */
     readonly preferContain?: boolean;
+    /** Which legend variant gets drawn — `'export'` shows only the active group,
+     *  `'preview'` keeps inactive pills. Used to size the reserved legend band so
+     *  the projected land starts below the legend. Defaults to `'preview'`. */
+    readonly legendMode?: LegendMode;
 }
 interface Size {
     readonly width: number;
@@ -4990,7 +5017,13 @@ interface MapExportDimensions {
     readonly height: number;
     readonly preferContain: boolean;
 }
-declare function mapExportDimensions(resolved: ResolvedMap, data: MapData, baseWidth?: number): MapExportDimensions;
+declare function mapExportDimensions(resolved: ResolvedMap, data: MapData, baseWidth?: number, 
+/** WYSIWYG override (app export): the live preview pane's displayed aspect
+ *  (width / height). When provided, the canvas adopts it verbatim and
+ *  stretch-fills (no clamp, no contain) so the PNG matches exactly what's on
+ *  screen. Omitted by every headless consumer (CLI / MCP / SSG / Obsidian),
+ *  which keep the intrinsic-aspect sizing below. */
+aspectOverride?: number): MapExportDimensions;
 
 /** Nearest gazetteer city to a point: the real haversine distance, plus the
  *  canonical name + ISO + (US-only) subdivision for token shaping. `lon`/`lat`

package/dist/advanced.d.ts

@@ -236,6 +236,28 @@ interface ParsedMap {
     readonly diagnostics: readonly DgmoError[];
     readonly error: string | null;
 }
+/** Legend descriptor for a rendered map (a layout-stage output, re-exported from
+ *  `layout.ts`). It lives here so the `legend-band` helper can consume it without
+ *  importing `layout` — `layout` already value-imports `mapLegendBand`, so the
+ *  reverse type import would form a layout↔legend-band cycle. */
+interface MapLayoutLegend {
+    readonly tagGroups: ReadonlyArray<{
+        name: string;
+        entries: ReadonlyArray<{
+            value: string;
+            color: string;
+        }>;
+    }>;
+    readonly activeGroup: string | null;
+    readonly ramp?: {
+        metric?: string;
+        min: number;
+        max: number;
+        hue: string;
+        /** Low end of the ramp gradient (the land colour the fills blend from). */
+        base: string;
+    };
+}
 
 /** A TopoJSON topology (world-coarse/world-detail keyed by ISO 3166-1 alpha-2;
  *  us-states keyed by ISO 3166-2). Geometry feature `id` is the ISO code;
@@ -1568,6 +1590,7 @@ declare function renderForExport(content: string, theme: 'light' | 'dark' | 'tra
     tagGroup?: string;
     exportMode?: boolean;
     mapData?: MapData;
+    mapAspect?: number;
 }): Promise<string>;
 
 /**
@@ -2500,6 +2523,9 @@ interface BLNode {
     readonly lineNumber: number;
     readonly metadata: Readonly<Record<string, string>>;
     readonly description?: readonly string[];
+    /** Numeric measure lifted from `value: X` metadata (mirror of map's
+     *  `region.value`). Drives the value ramp / choropleth tinting. */
+    readonly value?: number;
 }
 interface BLEdge {
     readonly source: string;
@@ -2527,6 +2553,12 @@ interface ParsedBoxesAndLines {
     readonly options: Readonly<Record<string, string>>;
     readonly initialHiddenTagValues: ReadonlyMap<string, ReadonlySet<string>>;
     readonly direction: 'LR' | 'TB';
+    /** `box-metric <label> [color]` — names the value-ramp dimension and
+     *  optionally sets its hue. Mirror of map's `region-metric`. */
+    readonly boxMetric?: string;
+    readonly boxMetricColor?: string;
+    /** `show-values` — print each box's numeric value as text (opt-in). */
+    readonly showValues?: boolean;
     readonly diagnostics: readonly DgmoError[];
     readonly error: string | null;
 }
@@ -4672,6 +4704,14 @@ interface MapLayoutRegion {
     /** The region's tag values keyed by group (lowercased) — emitted as
      *  `data-tag-<group>` so the app can highlight on legend-entry hover. */
     readonly tags?: Readonly<Record<string, string>>;
+    /** Area-weighted screen centroid (px) of the DRAWN geometry — emitted as
+     *  `data-label-x`/`data-label-y` so the app can anchor the hover label here
+     *  instead of the path's bounding-box centre. The bbox centre breaks for
+     *  antimeridian crossers (Russia's wrapped Chukotka sliver pins the box's left
+     *  edge to the far side of the map, dropping the centre into the Atlantic); the
+     *  area-weighted centroid stays on the body. Honours WORLD_LABEL_ANCHORS. */
+    readonly labelX?: number;
+    readonly labelY?: number;
 }
 /** A framed inset "cutout" (albers-usa AK/HI), in screen px. The frame is a
  *  quad whose TOP edge is angled to ride just under the conus southern coast,
@@ -4822,24 +4862,7 @@ interface PlacedLabel {
     readonly clusterMember?: string;
     readonly lineNumber: number;
 }
-interface MapLayoutLegend {
-    readonly tagGroups: ReadonlyArray<{
-        name: string;
-        entries: ReadonlyArray<{
-            value: string;
-            color: string;
-        }>;
-    }>;
-    readonly activeGroup: string | null;
-    readonly ramp?: {
-        metric?: string;
-        min: number;
-        max: number;
-        hue: string;
-        /** Low end of the ramp gradient (the land colour the fills blend from). */
-        base: string;
-    };
-}
+
 /** A drawn river centerline — an open stroked path (no fill). */
 interface MapLayoutRiver {
     readonly d: string;
@@ -4938,6 +4961,10 @@ interface LayoutOptions {
      *  canvas away from the content aspect, so the off-aspect canvas doesn't
      *  re-distort. The in-app preview pane leaves this unset (keeps stretch-fill). */
     readonly preferContain?: boolean;
+    /** Which legend variant gets drawn — `'export'` shows only the active group,
+     *  `'preview'` keeps inactive pills. Used to size the reserved legend band so
+     *  the projected land starts below the legend. Defaults to `'preview'`. */
+    readonly legendMode?: LegendMode;
 }
 interface Size {
     readonly width: number;
@@ -4990,7 +5017,13 @@ interface MapExportDimensions {
     readonly height: number;
     readonly preferContain: boolean;
 }
-declare function mapExportDimensions(resolved: ResolvedMap, data: MapData, baseWidth?: number): MapExportDimensions;
+declare function mapExportDimensions(resolved: ResolvedMap, data: MapData, baseWidth?: number, 
+/** WYSIWYG override (app export): the live preview pane's displayed aspect
+ *  (width / height). When provided, the canvas adopts it verbatim and
+ *  stretch-fills (no clamp, no contain) so the PNG matches exactly what's on
+ *  screen. Omitted by every headless consumer (CLI / MCP / SSG / Obsidian),
+ *  which keep the intrinsic-aspect sizing below. */
+aspectOverride?: number): MapExportDimensions;
 
 /** Nearest gazetteer city to a point: the real haversine distance, plus the
  *  canonical name + ISO + (US-only) subdivision for token shaping. `lon`/`lat`