Merge pull request #81 from barrulus/feat/settlemaker-water-context-v1

Add gated measured water context for Settlemaker village previews

Author: barrulus

docs/domain/settlemaker-water-context.md

@@ -0,0 +1,77 @@
+# Settlemaker measured village water
+
+FMG implements the sender side of Settlemaker's `water-context-v1` contract
+(`settlemaker/docs/water-context-v1.md`, revision `8ebc23a`). The renderer must
+implement that contract before this mode is enabled.
+
+## Rollout
+
+`VITE_SETTLEMAKER_WATER_CONTEXT_URL` is a build-time opt-in. Leave it unset for
+normal production builds until a deployed Settlemaker release explicitly supports
+water-context v1 for villages. An old decoder ignores the new field and can still
+invent a nearby shore from the legacy bearing.
+
+To exercise a supporting local renderer:
+
+```sh
+VITE_SETTLEMAKER_WATER_CONTEXT_URL=http://127.0.0.1:5173/fmg npm run dev
+```
+
+Production endpoints must use HTTPS and the `/fmg` path, without a query or
+fragment. Pin the supporting renderer release in the deployment and configure
+its endpoint when building FMG. This option routes both embedded and external
+village previews to the same URL. Population 1–1000 uses the new contract;
+cities continue using the existing production URL and payload.
+
+## Sender behavior
+
+- Survey a 3 km radius around the actual burg coordinates, independent of port
+  status. Export the enclosing 6 km square as simple filled water pieces, with
+  islands retained as dry land. Always include `coastlineGeometry`, including
+  an explicit empty array for a dry survey. No simple-coast approximation is used.
+- Use `Coastline.getFeaturePath`, shared with drawing and saving. Loading adopts
+  the saved SVG boundary; surveying does not regenerate or mutate it. Map changes,
+  coastline edits and coastline settings invalidate the geometry cache/index.
+- Convert map coordinates once using the selected distance unit. Flatten curves
+  adaptively within 0.2 m; report a conservative combined `geometryErrorM` of
+  0.5 m. Do not round or simplify exported coordinates. Reject ambiguous narrow
+  or crossing curved shores instead of silently changing local topology.
+- Measure exposed real shores from the same flattened boundary that supplies
+  the polygons. Shared piece edges and survey-square closures are not banks.
+  If real shores lie beyond coverage, search the canonical full boundary.
+- Unsupported custom units produce `unknown-units`, with no metric geometry.
+  FMG currently has no custom metres-per-unit setting.
+- Local river widths are unavailable from the burg context. Omit river surveys
+  and identify context rivers through `omittedRivers`; never substitute the
+  kilometre-valued river mouth width for the width beside the burg.
+- Keep the compressed `i` envelope. If the encoded payload exceeds 8192 bytes,
+  compression fails, or geometry cannot be surveyed safely, show the failure
+  in the burg editor and on an external-open attempt. Do not discard measured
+  state by falling back to a flat URL.
+
+Surveys extending beyond the map rectangle fail explicitly; wrapped geography
+is not inferred. Very detailed coasts can exceed the URL budget. There is no
+automatic simplification or resurvey in this implementation.
+
+## Renderer handoff and validation
+
+Settlemaker owns water-union bank queries, metric layout, bounded planning,
+frame/coverage validation, input precedence and visible iframe diagnostics.
+The FMG sender does not implement those renderer behaviors or an iframe message
+protocol. Before enabling production, verify those behaviors against the
+supporting release in both embedded and external-open flows.
+
+Focused tests cover distance/units, finite lakes and islands, peninsula geometry,
+curve inclusion and precision, narrow channels, union shore measurement, crop
+closures, unknown units, missing local river widths, saved geometry invalidation,
+URL-budget failures, and population 1000/1001 rollout boundaries. The 11,115 m
+Tarrimas-Ha case is synthetic geography reproducing the measured distance; it
+does not replay the original Borteland save.
+
+Browser validation with the sender enabled covered 394 generated villages:
+391 encoded successfully, including 34 with water, and three correctly failed
+the URL budget. Saving/reloading with hidden water layers retained the exact
+saved boundary and surveying left displayed paths untouched. These checks used
+a local URL target to inspect payloads, not a running measured-water renderer.
+The older 1.112.1 map fixture also retained its saved boundary through loading
+and a subsequent measured survey.

src/controllers/burg-editor.ts

@@ -754,9 +754,10 @@ function getPreviewTextureBudgetK(): number {
 }
 
 async function updateBurgPreview(burg: Burg): Promise<void> {
-  const preview = (await Burgs.getPreview(burg)).preview;
+  const { preview, error } = await Burgs.getPreview(burg);
   if (!preview) {
-    ensureEl("burgPreviewSection").style.display = "none";
+    ensureEl("burgPreviewSection").style.display = error ? "block" : "none";
+    ensureEl("burgPreviewObject").textContent = error ?? "";
     return;
   }
 
@@ -790,8 +791,9 @@ async function updateBurgPreview(burg: Burg): Promise<void> {
 async function openBurgLink(): Promise<void> {
   const id = getSelectedId();
   const burg = pack.burgs[id];
-  const link = (await Burgs.getPreview(burg)).link;
+  const { link, error } = await Burgs.getPreview(burg);
   if (link) openURL(link);
+  else if (error) tip(error, true, "error", 8000);
 }
 
 async function setCustomPreview(): Promise<void> {

src/generators/burg-context.ts

@@ -1,3 +1,4 @@
+import { getKmInDistanceUnit } from "@/utils/unitUtils";
 import { rn } from "../utils";
 import type { Burg } from "./burgs-generator";
 
@@ -604,7 +605,7 @@ export function buildBurgContext(burg: Burg): BurgContext {
     scale: populationRate,
     urbanization: { rate: urbanization }
   } = options.map.units.population;
-  const distanceScale = options.map.units.distance.scale;
+  const distanceScale = options.map.units.distance.scale * (getKmInDistanceUnit() || 1);
 
   const population = scaledPopulation(burg.population ?? 0, populationRate, urbanization);
   const radiusKm = effectiveWindowRadiusKm(DEFAULT_WINDOW_RADIUS_KM, distanceScale, Number(grid?.spacing ?? 0));

src/generators/burgs-generator.ts

@@ -1,12 +1,11 @@
 import { quadtree } from "d3-quadtree";
 import { AUTO_BURG_LIMIT } from "@/components/options-schema";
 import { Emblems } from "@/generators/emblems-generator";
-import { buildSettlemakerUrl } from "@/services/previews/settlemaker";
+import { createSettlemakerPreview } from "@/services/previews/settlemaker-burg";
 import type { BurgGroup } from "@/types/burg-groups";
 import type { Emblem } from "@/types/emblems";
 import { safeParseJSON } from "@/utils/stringUtils";
 import { each, gauss, minmax, normalize, P, rn } from "../utils";
-import { buildBurgContext } from "./burg-context";
 import { type CultureType, DEFAULT_CULTURE_TYPE } from "./cultures-generator";
 import { NON_NAVIGABLE_LAKE_GROUPS } from "./features";
 import type { Label } from "./labels-generator";
@@ -1425,7 +1424,7 @@ class BurgModule {
     return { link, preview: `${link}&preview=1` };
   }
 
-  async getPreview(burg: Burg): Promise<{ link: string | null; preview: string | null }> {
+  async getPreview(burg: Burg): Promise<{ link: string | null; preview: string | null; error?: string }> {
     const previewGeneratorsMap: Record<
       string,
       (
@@ -1435,11 +1434,7 @@ class BurgModule {
       "watabou-city": (burg: Burg) => this.createWatabouCityLinks(burg),
       "watabou-village": (burg: Burg) => this.createWatabouVillageLinks(burg),
       "watabou-dwelling": (burg: Burg) => this.createWatabouDwellingLinks(burg),
-      settlemaker: (burg: Burg) =>
-        buildSettlemakerUrl(buildBurgContext(burg), {
-          urbanDensity: options.map.units.population.urbanization.density,
-          trade: burg.tradeRole === "hub"
-        })
+      settlemaker: createSettlemakerPreview
     };
     if (burg.link) return { link: burg.link, preview: burg.link };
 
@@ -1451,7 +1446,11 @@ class BurgModule {
     } catch (error) {
       // Never throw into the editor: a broken preview must not take the dialog down.
       ERROR && console.error("Failed to build burg preview", error);
-      return { link: null, preview: null };
+      return {
+        link: null,
+        preview: null,
+        error: error instanceof Error ? error.message : "Cannot create this burg preview"
+      };
     }
   }
 

src/generators/coastline-generator.test.ts

@@ -49,6 +49,21 @@ describe("settings", () => {
 });
 
 describe("getFeaturePath", () => {
+  it("retains a loaded displayed boundary until its geometry or settings change", () => {
+    pack.features = [undefined, island] as unknown as typeof pack.features;
+    const saved = "M10,10L90,10L90,90L10,90Z";
+    Coastline.restorePaths([[1, saved]]);
+    const revision = Coastline.boundaryRevision;
+    expect(Coastline.getFeaturePath(island)).toBe(saved);
+    expect(Coastline.boundaryRevision).toBe(revision);
+    pack.vertices.p[0] = [12, 10];
+    expect(Coastline.getFeaturePath(island)).not.toBe(saved);
+    expect(Coastline.boundaryRevision).toBeGreaterThan(revision);
+    Coastline.restorePaths([[1, saved]]);
+    Coastline.update({ enabled: false });
+    expect(Coastline.getFeaturePath(island)).not.toBe(saved);
+  });
+
   it("reproduces the same coastline for the same seed and settings", () => {
     const path = Coastline.getFeaturePath(island);
 

src/generators/coastline-generator.ts

@@ -247,6 +247,41 @@ function buildCoastlinePath({ points, origIndices }: FractalizedShape): string {
  */
 class CoastlineGenerator {
   readonly PROFILE_SIZE = PROFILE_SIZE;
+  private paths = new WeakMap<Feature, { source: string; path: string }>();
+  private graph?: typeof pack.vertices;
+  private configuration = "";
+  private revision = 0;
+
+  get boundaryRevision(): number {
+    const configuration = JSON.stringify([
+      options.map.seed,
+      options.map.graph.width,
+      options.map.graph.height,
+      this.settings
+    ]);
+    if (this.graph !== pack.vertices || this.configuration !== configuration) {
+      this.graph = pack.vertices;
+      this.configuration = configuration;
+      this.paths = new WeakMap();
+      this.revision++;
+    }
+    return this.revision;
+  }
+
+  /** IO adopts the saved display geometry before any layer redraw can replace it. */
+  restorePaths(paths: Iterable<[number, string]>): void {
+    this.boundaryRevision;
+    this.paths = new WeakMap();
+    for (const [id, path] of paths) {
+      const feature = pack.features[id];
+      if (feature && path) this.paths.set(feature, { source: this.sourceKey(feature), path });
+    }
+    this.revision++;
+  }
+
+  private sourceKey(feature: Feature): string {
+    return JSON.stringify([feature.type, feature.vertices.map(vertex => pack.vertices.p[vertex])]);
+  }
 
   /** Settings of the map on screen: a fact, read at render time and saved with the file */
   get settings(): CoastlineSettings {
@@ -265,6 +300,10 @@ class CoastlineGenerator {
 
   /** Closed SVG path of the feature outline, fractalized as configured */
   getFeaturePath(feature: Feature): string {
+    this.boundaryRevision;
+    const source = this.sourceKey(feature);
+    const cached = this.paths.get(feature);
+    if (cached?.source === source) return cached.path;
     const points = feature.vertices.map(vertex => pack.vertices.p[vertex]);
     if (points.some(point => point === undefined)) {
       ERROR && console.error("Undefined point in getFeaturePath");
@@ -274,7 +313,10 @@ class CoastlineGenerator {
     const simplifiedPoints = simplify(points, SIMPLIFICATION_TOLERANCE);
     const clippedPoints = clipPoly(simplifiedPoints, options.map.graph.width, options.map.graph.height, 1);
     const shape = this.fractalizeFeature(clippedPoints, feature);
-    return `${round(buildCoastlinePath(shape))}Z`;
+    const path = `${round(buildCoastlinePath(shape))}Z`;
+    this.paths.set(feature, { source, path });
+    this.revision++;
+    return path;
   }
 
   /** Displace a polygon into a naturalistic coastline. Deterministic: the same rand and settings repeat the shape */

src/services/io/load.ts

@@ -7,6 +7,7 @@ import { syncOptionInputs } from "@/components/options/tabs/options-tab";
 import { clearMainTip, tip } from "@/components/tooltips";
 import { applyDefaultViewboxEvents } from "@/components/viewbox-events";
 import { resetZoom } from "@/components/zoom";
+import { Coastline } from "@/generators/coastline-generator";
 import { GraphOverride } from "@/generators/graph-override";
 import { invalidateEmblems } from "@/renderers/draw-emblems";
 import { onLegendClick } from "@/renderers/draw-legend";
@@ -383,6 +384,12 @@ async function parseLoadedData(data: string[], mapVersion: string | null): Promi
 
     if (data[50]) Layers.restore(JSON.parse(data[50]));
     if (data[51]) GraphOverride.restore(JSON.parse(data[51]));
+    Coastline.restorePaths(
+      Array.from(document.querySelectorAll<SVGPathElement>("#featurePaths > path"), path => [
+        Number(path.dataset.f ?? path.id.replace("feature_", "")),
+        path.getAttribute("d") ?? ""
+      ])
+    );
 
     Goods.sync();
     Markets.sync();

src/services/previews/burg-water-survey.test.ts

@@ -0,0 +1,15 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Burg } from "@/generators/burgs-generator";
+import { surveyBurgWater } from "./burg-water-survey";
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("unknown physical units", () => {
+  it("reports custom units without reading geometry or asserting empty water", () => {
+    vi.stubGlobal("options", { map: { units: { distance: { unit: "hexes", scale: 3 } } } });
+    expect(surveyBurgWater({ i: 7, x: 100, y: 100 } as Burg)).toEqual({
+      waterContext: { version: 1, status: "unknown-units", sourceUnit: "hexes" }
+    });
+  });
+});

src/services/previews/burg-water-survey.ts

@@ -0,0 +1,65 @@
+import { quadtree } from "d3";
+import type { Burg } from "@/generators/burgs-generator";
+import { Coastline } from "@/generators/coastline-generator";
+import { getKmInDistanceUnit } from "@/utils/unitUtils";
+import type { WaterSurvey } from "./water-context-types";
+import { WaterSurveyIndex } from "./water-survey";
+
+let cached:
+  | {
+      features: typeof pack.features;
+      revision: number;
+      index: WaterSurveyIndex;
+      oceans: ReturnType<typeof quadtree<[number, number, number]>>;
+    }
+  | undefined;
+
+export function surveyBurgWater(burg: Burg, omittedRiverIds: number[] = []): WaterSurvey {
+  const kmPerUnit = getKmInDistanceUnit();
+  if (!kmPerUnit)
+    return {
+      waterContext: {
+        version: 1,
+        status: "unknown-units",
+        sourceUnit: options.map.units.distance.unit
+      }
+    };
+  if (!cached || cached.features !== pack.features || cached.revision !== Coastline.boundaryRevision) {
+    const boundaries = pack.features
+      .filter(feature => feature && feature.type !== "ocean")
+      .map(feature => ({
+        id: feature.i,
+        kind: feature.type as "island" | "lake",
+        path: Coastline.getFeaturePath(feature)
+      }));
+    const oceans = quadtree<[number, number, number]>()
+      .x(p => p[0])
+      .y(p => p[1]);
+    for (const cell of pack.cells.i)
+      if (pack.features[pack.cells.f[cell]]?.type === "ocean") {
+        oceans.add([pack.cells.p[cell][0], pack.cells.p[cell][1], pack.cells.f[cell]]);
+      }
+    cached = {
+      features: pack.features,
+      revision: Coastline.boundaryRevision,
+      oceans,
+      index: new WaterSurveyIndex(boundaries, {
+        minX: 0,
+        minY: 0,
+        maxX: options.map.graph.width,
+        maxY: options.map.graph.height
+      })
+    };
+  }
+  const oceanIndex = cached.oceans;
+  return cached.index.survey({
+    burg,
+    metresPerMapUnit: options.map.units.distance.scale * kmPerUnit * 1000,
+    oceanAt: point => {
+      const ocean = oceanIndex.find(point.x, point.y);
+      if (!ocean) throw new Error("The map has no ocean feature for this measured water area");
+      return ocean[2];
+    },
+    omittedRiverIds
+  });
+}