@diagrammo/dgmo 0.21.1 → 0.22.0

package/dist/map-data/water-bodies.json

@@ -0,0 +1 @@
+{"entries":[[85.078,21.558,"Arctic Ocean",0,"ocean"],[-26.746,83.424,"Indian Ocean",0,"ocean"],[39.898,-30.68,"North Atlantic Ocean",0,"ocean",[[40,-55],[30,-45],[50,-25],[15,-45]]],[24.49,-136.445,"North Pacific Ocean",0,"ocean",[[36,-126],[47,-131],[55,-143],[35,160],[15,165]]],[-34.311,-18.311,"South Atlantic Ocean",0,"ocean",[[-25,-35],[-40,-15],[-10,-20]]],[-30.137,-126.822,"South Pacific Ocean",0,"ocean",[[-20,-110],[-40,-95],[-15,170],[-35,170]]],[-65.892,-18.447,"Southern Ocean",0,"ocean"],[13.692,63.675,"Arabian Sea",1,"sea"],[72.951,-66.643,"Baffin Bay",1,"bay"],[13.118,86.757,"Bay of Bengal",1,"bay"],[71.997,-136.388,"Beaufort Sea",1,"sea"],[43.547,31.292,"Black Sea",1,"sea"],[13.754,-78.235,"Caribbean Sea",1,"sea"],[41.954,50.61,"Caspian Sea",1,"sea"],[-18.886,157.126,"Coral Sea",1,"sea"],[58.108,-149.198,"Gulf of Alaska",1,"gulf"],[25.319,-90.053,"Gulf of America",1,"gulf"],[59.246,-85.292,"Hudson Bay",1,"bay"],[55.979,-52.602,"Labrador Sea",1,"sea"],[34.341,17.988,"Mediterranean Sea",1,"sea"],[25.683,52.866,"Persian Gulf",1,"gulf"],[17.263,133.481,"Philippine Sea",1,"sea"],[19.579,38.751,"Red Sea",1,"sea"],[-77.493,-169.96,"Ross Sea",1,"sea"],[40.613,136.423,"Sea of Japan",1,"sea"],[52.851,149.205,"Sea of Okhotsk",1,"sea"],[13.781,114.703,"South China Sea",1,"sea"],[-40.358,160.682,"Tasman Sea",1,"sea"],[-75.66,-53.473,"Weddell Sea",1,"sea"],[-73.979,-106.379,"Amundsen Sea",2,"sea"],[10.878,95.492,"Andaman Sea",2,"sea"],[-9.347,135.278,"Arafura Sea",2,"sea"],[19.67,-93.559,"Bahía de Campeche",2,"bay"],[56.024,19.234,"Baltic Sea",2,"sea"],[-5.658,126.23,"Banda Sea",2,"sea"],[74.604,43.063,"Barents Sea",2,"sea"],[45.627,-4.33,"Bay of Biscay",2,"bay"],[-72.084,-82.745,"Bellingshausen Sea",2,"sea"],[56.349,-171.512,"Bering Sea",2,"sea"],[3.571,122.574,"Celebes Sea",2,"sea"],[68.633,-169.418,"Chukchi Sea",2,"sea"],[64.549,-57.848,"Davis Strait",2,"strait"],[-66.686,-68.017,"Drake Passage",2,"channel"],[28.854,125.37,"East China Sea",2,"sea"],[76.558,-8.516,"Greenland Sea",2,"sea"],[3.294,2.903,"Gulf of Guinea",2,"gulf"],[9.545,101.832,"Gulf of Thailand",2,"gulf"],[53.543,-5.35,"Irish Sea",2,"sea"],[-5.2,112.569,"Java Sea",2,"sea"],[76.92,73.103,"Kara Sea",2,"sea"],[5.871,75.234,"Laccadive Sea",2,"sea"],[75.961,120.379,"Laptev Sea",2,"sea"],[22.073,120.87,"Luzon Strait",2,"strait"],[-20.03,40.414,"Mozambique Channel",2,"channel"],[56.502,2.655,"North Sea",2,"sea"],[66.883,1.329,"Norwegian Sea",2,"sea"],[27.646,-59.716,"Sargasso Sea",2,"sea"],[-61.149,-54.893,"Scotia Sea",2,"sea"],[8.392,120.208,"Sulu Sea",2,"sea"],[-10.978,127.712,"Timor Sea",2,"sea"],[35.164,123.956,"Yellow Sea",2,"sea"],[42.81,15.327,"Adriatic Sea",3,"sea"],[49.707,-2.894,"English Channel",3,"channel"],[26.35,-110.53,"Golfo de California",3,"gulf"],[-35.41,131.682,"Great Australian Bight",3,"gulf"],[12.621,48.305,"Gulf of Aden",3,"gulf"],[61.904,19.763,"Gulf of Bothnia",3,"gulf"],[-14.387,139.215,"Gulf of Carpentaria",3,"gulf"],[16.3,-88.001,"Gulf of Honduras",3,"gulf"],[24.54,58.766,"Gulf of Oman",3,"gulf"],[63.3,-73.224,"Hudson Strait",3,"strait"],[53.746,-80.255,"James Bay",3,"bay"],[39.863,12.144,"Tyrrhenian Sea",3,"sea"],[65.418,38.854,"White Sea",3,"sea"],[38.899,24.994,"Aegean Sea",4,"sea"],[70.531,-120.687,"Amundsen Gulf",4,"gulf"],[40.132,1.619,"Balearic Sea",4,"sea"],[44.909,-66.051,"Bay of Fundy",4,"bay"],[-37.489,176.808,"Bay of Plenty",4,"bay"],[-3.776,147.903,"Bismarck Sea",4,"sea"],[38.756,120.053,"Bo Hai",4,"sea"],[57.651,-160.179,"Bristol Bay",4,"bay"],[51.086,-5.339,"Bristol Channel",4,"channel"],[-2.412,131.169,"Ceram Sea",4,"sea"],[37.829,-76.031,"Chesapeake Bay",4,"bay"],[59.657,-152.312,"Cook Inlet",4,"bay"],[42.981,3.976,"Golfe du Lion",4,"gulf"],[-46.117,-66.587,"Golfo San Jorge",4,"gulf"],[8.18,-79.211,"Golfo de Panamá",4,"gulf"],[59.969,26.987,"Gulf of Finland",4,"gulf"],[22.57,69.333,"Gulf of Kutch",4,"gulf"],[43.368,-68.504,"Gulf of Maine",4,"gulf"],[8.43,78.962,"Gulf of Mannar",4,"gulf"],[48.615,-60.525,"Gulf of Saint Lawrence",4,"gulf"],[19.791,107.611,"Gulf of Tonkin",4,"gulf"],[33.956,132.471,"Inner Sea",4,"sea"],[56.267,-7.03,"Inner Seas",4,"sea"],[38.178,18.626,"Ionian Sea",4,"sea"],[33.799,128.392,"Korea Strait",4,"strait"],[-1.86,118.021,"Makassar Strait",4,"strait"],[75.523,-61.147,"Melville Bay",4,"bay"],[0.591,126.128,"Molucca Sea",4,"sea"],[-35.469,-56.554,"Río de la Plata",4,"gulf"],[59.897,157.821,"Shelikhova Gulf",4,"gulf"],[-9.247,155.069,"Solomon Sea",4,"sea"],[35.783,-5.919,"Strait of Gibraltar",4,"strait"],[5.586,99.038,"Strait of Malacca",4,"strait"],[1.193,103.68,"Strait of Singapore",4,"strait"],[25.571,-79.276,"Straits of Florida",4,"strait"],[24.166,119.387,"Taiwan Strait",4,"strait"],[70.288,-99.272,"The North Western Passages",4,"channel"],[59.341,-67.41,"Ungava Bay",4,"bay"],[73.851,-109.102,"Viscount Melville Sound",4,"sound"]]}

package/docs/language-reference.md

@@ -2644,7 +2644,9 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
 
-**How the map type is decided (inference):** the resolver takes the bounding box of everything referenced (valued/tagged regions + POIs + edge endpoints), pads it, and measures its span. Projection: `albers-usa` (US conic + AK/HI insets) when the map is US-only; else `equirectangular` snapped to the full Greenwich world when the span is world-scale (≥ ~90°); else `mercator` for a tight regional cluster; else `equirectangular`. The US-state mesh is added whenever you name a US state. Directives only matter to *override* this: `region us-states` forces the state mesh + US scoping (useful on a POI-only US map, redundant once you name a state); `projection …` forces the projection; **`region world` is currently inert** — world is already the default, so it changes nothing (the frame widens from a world-scale longitude span, not this directive).
+**The zero-config map is the good-looking map.** Type `map`, name some places, and you're done — coastlines, mountain relief (on reference maps), region/POI labels, and orientation labels all render by default. There is no projection, scale, or label directive; the only knobs are the bare `no-*` opt-outs.
+
+**How the map type is decided (inference):** the resolver takes the bounding box of everything referenced (valued/tagged regions + POIs + edge endpoints), pads it, and measures its span. Projection is **always inferred — never configured**: `albers-usa` (US conic + AK/HI insets) when the map is US-oriented; at world/multi-continent scale a **data** map (any region/POI carries `value:` or a tag) gets **Equal Earth** (equal-area — honest for thematic comparison) while a **dataless reference** map gets **natural-earth** (the prettier curved compromise); `mercator` for a tight regional or single-continent cluster. The US-state mesh is added whenever you name a US state (or the map is US-oriented).
 
 ### Declaration
 
@@ -2660,7 +2662,6 @@ A subdivision name on its own line with a `value:` fills with a single-hue tint
 
 ```
 map US Sales
-region us-states
 region-metric Sales ($M)
 
 California value: 92
@@ -2668,7 +2669,8 @@ Texas value: 78
 Florida value: 51
 ```
 
-- `region-metric <label>` labels the ramp in the legend; a trailing color on it sets the ramp hue (`region-metric Sales ($M) blue` → blue ramp, default red). `scale <min> <max>` overrides the auto anchors.
+- `region-metric <label>` labels the ramp in the legend; a trailing color on it sets the ramp hue (`region-metric Sales ($M) blue` → blue ramp, default red).
+- The ramp **auto-fits**: all-non-negative data anchors the low end at **0** (shared baseline); mixed-sign data fits data-min→data-max. There is no `scale` directive.
 - A subdivision with no `value:`/tag renders as the neutral base.
 
 ### Region fill — categorical (tags)
@@ -2677,7 +2679,6 @@ Uses the universal tag model (§1.3): declare a `tag` group and apply its alias
 
 ```
 map Global Presence
-region world
 
 tag Market as m
   HQ blue
@@ -2734,18 +2735,28 @@ dcw                     # hub/star — indented edges share the source
   -> office-west
 ```
 
-`~>` curves a single edge. No geographic path-finding — legs are straight or arced.
+`~>` curves a single edge. There is no geographic path-finding and no `surface:` — legs are plain straight or arced geometry (`style: arc` to bow one) and may cross land.
+
+```
+map Caribbean Cruise
+
+route Miami style: arc
+  -weigh anchor-> Havana
+  -> Kingston
+  -> Cartagena
+```
 
 ### Labels, legend & chrome
 
-- Title is the declaration line; `subtitle` / `caption` are directives.
+- Title is the declaration line; `caption` (data-source attribution, travels with the exported PNG) is the only chrome directive. There is no `subtitle`.
 - Legend auto-composes below the title: the value ramp + `region-metric` and each tag group are **selectable colouring groups** (collapse/activate to flip the fill); POI size (`poi-metric`) and edge thickness (`flow-metric`) are self-evident from scale and carry no legend key in v1. `no-legend` suppresses all of it.
-- `region-labels full | abbrev | off` (default `off`); `poi-labels off | auto | all` (default `auto`). Labels render **on the map** (export-safe), escalating inline → leader line → numbered pin in dense clusters; markers never move.
+- **Region and POI labels are on by default.** Region labels auto-fit **full → abbrev → hide** (a US-state 2-letter abbreviation is tried when the full name doesn't fit; other regions degrade full → hide); POI labels are collision-managed. Labels render **on the map** (export-safe), escalating inline → leader line → numbered pin in dense clusters; markers never move. A wide map in a narrow column (< ~480px) prefers abbreviations and drops reference relief, as if zoomed out.
+- **Cosmetic features are on by default**; the only switches are bare `no-*` opt-outs (no positive opt-in flag): `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-legend`. A plain look = the four basemap flags together.
 
 ### Name resolution
 
 - Admin units use **ISO 3166** (geometry keyed by code, so "United States" / "USA" / "US" resolve alike); cities use **GeoNames** (alias/accent matching, population ranking, did-you-mean).
-- `default-country` / `default-state <ISO>` scopes bare city resolution (inferred from content if unset).
+- `locale <ISO>` scopes bare city resolution to a country (`locale US`) or subdivision (`locale US-GA`) — inferred from content if unset.
 - A bare ambiguous, undeclared name → most-populous in scope (info note).
 - **Disambiguate once:** trailing ISO code at first declaration — `San Jose CR` (country) or `Portland US-OR` (subdivision). Thereafter reference the bare name. Two same-named cities → `as <alias>` each.
 - **Region fills disambiguate the country-vs-state collision** (`Georgia` = country `GE` or US state `US-GA`) by ISO code or name + scope — pick whichever reads best:
@@ -2756,7 +2767,7 @@ dcw                     # hub/star — indented edges share the source
 
 ### Directives & reserved keys
 
-Directives (no colon): `region` (world | us-states), `projection` (equirectangular | natural-earth | albers-usa | mercator), `region-metric`, `poi-metric`, `flow-metric`, `scale`, `region-labels`, `poi-labels`, `default-country`, `default-state`, `active-tag`, `no-legend`, `subtitle`, `caption`. Reserved metadata keys (need colons): `value`, `label`, `style` (`value` = the one numeric channel: region shade / POI size / edge thickness). A bare US state postal code resolves to that state (`poi Portland OR` → Oregon; `CA` = California). Coordinates are positional (no `at:` key). Projection is auto-picked by extent span (world → equirectangular, full Greenwich frame; US → albers-usa with Alaska/Hawaii insets; tight regional → mercator) unless overridden.
+The directive set is **12, all colon-free**: six naming intent the renderer can't infer — `region-metric`, `poi-metric`, `flow-metric`, `locale`, `active-tag`, `caption` — and six `no-*` cosmetic opt-outs — `no-legend`, `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`. There is **no** `projection`, `scale`, `subtitle`, `surface`, `region`, or label-enum directive, and cosmetics have no positive opt-in form. Reserved metadata keys (need colons): `value`, `label`, `style` (`value` = the one numeric channel: region shade / POI size / edge thickness); `surface:` is no longer recognized. A bare US state postal code resolves to that state (`poi Portland OR` → Oregon; `CA` = California). Coordinates are positional (no `at:` key). Projection is inferred from extent + whether the map carries data (US → albers-usa; world data → Equal Earth; world reference → natural-earth; regional → mercator) and cannot be overridden.
 
 ---
 

package/gallery/fixtures/map-categorical-world.dgmo

@@ -0,0 +1,16 @@
+map Global Market Presence
+
+tag Market as m
+  HQ blue
+  Region teal
+  Prospect orange
+active-tag Market
+
+United States m: HQ
+Germany m: Region
+Japan m: Region
+Brazil m: Prospect
+India m: Region
+Australia m: Prospect
+South Africa m: Prospect
+Indonesia m: Prospect

package/gallery/fixtures/map-categorical.dgmo

@@ -1,5 +1,4 @@
 map Global Market Presence
-region world
 
 tag Market as m
   HQ blue

package/gallery/fixtures/map-choropleth.dgmo

@@ -1,5 +1,4 @@
 map US Sales by State
-region us-states
 region-metric Sales ($M)
 
 California value: 92

package/gallery/fixtures/map-coastline.dgmo

@@ -0,0 +1,7 @@
+map Smuggler's Run
+
+poi Havana value: 90
+poi Kingston value: 120
+
+route Havana style: arc
+  -run the blockade-> Kingston

package/gallery/fixtures/map-colorize.dgmo

@@ -0,0 +1,11 @@
+map Privateer's Atlas
+
+// Regions named, no value: or tags → colorize is the inferred dress: every
+// state/country gets a distinct pastel and no two neighbours share a hue
+// (4-colour political look). The named states aren't special — the whole drawn
+// mesh colours, so it reads as one chart. `no-colorize` would force green-land.
+California
+Texas
+Florida
+New York
+Washington

package/gallery/fixtures/map-direct-color.dgmo

@@ -1,5 +1,4 @@
 map Regional Focus
-region us-states
 region-metric Sales ($M) blue
 
 California value: 92

package/gallery/fixtures/map-reference-world.dgmo

@@ -0,0 +1,11 @@
+map World Reference
+
+// A dataless reference map (regions named, no value: or tags) — so the
+// zero-config basemap shows its full dress: coastline water-lines, mountain
+// relief, and orientation labels, on a natural-earth projection.
+United States
+Brazil
+Egypt
+India
+Japan
+Australia

package/gallery/fixtures/map-region-scope.dgmo

@@ -1,8 +1,5 @@
 map Region Scope Disambiguation
-region us-states
 region-metric Sales ($M)
-region-labels abbrev
-subtitle Pin a country/state name clash by ISO code (US-GA) or name + scope (Georgia US)
 
 California value: 92
 Texas value: 78

package/gallery/fixtures/map-route.dgmo

@@ -1,5 +1,4 @@
 map Caribbean Cruise
-projection mercator
 
 route Miami style: arc
   -weigh anchor-> Havana

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

package/src/advanced.ts

@@ -540,6 +540,14 @@ export type {
   MapLayoutLegend,
 } from './map/layout';
 export { renderMap, renderMapForExport } from './map/renderer';
+// Content-aware export dimensions — derive the canvas height from a map's intrinsic
+// projected aspect so exports/embeds match the content's natural shape (no vertical
+// stretch). Used by the CLI/MCP/SSG export path and by Obsidian's DI render.
+export {
+  mapContentAspect,
+  mapExportDimensions,
+  type MapExportDimensions,
+} from './map/dimensions';
 // Map geo-query (step-5 coordinate/location inspector) — a SEPARATE entry from
 // the renderer; takes `MapData` by DI so it's browser-safe (never calls the
 // Node-only `loadMapData`).
@@ -734,7 +742,10 @@ export {
   gruvboxPalette,
   tokyoNightPalette,
   oneDarkPalette,
-  boldPalette,
+  atlasPalette,
+  blueprintPalette,
+  slatePalette,
+  tidewaterPalette,
   draculaPalette,
   monokaiPalette,
 } from './palettes';

package/src/boxes-and-lines/renderer.ts

@@ -324,6 +324,9 @@ interface BLRenderOptions {
   onToggleDescriptions?: (active: boolean) => void;
   onToggleControlsExpand?: () => void;
   exportMode?: boolean;
+  /** When 'app', the description toggle is hosted by the app overlay strip
+   *  (inline gear suppressed, controls row + anchor reserved). */
+  controlsHost?: 'app' | 'inline';
 }
 
 export function renderBoxesAndLines(
@@ -344,6 +347,7 @@ export function renderBoxesAndLines(
     onToggleDescriptions,
     onToggleControlsExpand,
     exportMode = false,
+    controlsHost,
   } = options ?? {};
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
 
@@ -364,16 +368,27 @@ export function renderBoxesAndLines(
   const sGroupLabelZone = sctx.structural(GROUP_LABEL_ZONE);
   const sTitleFontSize = sctx.text(TITLE_FONT_SIZE);
   const sTitleY = sctx.structural(TITLE_Y);
-  const sLegendHeight = sctx.structural(
-    getMaxLegendReservedHeight(
-      {
-        groups: parsed.tagGroups,
-        position: { placement: 'top-center', titleRelation: 'below-title' },
-        mode: exportMode ? 'export' : 'preview',
-      },
-      width
-    )
+  // Reserve legend height only when a legend will actually render. App-hosted
+  // controls move the Descriptions toggle to the app overlay, so a
+  // descriptions-only chart (no tag groups) reserves nothing.
+  const reserveHasDescriptions = parsed.nodes.some(
+    (n) => n.description && n.description.length > 0
   );
+  const willRenderLegend =
+    parsed.tagGroups.length > 0 ||
+    (reserveHasDescriptions && controlsHost !== 'app');
+  const sLegendHeight = willRenderLegend
+    ? sctx.structural(
+        getMaxLegendReservedHeight(
+          {
+            groups: parsed.tagGroups,
+            position: { placement: 'top-center', titleRelation: 'below-title' },
+            mode: exportMode ? 'export' : 'preview',
+          },
+          width
+        )
+      )
+    : 0;
 
   const activeGroup = resolveActiveTagGroup(
     parsed.tagGroups,
@@ -995,12 +1010,17 @@ export function renderBoxesAndLines(
   const hasDescriptions = parsed.nodes.some(
     (n) => n.description && n.description.length > 0
   );
-  const hasLegend = parsed.tagGroups.length > 0 || hasDescriptions;
+  // App-hosted: the Descriptions control moves to the app overlay, so a
+  // descriptions-only legend (no tag groups) has nothing left to render.
+  const hasLegend =
+    parsed.tagGroups.length > 0 || (hasDescriptions && controlsHost !== 'app');
 
   if (hasLegend) {
-    // Build controls group for description toggle
+    // Build controls group for description toggle. App-hosted controls own the
+    // toggling, so the group is built (to gate + size the row) even without the
+    // inline-gear callback.
     let controlsGroup: { toggles: ControlsGroupToggle[] } | undefined;
-    if (hasDescriptions && onToggleDescriptions) {
+    if (hasDescriptions && (onToggleDescriptions || controlsHost === 'app')) {
       controlsGroup = {
         toggles: [
           {
@@ -1018,7 +1038,14 @@ export function renderBoxesAndLines(
       groups: parsed.tagGroups,
       position: { placement: 'top-center', titleRelation: 'below-title' },
       mode: exportMode ? 'export' : 'preview',
+      // Keep inactive sibling tag groups visible as collapsed pills so the user
+      // can click one to flip the active colouring dimension (preview only —
+      // export shows just the active group). Without this, declaring a second
+      // tag group (e.g. Team) leaves it invisible whenever another group is
+      // active. The app's BoxesAndLinesPreview already wires pill clicks.
+      showInactivePills: true,
       ...(controlsGroup !== undefined && { controlsGroup }),
+      ...(controlsHost !== undefined && { controlsHost }),
     };
     const legendState: LegendState = {
       activeGroup,

package/src/cli.ts

@@ -136,7 +136,7 @@ Key options:
 - \`-o <file>\` — output file; format inferred from extension (\`.svg\` → SVG, else PNG)
 - \`-o url\` — output a shareable diagrammo.app URL
 - \`--theme <theme>\` — \`light\` (default), \`dark\`, \`transparent\`
-- \`--palette <name>\` — \`nord\` (default), \`solarized\`, \`catppuccin\`, \`rose-pine\`, \`gruvbox\`, \`tokyo-night\`, \`one-dark\`, \`bold\`
+- \`--palette <name>\` — \`nord\` (default), \`atlas\`, \`blueprint\`, \`slate\`, \`tidewater\`, \`solarized\`, \`catppuccin\`, \`rose-pine\`, \`gruvbox\`, \`tokyo-night\`, \`one-dark\`, \`dracula\`, \`monokai\`
 - \`--copy\` — copy the URL to clipboard (use with \`-o url\`)
 - \`--chart-types\` — list all supported chart types
 

package/src/completion.ts

@@ -98,9 +98,12 @@ const GLOBAL_DIRECTIVES: Record<string, DirectiveValueSpec> = {
       'gruvbox',
       'tokyo-night',
       'one-dark',
-      'bold',
       'dracula',
       'monokai',
+      'atlas',
+      'blueprint',
+      'slate',
+      'tidewater',
     ],
   },
   theme: {
@@ -508,19 +511,12 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
   ],
   [
     'map',
-    // Geographic map directives (§24B.2/.7). `poi`/`route` are content
-    // keywords, not directives; metadata keys (value/label/style) live in the
-    // reserved-key registry.
+    // Geographic map directives (§24B.2/.7). Cosmetics are ON by default — the
+    // only switches are bare `no-*` opt-outs, surfaced proactively so a
+    // zero-config map still hints at what can be turned off. `poi`/`route` are
+    // content keywords, not directives; metadata keys (value/label/style) live
+    // in the reserved-key registry.
     withGlobals({
-      region: {
-        description:
-          'Basemap: us-states (force US state mesh + scoping) | world (inert — already the default)',
-        values: ['us-states', 'world'],
-      },
-      projection: {
-        description: 'Override the auto projection',
-        values: ['equirectangular', 'natural-earth', 'albers-usa', 'mercator'],
-      },
       'region-metric': { description: 'Label for the region value ramp' },
       'poi-metric': {
         description: 'Label for the POI value (marker size) channel',
@@ -528,21 +524,32 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
       'flow-metric': {
         description: 'Label for the edge/leg value (thickness) channel',
       },
-      scale: { description: 'Override value ramp anchors: scale <min> <max>' },
-      'region-labels': {
-        description: 'Subdivision name labels',
-        values: ['full', 'abbrev', 'off'],
+      locale: {
+        description:
+          'Default country/state for bare place names, e.g. locale US-GA',
       },
-      'poi-labels': {
-        description: 'POI labels/values',
-        values: ['off', 'auto', 'all'],
+      'active-tag': {
+        description: 'Which tag group leads when several are present',
       },
-      'default-country': { description: 'ISO scope for bare city resolution' },
-      'default-state': { description: 'ISO subdivision scope' },
+      caption: { description: 'Caption line (data-source attribution)' },
       'no-legend': { description: 'Suppress the legend' },
-      relief: { description: 'Subtle mountain-range relief shading' },
-      subtitle: { description: 'Subtitle line' },
-      caption: { description: 'Caption line' },
+      'no-coastline': {
+        description: 'Turn off coastal water-lines (on by default)',
+      },
+      'no-relief': {
+        description: 'Turn off mountain-range relief shading (on by default)',
+      },
+      'no-context-labels': {
+        description: 'Turn off orientation labels for water + nearby countries',
+      },
+      'no-region-labels': {
+        description: 'Turn off subdivision name labels (on by default)',
+      },
+      'no-poi-labels': { description: 'Turn off POI labels (on by default)' },
+      'no-colorize': {
+        description:
+          'Force plain green-land reference dress (regions are auto-coloured by default)',
+      },
     }),
   ],
 ]);

package/src/cycle/renderer.ts

@@ -48,6 +48,10 @@ export interface CycleRenderOptions {
   onToggleDescriptions?: (active: boolean) => void;
   onToggleControlsExpand?: () => void;
   exportMode?: boolean;
+  /** When 'app', the description toggle is hosted by the app overlay strip:
+   *  the inline gear is suppressed and a controls row + anchor are reserved.
+   *  Default (inline) renders the gear as before. */
+  controlsHost?: 'app' | 'inline';
 }
 
 /**
@@ -92,7 +96,13 @@ export function renderCycle(
   const hasDescriptions =
     parsed.nodes.some((n) => n.description.length > 0) ||
     parsed.edges.some((e) => e.description.length > 0);
-  const hasLegend = hasDescriptions && !!renderOptions?.onToggleDescriptions;
+  // App-hosted: controls live in the app overlay strip. Cycle has no tag groups,
+  // so there's no in-SVG legend left to render — don't reserve a legend band.
+  const appHostedControls = renderOptions?.controlsHost === 'app';
+  const hasLegend =
+    !appHostedControls &&
+    hasDescriptions &&
+    !!renderOptions?.onToggleDescriptions;
 
   const showTitle = !!parsed.title && parsed.options['no-title'] !== 'on';
   const legendOffset = hasLegend ? sLegendHeight : 0;
@@ -160,6 +170,9 @@ export function renderCycle(
       position: { placement: 'top-center', titleRelation: 'below-title' },
       mode: renderOptions?.exportMode ? 'export' : 'preview',
       controlsGroup,
+      ...(renderOptions?.controlsHost !== undefined && {
+        controlsHost: renderOptions.controlsHost,
+      }),
     };
     const legendState: LegendState = {
       activeGroup: null,

package/src/d3.ts

@@ -8459,6 +8459,7 @@ export async function renderForExport(
     const { parseMap } = await import('./map/parser');
     const { resolveMap } = await import('./map/resolver');
     const { renderMapForExport } = await import('./map/renderer');
+    const { mapExportDimensions } = await import('./map/dimensions');
 
     const effectivePalette = await resolveExportPalette(theme, palette);
     const mapParsed = parseMap(content);
@@ -8478,14 +8479,19 @@ export async function renderForExport(
     }
     const mapResolved = resolveMap(mapParsed, mapData);
 
-    const container = createExportContainer(EXPORT_WIDTH, EXPORT_HEIGHT);
+    // Content-aware canvas: derive the height from the map's intrinsic projected
+    // aspect (world ~2.3:1, a region taller, etc.) instead of the fixed 800, so the
+    // export matches the content's natural shape — no vertical stretch, no
+    // letterbox bands. `preferContain` rides along to the renderer.
+    const dims = mapExportDimensions(mapResolved, mapData, EXPORT_WIDTH);
+    const container = createExportContainer(dims.width, dims.height);
     renderMapForExport(
       container,
       mapResolved,
       mapData,
       effectivePalette,
       theme === 'dark',
-      { width: EXPORT_WIDTH, height: EXPORT_HEIGHT }
+      dims
     );
     return finalizeSvgExport(container, theme, effectivePalette);
   }

package/src/editor/highlight-api.ts

@@ -200,6 +200,10 @@ const ATTRIBUTE_KEYS = new Set([
   'tech',
   'span',
   'split',
+  // Map (§24B) reserved keys
+  'value',
+  'label',
+  'style',
 ]);
 
 /**

package/src/editor/keywords.ts

@@ -80,11 +80,10 @@ export const METADATA_KEYS = new Set([
   'quadrant',
   'ring',
   'trend',
-  // Map (§24B) metadata keys
-  'score',
+  // Map (§24B) reserved metadata keys
+  'value',
   'label',
-  'description',
-  'weight',
+  'style',
 ]);
 
 /** Tag declaration keyword. */
@@ -150,22 +149,20 @@ export const DIRECTIVE_KEYWORDS = new Set([
   // Sequence
   'activations',
   'no-activations',
-  // Map (§24B) directives
-  'region',
-  'projection',
+  // Map (§24B) directives — cosmetics on by default, bare `no-*` opt-outs
   'region-metric',
   'poi-metric',
   'flow-metric',
-  'region-labels',
-  'poi-labels',
-  'default-country',
-  'default-state',
-  'no-legend',
-  'no-insets',
-  'muted',
-  'natural',
-  'subtitle',
+  'locale',
+  'active-tag',
   'caption',
+  'no-legend',
+  'no-coastline',
+  'no-relief',
+  'no-context-labels',
+  'no-region-labels',
+  'no-poi-labels',
+  'no-colorize',
   'poi',
   'route',
   // Data charts

package/src/infra/renderer.ts

@@ -2080,9 +2080,13 @@ function renderLegend(
   isDark: boolean,
   activeGroup: string | null,
   playback?: InfraPlaybackState,
-  exportMode = false
+  exportMode = false,
+  controlsHost?: 'app' | 'inline'
 ) {
   if (legendGroups.length === 0 && !playback) return;
+  // App-hosted playback: the play/pause + speed UI lives in the app overlay
+  // strip, so suppress the in-SVG Playback pill and emit the controls anchor.
+  const appHostedPlayback = controlsHost === 'app' && !!playback;
 
   const legendG = rootSvg
     .append('g')
@@ -2097,8 +2101,9 @@ function renderLegend(
     name: g.name,
     entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
   }));
-  // Add Playback as a group with empty entries (collapsed pill) or dummy entries (expanded)
-  if (playback) {
+  // Add Playback as a group with empty entries (collapsed pill) or dummy entries
+  // (expanded) — unless the app hosts it, in which case it's suppressed.
+  if (playback && !appHostedPlayback) {
     allGroups.push({ name: 'Playback', entries: [] });
   }
 
@@ -2107,6 +2112,20 @@ function renderLegend(
     position: { placement: 'top-center', titleRelation: 'below-title' },
     mode: exportMode ? 'export' : 'preview',
     showEmptyGroups: true,
+    ...(appHostedPlayback && {
+      controlsHost: 'app' as const,
+      controlsGroup: {
+        toggles: [
+          {
+            id: 'playback',
+            type: 'toggle' as const,
+            label: 'Playback',
+            active: true,
+            onToggle: () => {},
+          },
+        ],
+      },
+    }),
   };
   const legendState: LegendState = { activeGroup };
   renderLegendD3(
@@ -2233,9 +2252,13 @@ export function renderInfra(
   playback?: InfraPlaybackState | null,
   expandedNodeIds?: Set<string> | null,
   exportMode?: boolean,
-  collapsedNodes?: Set<string> | null
+  collapsedNodes?: Set<string> | null,
+  /** When 'app', the playback pill is suppressed and a controls row + anchor are
+   *  reserved for the app overlay strip (play/pause + speed live there). */
+  controlsHost?: 'app' | 'inline'
 ) {
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
+  const appHostedPlayback = controlsHost === 'app' && !!playback;
 
   const ctx = ScaleContext.identity();
   const sc = buildScaledConstants(ctx);
@@ -2246,7 +2269,10 @@ export function renderInfra(
     palette,
     layout.edges
   );
-  const hasLegend = legendGroups.length > 0 || !!playback;
+  // App-hosted: the playback pill moves to the app overlay, so a playback-only
+  // legend (no tag groups) has nothing left to render.
+  const hasLegend =
+    legendGroups.length > 0 || (!!playback && !appHostedPlayback);
   const fixedLegend = !exportMode && hasLegend;
   const legendDynamicH = hasLegend
     ? getMaxLegendReservedHeight(
@@ -2461,7 +2487,8 @@ export function renderInfra(
         isDark,
         activeGroup ?? null,
         playback ?? undefined,
-        exportMode
+        exportMode,
+        controlsHost
       );
       // Re-enable pointer events on interactive legend elements
       legendSvg
@@ -2478,7 +2505,8 @@ export function renderInfra(
         isDark,
         activeGroup ?? null,
         playback ?? undefined,
-        exportMode
+        exportMode,
+        controlsHost
       );
     }
   }