@world-engines/project-host 0.1.0-alpha.0

package/assets/gui/world-map.js

@@ -0,0 +1,2466 @@
+import { DEFAULT_PLANE_GENERATION, PLANE_GENERATION_MAX_EXTENT_METERS, PLANE_GENERATION_PROFILE, validatePlaneGeneration } from "./plane-generation.js";
+import { PALETTE, PROCEDURAL_GENERATOR_IDENTITY, PROCEDURAL_WORLD_PROFILE, generateCityLayout, validateProceduralWorld } from "./procedural-city.js";
+import { DEFAULT_ROAD_GENERATION, ROAD_GENERATION_IDENTITY, ROAD_GENERATION_PROFILE, roadGenerationUpgradeTarget, roadParcelAlgorithm, validateRoadGeneration } from "./road-generation.js";
+import { generateRoadParcels } from "./road-parcels.js";
+import { resolveRoadParcelTemplateSettings, validateSpatialTemplateConfiguration } from "./spatial-templates.js";
+import { DEFAULT_TERRAIN_LAYERS, contourSegments, hillshadeAt, packContourSegments, sharedContourPlan } from "./terrain-render.js";
+import { renderWorkspaceStatus } from "./workspace-status.js";
+
+const LOD_TILE_SIZE = 128;
+const LOD_MAX_LEVEL = 12;
+const LOD_CACHE_MAX_TILES = 192;
+const LOD_CACHE_BYTE_BUDGET = 16 * 1024 * 1024;
+const LOD_REQUEST_DEBOUNCE_MS = 80;
+const LOD_MAX_IN_FLIGHT = 6;
+const LOD_MAX_VISIBLE_TILES = 120;
+// 120 个可见 tile：raster 约 7.5MiB，1200×40B 等高线约 5.5MiB，给边界向量和 LRU 留余量。
+const LOD_CONTOUR_SEGMENT_CAP = 1200;
+const LOD_CROSSFADE_MS = 150;
+const LOD_DENSITY = { low: 1, normal: 1.25, high: 1.55 };
+const CITY_LAYOUT_CACHE_MAX = 16;
+const CITY_LAYOUT_CACHE_BYTE_BUDGET = 24 * 1024 * 1024;
+const ROAD_PREVIEW_DEBOUNCE_MS = 220;
+const CITY_SIZE_PRESETS = Object.freeze([
+  Object.freeze({ id: "town", label: "小镇", radiusMeters: 480 }),
+  Object.freeze({ id: "small-city", label: "小城", radiusMeters: 1_200 }),
+  Object.freeze({ id: "city", label: "中城", radiusMeters: 3_000 }),
+  Object.freeze({ id: "large-city", label: "大城", radiusMeters: 8_000 }),
+]);
+const PROCEDURAL_CITY = { PALETTE, PROCEDURAL_GENERATOR_IDENTITY, PROCEDURAL_WORLD_PROFILE, generateCityLayout, validateProceduralWorld };
+
+function element(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function svgIcon(kind) {
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("aria-hidden", "true");
+  const paths = {
+    plus: ["M12 5v14", "M5 12h14"],
+    minus: ["M5 12h14"],
+    fit: ["M8 4H4v4", "M16 4h4v4", "M4 16v4h4", "M20 16v4h-4"],
+    settings: ["M4 7h10", "M18 7h2", "M4 17h2", "M10 17h10", "M14 4v6", "M6 14v6"],
+  };
+  for (const d of paths[kind] ?? []) {
+    const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+    path.setAttribute("d", d);
+    svg.append(path);
+  }
+  return svg;
+}
+
+function iconButton(kind, label) {
+  const button = element("button", "graph-fab world-map-icon-button");
+  button.type = "button";
+  button.title = label;
+  button.setAttribute("aria-label", label);
+  button.append(svgIcon(kind));
+  return button;
+}
+
+function numberInRange(value, name, minimum, maximum, integer = false) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum || (integer && !Number.isInteger(value))) {
+    throw new TypeError(`${name} 参数无效`);
+  }
+  return value;
+}
+
+function sameGeneration(left, right) {
+  if (!left || !right) return false;
+  return Object.keys(DEFAULT_PLANE_GENERATION).every((key) => left[key] === right[key]);
+}
+
+function validatePlaneOnlyGeneration(value) {
+  if (value?.profile !== PLANE_GENERATION_PROFILE) throw new TypeError("平面地图仅支持 Perlin 水文生成参数");
+  return validatePlaneGeneration(value);
+}
+
+function validateSnapshot(value) {
+  if (!value || typeof value !== "object") throw new TypeError("项目地图读回无效");
+  if ((typeof value.projectId !== "string" && typeof value.projectId !== "number") || value.projectId === "") throw new TypeError("项目 ID 缺失");
+  if (!Number.isSafeInteger(value.revision) || value.revision < 0) throw new TypeError("项目 revision 无效");
+  if (value.source !== null && (typeof value.source !== "object" || Array.isArray(value.source))) throw new TypeError("地图 source 无效");
+  const savedGeneration = value.source?.topology?.generation == null ? null : validatePlaneOnlyGeneration(value.source.topology.generation);
+  const savedRoadGeneration = value.source?.topology?.roadGeneration == null ? null : validateRoadGeneration(value.source.topology.roadGeneration);
+  return { value, savedGeneration, savedRoadGeneration };
+}
+
+function initialGeneration(snapshot, savedGeneration) {
+  if (savedGeneration) return savedGeneration;
+  const topology = snapshot.source?.topology;
+  const width = topology?.width;
+  const height = topology?.height;
+  const generation = { ...DEFAULT_PLANE_GENERATION };
+  if (typeof width === "number" && Number.isSafeInteger(width) && width > 0) generation.widthMeters = width;
+  if (typeof height === "number" && Number.isSafeInteger(height) && height > 0) generation.heightMeters = height;
+  return validatePlaneOnlyGeneration(generation);
+}
+
+function validateResult(value, settings) {
+  if (!value || typeof value !== "object") throw new TypeError("WASM 返回了无效地图");
+  const expectedKeys = ["width", "height", "elevations", "riverFlux", "lakeMask", "seaLevel", "seed", "profile"];
+  if (Object.keys(value).length !== expectedKeys.length || expectedKeys.some((key) => !Object.hasOwn(value, key))) throw new TypeError("WASM 返回了未知字段");
+  const width = numberInRange(value.width, "width", 1, 4096, true);
+  const height = numberInRange(value.height, "height", 1, 4096, true);
+  const size = width * height;
+  if (size > settings.resolution * settings.resolution) throw new TypeError("WASM 地图网格超过请求分辨率");
+  for (const name of ["elevations", "riverFlux"]) {
+    const values = value[name];
+    if ((!Array.isArray(values) && !ArrayBuffer.isView(values)) || values.length !== size) throw new TypeError(`WASM ${name} 长度无效`);
+    for (let index = 0; index < values.length; index += 1) {
+      if (typeof values[index] !== "number" || !Number.isFinite(values[index])) throw new TypeError(`WASM ${name} 包含非数值`);
+      if (name === "elevations" && (values[index] < -1 || values[index] > 1)) throw new RangeError("WASM elevations 必须位于 -1..1");
+    }
+  }
+  const lakeMask = value.lakeMask;
+  if (!Array.isArray(lakeMask) || lakeMask.length !== size || lakeMask.some((entry) => typeof entry !== "boolean")) throw new TypeError("WASM lakeMask 必须是布尔网格");
+  if (value.profile !== settings.profile || value.seed !== settings.seed) throw new TypeError("WASM 返回的生成身份不匹配");
+  const seaLevel = numberInRange(value.seaLevel, "seaLevel", -1, 1);
+  return { ...value, width, height, seaLevel };
+}
+
+function validateTileResult(value, settings, requestedTile) {
+  if (!value || typeof value !== "object") throw new TypeError("WASM 返回了无效地图细节区块");
+  const expectedKeys = ["level", "x", "y", "width", "height", "elevations", "riverFlux", "lakeMask", "seaLevel", "seed", "profile"];
+  if (Object.keys(value).length !== expectedKeys.length || expectedKeys.some((key) => !Object.hasOwn(value, key))) throw new TypeError("WASM 细节区块返回了未知字段");
+  if (value.level !== requestedTile.level || value.x !== requestedTile.x || value.y !== requestedTile.y
+    || value.width !== LOD_TILE_SIZE || value.height !== LOD_TILE_SIZE) {
+    throw new TypeError("WASM 细节区块身份不匹配");
+  }
+  const size = LOD_TILE_SIZE * LOD_TILE_SIZE;
+  for (const name of ["elevations", "riverFlux"]) {
+    const values = value[name];
+    if ((!Array.isArray(values) && !ArrayBuffer.isView(values)) || values.length !== size) throw new TypeError(`WASM ${name} 长度无效`);
+    for (let index = 0; index < values.length; index += 1) {
+      if (typeof values[index] !== "number" || !Number.isFinite(values[index])) throw new TypeError(`WASM ${name} 包含非数值`);
+      if (name === "elevations" && (values[index] < -1 || values[index] > 1)) throw new RangeError("WASM elevations 必须位于 -1..1");
+    }
+  }
+  if (!Array.isArray(value.lakeMask) || value.lakeMask.length !== size || value.lakeMask.some((entry) => typeof entry !== "boolean")) {
+    throw new TypeError("WASM lakeMask 必须是布尔网格");
+  }
+  if (value.profile !== settings.profile || value.seed !== settings.seed) throw new TypeError("WASM 细节区块生成身份不匹配");
+  return { ...value, width: LOD_TILE_SIZE, height: LOD_TILE_SIZE, seaLevel: numberInRange(value.seaLevel, "seaLevel", -1, 1) };
+}
+
+function field(form, name) {
+  const input = form.elements.namedItem(name);
+  if (!(input instanceof HTMLInputElement) && !(input instanceof HTMLSelectElement)) throw new TypeError(`缺少 ${name} 控件`);
+  return input;
+}
+
+function numberFromForm(form, name) {
+  const control = field(form, name);
+  const raw = control.value.trim();
+  if (!raw) throw new TypeError(`${name} 参数不能为空`);
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw new TypeError(`${name} 参数无效`);
+  return value;
+}
+
+function generationFromForm(form) {
+  const widthMeters = Math.round(numberFromForm(form, "widthKm") * 1000);
+  const heightMeters = Math.round(numberFromForm(form, "heightKm") * 1000);
+  return validatePlaneOnlyGeneration({
+    profile: PLANE_GENERATION_PROFILE,
+    seed: numberFromForm(form, "seed"),
+    widthMeters,
+    heightMeters,
+    resolution: numberFromForm(form, "resolution"),
+    waterCoverage: numberFromForm(form, "waterCoverage"),
+    relief: numberFromForm(form, "relief"),
+    riverDensity: numberFromForm(form, "riverDensity"),
+    lakeDensity: numberFromForm(form, "lakeDensity"),
+    rainfall: numberFromForm(form, "rainfall"),
+  });
+}
+
+function setFormGeneration(form, generation) {
+  const values = {
+    seed: generation.seed,
+    widthKm: generation.widthMeters / 1000,
+    heightKm: generation.heightMeters / 1000,
+    resolution: generation.resolution,
+    waterCoverage: generation.waterCoverage,
+    relief: generation.relief,
+    riverDensity: generation.riverDensity,
+    lakeDensity: generation.lakeDensity,
+    rainfall: generation.rainfall,
+  };
+  for (const [name, value] of Object.entries(values)) field(form, name).value = String(value);
+}
+
+function settingField(labelText, name, options = {}) {
+  const label = element("label", "world-map-field");
+  const labelRow = element("span", "world-map-field-label");
+  labelRow.append(element("span", "", labelText));
+  if (options.hint) labelRow.append(element("small", "", options.hint));
+  let input;
+  if (options.values) {
+    input = document.createElement("select");
+    for (const value of options.values) {
+      const option = element("option", "", String(value));
+      option.value = String(value);
+      input.append(option);
+    }
+  } else {
+    input = document.createElement("input");
+    input.type = "number";
+    for (const key of ["min", "max", "step"]) if (options[key] !== undefined) input.setAttribute(key, String(options[key]));
+    input.inputMode = "decimal";
+  }
+  input.name = name;
+  input.setAttribute("aria-label", labelText);
+  label.append(labelRow, input);
+  return label;
+}
+
+function layerToggle(name, text, checked = true) {
+  const label = element("label", "world-map-layer");
+  const input = document.createElement("input");
+  input.type = "checkbox";
+  input.name = name;
+  input.checked = checked;
+  label.append(input, element("span", "", text));
+  return label;
+}
+
+function objectRows(objects) {
+  if (Array.isArray(objects)) return objects.map((value, index) => [String(index), value]);
+  if (objects && typeof objects === "object") return Object.entries(objects);
+  return [];
+}
+
+function objectMarkers(objects, generation) {
+  const markers = [];
+  for (const [key, value] of objectRows(objects)) {
+    if (!value || typeof value !== "object") continue;
+    const position = value.position && typeof value.position === "object" ? value.position : value;
+    const coordinates = Array.isArray(position.coordinates) ? position.coordinates : null;
+    const rawX = coordinates?.[0] ?? position.x;
+    const rawY = coordinates?.[1] ?? position.y;
+    if (typeof rawX !== "number" || typeof rawY !== "number" || !Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+    const x = rawX >= 0 && rawX <= 1 ? rawX : rawX / generation.widthMeters;
+    const y = rawY >= 0 && rawY <= 1 ? rawY : rawY / generation.heightMeters;
+    if (x < 0 || x > 1 || y < 0 || y > 1) continue;
+    const idValue = value.id ?? value.objectId ?? value.object_id ?? key;
+    markers.push({ id: String(idValue), x, y });
+  }
+  return markers;
+}
+
+function formatPercent(value) {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function errorText(error) {
+  if (typeof error === "string") return error;
+  if (error && typeof error.message === "string") return `${typeof error.code === "string" ? `${error.code}: ` : ""}${error.message}`;
+  return "未知错误";
+}
+
+function sameRoadGeneration(left, right) {
+  if (!left || !right) return false;
+  return Object.keys(DEFAULT_ROAD_GENERATION).every((key) => left[key] === right[key]);
+}
+
+function checkedFromForm(form, name) {
+  const control = form.elements.namedItem(name);
+  if (!(control instanceof HTMLInputElement) || control.type !== "checkbox") throw new TypeError(`缺少 ${name} 控件`);
+  return control.checked;
+}
+
+function roadGenerationFromForm(form, identity = ROAD_GENERATION_IDENTITY) {
+  return validateRoadGeneration({
+    profile: ROAD_GENERATION_PROFILE,
+    identity,
+    allowBridges: checkedFromForm(form, "allowBridges"),
+    allowTunnels: checkedFromForm(form, "allowTunnels"),
+    maxBridgeLengthMeters: numberFromForm(form, "maxBridgeLengthMeters"),
+    maxTunnelLengthMeters: numberFromForm(form, "maxTunnelLengthMeters"),
+    maxGrade: numberFromForm(form, "maxGradePercent") / 100,
+    roadWidthMeters: numberFromForm(form, "roadWidthMeters"),
+    elevationScaleMeters: numberFromForm(form, "elevationScaleMeters"),
+  });
+}
+
+function setFormRoadGeneration(form, generation) {
+  const values = {
+    allowBridges: generation.allowBridges,
+    allowTunnels: generation.allowTunnels,
+    maxBridgeLengthMeters: generation.maxBridgeLengthMeters,
+    maxTunnelLengthMeters: generation.maxTunnelLengthMeters,
+    maxGradePercent: generation.maxGrade * 100,
+    roadWidthMeters: generation.roadWidthMeters,
+    elevationScaleMeters: generation.elevationScaleMeters,
+  };
+  for (const [name, value] of Object.entries(values)) {
+    const control = form.elements.namedItem(name);
+    if (control instanceof HTMLInputElement && control.type === "checkbox") control.checked = value === true;
+    else if (control instanceof HTMLInputElement || control instanceof HTMLSelectElement) control.value = String(value);
+  }
+}
+
+function point3(value, label) {
+  if (!value || typeof value !== "object") throw new TypeError(`${label} 点无效`);
+  const point = {};
+  for (const key of ["x", "y", "z"]) point[key] = numberInRange(value[key], `${label}.${key}`, -1_000_000_000, 1_000_000_000);
+  return point;
+}
+
+function validateRoadParcelTerrain(value, label) {
+  if (!value || typeof value !== "object") throw new TypeError(`${label} 缺少 terrain`);
+  const width = numberInRange(value.width, `${label}.terrain.width`, 2, 4096, true);
+  const height = numberInRange(value.height, `${label}.terrain.height`, 2, 4096, true);
+  const size = width * height;
+  const widthMeters = numberInRange(value.widthMeters, `${label}.terrain.widthMeters`, Number.EPSILON, 1_000_000_000);
+  const heightMeters = numberInRange(value.heightMeters, `${label}.terrain.heightMeters`, Number.EPSILON, 1_000_000_000);
+  const originX = numberInRange(value.originX, `${label}.terrain.originX`, -1_000_000_000, 1_000_000_000);
+  const originY = numberInRange(value.originY, `${label}.terrain.originY`, -1_000_000_000, 1_000_000_000);
+  if (!Array.isArray(value.elevationsMeters) || value.elevationsMeters.length !== size || value.elevationsMeters.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+    throw new TypeError(`${label}.terrain.elevationsMeters 无效`);
+  }
+  if (!Array.isArray(value.waterMask) || value.waterMask.length !== size || value.waterMask.some((entry) => entry !== true && entry !== false && entry !== 0 && entry !== 1)) {
+    throw new TypeError(`${label}.terrain.waterMask 无效`);
+  }
+  return { width, height, widthMeters, heightMeters, originX, originY, elevationsMeters: [...value.elevationsMeters], waterMask: [...value.waterMask] };
+}
+
+/** 道路结果在渲染前收紧为唯一的 terrain-roads-v1 形状，杜绝旧正交道路伪装成成功结果。 */
+export function validateTerrainRoadResult(value, expectedCityIds = []) {
+  if (!value || typeof value !== "object" || value.profile !== "terrain-roads-v1" || !Array.isArray(value.roads)
+    || !Array.isArray(value.unreachable) || !Array.isArray(value.cityLayouts)) throw new TypeError("WASM 返回了无效地形路网");
+  const roads = value.roads.map((road, index) => {
+    if (!road || typeof road !== "object" || typeof road.id !== "string" || !road.id || !["intercity", "arterial", "local"].includes(road.kind)
+      || !["motorway", "street"].includes(road.roadClass) || (road.kind === "intercity" ? road.roadClass !== "motorway" : road.roadClass !== "street")
+      || !Array.isArray(road.points) || road.points.length < 2 || !Array.isArray(road.segments) || !road.segments.length) throw new TypeError(`道路 ${index} 无效`);
+    const points = road.points.map((point, pointIndex) => point3(point, `roads[${index}].points[${pointIndex}]`));
+    const segments = road.segments.map((segment, segmentIndex) => {
+      if (!segment || typeof segment !== "object" || !["surface", "bridge", "tunnel"].includes(segment.kind)
+        || !Array.isArray(segment.points) || segment.points.length < 2) throw new TypeError(`道路 ${index} 路段 ${segmentIndex} 无效`);
+      return { kind: segment.kind, points: segment.points.map((point, pointIndex) => point3(point, `roads[${index}].segments[${segmentIndex}].points[${pointIndex}]`)), lengthMeters: numberInRange(segment.lengthMeters, "道路长度", 0, 1_000_000_000) };
+    });
+    return { id: road.id, kind: road.kind, roadClass: road.roadClass, cityId: typeof road.cityId === "string" ? road.cityId : undefined, fromCityId: typeof road.fromCityId === "string" ? road.fromCityId : undefined, toCityId: typeof road.toCityId === "string" ? road.toCityId : undefined, widthMeters: numberInRange(road.widthMeters, "道路宽度", 0.1, 10_000), points, segments };
+  });
+  const unreachable = value.unreachable.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || typeof entry.fromId !== "string" || typeof entry.toId !== "string" || typeof entry.reason !== "string") throw new TypeError(`不可达道路 ${index} 无效`);
+    return { fromId: entry.fromId, toId: entry.toId, reason: entry.reason };
+  });
+  const cityLayoutIds = new Set();
+  const cityLayouts = value.cityLayouts.map((layout, index) => {
+    if (!layout || typeof layout !== "object" || typeof layout.cityId !== "string" || !layout.cityId || !Array.isArray(layout.roads)
+      || layout.roads.some((roadId) => typeof roadId !== "string")) throw new TypeError(`城市道路布局 ${index} 无效`);
+    if (cityLayoutIds.has(layout.cityId)) throw new TypeError(`城市道路布局 ${index} 重复`);
+    cityLayoutIds.add(layout.cityId);
+    const boundaryValue = layout.boundary;
+    if (!boundaryValue || typeof boundaryValue !== "object" || Array.isArray(boundaryValue)
+      || Object.keys(boundaryValue).sort().join(",") !== "cityId,points,status" || !["bounded", "unbuildable"].includes(boundaryValue.status)
+      || boundaryValue.cityId !== layout.cityId || !Array.isArray(boundaryValue.points)) throw new TypeError(`城市道路布局 ${index} 边界无效`);
+    const points = boundaryValue.points.map((point, pointIndex) => {
+      if (!point || typeof point !== "object") throw new TypeError(`城市道路布局 ${index} 边界点 ${pointIndex} 无效`);
+      return { x: numberInRange(point.x, "城市边界.x", -1_000_000_000, 1_000_000_000), y: numberInRange(point.y, "城市边界.y", -1_000_000_000, 1_000_000_000) };
+    });
+    if (boundaryValue.status === "unbuildable" && (points.length !== 0 || layout.roads.length !== 0)) throw new TypeError(`城市道路布局 ${index} 不可建边界无效`);
+    if (boundaryValue.status === "bounded") {
+      if (points.length < 3 || points.some((point, pointIndex) => pointIndex > 0 && point.x === points[pointIndex - 1].x && point.y === points[pointIndex - 1].y)) throw new TypeError(`城市道路布局 ${index} 有界点无效`);
+      if (points[0].x === points.at(-1).x && points[0].y === points.at(-1).y) throw new TypeError(`城市道路布局 ${index} 边界不得闭合重复点`);
+      const twiceArea = points.reduce((sum, point, pointIndex) => { const next = points[(pointIndex + 1) % points.length]; return sum + point.x * next.y - next.x * point.y; }, 0);
+      if (!(twiceArea > 0)) throw new TypeError(`城市道路布局 ${index} 边界必须逆时针`);
+    }
+    return { cityId: layout.cityId, roads: [...layout.roads], boundary: { status: boundaryValue.status, cityId: layout.cityId, points }, terrain: validateRoadParcelTerrain(layout.terrain, `城市道路布局 ${index}`) };
+  });
+  for (const cityId of expectedCityIds) if (!cityLayoutIds.has(cityId)) throw new TypeError(`道路结果缺少城市 ${cityId} 的 terrain 布局`);
+  return { profile: value.profile, roads, unreachable, cityLayouts };
+}
+
+/** 供 Canvas 与测试共用：overview 只画城际路，靠近城市后再画 arterial/local。 */
+export function roadVisibleAtMetersPerPixel(road, metersPerPixel) {
+  return road.kind === "intercity" || Number(metersPerPixel) <= (road.kind === "arterial" ? 140 : 38);
+}
+
+export function mountWorldMap(root, options) {
+  if (!(root instanceof HTMLElement)) throw new TypeError("world map root 必须是 HTMLElement");
+  if (!options || typeof options.read !== "function" || typeof options.save !== "function" || typeof options.notify !== "function") {
+    throw new TypeError("world map 需要 read、save 与 notify 回调");
+  }
+  let cityTemplates = [];
+  function normalizeCityTemplates(records) {
+    return Array.isArray(records) ? records.filter((template) => template && typeof template.id === "string" && template.id
+      && typeof template.label === "string" && template.label && template.parameters && typeof template.parameters === "object") : [];
+  }
+  cityTemplates = normalizeCityTemplates(options.cityTemplates);
+
+  const shell = element("section", "world-map-shell");
+  shell.hidden = true;
+  shell.setAttribute("aria-label", "世界地图编辑器");
+  const header = element("header", "world-map-header");
+  const heading = element("div", "world-map-heading");
+  const title = element("h1", "", "世界地图");
+  const status = element("p", "world-map-status", "尚未打开");
+  status.setAttribute("role", "status");
+  status.setAttribute("aria-live", "polite");
+  heading.append(title, status);
+  const actions = element("div", "world-map-header-actions");
+  const settingsButton = iconButton("settings", "地图设置");
+  settingsButton.dataset.action = "edit-parameters";
+  settingsButton.setAttribute("aria-expanded", "false");
+  const generateButton = element("button", "button ghost compact", "下一步：生成预览");
+  generateButton.type = "button";
+  generateButton.dataset.action = "generate-preview";
+  const adjustButton = element("button", "button ghost compact", "返回调整参数");
+  adjustButton.type = "button";
+  adjustButton.dataset.action = "adjust-parameters";
+  adjustButton.hidden = true;
+  const saveButton = element("button", "button primary compact", "确认并保存");
+  saveButton.type = "button";
+  saveButton.dataset.action = "confirm-save";
+  saveButton.disabled = true;
+  actions.append(settingsButton, adjustButton, generateButton, saveButton);
+  header.append(heading, actions);
+
+  const stage = element("div", "world-map-stage");
+  const phaseBadge = element("div", "world-map-phase", "阶段 1/2 · 参数");
+  phaseBadge.setAttribute("aria-hidden", "true");
+  const canvas = document.createElement("canvas");
+  canvas.className = "world-map-canvas";
+  canvas.tabIndex = 0;
+  canvas.setAttribute("role", "img");
+  canvas.setAttribute("aria-label", "生成的世界地图，可拖动画布并使用滚轮缩放");
+  const overlay = element("div", "world-map-overlay", "正在读取地图…");
+  overlay.setAttribute("role", "status");
+  const previewWatermark = element("div", "world-map-preview-watermark");
+  previewWatermark.hidden = true;
+  const controls = element("div", "world-map-controls");
+  const zoomIn = iconButton("plus", "放大地图");
+  const zoomOut = iconButton("minus", "缩小地图");
+  const fit = iconButton("fit", "适合画布");
+  controls.append(zoomIn, zoomOut, fit);
+  const detailStatus = element("output", "world-map-detail-status", "细节待命");
+  detailStatus.setAttribute("aria-label", "地图镜头与细节状态");
+
+  const settingsPanel = element("section", "world-map-settings");
+  settingsPanel.hidden = true;
+  settingsPanel.setAttribute("aria-label", "地图生成设置");
+  const panelHeading = element("div", "world-map-settings-heading");
+  const panelHint = element("small", "", "下一步生成预览");
+  panelHeading.append(element("h2", "", "地图参数"), panelHint);
+  const wizardProgress = element("div", "world-map-wizard-progress");
+  const parameterStep = element("span", "is-active", "1 参数");
+  parameterStep.dataset.step = "parameters";
+  const previewStep = element("span", "", "2 预览并保存");
+  previewStep.dataset.step = "preview";
+  wizardProgress.append(parameterStep, previewStep);
+  const form = element("form", "world-map-form");
+  form.append(
+    settingField("种子", "seed", { min: 0, max: 0xffffffff, step: 1 }),
+    settingField("东西长度", "widthKm", { min: 0.001, max: PLANE_GENERATION_MAX_EXTENT_METERS / 1000, step: 0.001, hint: "km（最小 1 m）" }),
+    settingField("南北长度", "heightKm", { min: 0.001, max: PLANE_GENERATION_MAX_EXTENT_METERS / 1000, step: 0.001, hint: "km（最小 1 m）" }),
+    settingField("分辨率", "resolution", { values: [128, 256, 512] }),
+    settingField("水域覆盖", "waterCoverage", { min: 0, max: 0.95, step: 0.01 }),
+    settingField("地形起伏", "relief", { min: 0, max: 1, step: 0.01 }),
+    settingField("河流密度", "riverDensity", { min: 0, max: 1, step: 0.01 }),
+    settingField("湖泊密度", "lakeDensity", { min: 0, max: 0.25, step: 0.01 }),
+    settingField("降雨量", "rainfall", { min: 0.1, max: 8, step: 0.1 }),
+  );
+  form.addEventListener("submit", (event) => event.preventDefault());
+  const layerHeading = element("h3", "", "显示图层");
+  const layers = element("div", "world-map-layers");
+  layers.append(layerToggle("showRelief", "高地阴影"), layerToggle("showContours", "等高线", DEFAULT_TERRAIN_LAYERS.showContours), layerToggle("showRivers", "河流"), layerToggle("showLakes", "湖泊"), layerToggle("showRoads", "地形路网"), layerToggle("showCities", "程序化城市"), layerToggle("showObjects", "世界对象"));
+  const roadHeading = element("h3", "", "地形路网");
+  const roadHint = element("p", "world-map-road-hint", "道路仅为预览；保存前不会改写世界 source。");
+  const roadForm = element("form", "world-map-road-form");
+  roadForm.append(
+    layerToggle("allowBridges", "允许架桥", DEFAULT_ROAD_GENERATION.allowBridges),
+    layerToggle("allowTunnels", "允许隧道", DEFAULT_ROAD_GENERATION.allowTunnels),
+    settingField("最大单座桥长度", "maxBridgeLengthMeters", { min: 1, max: 200000, step: 1, hint: "m" }),
+    settingField("最大单隧道长度", "maxTunnelLengthMeters", { min: 1, max: 200000, step: 1, hint: "m" }),
+    settingField("最大坡度", "maxGradePercent", { min: 0.1, max: 100, step: 0.1, hint: "%" }),
+    settingField("道路宽度", "roadWidthMeters", { min: 3, max: 40, step: 0.5, hint: "m" }),
+    settingField("高程米制尺度", "elevationScaleMeters", { min: 1, max: 100000, step: 1, hint: "m" }),
+  );
+  setFormRoadGeneration(roadForm, DEFAULT_ROAD_GENERATION);
+  roadForm.addEventListener("submit", (event) => event.preventDefault());
+  const roadActions = element("div", "world-map-road-actions");
+  const previewRoadsButton = element("button", "button ghost compact", "预览地形路网"); previewRoadsButton.type = "button"; previewRoadsButton.dataset.action = "preview-roads";
+  const previewRoadUpgradeButton = element("button", "button ghost compact", "使用新版规则预览"); previewRoadUpgradeButton.type = "button"; previewRoadUpgradeButton.dataset.action = "preview-road-upgrade";
+  const saveRoadsButton = element("button", "button ghost compact", "保存道路参数"); saveRoadsButton.type = "button"; saveRoadsButton.dataset.action = "save-roads";
+  roadActions.append(previewRoadsButton, previewRoadUpgradeButton, saveRoadsButton);
+  const roadStatus = element("p", "world-map-road-status", "等待地图和城市…"); roadStatus.setAttribute("role", "status");
+  const roadParcelError = element("details", "world-map-road-parcel-error");
+  const roadParcelErrorSummary = element("summary", "", "地块生成失败，请调整参数/重试");
+  const roadParcelErrorDetail = element("pre", "", "");
+  roadParcelError.append(roadParcelErrorSummary, roadParcelErrorDetail);
+  roadParcelError.hidden = true;
+  const detailHeading = element("h3", "", "镜头细节");
+  const detailControls = element("div", "world-map-detail-controls");
+  const densityLabel = element("label", "world-map-field");
+  const densityLabelRow = element("span", "world-map-field-label");
+  densityLabelRow.append(element("span", "", "细节密度"), element("small", "", "带滞回切换"));
+  const densitySelect = document.createElement("select");
+  densitySelect.name = "detailDensity";
+  densitySelect.setAttribute("aria-label", "地图细节密度");
+  for (const [value, text] of [["low", "低"], ["normal", "标准"], ["high", "高"]]) {
+    const option = element("option", "", text); option.value = value; densitySelect.append(option);
+  }
+  densitySelect.value = "normal";
+  densityLabel.append(densityLabelRow, densitySelect);
+  const cameraField = element("div", "world-map-camera-field");
+  cameraField.append(element("span", "", "镜头比例"));
+  const cameraMpp = element("output", "", "— m/px");
+  cameraMpp.setAttribute("aria-label", "镜头米每像素");
+  cameraField.append(cameraMpp);
+  const roadThresholdLabel = settingField("道路显示半径", "roadThreshold", { min: 40, max: 200, step: 5, hint: "px" });
+  const parcelThresholdLabel = settingField("地块显示尺度", "parcelThreshold", { min: 6, max: 40, step: 1, hint: "px" });
+  const roadThresholdInput = roadThresholdLabel.querySelector("input");
+  const parcelThresholdInput = parcelThresholdLabel.querySelector("input");
+  roadThresholdInput.value = "80";
+  parcelThresholdInput.value = "12";
+  detailControls.append(densityLabel, cameraField, roadThresholdLabel, parcelThresholdLabel);
+  const actorBinding = element("section", "world-map-actor-binding");
+  actorBinding.hidden = typeof options.setControlledActor !== "function";
+  const actorHeading = element("h3", "", "Player 受控角色");
+  const actorRow = element("div", "world-map-actor-row");
+  const actorSelect = document.createElement("select"); actorSelect.setAttribute("aria-label", "受控角色");
+  const saveActorButton = element("button", "button ghost compact", "保存角色绑定"); saveActorButton.type = "button";
+  const actorStatus = element("p", "world-map-actor-status", ""); actorStatus.setAttribute("role", "status");
+  actorRow.append(actorSelect, saveActorButton); actorBinding.append(actorHeading, actorRow, actorStatus);
+  settingsPanel.append(panelHeading, wizardProgress, form, layerHeading, layers, roadHeading, roadHint, roadForm, roadActions, roadStatus, roadParcelError, detailHeading, detailControls, actorBinding);
+
+  const createHint = element("div", "world-map-create-hint", "右键地图新建城市");
+  createHint.hidden = typeof options.createCity !== "function";
+  const cityDialog = document.createElement("dialog");
+  cityDialog.className = "world-map-city-dialog";
+  cityDialog.setAttribute("aria-label", "新建城市");
+  const cityForm = element("form", "world-map-city-form");
+  cityForm.append(element("h2", "", "新建程序化城市"));
+  const cityTemplateLabel = element("label", "world-map-field");
+  cityTemplateLabel.append(element("span", "world-map-field-label", "城市模板"));
+  const cityTemplate = document.createElement("select"); cityTemplate.name = "cityTemplate"; cityTemplate.setAttribute("aria-label", "城市模板");
+  const customTemplate = element("option", "", "自定义"); customTemplate.value = ""; cityTemplate.append(customTemplate);
+  for (const template of cityTemplates) { const option = element("option", "", template.label); option.value = template.id; cityTemplate.append(option); }
+  cityTemplateLabel.append(cityTemplate);
+  const cityGrid = element("div", "world-map-city-grid");
+  const citySizeLabel = element("label", "world-map-field");
+  citySizeLabel.append(element("span", "world-map-field-label", "城市规模"));
+  const citySize = document.createElement("select"); citySize.name = "citySize"; citySize.setAttribute("aria-label", "城市规模");
+  const customSize = element("option", "", "自定义"); customSize.value = ""; citySize.append(customSize);
+  for (const preset of CITY_SIZE_PRESETS) { const option = element("option", "", `${preset.label} · 约半径 ${preset.radiusMeters.toLocaleString()} m`); option.value = preset.id; citySize.append(option); }
+  citySizeLabel.append(citySize);
+  const cityNameLabel = element("label", "world-map-field");
+  cityNameLabel.append(element("span", "world-map-field-label", "名称"));
+  const cityName = document.createElement("input"); cityName.name = "cityName"; cityName.required = true; cityName.maxLength = 128; cityNameLabel.append(cityName);
+  cityGrid.append(
+    cityNameLabel,
+    citySizeLabel,
+    settingField("半径", "cityRadius", { min: 32, max: 200000, step: 1, hint: "m" }),
+    settingField("街区尺度", "cityBlockSize", { min: 16, max: 2000, step: 1, hint: "m" }),
+    settingField("道路宽度", "cityRoadWidth", { min: 3, max: 40, step: .5, hint: "m" }),
+  );
+  const useHeading = element("h3", "", "用途权重");
+  const useGrid = element("div", "world-map-city-grid land-use");
+  for (const [name, label] of [["residential", "居住"], ["commercial", "商业"], ["industrial", "工业"], ["civic", "公共设施"], ["park", "公园"]]) {
+    useGrid.append(settingField(label, `cityUse_${name}`, { min: 0, max: 100, step: 1 }));
+  }
+  const cityDialogStatus = element("p", "world-map-city-dialog-status", "");
+  cityDialogStatus.setAttribute("role", "status");
+  const cityActions = element("div", "world-map-city-actions");
+  const cancelCity = element("button", "button ghost compact", "取消"); cancelCity.type = "button";
+  const submitCity = element("button", "button primary compact", "生成城市"); submitCity.type = "submit";
+  cityActions.append(cancelCity, submitCity);
+  cityForm.append(cityTemplateLabel, cityGrid, useHeading, useGrid, cityDialogStatus, cityActions);
+  cityDialog.append(cityForm);
+
+  const stats = element("dl", "world-map-stats");
+  const statNodes = {};
+  for (const [key, label] of [["size", "范围"], ["grid", "网格"], ["water", "水域"], ["relief", "相对高程"], ["rivers", "河网"], ["objects", "对象"]]) {
+    const item = element("div", "world-map-stat");
+    const value = element("dd", "", "—");
+    item.append(element("dt", "", label), value);
+    stats.append(item);
+    statNodes[key] = value;
+  }
+  const legend = element("div", "world-map-legend");
+  for (const [className, text] of [["sea", "海洋"], ["land", "陆地"], ["high", "高地"], ["river", "河流"], ["lake", "湖泊"], ["object", "对象"]]) {
+    const item = element("span", "");
+    item.append(element("i", className), document.createTextNode(text));
+    legend.append(item);
+  }
+  const cityLegend = element("div", "world-map-city-legend");
+  cityLegend.hidden = true;
+  cityLegend.setAttribute("aria-label", "城市用途图例");
+  for (const [landUse, entry] of Object.entries(PALETTE)) {
+    const item = element("span", "");
+    const swatch = element("i", ""); swatch.style.backgroundColor = entry.color; swatch.dataset.landUse = landUse;
+    item.append(swatch, document.createTextNode(entry.label)); cityLegend.append(item);
+  }
+  const roadLegend = element("div", "world-map-road-legend");
+  roadLegend.hidden = true;
+  roadLegend.setAttribute("aria-label", "地形路网图例");
+  for (const [className, text] of [["intercity", "高速公路"], ["arterial", "城市干道"], ["local", "城市支路"], ["bridge", "桥梁"], ["tunnel", "隧道"]]) {
+    const item = element("span", ""); item.append(element("i", className), document.createTextNode(text)); roadLegend.append(item);
+  }
+  stage.append(canvas, phaseBadge, overlay, previewWatermark, controls, detailStatus, createHint, settingsPanel, stats, legend, cityLegend, roadLegend, cityDialog);
+  shell.append(header, stage);
+  root.replaceChildren(shell);
+
+  const state = {
+    open: false,
+    destroyed: false,
+    epoch: 0,
+    requestId: 0,
+    tileRequestId: 0,
+    worker: null,
+    snapshot: null,
+    savedGeneration: null,
+    previewGeneration: null,
+    result: null,
+    baseCanvas: null,
+    baseRenderStats: null,
+    tileWorker: null,
+    tileQueue: [],
+    tileInFlight: new Map(),
+    tileCache: new Map(),
+    tileCacheBytes: 0,
+    tileRequestTimer: null,
+    tileEpoch: 0,
+    lodLevel: 0,
+    lodLevelInitialized: false,
+    lodLoading: false,
+    lodError: null,
+    visibleTiles: [],
+    metersPerPixel: null,
+    desiredTileSignature: "",
+    fadeFrame: null,
+    cityModule: PROCEDURAL_CITY,
+    cityWorld: null,
+    cities: [],
+    cityLayouts: new Map(),
+    cityLayoutBytes: 0,
+    cityModes: new Map(),
+    roadParcelLayouts: new Map(),
+    roadParcelTemplateKey: "parcel-template:absent",
+    roadParcelError: null,
+    roadWorker: null,
+    roadRequestId: 0,
+    roadPreviewTimer: null,
+    roadResult: null,
+    roadRequestedKey: "",
+    savedRoadGeneration: null,
+    previewRoadGeneration: null,
+    // 已保存 source 的 identity 与表单参数分开保存；只有显式新版规则预览才可切换草稿 identity。
+    roadDraftIdentity: ROAD_GENERATION_IDENTITY,
+    roadBusy: false,
+    roadSaving: false,
+    roadSaveToken: 0,
+    roadAutoPreviewEnabled: false,
+    roadError: null,
+    cityTemplateDefaultId: "",
+    cityPoint: null,
+    creatingCity: false,
+    savingActor: false,
+    markers: [],
+    loading: false,
+    busy: false,
+    saving: false,
+    saveToken: 0,
+    requestedGeneration: null,
+    autoPreviewEnabled: false,
+    previewTimer: null,
+    errorKind: null,
+    view: { scale: 1, x: 0, y: 0 },
+    fitted: false,
+    drag: null,
+  };
+
+  function notify(text, isError = false) {
+    options.notify(String(text), Boolean(isError));
+  }
+
+  function setOverlay(text, error = false, actionLabel, action) {
+    const statusView = Boolean(text && (error || text.startsWith("正在")));
+    overlay.classList.toggle("is-workspace-status", statusView);
+    if (statusView) {
+      const view = renderWorkspaceStatus(overlay, {
+        state: error ? "error" : "loading", surface: "map", error: text,
+        onRetry: action, retryLabel: actionLabel,
+      });
+      const retryButton = view.querySelector("button");
+      if (retryButton) retryButton.dataset.action = `retry-${state.errorKind ?? "operation"}`;
+      overlay.hidden = false;
+      overlay.classList.toggle("error", error);
+      overlay.classList.toggle("has-action", Boolean(retryButton));
+      return;
+    }
+    overlay.replaceChildren();
+    if (text) overlay.append(element("p", "", text));
+    if (text && actionLabel && typeof action === "function") {
+      const button = element("button", "button ghost compact", actionLabel);
+      button.type = "button";
+      button.dataset.action = error ? `retry-${state.errorKind ?? "operation"}` : "generate-preview-empty";
+      button.addEventListener("click", action);
+      overlay.append(button);
+    }
+    overlay.hidden = !text;
+    overlay.classList.toggle("error", error);
+    overlay.classList.toggle("has-action", Boolean(text && actionLabel && typeof action === "function"));
+  }
+
+  function draftGeneration() {
+    try { return generationFromForm(form); } catch { return null; }
+  }
+
+  function updateStatus() {
+    const draft = draftGeneration();
+    const previewCurrent = draft && state.previewGeneration && sameGeneration(draft, state.previewGeneration);
+    const saved = previewCurrent && state.savedGeneration && sameGeneration(state.previewGeneration, state.savedGeneration);
+    const phase = previewCurrent && state.result ? "preview" : "parameters";
+    shell.dataset.phase = phase;
+    shell.dataset.state = state.loading ? "loading" : state.errorKind ? `${state.errorKind}-error` : state.saving ? "saving" : state.busy ? "generating" : saved ? "saved" : previewCurrent ? "preview-ready" : "parameters";
+    phaseBadge.textContent = phase === "preview" ? "阶段 2/2 · 预览" : "阶段 1/2 · 参数";
+    parameterStep.classList.toggle("is-active", phase === "parameters");
+    parameterStep.classList.toggle("is-complete", phase === "preview");
+    previewStep.classList.toggle("is-active", phase === "preview");
+    panelHint.textContent = phase === "preview" ? "可确认保存或返回调整" : "下一步生成预览";
+    if (state.loading) status.textContent = "正在读取项目地图…";
+    else if (state.saving) status.textContent = "正在保存…";
+    else if (state.busy) status.textContent = "正在运行 WASM 水文生成器…";
+    else if (state.errorKind === "read") status.textContent = "地图读取失败 · 可重试";
+    else if (state.errorKind === "generate") status.textContent = "预览生成失败 · 参数已保留";
+    else if (state.errorKind === "save") status.textContent = "保存失败 · 预览仍保留";
+    else if (!draft) status.textContent = "设置无效";
+    else if (!previewCurrent) status.textContent = state.result ? "参数已调整 · 待重新生成" : "阶段 1 · 设置参数";
+    else if (saved) status.textContent = `已保存 · revision ${state.snapshot?.revision ?? "—"}`;
+    else status.textContent = "阶段 2 · 预览待确认";
+    generateButton.textContent = state.errorKind === "read" ? "重新读取" : state.busy ? "正在生成…" : state.result ? "重新生成预览" : "下一步：生成预览";
+    generateButton.disabled = state.loading || state.busy || state.saving || state.errorKind === "read" || !state.snapshot || !draft;
+    saveButton.disabled = state.loading || state.busy || state.saving || state.errorKind === "read" || !state.snapshot || !previewCurrent || Boolean(saved) || !state.result;
+    settingsButton.disabled = state.saving;
+    adjustButton.hidden = phase !== "preview";
+    adjustButton.disabled = state.busy || state.saving;
+    shell.classList.toggle("is-dirty", Boolean(previewCurrent && !saved));
+    shell.classList.toggle("has-map-preview", Boolean(state.baseCanvas));
+    previewWatermark.hidden = !state.result;
+    previewWatermark.textContent = previewCurrent ? (saved ? "已保存地图预览" : "未保存预览") : "上次预览 · 参数已调整";
+    const roadDraft = draftRoadGeneration();
+    const roadSaved = roadDraft && state.savedRoadGeneration && sameRoadGeneration(roadDraft, state.savedRoadGeneration);
+    const roadPreviewCurrent = roadDraft && state.previewRoadGeneration && sameRoadGeneration(roadDraft, state.previewRoadGeneration);
+    roadParcelError.hidden = !state.roadParcelError;
+    roadParcelErrorDetail.textContent = state.roadParcelError ?? "";
+    roadStatus.dataset.state = state.roadSaving ? "saving" : state.roadBusy ? "loading" : state.roadError ? "error" : state.roadResult ? "ready" : "idle";
+    if (!state.result) roadStatus.textContent = "先生成地形后才能预览道路。";
+    else if (!roadDraft) roadStatus.textContent = "道路参数无效。";
+    else if (state.roadSaving) roadStatus.textContent = "正在保存道路参数…";
+    else if (state.roadBusy) roadStatus.textContent = "正在生成地形路网…";
+    else if (state.roadError) roadStatus.textContent = `道路预览失败：${state.roadError}`;
+    else if (state.roadResult && !roadPreviewCurrent) roadStatus.textContent = "上次道路预览仍可见；参数已调整，正在等待新预览。";
+    else if (state.roadResult?.unreachable?.length) roadStatus.textContent = `已预览；${state.roadResult.unreachable.length} 条连接受坡度/桥隧限制不可达。${roadSaved ? "参数已保存。" : "参数尚未保存。"}`;
+    else if (state.roadResult) roadStatus.textContent = state.roadParcelError ? "地形路网预览可用；地块未生成。" : state.cities.length === 1 ? (roadSaved ? "单城地形路网已保存。" : "单城地形路网已预览，参数未保存。") : roadSaved ? "地形路网已保存。" : "地形路网预览可用，参数尚未保存。";
+    else if (!state.cities.length) roadStatus.textContent = "没有城市：路网预览为空；新增城市后会自动重算。";
+    else if (state.cities.length === 1) roadStatus.textContent = "单城地形路网待预览。";
+    const roadUpgradeTarget = state.savedRoadGeneration === null ? undefined : roadGenerationUpgradeTarget(state.savedRoadGeneration.identity);
+    previewRoadUpgradeButton.hidden = roadUpgradeTarget === undefined;
+    previewRoadUpgradeButton.disabled = roadUpgradeTarget === undefined || !state.result || state.roadBusy || state.roadSaving;
+    previewRoadsButton.disabled = !state.result || state.roadBusy || state.roadSaving || !roadDraft;
+    saveRoadsButton.disabled = !state.result || state.roadBusy || state.roadSaving || !roadDraft || !roadPreviewCurrent || roadSaved || typeof options.saveRoadGeneration !== "function";
+    roadLegend.hidden = !state.roadResult || !layerEnabled("showRoads");
+  }
+
+  function terminateWorker() {
+    if (state.worker) state.worker.terminate();
+    state.worker = null;
+    state.busy = false;
+  }
+
+  function clearRoadPreviewTimer() {
+    if (state.roadPreviewTimer !== null) clearTimeout(state.roadPreviewTimer);
+    state.roadPreviewTimer = null;
+  }
+
+  function terminateRoadWorker() {
+    if (state.roadWorker) state.roadWorker.terminate();
+    state.roadWorker = null;
+    state.roadBusy = false;
+  }
+
+  function draftRoadGeneration() {
+    try { return roadGenerationFromForm(roadForm, state.roadDraftIdentity); } catch { return null; }
+  }
+
+  function previewRoadGenerationUpgrade() {
+    const saved = state.savedRoadGeneration;
+    const target = saved === null ? undefined : roadGenerationUpgradeTarget(saved.identity);
+    if (target === undefined || target === state.roadDraftIdentity) return;
+    // 只有用户点击此按钮才切换内存草稿 identity；不会写 source。
+    state.roadDraftIdentity = target;
+    state.roadAutoPreviewEnabled = true;
+    generateRoadPreview();
+    updateStatus();
+  }
+
+  function cityRoadKey(cities) {
+    return cities.map((city) => `${city.id}:${city.x}:${city.y}:${city.seed}:${JSON.stringify(city.parameters)}`).sort().join("|");
+  }
+
+  function roadParcelTemplate(snapshot = state.snapshot) {
+    const templates = snapshot?.source?.topology?.templates;
+    if (templates === undefined) return { key: "parcel-template:absent", settings: undefined };
+    const validated = validateSpatialTemplateConfiguration(templates);
+    const parcel = validated.parcel;
+    if (parcel === undefined) return { key: "parcel-template:absent", settings: undefined };
+    return {
+      key: `parcel-template:${parcel.presetId}:${parcel.revision}:${parcel.parameters?.subdivision}:${parcel.parameters?.roadParcelMaxFaceAreaMeters}`,
+      settings: resolveRoadParcelTemplateSettings(validated),
+    };
+  }
+
+  function roadPreviewKey(generation, roadGeneration, cities) {
+    return `${generationCacheKey(generation)}|${Object.keys(DEFAULT_ROAD_GENERATION).map((key) => `${key}:${roadGeneration[key]}`).join("|")}|${cityRoadKey(cities)}|${roadParcelTemplate().key}`;
+  }
+
+  function currentRoadGate(gate) {
+    return state.open && !state.destroyed && gate.worker === state.roadWorker && gate.epoch === state.epoch && gate.id === state.roadRequestId
+      && state.snapshot?.projectId === gate.projectId && state.snapshot?.revision === gate.revision && state.roadRequestedKey === gate.key;
+  }
+
+  function clearTileTimer() {
+    if (state.tileRequestTimer !== null) clearTimeout(state.tileRequestTimer);
+    state.tileRequestTimer = null;
+  }
+
+  function clearTileRuntime(clearCache = false) {
+    clearTileTimer();
+    if (state.tileWorker) state.tileWorker.terminate();
+    state.tileWorker = null;
+    state.tileQueue = [];
+    state.tileInFlight.clear();
+    state.lodLoading = false;
+    state.tileEpoch += 1;
+    if (state.fadeFrame !== null && typeof cancelAnimationFrame === "function") cancelAnimationFrame(state.fadeFrame);
+    state.fadeFrame = null;
+    if (clearCache) {
+      state.tileCache.clear();
+      state.tileCacheBytes = 0;
+      state.lodLevel = 0;
+    }
+  }
+
+  function clearPreviewTimer() {
+    if (state.previewTimer !== null) clearTimeout(state.previewTimer);
+    state.previewTimer = null;
+  }
+
+  function currentGate(gate) {
+    return state.open && !state.destroyed && gate.worker === state.worker && gate.epoch === state.epoch && gate.id === state.requestId && state.snapshot?.projectId === gate.projectId && state.snapshot?.revision === gate.revision;
+  }
+
+  function percentileThreshold(values, density) {
+    const positive = [];
+    for (let index = 0; index < values.length; index += 1) if (Number(values[index]) > 0) positive.push(Number(values[index]));
+    if (!positive.length) return Infinity;
+    positive.sort((a, b) => a - b);
+    const visibleShare = Math.max(0.015, Math.min(0.2, density * 0.16));
+    return positive[Math.max(0, Math.floor(positive.length * (1 - visibleShare)))] ?? Infinity;
+  }
+
+  function layerEnabled(name) {
+    return layers.querySelector(`input[name="${name}"]`)?.checked === true;
+  }
+
+  function terrainElevationScaleMeters() {
+    return draftRoadGeneration()?.elevationScaleMeters ?? DEFAULT_ROAD_GENERATION.elevationScaleMeters;
+  }
+
+  function buildBaseMap(result, generation, reference = null) {
+    const base = document.createElement("canvas");
+    base.width = result.width;
+    base.height = result.height;
+    const context = base.getContext("2d", { alpha: false });
+    if (!context) throw new Error("浏览器不支持 2D 地图画布");
+    const image = context.createImageData(result.width, result.height);
+    const elevations = result.elevations;
+    const rivers = result.riverFlux;
+    const lakes = result.lakeMask;
+    let minimum = Infinity;
+    let maximum = -Infinity;
+    let waterCells = 0;
+    let riverCells = 0;
+    let lakeCells = 0;
+    for (let index = 0; index < elevations.length; index += 1) {
+      const elevation = Number(elevations[index]);
+      if (!Number.isFinite(elevation)) throw new TypeError("WASM elevations 包含非数值");
+      minimum = Math.min(minimum, elevation);
+      maximum = Math.max(maximum, elevation);
+    }
+    const colorMinimum = reference?.minimum ?? minimum;
+    const colorMaximum = reference?.maximum ?? maximum;
+    const landRange = Math.max(0.000001, colorMaximum - result.seaLevel);
+    const seaRange = Math.max(0.000001, result.seaLevel - colorMinimum);
+    const riverThreshold = reference?.riverThreshold ?? percentileThreshold(rivers, generation.riverDensity);
+    for (let y = 0; y < result.height; y += 1) {
+      for (let x = 0; x < result.width; x += 1) {
+        const index = y * result.width + x;
+        const elevation = Number(elevations[index]);
+        const lake = lakes[index] === true;
+        const sea = elevation <= result.seaLevel;
+        const river = Number(rivers[index]) >= riverThreshold;
+        if (lake) lakeCells += 1;
+        if (!sea && river) riverCells += 1;
+        let red;
+        let green;
+        let blue;
+        if (sea) {
+          const depth = Math.max(0, Math.min(1, (result.seaLevel - elevation) / seaRange));
+          red = 15 - depth * 7; green = 54 - depth * 19; blue = 82 - depth * 20; waterCells += 1;
+        } else {
+          const height = Math.max(0, Math.min(1, (elevation - result.seaLevel) / landRange));
+          const shade = layerEnabled("showRelief")
+            ? (hillshadeAt({
+              elevations, width: result.width, height: result.height, x, y,
+              extentWidthMeters: generation.widthMeters / (result.level === undefined ? 1 : 2 ** result.level),
+              extentHeightMeters: generation.heightMeters / (result.level === undefined ? 1 : 2 ** result.level),
+              elevationScaleMeters: terrainElevationScaleMeters(),
+            }) - 0.5) * 42
+            : 0;
+          red = 42 + height * 112 + shade; green = 91 + height * 69 + shade; blue = 52 + height * 52 + shade;
+        }
+        if (lake && !sea) waterCells += 1;
+        if (lake && layerEnabled("showLakes")) { red = 22; green = 103; blue = 131; }
+        if (!sea && river && layerEnabled("showRivers")) { red = 28; green = 121; blue = 167; }
+        const offset = index * 4;
+        image.data[offset] = Math.max(0, Math.min(255, Math.round(red)));
+        image.data[offset + 1] = Math.max(0, Math.min(255, Math.round(green)));
+        image.data[offset + 2] = Math.max(0, Math.min(255, Math.round(blue)));
+        image.data[offset + 3] = 255;
+      }
+    }
+    context.putImageData(image, 0, 0);
+    const surfaceContours = packContourSegments(contourSegments({
+      elevations, width: result.width, height: result.height, seaLevel: result.seaLevel, lakeMask: lakes,
+      extentWidthMeters: generation.widthMeters, extentHeightMeters: generation.heightMeters, elevationScaleMeters: terrainElevationScaleMeters(), intervalMeters: 5,
+    }));
+    return { canvas: base, minimum, maximum, riverThreshold, waterCells, riverCells, lakeCells, surfaceContours };
+  }
+
+  function pixelRatio() {
+    return Math.max(1, Math.min(3, window.devicePixelRatio || 1));
+  }
+
+  function shorelineSegments(result) {
+    const segments = [];
+    const width = result.width;
+    const height = result.height;
+    const values = result.elevations;
+    const seaLevel = result.seaLevel;
+    const interpolate = (left, right) => {
+      const span = right - left;
+      return Math.max(0, Math.min(1, Math.abs(span) < 1e-12 ? 0.5 : (seaLevel - left) / span));
+    };
+    for (let y = 0; y + 1 < height; y += 1) {
+      for (let x = 0; x + 1 < width; x += 1) {
+        const topLeft = Number(values[y * width + x]);
+        const topRight = Number(values[y * width + x + 1]);
+        const bottomRight = Number(values[(y + 1) * width + x + 1]);
+        const bottomLeft = Number(values[(y + 1) * width + x]);
+        const mask = Number(topLeft > seaLevel) | Number(topRight > seaLevel) << 1
+          | Number(bottomRight > seaLevel) << 2 | Number(bottomLeft > seaLevel) << 3;
+        if (mask === 0 || mask === 15) continue;
+        const edges = {
+          top: [x + interpolate(topLeft, topRight), y],
+          right: [x + 1, y + interpolate(topRight, bottomRight)],
+          bottom: [x + interpolate(bottomLeft, bottomRight), y + 1],
+          left: [x, y + interpolate(topLeft, bottomLeft)],
+        };
+        const pairs = {
+          1: [["left", "top"]], 2: [["top", "right"]], 3: [["left", "right"]],
+          4: [["right", "bottom"]], 5: [["left", "top"], ["right", "bottom"]], 6: [["top", "bottom"]],
+          7: [["left", "bottom"]], 8: [["bottom", "left"]], 9: [["top", "bottom"]],
+          10: [["top", "right"], ["bottom", "left"]], 11: [["right", "bottom"]],
+          12: [["left", "right"]], 13: [["top", "right"]], 14: [["left", "top"]],
+        }[mask] ?? [];
+        for (const [from, to] of pairs) segments.push([...edges[from], ...edges[to]]);
+      }
+    }
+    return segments;
+  }
+
+  function lakeBoundarySegments(result) {
+    const segments = [];
+    const width = result.width;
+    const height = result.height;
+    const lake = (x, y) => result.lakeMask[y * width + x] === true && Number(result.elevations[y * width + x]) > result.seaLevel;
+    for (let y = 0; y < height; y += 1) {
+      for (let x = 0; x < width; x += 1) {
+        if (x + 1 < width && lake(x, y) !== lake(x + 1, y)) segments.push([x + 0.5, Math.max(0, y - 0.5), x + 0.5, Math.min(height - 1, y + 0.5)]);
+        if (y + 1 < height && lake(x, y) !== lake(x, y + 1)) segments.push([Math.max(0, x - 0.5), y + 0.5, Math.min(width - 1, x + 0.5), y + 0.5]);
+      }
+    }
+    return segments;
+  }
+
+  function generationCacheKey(generation) {
+    return Object.keys(DEFAULT_PLANE_GENERATION).map((key) => `${key}:${generation[key]}`).join("|");
+  }
+
+  function tileCacheKey(generation, tile) {
+    return `${generationCacheKey(generation)}|${tile.level}/${tile.x}/${tile.y}`;
+  }
+
+  function touchTile(key) {
+    const cached = state.tileCache.get(key);
+    if (!cached) return null;
+    state.tileCache.delete(key);
+    state.tileCache.set(key, cached);
+    return cached;
+  }
+
+  function cacheTile(key, tile, result, canvas) {
+    const generation = state.previewGeneration;
+    if (!generation) return;
+    const previous = state.tileCache.get(key);
+    if (previous) state.tileCacheBytes -= previous.bytes;
+    const contours = shorelineSegments(result);
+    const lakeContours = lakeBoundarySegments(result);
+    const count = 2 ** tile.level;
+    const originXMeters = tile.x * generation.widthMeters / count;
+    const originYMeters = tile.y * generation.heightMeters / count;
+    const contourInput = {
+      elevations: result.elevations, width: result.width, height: result.height, seaLevel: result.seaLevel, lakeMask: result.lakeMask,
+      originXMeters, originYMeters, extentWidthMeters: generation.widthMeters / count, extentHeightMeters: generation.heightMeters / count,
+      elevationScaleMeters: terrainElevationScaleMeters(),
+    };
+    const surfaceContours = packContourSegments(contourSegments({ ...contourInput, intervalMeters: 5, maxSegments: LOD_CONTOUR_SEGMENT_CAP }));
+    const bytes = LOD_TILE_SIZE * LOD_TILE_SIZE * 4 + (contours.length + lakeContours.length) * 32 + surfaceContours.byteLength;
+    state.tileCache.delete(key);
+    state.tileCache.set(key, { canvas, contours, lakeContours, surfaceContours, contourIntervalMeters: surfaceContours.intervalMeters, tile: { level: tile.level, x: tile.x, y: tile.y }, loadedAt: performance.now(), bytes });
+    state.tileCacheBytes += bytes;
+    const visible = new Set(state.visibleTiles.map((tile) => tile.key));
+    while (state.tileCache.size > LOD_CACHE_MAX_TILES || state.tileCacheBytes > LOD_CACHE_BYTE_BUDGET) {
+      const candidate = [...state.tileCache.keys()].find((entry) => !visible.has(entry)) ?? state.tileCache.keys().next().value;
+      if (!candidate) break;
+      const removed = state.tileCache.get(candidate);
+      state.tileCache.delete(candidate);
+      state.tileCacheBytes -= removed?.bytes ?? 0;
+    }
+  }
+
+  function detailPlan() {
+    if (!state.baseCanvas || !state.previewGeneration) return null;
+    const viewport = canvasSize();
+    const generation = state.previewGeneration;
+    const metersPerBasePixel = Math.sqrt(
+      generation.widthMeters / state.baseCanvas.width * generation.heightMeters / state.baseCanvas.height,
+    );
+    const metersPerPixel = metersPerBasePixel / Math.max(0.000001, state.view.scale);
+    state.metersPerPixel = metersPerPixel;
+    const density = (LOD_DENSITY[densitySelect.value] ?? LOD_DENSITY.normal) * pixelRatio();
+    const ideal = Math.log2(Math.max(generation.widthMeters, generation.heightMeters) * density / (LOD_TILE_SIZE * metersPerPixel));
+    let level = state.lodLevel;
+    if (!state.lodLevelInitialized) {
+      level = Math.round(ideal);
+      state.lodLevelInitialized = true;
+    } else {
+      while (level < LOD_MAX_LEVEL && ideal > level + 0.62) level += 1;
+      while (level > 0 && ideal < level - 0.62) level -= 1;
+    }
+    level = Math.max(0, Math.min(LOD_MAX_LEVEL, level));
+    const normalizedBounds = () => ({
+      left: Math.max(0, Math.min(1, (0 - state.view.x) / state.view.scale / state.baseCanvas.width)),
+      right: Math.max(0, Math.min(1, (viewport.width - state.view.x) / state.view.scale / state.baseCanvas.width)),
+      top: Math.max(0, Math.min(1, (0 - state.view.y) / state.view.scale / state.baseCanvas.height)),
+      bottom: Math.max(0, Math.min(1, (viewport.height - state.view.y) / state.view.scale / state.baseCanvas.height)),
+    });
+    const bounds = normalizedBounds();
+    if (bounds.right <= bounds.left || bounds.bottom <= bounds.top) {
+      state.lodLevel = level;
+      return { level, metersPerPixel, tiles: [], signature: `${generationCacheKey(generation)}|${level}|offscreen` };
+    }
+    const tileRange = (candidateLevel) => {
+      const count = 2 ** candidateLevel;
+      const margin = candidateLevel > 0 ? 1 : 0;
+      const minimumX = Math.max(0, Math.floor(bounds.left * count) - margin);
+      const maximumX = Math.min(count - 1, Math.ceil(bounds.right * count) - 1 + margin);
+      const minimumY = Math.max(0, Math.floor(bounds.top * count) - margin);
+      const maximumY = Math.min(count - 1, Math.ceil(bounds.bottom * count) - 1 + margin);
+      return { count, minimumX, maximumX, minimumY, maximumY, total: (maximumX - minimumX + 1) * (maximumY - minimumY + 1) };
+    };
+    const requiredTileRange = (candidateLevel) => {
+      const count = 2 ** candidateLevel;
+      const minimumX = Math.max(0, Math.floor(bounds.left * count));
+      const maximumX = Math.min(count - 1, Math.ceil(bounds.right * count) - 1);
+      const minimumY = Math.max(0, Math.floor(bounds.top * count));
+      const maximumY = Math.min(count - 1, Math.ceil(bounds.bottom * count) - 1);
+      return { count, minimumX, maximumX, minimumY, maximumY, total: (maximumX - minimumX + 1) * (maximumY - minimumY + 1) };
+    };
+    let range = tileRange(level);
+    while (level > 0 && requiredTileRange(level).total > LOD_MAX_VISIBLE_TILES) { level -= 1; range = tileRange(level); }
+    const required = requiredTileRange(level);
+    state.lodLevel = level;
+    const centerX = (bounds.left + bounds.right) / 2 * range.count;
+    const centerY = (bounds.top + bounds.bottom) / 2 * range.count;
+    const tiles = [];
+    for (let y = range.minimumY; y <= range.maximumY; y += 1) {
+      for (let x = range.minimumX; x <= range.maximumX; x += 1) {
+        const tile = { level, x, y, size: LOD_TILE_SIZE };
+        const requiredTile = x >= required.minimumX && x <= required.maximumX && y >= required.minimumY && y <= required.maximumY;
+        tiles.push({ ...tile, key: tileCacheKey(generation, tile), required: requiredTile, distance: Math.hypot(x + 0.5 - centerX, y + 0.5 - centerY) });
+      }
+    }
+    tiles.sort((left, right) => Number(right.required) - Number(left.required) || left.distance - right.distance);
+    const visibleTiles = tiles.slice(0, LOD_MAX_VISIBLE_TILES);
+    return { level, metersPerPixel, tiles: visibleTiles, signature: `${generationCacheKey(generation)}|${level}|${visibleTiles.map((tile) => `${tile.x},${tile.y}`).join(";")}` };
+  }
+
+  function updateDetailStatus() {
+    if (!state.baseCanvas || !state.previewGeneration) {
+      detailStatus.dataset.state = "idle";
+      detailStatus.textContent = "细节待命";
+      cameraMpp.textContent = "— m/px";
+      return;
+    }
+    const loaded = state.visibleTiles.reduce((count, tile) => count + Number(state.tileCache.has(tile.key)), 0);
+    const total = state.visibleTiles.length;
+    cameraMpp.textContent = `${state.metersPerPixel < 10 ? state.metersPerPixel.toFixed(1) : Math.round(state.metersPerPixel).toLocaleString()} m/px`;
+    if (state.lodError) {
+      detailStatus.dataset.state = "error";
+      detailStatus.textContent = `LOD ${state.lodLevel} · 细节加载失败，底图可用`;
+    } else if (loaded < total || state.lodLoading) {
+      detailStatus.dataset.state = "loading";
+      detailStatus.textContent = `LOD ${state.lodLevel} · ${loaded}/${total} 区块加载中`;
+    } else {
+      detailStatus.dataset.state = "ready";
+      detailStatus.textContent = `LOD ${state.lodLevel} · ${total} 区块已加载`;
+    }
+  }
+
+  function pumpTileQueue(worker, epoch, generation) {
+    if (state.tileWorker !== worker || state.tileEpoch !== epoch) return;
+    while (state.tileInFlight.size < LOD_MAX_IN_FLIGHT && state.tileQueue.length) {
+      const tile = state.tileQueue.shift();
+      const id = ++state.tileRequestId;
+      state.tileInFlight.set(id, tile);
+      worker.postMessage({ id, kind: "tile", settings: generation, tile: { level: tile.level, x: tile.x, y: tile.y, size: LOD_TILE_SIZE } });
+    }
+    if (!state.tileQueue.length && !state.tileInFlight.size) {
+      state.lodLoading = false;
+      updateDetailStatus();
+    }
+  }
+
+  function beginTileRequests(plan) {
+    if (!state.open || !state.previewGeneration || state.desiredTileSignature !== plan.signature) return;
+    const missing = plan.tiles.filter((tile) => !state.tileCache.has(tile.key));
+    clearTileRuntime(false);
+    if (!missing.length) { updateDetailStatus(); return; }
+    state.lodLoading = true;
+    state.lodError = null;
+    state.tileQueue = missing;
+    const generation = state.previewGeneration;
+    const epoch = state.tileEpoch;
+    const worker = new Worker(new URL("./world-map-worker.js", import.meta.url), { type: "module", name: "world-map-detail-loader" });
+    state.tileWorker = worker;
+    worker.addEventListener("message", (event) => {
+      if (state.tileWorker !== worker || state.tileEpoch !== epoch || event.data?.kind !== "tile") return;
+      const requested = state.tileInFlight.get(event.data?.id);
+      if (!requested) return;
+      state.tileInFlight.delete(event.data.id);
+      if (event.data?.error) {
+        state.lodError = String(event.data.error);
+      } else {
+        try {
+          const result = validateTileResult(event.data?.result, generation, requested);
+          if (!state.baseRenderStats) throw new Error("地图底图调色基准缺失");
+          cacheTile(requested.key, requested, result, buildBaseMap(result, generation, state.baseRenderStats).canvas);
+          draw();
+        } catch (error) {
+          state.lodError = errorText(error);
+        }
+      }
+      pumpTileQueue(worker, epoch, generation);
+      updateDetailStatus();
+    });
+    worker.addEventListener("error", (event) => {
+      if (state.tileWorker !== worker || state.tileEpoch !== epoch) return;
+      state.lodError = event.message || "地图细节 Worker 失败";
+      state.tileQueue = [];
+      state.tileInFlight.clear();
+      state.lodLoading = false;
+      worker.terminate();
+      state.tileWorker = null;
+      updateDetailStatus();
+    });
+    pumpTileQueue(worker, epoch, generation);
+    updateDetailStatus();
+  }
+
+  function refreshDetailPlan(immediate = false) {
+    const plan = detailPlan();
+    if (!plan) { state.visibleTiles = []; updateDetailStatus(); return; }
+    state.visibleTiles = plan.tiles;
+    state.desiredTileSignature = plan.signature;
+    state.lodLoading = plan.tiles.some((tile) => !state.tileCache.has(tile.key));
+    state.lodError = null;
+    clearTileTimer();
+    updateDetailStatus();
+    if (!state.lodLoading) return;
+    if (immediate) beginTileRequests(plan);
+    else state.tileRequestTimer = setTimeout(() => { state.tileRequestTimer = null; beginTileRequests(plan); }, LOD_REQUEST_DEBOUNCE_MS);
+  }
+
+  function cachedTileOrParent(tile, skipExact = false) {
+    const generation = state.previewGeneration;
+    if (!generation) return null;
+    for (let level = skipExact ? tile.level - 1 : tile.level; level >= 0; level -= 1) {
+      const divisor = 2 ** (tile.level - level);
+      const ancestor = { level, x: Math.floor(tile.x / divisor), y: Math.floor(tile.y / divisor), size: LOD_TILE_SIZE };
+      const key = tileCacheKey(generation, ancestor);
+      const cached = touchTile(key);
+      if (cached) return { cached, ancestor, divisor };
+    }
+    return null;
+  }
+
+  function drawTileRaster(context, tile, source, alpha = 1) {
+    const count = 2 ** tile.level;
+    const destinationWidth = state.baseCanvas.width / count;
+    const destinationHeight = state.baseCanvas.height / count;
+    const relativeX = tile.x - source.ancestor.x * source.divisor;
+    const relativeY = tile.y - source.ancestor.y * source.divisor;
+    const sourceWidth = LOD_TILE_SIZE / source.divisor;
+    const sourceHeight = LOD_TILE_SIZE / source.divisor;
+    const previousAlpha = context.globalAlpha;
+    context.globalAlpha = alpha;
+    context.drawImage(
+      source.cached.canvas,
+      relativeX * sourceWidth, relativeY * sourceHeight, sourceWidth, sourceHeight,
+      tile.x * destinationWidth, tile.y * destinationHeight, destinationWidth, destinationHeight,
+    );
+    context.globalAlpha = previousAlpha;
+  }
+
+  function drawTileShoreline(context, tile, cached, alpha = 1) {
+    if (!cached.contours.length && !cached.lakeContours.length) return;
+    const count = 2 ** tile.level;
+    const destinationWidth = state.baseCanvas.width / count;
+    const destinationHeight = state.baseCanvas.height / count;
+    const denominator = LOD_TILE_SIZE - 1;
+    const previousAlpha = context.globalAlpha;
+    context.globalAlpha = alpha;
+    const stroke = (segments, color) => {
+      if (!segments.length) return;
+      context.beginPath();
+      for (const [x1, y1, x2, y2] of segments) {
+        context.moveTo(tile.x * destinationWidth + x1 / denominator * destinationWidth, tile.y * destinationHeight + y1 / denominator * destinationHeight);
+        context.lineTo(tile.x * destinationWidth + x2 / denominator * destinationWidth, tile.y * destinationHeight + y2 / denominator * destinationHeight);
+      }
+      context.strokeStyle = color;
+      context.lineWidth = 0.7 / state.view.scale;
+      context.lineCap = "round";
+      context.stroke();
+    };
+    stroke(cached.contours, "rgba(224,244,249,.88)");
+    stroke(cached.lakeContours, "rgba(116,211,232,.9)");
+    context.globalAlpha = previousAlpha;
+  }
+
+  function drawTileTerrainContours(context, tile, cached, plan, alpha = 1) {
+    if (!layerEnabled("showContours") || !cached.surfaceContours.length || !state.metersPerPixel) return;
+    const count = 2 ** tile.level;
+    const destinationWidth = state.baseCanvas.width / count;
+    const destinationHeight = state.baseCanvas.height / count;
+    const originX = tile.x * state.previewGeneration.widthMeters / count;
+    const originY = tile.y * state.previewGeneration.heightMeters / count;
+    for (const [interval, opacity] of [[plan.fineIntervalMeters, 1 - plan.coarseAlpha], [plan.coarseIntervalMeters, plan.coarseAlpha]]) {
+      if (opacity <= 0) continue;
+      context.beginPath();
+      for (let index = 0; index < cached.surfaceContours.length; index += 5) {
+        const x1 = cached.surfaceContours[index]; const y1 = cached.surfaceContours[index + 1];
+        const x2 = cached.surfaceContours[index + 2]; const y2 = cached.surfaceContours[index + 3]; const elevation = cached.surfaceContours[index + 4];
+        if (Math.abs(elevation / interval - Math.round(elevation / interval)) > 1e-8) continue;
+        context.moveTo(tile.x * destinationWidth + (x1 - originX) / (state.previewGeneration.widthMeters / count) * destinationWidth, tile.y * destinationHeight + (y1 - originY) / (state.previewGeneration.heightMeters / count) * destinationHeight);
+        context.lineTo(tile.x * destinationWidth + (x2 - originX) / (state.previewGeneration.widthMeters / count) * destinationWidth, tile.y * destinationHeight + (y2 - originY) / (state.previewGeneration.heightMeters / count) * destinationHeight);
+      }
+      context.globalAlpha = alpha * opacity;
+      context.strokeStyle = "rgba(18,37,22,.78)";
+      context.lineWidth = 0.65 / state.view.scale;
+      context.lineCap = "round";
+      context.stroke();
+    }
+    context.globalAlpha = alpha;
+  }
+
+  function drawBaseTerrainContours(context, plan) {
+    if (!layerEnabled("showContours") || !state.baseRenderStats?.surfaceContours?.length || !state.metersPerPixel) return;
+    for (const [interval, opacity] of [[plan.fineIntervalMeters, 1 - plan.coarseAlpha], [plan.coarseIntervalMeters, plan.coarseAlpha]]) {
+      if (opacity <= 0) continue;
+      context.beginPath();
+      for (let index = 0; index < state.baseRenderStats.surfaceContours.length; index += 5) {
+        const x1 = state.baseRenderStats.surfaceContours[index]; const y1 = state.baseRenderStats.surfaceContours[index + 1];
+        const x2 = state.baseRenderStats.surfaceContours[index + 2]; const y2 = state.baseRenderStats.surfaceContours[index + 3]; const elevation = state.baseRenderStats.surfaceContours[index + 4];
+        if (Math.abs(elevation / interval - Math.round(elevation / interval)) > 1e-8) continue;
+        context.moveTo(x1 / state.previewGeneration.widthMeters * state.baseCanvas.width, y1 / state.previewGeneration.heightMeters * state.baseCanvas.height);
+        context.lineTo(x2 / state.previewGeneration.widthMeters * state.baseCanvas.width, y2 / state.previewGeneration.heightMeters * state.baseCanvas.height);
+      }
+      context.globalAlpha = opacity;
+      context.strokeStyle = "rgba(18,37,22,.58)";
+      context.lineWidth = 0.55 / state.view.scale;
+      context.stroke();
+    }
+    context.globalAlpha = 1;
+  }
+
+  function visibleContourPlan() {
+    let minimumAvailableIntervalMeters = 5;
+    for (const tile of state.visibleTiles) {
+      const cached = state.tileCache.get(tile.key);
+      if (cached?.tile.level === tile.level) minimumAvailableIntervalMeters = Math.max(minimumAvailableIntervalMeters, cached.contourIntervalMeters ?? 5);
+    }
+    return sharedContourPlan(state.metersPerPixel ?? Infinity, minimumAvailableIntervalMeters);
+  }
+
+  function scheduleFadeFrame() {
+    if (state.fadeFrame !== null || typeof requestAnimationFrame !== "function") return;
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
+    state.fadeFrame = requestAnimationFrame(() => {
+      state.fadeFrame = null;
+      if (state.open) draw();
+    });
+  }
+
+  function proceduralInput(snapshot) {
+    return snapshot?.source?.topology?.procedural ?? null;
+  }
+
+  async function loadCities(snapshot, generation, isCurrent = () => true) {
+    if (!isCurrent()) return false;
+    const input = proceduralInput(snapshot);
+    if (!input) {
+      if (!isCurrent()) return false;
+      state.cityWorld = null;
+      state.cities = [];
+      state.cityLayouts.clear();
+      state.roadParcelLayouts.clear();
+      state.roadParcelError = null;
+      state.cityLayoutBytes = 0;
+      return true;
+    }
+    const cityModule = state.cityModule;
+    if (!isCurrent()) return false;
+    const world = cityModule.validateProceduralWorld(input, { widthMeters: generation.widthMeters, heightMeters: generation.heightMeters });
+    state.cityWorld = world;
+    state.cities = [...world.cities];
+    const liveIds = new Set(state.cities.map((city) => city.id));
+    for (const [key, cached] of state.cityLayouts) {
+      if (!liveIds.has(cached.cityId)) { state.cityLayouts.delete(key); state.cityLayoutBytes -= cached.bytes; }
+    }
+    if (state.roadResult) {
+      try {
+        cacheRoadParcels(state.roadResult, state.previewRoadGeneration);
+        state.roadParcelError = null;
+      } catch (error) {
+        state.roadParcelLayouts.clear();
+        state.roadParcelError = errorText(error);
+      }
+    }
+    return true;
+  }
+
+  function updateActorBinding(snapshot) {
+    if (typeof options.setControlledActor !== "function") return;
+    const choices = Array.isArray(snapshot?.actorChoices) ? snapshot.actorChoices.filter((choice) => choice
+      && typeof choice.id === "string" && choice.id && typeof choice.label === "string" && choice.label) : [];
+    const saved = snapshot?.source?.topology?.controlledActorId;
+    actorSelect.replaceChildren();
+    if (!choices.length) {
+      const option = element("option", "", "暂无可绑定角色"); option.value = ""; actorSelect.append(option);
+      actorStatus.textContent = "请先在世界图中新建人物实体。";
+    } else {
+      for (const choice of choices) { const option = element("option", "", choice.label); option.value = choice.id; actorSelect.append(option); }
+      actorSelect.value = choices.some((choice) => choice.id === saved) ? saved : choices[0].id;
+      actorStatus.textContent = saved ? `当前绑定：${choices.find((choice) => choice.id === saved)?.label ?? saved}` : "尚未保存受控角色绑定。";
+    }
+    const worldSaved = Boolean(state.savedGeneration && state.previewGeneration && sameGeneration(state.savedGeneration, state.previewGeneration));
+    actorSelect.disabled = state.savingActor || !choices.length || !worldSaved;
+    saveActorButton.disabled = actorSelect.disabled || actorSelect.value === saved;
+  }
+
+  async function saveActorBinding() {
+    if (typeof options.setControlledActor !== "function" || state.savingActor || !state.open || !state.snapshot || !state.previewGeneration) return;
+    const actorId = actorSelect.value;
+    const expectedProject = state.snapshot.projectId;
+    const expectedRevision = state.snapshot.revision;
+    const expectedEpoch = state.epoch;
+    const draft = draftGeneration();
+    if (!actorId || !draft || !state.savedGeneration || !sameGeneration(draft, state.previewGeneration)
+      || !sameGeneration(state.savedGeneration, state.previewGeneration) || state.busy || state.saving || state.loading) return;
+    state.savingActor = true; updateActorBinding(state.snapshot); actorStatus.textContent = "正在保存角色绑定…";
+    try {
+      const response = await options.setControlledActor(actorId, expectedRevision);
+      if (!state.open || state.epoch !== expectedEpoch || state.snapshot?.projectId !== expectedProject || state.snapshot?.revision !== expectedRevision) return;
+      const validated = validateSnapshot(response);
+      if (validated.value.projectId !== expectedProject || validated.value.revision <= expectedRevision
+        || validated.value.source?.topology?.controlledActorId !== actorId) throw new Error("角色绑定读回无效");
+      state.snapshot = validated.value; state.savedGeneration = validated.savedGeneration;
+      state.markers = objectMarkers(validated.value.source?.objects, state.previewGeneration);
+      updateActorBinding(validated.value); notify("受控角色绑定已保存。", false); draw(); updateStatus();
+    } catch (error) {
+      if (state.open && state.epoch === expectedEpoch && state.snapshot?.projectId === expectedProject) {
+        actorStatus.textContent = errorText(error); notify(errorText(error), true);
+      }
+    } finally {
+      state.savingActor = false;
+      if (state.open && state.epoch === expectedEpoch) updateActorBinding(state.snapshot);
+    }
+  }
+
+  function cityCacheKey(city) {
+    return `${state.cityWorld?.identity ?? ""}|${state.cityWorld?.worldSeed ?? ""}|${city.id}|${city.seed}|${JSON.stringify(city.parameters)}`;
+  }
+
+  function cityLayout(city) {
+    if (!state.cityModule || !state.cityWorld) return null;
+    const key = cityCacheKey(city);
+    const cached = state.cityLayouts.get(key);
+    if (cached) {
+      state.cityLayouts.delete(key); state.cityLayouts.set(key, cached); return cached.layout;
+    }
+    const layout = state.cityModule.generateCityLayout(state.cityWorld.worldSeed, city);
+    const bytes = layout.roads.length * 72 + layout.parcels.length * 96;
+    state.cityLayouts.set(key, { cityId: city.id, layout, bytes });
+    state.cityLayoutBytes += bytes;
+    while (state.cityLayouts.size > CITY_LAYOUT_CACHE_MAX || state.cityLayoutBytes > CITY_LAYOUT_CACHE_BYTE_BUDGET) {
+      const oldest = state.cityLayouts.keys().next().value;
+      if (!oldest) break;
+      const removed = state.cityLayouts.get(oldest); state.cityLayouts.delete(oldest); state.cityLayoutBytes -= removed?.bytes ?? 0;
+    }
+    return layout;
+  }
+
+  /** 道路响应到达时只生成一次；此函数失败必须由调用方可见报告，不能伪装成合法空地块。 */
+  function cacheRoadParcels(result, roadGeneration) {
+    state.roadParcelLayouts.clear();
+    if (!state.cityWorld || !roadGeneration) throw new Error("道路地块缺少城市或道路设置上下文");
+    for (const city of state.cities) {
+      const cityLayout = result.cityLayouts.find((layout) => layout.cityId === city.id);
+      const terrain = cityLayout?.terrain;
+      const boundary = cityLayout?.boundary;
+      const roads = result.roads;
+      if (!terrain) throw new Error(`城市 ${city.label} 缺少确定性地形采样`);
+      if (!boundary) throw new Error(`城市 ${city.label} 缺少地形边界`);
+      if (boundary.status === "unbuildable") { state.roadParcelLayouts.set(city.id, []); continue; }
+      const parcelTemplate = roadParcelTemplate();
+      const layout = generateRoadParcels(state.cityWorld.worldSeed, city, { roads, boundary, terrain,
+        // preview 的 identity 来自当前 draft（旧图打开时就是 saved identity），不是 current 默认值。
+        algorithm: roadParcelAlgorithm(roadGeneration.identity), settings: {
+        maxSlope: roadGeneration.maxGrade,
+        ...parcelTemplate.settings,
+      } });
+      if (!Array.isArray(layout?.parcels)) throw new Error(`城市 ${city.label} 的地块结果无效`);
+      state.roadParcelLayouts.set(city.id, layout.parcels.filter((parcel) => Array.isArray(parcel?.polygon) && parcel.polygon.length >= 3));
+    }
+    state.roadParcelTemplateKey = roadParcelTemplate().key;
+  }
+
+  function drawRoadParcels(context, city, metersToMapX, metersToMapY) {
+    for (const parcel of state.roadParcelLayouts.get(city.id) ?? []) {
+      const palette = state.cityModule.PALETTE[parcel.landUse];
+      if (!palette) continue;
+      const [first, ...rest] = parcel.polygon;
+      context.beginPath(); context.moveTo(first.x * metersToMapX, first.y * metersToMapY);
+      for (const point of rest) context.lineTo(point.x * metersToMapX, point.y * metersToMapY);
+      context.closePath(); context.fillStyle = `${palette.color}c4`; context.fill();
+    }
+  }
+
+  function nextCityMode(city, screenRadius, screenBlock) {
+    const roadThreshold = Number(roadThresholdInput.value) || 80;
+    const parcelThreshold = Number(parcelThresholdInput.value) || 12;
+    const previous = state.cityModes.get(city.id) ?? "marker";
+    let mode = previous;
+    if (previous === "marker") {
+      if (screenRadius >= roadThreshold) mode = "roads";
+    } else if (screenRadius < roadThreshold * 0.86) mode = "marker";
+    if (mode === "roads" && screenBlock >= parcelThreshold) mode = "parcels";
+    else if (mode === "parcels" && screenBlock < parcelThreshold * 0.86) mode = "roads";
+    state.cityModes.set(city.id, mode);
+    return mode;
+  }
+
+  function drawCities(context) {
+    cityLegend.hidden = true;
+    if (!layerEnabled("showCities") || !state.previewGeneration || !state.cityModule || !state.cityWorld) return;
+    const generation = state.previewGeneration;
+    const metersToMapX = state.baseCanvas.width / generation.widthMeters;
+    const metersToMapY = state.baseCanvas.height / generation.heightMeters;
+    const viewport = canvasSize();
+    let parcelsVisible = false;
+    for (const city of state.cities) {
+      const x = city.x * metersToMapX;
+      const y = city.y * metersToMapY;
+      const screenRadius = city.parameters.radiusMeters * Math.sqrt(metersToMapX * metersToMapY) * state.view.scale;
+      const screenBlock = city.parameters.blockSizeMeters * Math.sqrt(metersToMapX * metersToMapY) * state.view.scale;
+      const screenX = state.view.x + x * state.view.scale;
+      const screenY = state.view.y + y * state.view.scale;
+      if (screenX + screenRadius < 0 || screenY + screenRadius < 0 || screenX - screenRadius > viewport.width || screenY - screenRadius > viewport.height) continue;
+      const mode = state.roadResult ? nextCityMode(city, screenRadius, screenBlock) : "marker";
+      if (mode !== "marker") {
+        const boundaryValue = state.roadResult?.cityLayouts.find((layout) => layout.cityId === city.id)?.boundary;
+        const boundary = boundaryValue?.status === "bounded" ? boundaryValue.points : null;
+        if (boundary) {
+          context.beginPath(); context.moveTo(boundary[0].x * metersToMapX, boundary[0].y * metersToMapY);
+          for (let index = 1; index < boundary.length; index += 1) context.lineTo(boundary[index].x * metersToMapX, boundary[index].y * metersToMapY);
+          context.closePath(); context.lineWidth = Math.max(.8 / state.view.scale, 2 / state.view.scale); context.strokeStyle = "rgba(255,206,102,.9)"; context.setLineDash([4 / state.view.scale, 3 / state.view.scale]); context.stroke(); context.setLineDash([]);
+        }
+        if (state.roadResult && mode === "parcels") {
+          const parcels = state.roadParcelLayouts.get(city.id) ?? [];
+          parcelsVisible ||= parcels.length > 0;
+          drawRoadParcels(context, city, metersToMapX, metersToMapY);
+        }
+      }
+      if (mode === "marker") {
+        context.beginPath(); context.arc(x, y, Math.max(3 / state.view.scale, Math.min(city.parameters.radiusMeters * metersToMapX, 9 / state.view.scale)), 0, Math.PI * 2);
+        context.fillStyle = "#ffce66"; context.fill();
+      }
+      if (mode !== "parcels") {
+        context.fillStyle = "#fff4d6"; context.font = `${11 / state.view.scale}px ui-sans-serif, sans-serif`;
+        context.fillText(city.label, x + (mode === "marker" ? 8 / state.view.scale : 4 / state.view.scale), y);
+      }
+    }
+    cityLegend.hidden = !parcelsVisible;
+  }
+
+  function drawCityDraft(context) {
+    const draft = state.cityPoint;
+    if (!draft || !state.previewGeneration || !state.baseCanvas) return;
+    const x = draft.x / state.previewGeneration.widthMeters * state.baseCanvas.width;
+    const y = draft.y / state.previewGeneration.heightMeters * state.baseCanvas.height;
+    const busy = draft.phase === "creating" || draft.phase === "roads";
+    const failed = draft.phase === "error";
+    const radius = 7 / state.view.scale;
+    context.beginPath(); context.arc(x, y, radius, 0, Math.PI * 2);
+    context.fillStyle = failed ? "#ff959a" : busy ? "#ffd879" : "#32d551";
+    context.fill();
+    context.beginPath(); context.arc(x, y, radius * .48, 0, Math.PI * 2);
+    context.fillStyle = "#201f20"; context.fill();
+    const label = failed ? "生成失败，可重试" : draft.phase === "creating" ? "正在生成城市…" : draft.phase === "roads" ? "正在生成地形路网…" : "待生成城市";
+    context.fillStyle = "#fff4d6";
+    context.font = `${11 / state.view.scale}px ui-sans-serif, sans-serif`;
+    context.fillText(label, x + radius * 1.7, y + radius * 1.7);
+  }
+
+  function roadPath(context, points, metersToMapX, metersToMapY) {
+    const first = points[0];
+    context.beginPath();
+    context.moveTo(first.x * metersToMapX, first.y * metersToMapY);
+    for (let index = 1; index < points.length; index += 1) context.lineTo(points[index].x * metersToMapX, points[index].y * metersToMapY);
+  }
+
+  function drawRoads(context) {
+    if (!layerEnabled("showRoads") || !state.roadResult || !state.previewGeneration || !state.baseCanvas) return;
+    const metersToMapX = state.baseCanvas.width / state.previewGeneration.widthMeters;
+    const metersToMapY = state.baseCanvas.height / state.previewGeneration.heightMeters;
+    for (const road of state.roadResult.roads) {
+      if (!roadVisibleAtMetersPerPixel(road, state.metersPerPixel ?? Infinity)) continue;
+      const width = Math.max(0.65 / state.view.scale, road.widthMeters * Math.sqrt(metersToMapX * metersToMapY));
+      for (const segment of road.segments) {
+        roadPath(context, segment.points, metersToMapX, metersToMapY);
+        context.lineCap = "round";
+        context.lineJoin = "round";
+        context.lineWidth = width;
+        context.setLineDash(segment.kind === "bridge" ? [width * 3, width * 1.6] : segment.kind === "tunnel" ? [width * 1.2, width * 2.2] : []);
+        context.strokeStyle = segment.kind === "bridge" ? "#e9c46a" : segment.kind === "tunnel" ? "#b592f5" : road.roadClass === "motorway" ? "#f5f5f5" : road.kind === "arterial" ? "#e0a85d" : "rgba(242,242,242,.75)";
+        context.stroke();
+      }
+      context.setLineDash([]);
+    }
+  }
+
+  function stableCityId(label, x, y) {
+    const input = `${state.snapshot?.projectId ?? "world"}\u001f${label}\u001f${x.toFixed(3)}\u001f${y.toFixed(3)}`;
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) hash = Math.imul(hash ^ input.charCodeAt(index), 0x01000193);
+    return `city:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+  }
+
+  function stableCitySeed(id, x, y) {
+    const input = `${state.previewGeneration?.seed ?? 0}\u001f${id}\u001f${x.toFixed(3)}\u001f${y.toFixed(3)}`;
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) hash = Math.imul(hash ^ input.charCodeAt(index), 0x01000193);
+    return hash >>> 0;
+  }
+
+  function closeCityDialog() {
+    state.cityPoint = null;
+    cityDialogStatus.textContent = "";
+    cityDialogStatus.dataset.state = "idle";
+    if (typeof cityDialog.close === "function" && cityDialog.open) cityDialog.close();
+    else { cityDialog.removeAttribute("open"); cityDialog.hidden = true; }
+    submitCity.textContent = "生成城市";
+    cancelCity.textContent = "取消";
+    draw();
+  }
+
+  function applyCityTemplate(templateId) {
+    const template = cityTemplates.find((candidate) => candidate.id === templateId);
+    if (!template || !state.cityPoint) return;
+    applyCityParameters(template.parameters);
+  }
+
+  function applyCityParameters(parameters) {
+    if (!state.cityPoint || !parameters || typeof parameters !== "object") return;
+    const radius = Math.max(32, Math.min(state.cityPoint.maximumRadius, Number(parameters.radiusMeters)));
+    if (Number.isFinite(radius)) cityForm.elements.namedItem("cityRadius").value = String(Math.round(radius));
+    for (const [name, value] of [["cityBlockSize", parameters.blockSizeMeters], ["cityRoadWidth", parameters.roadWidthMeters], ...Object.entries(parameters.landUseWeights ?? {}).map(([name, value]) => [`cityUse_${name}`, value])]) {
+      const control = cityForm.elements.namedItem(name);
+      if ((control instanceof HTMLInputElement || control instanceof HTMLSelectElement) && typeof value === "number" && Number.isFinite(value)) control.value = String(value);
+    }
+    syncCitySize();
+  }
+
+  function syncCitySize() {
+    const radius = Number(cityForm.elements.namedItem("cityRadius")?.value);
+    citySize.value = CITY_SIZE_PRESETS.find((preset) => preset.radiusMeters === radius)?.id ?? "";
+  }
+
+  function sourceCityTemplate() {
+    const templates = state.snapshot?.source?.topology?.templates;
+    if (templates === undefined) return null;
+    const city = validateSpatialTemplateConfiguration(templates).city;
+    return city === undefined ? null : {
+      value: `source:${city.presetId}@${city.revision}`,
+      label: `当前已套用：${city.presetId} r${city.revision}`,
+      parameters: city.parameters,
+    };
+  }
+
+  function populateCityTemplateOptions(active = cityTemplate.value) {
+    const applied = sourceCityTemplate();
+    cityTemplate.replaceChildren();
+    const custom = element("option", "", "自定义"); custom.value = ""; cityTemplate.append(custom);
+    if (applied) { const option = element("option", "", applied.label); option.value = applied.value; cityTemplate.append(option); }
+    for (const template of cityTemplates) { const option = element("option", "", template.label); option.value = template.id; cityTemplate.append(option); }
+    const values = new Set([...cityTemplate.options].map((option) => option.value));
+    cityTemplate.value = values.has(active) ? active : "";
+    return applied;
+  }
+
+  function setCityTemplates(records, templateOptions = {}) {
+    const active = cityTemplate.value;
+    const focused = document.activeElement === cityTemplate;
+    cityTemplates = normalizeCityTemplates(records);
+    state.cityTemplateDefaultId = typeof templateOptions.defaultId === "string" ? templateOptions.defaultId : state.cityTemplateDefaultId;
+    populateCityTemplateOptions(active);
+    if (focused) cityTemplate.focus();
+  }
+
+  function markCityRoadPreviewError(error) {
+    if (!state.cityPoint?.cityId) return;
+    state.cityPoint.phase = "error";
+    state.cityPoint.error = errorText(error);
+    cityDialogStatus.dataset.state = "error";
+    cityDialogStatus.textContent = `城市已保存，但地形路网生成失败：${state.cityPoint.error}`;
+    submitCity.textContent = "重试生成路网";
+    submitCity.disabled = false;
+    cancelCity.disabled = false;
+    cancelCity.textContent = "关闭";
+    draw();
+  }
+
+  function completeCityRoadPreview(result) {
+    const cityId = state.cityPoint?.cityId;
+    if (!cityId) return;
+    const layout = result.cityLayouts.find((candidate) => candidate.cityId === cityId);
+    const cityRoads = result.roads.filter((road) => road.cityId === cityId);
+    const connectedRoads = layout ? cityRoads.filter((road) => layout.roads.includes(road.id)) : [];
+    const unreachable = result.unreachable.filter((entry) => entry.fromId === cityId || entry.toId === cityId);
+    if (!connectedRoads.length) {
+      markCityRoadPreviewError(`城市已保存，但路网全部不可达${unreachable.length ? `（${unreachable.length} 条受限连接）` : ""}`);
+      return;
+    }
+    const cityLabel = state.cities.find((city) => city.id === cityId)?.label ?? cityId;
+    closeCityDialog();
+    notify(unreachable.length ? `城市“${cityLabel}”已保存；${unreachable.length} 条路网连接不可达，其余道路已生成。` : `城市“${cityLabel}”及地形路网已生成。`, unreachable.length > 0);
+  }
+
+  async function openCityDialogAt(clientX, clientY) {
+    if (typeof options.createCity !== "function" || !state.baseCanvas || !state.previewGeneration || !state.snapshot) return;
+    const draft = draftGeneration();
+    if (state.busy || state.saving || state.loading || !draft || !state.savedGeneration
+      || !sameGeneration(state.savedGeneration, state.previewGeneration) || !sameGeneration(draft, state.previewGeneration)) {
+      notify("请先确认并保存地图地形，再创建城市。", true); return;
+    }
+    const rect = canvas.getBoundingClientRect();
+    const mapX = (clientX - rect.left - state.view.x) / state.view.scale;
+    const mapY = (clientY - rect.top - state.view.y) / state.view.scale;
+    if (mapX < 0 || mapY < 0 || mapX > state.baseCanvas.width || mapY > state.baseCanvas.height) return;
+    const x = mapX / state.baseCanvas.width * state.previewGeneration.widthMeters;
+    const y = mapY / state.baseCanvas.height * state.previewGeneration.heightMeters;
+    const maximumRadius = Math.min(x, y, state.previewGeneration.widthMeters - x, state.previewGeneration.heightMeters - y, 200_000);
+    if (maximumRadius < 32) { notify("该坐标离地图边界过近，无法容纳最小城市。", true); return; }
+    state.cityPoint = { x, y, maximumRadius, phase: "draft", cityId: null, error: null, cityTemplateTouched: false };
+    cityName.value = `城市 ${state.cities.length + 1}`;
+    const radius = Math.max(32, Math.min(maximumRadius, Math.max(240, Math.min(state.previewGeneration.widthMeters, state.previewGeneration.heightMeters) / 40)));
+    const blockSize = Math.max(16, Math.min(2000, Math.floor(radius / 6)));
+    cityForm.elements.namedItem("cityRadius").value = String(Math.round(radius));
+    cityForm.elements.namedItem("cityBlockSize").value = String(blockSize);
+    cityForm.elements.namedItem("cityRoadWidth").value = String(Math.max(3, Math.min(40, blockSize * .18)));
+    syncCitySize();
+    for (const [name, value] of Object.entries({ residential: 50, commercial: 20, industrial: 10, civic: 10, park: 10 })) {
+      cityForm.elements.namedItem(`cityUse_${name}`).value = String(value);
+    }
+    const appliedTemplate = populateCityTemplateOptions();
+    if (appliedTemplate) {
+      cityTemplate.value = appliedTemplate.value;
+      applyCityParameters(appliedTemplate.parameters);
+    } else {
+      const defaultTemplate = cityTemplates.find((template) => template.id === state.cityTemplateDefaultId);
+      if (defaultTemplate) { cityTemplate.value = defaultTemplate.id; applyCityParameters(defaultTemplate.parameters); }
+    }
+    cityDialogStatus.textContent = `坐标 ${Math.round(x).toLocaleString()}, ${Math.round(y).toLocaleString()} m`;
+    cityDialogStatus.dataset.state = "ready";
+    cityDialog.hidden = false;
+    if (typeof cityDialog.show === "function") cityDialog.show(); else cityDialog.setAttribute("open", "");
+    draw();
+    cityName.focus(); cityName.select();
+  }
+
+  async function createCityFromDialog(event) {
+    event.preventDefault();
+    if (state.creatingCity || !state.cityPoint || !state.snapshot || !state.previewGeneration || !state.cityModule) return;
+    if (state.cityPoint.cityId) {
+      state.cityPoint.phase = "roads";
+      state.cityPoint.error = null;
+      cityDialogStatus.dataset.state = "loading";
+      cityDialogStatus.textContent = "正在重新生成地形路网…";
+      submitCity.disabled = true;
+      state.roadAutoPreviewEnabled = true;
+      generateRoadPreview();
+      draw();
+      return;
+    }
+    const expectedProject = state.snapshot.projectId;
+    const expectedRevision = state.snapshot.revision;
+    const expectedEpoch = state.epoch;
+    const point = state.cityPoint;
+    try {
+      const draft = draftGeneration();
+      if (state.busy || state.saving || state.loading || !draft || !state.savedGeneration
+        || !sameGeneration(state.savedGeneration, state.previewGeneration) || !sameGeneration(draft, state.previewGeneration)) {
+        throw new Error("地图生成参数已变化，请先重新生成并保存。");
+      }
+      const label = cityName.value.trim();
+      const radiusMeters = numberFromForm(cityForm, "cityRadius");
+      const blockSizeMeters = numberFromForm(cityForm, "cityBlockSize");
+      const landUseWeights = Object.fromEntries(["residential", "commercial", "industrial", "civic", "park"].map((name) => [name, numberFromForm(cityForm, `cityUse_${name}`)]));
+      const roadWidthMeters = numberFromForm(cityForm, "cityRoadWidth");
+      const id = stableCityId(label, point.x, point.y);
+      const city = {
+        id, label, x: point.x, y: point.y,
+        seed: stableCitySeed(id, point.x, point.y),
+        parameters: { radiusMeters, blockSizeMeters, roadWidthMeters, landUseWeights },
+      };
+      const currentWorld = state.cityWorld ?? {
+        profile: state.cityModule.PROCEDURAL_WORLD_PROFILE,
+        identity: state.cityModule.PROCEDURAL_GENERATOR_IDENTITY,
+        worldSeed: state.previewGeneration.seed,
+        cities: [],
+      };
+      const validatedWorld = state.cityModule.validateProceduralWorld(
+        { ...currentWorld, cities: [...currentWorld.cities, city] },
+        { widthMeters: state.previewGeneration.widthMeters, heightMeters: state.previewGeneration.heightMeters },
+      );
+      const validatedCity = validatedWorld.cities.at(-1);
+      state.creatingCity = true; state.cityPoint.phase = "creating"; submitCity.disabled = true; cancelCity.disabled = true;
+      cityDialogStatus.dataset.state = "loading"; cityDialogStatus.textContent = "正在生成城市…"; draw();
+      const response = await options.createCity(validatedCity, expectedRevision);
+      if (!state.open || state.epoch !== expectedEpoch || state.snapshot?.projectId !== expectedProject || state.snapshot?.revision !== expectedRevision) {
+        closeCityDialog(); return;
+      }
+      const validated = validateSnapshot(response);
+      if (validated.value.projectId !== expectedProject || validated.value.revision <= expectedRevision) throw new Error("城市创建读回 revision 无效");
+      state.snapshot = validated.value;
+      state.savedGeneration = validated.savedGeneration;
+      state.savedRoadGeneration = validated.savedRoadGeneration;
+      updateActorBinding(validated.value);
+      if (!await loadCities(validated.value, state.previewGeneration, () => state.open && state.epoch === expectedEpoch
+        && state.snapshot?.projectId === expectedProject && state.snapshot?.revision === validated.value.revision)) return;
+      state.roadAutoPreviewEnabled = true;
+      state.cityPoint = { ...point, phase: "roads", cityId: validatedCity.id, error: null };
+      cityDialogStatus.dataset.state = "loading";
+      cityDialogStatus.textContent = "城市已保存，正在生成地形路网…";
+      submitCity.textContent = "重试生成路网";
+      cancelCity.textContent = "关闭";
+      scheduleRoadPreview();
+      draw(); updateStatus();
+    } catch (error) {
+      if (state.open && state.epoch === expectedEpoch && state.snapshot?.projectId === expectedProject) {
+        state.cityPoint = { ...point, phase: "error", cityId: null, error: errorText(error) };
+        cityDialogStatus.dataset.state = "error"; cityDialogStatus.textContent = errorText(error); submitCity.textContent = "重试生成城市"; notify(errorText(error), true); draw();
+      }
+    } finally {
+      state.creatingCity = false; submitCity.disabled = false; cancelCity.disabled = false;
+    }
+  }
+
+  function canvasSize() {
+    const rect = canvas.getBoundingClientRect();
+    return { width: Math.max(320, Math.round(rect.width || stage.clientWidth || 800)), height: Math.max(320, Math.round(rect.height || stage.clientHeight || 560)) };
+  }
+
+  function draw() {
+    const context = canvas.getContext("2d", { alpha: false });
+    if (!context) return;
+    const size = canvasSize();
+    const ratio = pixelRatio();
+    if (canvas.width !== Math.round(size.width * ratio) || canvas.height !== Math.round(size.height * ratio)) {
+      canvas.width = Math.round(size.width * ratio); canvas.height = Math.round(size.height * ratio);
+    }
+    context.setTransform(ratio, 0, 0, ratio, 0, 0);
+    context.fillStyle = "#161516";
+    context.fillRect(0, 0, size.width, size.height);
+    if (!state.baseCanvas) return;
+    context.save();
+    context.translate(state.view.x, state.view.y);
+    context.scale(state.view.scale, state.view.scale);
+    context.imageSmoothingEnabled = true;
+    context.drawImage(state.baseCanvas, 0, 0);
+    const terrainContours = visibleContourPlan();
+    drawBaseTerrainContours(context, terrainContours);
+    const shorelines = [];
+    const reducedMotion = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+    const now = performance.now();
+    for (const tile of state.visibleTiles) {
+      const exact = cachedTileOrParent(tile);
+      if (!exact) continue;
+      if (exact.ancestor.level !== tile.level) {
+        drawTileRaster(context, tile, exact);
+        continue;
+      }
+      const alpha = reducedMotion ? 1 : Math.max(0, Math.min(1, (now - exact.cached.loadedAt) / LOD_CROSSFADE_MS));
+      if (alpha < 1) {
+        const parent = cachedTileOrParent(tile, true);
+        if (parent) drawTileRaster(context, tile, parent);
+        scheduleFadeFrame();
+      }
+      drawTileRaster(context, tile, exact, alpha);
+      shorelines.push({ tile, cached: exact.cached, alpha });
+    }
+    for (const shoreline of shorelines) {
+      drawTileShoreline(context, shoreline.tile, shoreline.cached, shoreline.alpha);
+      drawTileTerrainContours(context, shoreline.tile, shoreline.cached, terrainContours, shoreline.alpha);
+    }
+    drawRoads(context);
+    drawCities(context);
+    drawCityDraft(context);
+    if (layerEnabled("showObjects")) {
+      context.font = `${11 / state.view.scale}px ui-sans-serif, sans-serif`;
+      context.textBaseline = "middle";
+      for (const marker of state.markers) {
+        const x = marker.x * state.baseCanvas.width;
+        const y = marker.y * state.baseCanvas.height;
+        const radius = 4 / state.view.scale;
+        context.beginPath(); context.arc(x, y, radius, 0, Math.PI * 2); context.fillStyle = "#f2f2f2"; context.fill();
+        context.beginPath(); context.arc(x, y, radius * 0.5, 0, Math.PI * 2); context.fillStyle = "#32d551"; context.fill();
+        context.fillStyle = "#f2f2f2"; context.fillText(marker.id, x + radius * 1.8, y);
+      }
+    }
+    context.restore();
+  }
+
+  function fitMap() {
+    if (!state.baseCanvas) return;
+    const size = canvasSize();
+    state.view.scale = Math.min(size.width / state.baseCanvas.width, size.height / state.baseCanvas.height) * 0.92;
+    state.view.x = (size.width - state.baseCanvas.width * state.view.scale) / 2;
+    state.view.y = (size.height - state.baseCanvas.height * state.view.scale) / 2;
+    state.fitted = true;
+    refreshDetailPlan(true);
+    draw();
+  }
+
+  function zoom(factor, centerX, centerY) {
+    if (!state.baseCanvas) return;
+    const size = canvasSize();
+    const x = centerX ?? size.width / 2;
+    const y = centerY ?? size.height / 2;
+    const metersPerBasePixel = Math.sqrt(
+      state.previewGeneration.widthMeters / state.baseCanvas.width * state.previewGeneration.heightMeters / state.baseCanvas.height,
+    );
+    const finestMetersPerTexel = Math.max(state.previewGeneration.widthMeters, state.previewGeneration.heightMeters) / (2 ** LOD_MAX_LEVEL * (LOD_TILE_SIZE - 1));
+    const maxScale = metersPerBasePixel / Math.max(0.25, finestMetersPerTexel);
+    const next = Math.max(0.25, Math.min(maxScale, state.view.scale * factor));
+    const worldX = (x - state.view.x) / state.view.scale;
+    const worldY = (y - state.view.y) / state.view.scale;
+    state.view.scale = next;
+    state.view.x = x - worldX * next;
+    state.view.y = y - worldY * next;
+    state.fitted = false;
+    refreshDetailPlan();
+    draw();
+  }
+
+  function focusObject(spatialId) {
+    if (!state.open || !state.result || !state.baseCanvas || !state.previewGeneration || typeof spatialId !== "string" || !spatialId) return false;
+    const viewport = canvasSize();
+    const marker = state.markers.find((entry) => entry.id === spatialId);
+    const city = state.cities.find((entry) => entry.id === spatialId);
+    if (!marker && !city) return false;
+    let mapX;
+    let mapY;
+    if (city) {
+      mapX = city.x / state.previewGeneration.widthMeters * state.baseCanvas.width;
+      mapY = city.y / state.previewGeneration.heightMeters * state.baseCanvas.height;
+      const radiusInMapPixels = city.parameters.radiusMeters * Math.sqrt(
+        state.baseCanvas.width / state.previewGeneration.widthMeters * state.baseCanvas.height / state.previewGeneration.heightMeters,
+      );
+      const roadThreshold = Number(roadThresholdInput.value) || 80;
+      state.view.scale = Math.max(state.view.scale, roadThreshold / Math.max(0.000001, radiusInMapPixels));
+    } else {
+      mapX = marker.x * state.baseCanvas.width;
+      mapY = marker.y * state.baseCanvas.height;
+    }
+    state.view.x = viewport.width / 2 - mapX * state.view.scale;
+    state.view.y = viewport.height / 2 - mapY * state.view.scale;
+    state.fitted = false;
+    refreshDetailPlan();
+    draw();
+    return true;
+  }
+
+  function updateStats(rendered, result, generation) {
+    statNodes.size.textContent = `${(generation.widthMeters / 1000).toLocaleString()} × ${(generation.heightMeters / 1000).toLocaleString()} km`;
+    statNodes.grid.textContent = `${result.width} × ${result.height}`;
+    statNodes.water.textContent = formatPercent(rendered.waterCells / result.elevations.length);
+    statNodes.relief.textContent = `${rendered.minimum.toFixed(2)} — ${rendered.maximum.toFixed(2)}`;
+    statNodes.rivers.textContent = `${rendered.riverCells.toLocaleString()} 格`;
+    statNodes.objects.textContent = `${state.markers.length.toLocaleString()} 个`;
+  }
+
+  function acceptResult(result, generation) {
+    const generationChanged = state.previewGeneration && !sameGeneration(state.previewGeneration, generation);
+    if (generationChanged) {
+      clearTileRuntime(true);
+      terminateRoadWorker();
+      state.roadResult = null;
+      state.previewRoadGeneration = null;
+    }
+    const firstPreview = !state.baseCanvas;
+    const previousGeneration = state.previewGeneration;
+    const previousWidth = state.baseCanvas?.width ?? result.width;
+    const previousHeight = state.baseCanvas?.height ?? result.height;
+    const viewport = canvasSize();
+    const centerX = (viewport.width / 2 - state.view.x) / state.view.scale / previousWidth;
+    const centerY = (viewport.height / 2 - state.view.y) / state.view.scale / previousHeight;
+    const rendered = buildBaseMap(result, generation);
+    state.result = result;
+    state.previewGeneration = generation;
+    state.baseCanvas = rendered.canvas;
+    state.baseRenderStats = rendered;
+    state.requestedGeneration = null;
+    state.markers = objectMarkers(state.snapshot?.source?.objects, generation);
+    updateActorBinding(state.snapshot);
+    updateStats(rendered, result, generation);
+    state.errorKind = null;
+    setOverlay("");
+    if (firstPreview) fitMap();
+    else {
+      let nextCenterX = centerX;
+      let nextCenterY = centerY;
+      if (previousGeneration) {
+        nextCenterX = Math.max(0, Math.min(1, centerX * previousGeneration.widthMeters / generation.widthMeters));
+        nextCenterY = Math.max(0, Math.min(1, centerY * previousGeneration.heightMeters / generation.heightMeters));
+        const scaleX = state.view.scale * previousWidth / previousGeneration.widthMeters * generation.widthMeters / result.width;
+        const scaleY = state.view.scale * previousHeight / previousGeneration.heightMeters * generation.heightMeters / result.height;
+        const metersPerBasePixel = Math.sqrt(generation.widthMeters / result.width * generation.heightMeters / result.height);
+        state.view.scale = Math.max(0.01, Math.min(metersPerBasePixel / 0.25, Math.sqrt(scaleX * scaleY)));
+      }
+      state.view.x = viewport.width / 2 - nextCenterX * result.width * state.view.scale;
+      state.view.y = viewport.height / 2 - nextCenterY * result.height * state.view.scale;
+      state.fitted = false;
+      refreshDetailPlan(true);
+      draw();
+    }
+    if (state.roadAutoPreviewEnabled) scheduleRoadPreview();
+    updateStatus();
+  }
+
+  function staleGeneration(message) {
+    terminateWorker();
+    state.result = null;
+    state.previewGeneration = null;
+    state.requestedGeneration = null;
+    state.errorKind = "generate";
+    setOverlay(message, true, "重新读取", () => { void open(); });
+    status.textContent = "项目已变化 · 预览已丢弃";
+    notify(message, true);
+    updateStatus();
+  }
+
+  function generate(generation) {
+    if (!state.snapshot || state.loading || state.errorKind === "read") return;
+    clearPreviewTimer();
+    terminateWorker();
+    clearTileRuntime(false);
+    state.errorKind = null;
+    state.busy = true;
+    state.requestedGeneration = generation;
+    const id = ++state.requestId;
+    const gate = { id, epoch: state.epoch, projectId: state.snapshot.projectId, revision: state.snapshot.revision };
+    const worker = new Worker(new URL("./world-map-worker.js", import.meta.url), { type: "module", name: "world-map-generator" });
+    gate.worker = worker;
+    state.worker = worker;
+    worker.addEventListener("message", async (event) => {
+      if (event.data?.id !== id || !currentGate(gate)) return;
+      if (event.data?.error) {
+        terminateWorker();
+        state.errorKind = "generate";
+        const message = String(event.data.error);
+        setOverlay(message, true, "重试生成", generateFromCurrentForm);
+        notify(message, true); updateStatus(); return;
+      }
+      try {
+        const result = validateResult(event.data?.result, generation);
+        const latest = validateSnapshot(await options.read()).value;
+        if (!currentGate(gate)) return;
+        if (latest.projectId !== gate.projectId || latest.revision !== gate.revision) {
+          staleGeneration("项目在生成期间已变化，旧预览已丢弃，请重新打开地图。");
+          return;
+        }
+        terminateWorker();
+        acceptResult(result, generation);
+      } catch (error) {
+        if (!currentGate(gate)) return;
+        terminateWorker();
+        state.errorKind = "generate";
+        setOverlay(errorText(error), true, "重试生成", generateFromCurrentForm);
+        notify(errorText(error), true); updateStatus();
+      }
+    });
+    worker.addEventListener("error", (event) => {
+      if (!currentGate(gate)) return;
+      const message = event.message || "地图生成 Worker 失败";
+      terminateWorker();
+      state.errorKind = "generate";
+      setOverlay(message, true, "重试生成", generateFromCurrentForm);
+      notify(message, true); updateStatus();
+    });
+    setOverlay("正在运行 WASM 水文生成器…");
+    updateStatus();
+    worker.postMessage({ id, settings: generation });
+  }
+
+  function generateFromCurrentForm() {
+    state.autoPreviewEnabled = true;
+    const generation = draftGeneration();
+    if (generation) generate(generation);
+    else updateStatus();
+  }
+
+  function schedulePreview() {
+    updateStatus();
+    if (!state.autoPreviewEnabled || !state.open || state.loading || state.saving || state.errorKind === "read") return;
+    const generation = draftGeneration();
+    if (!generation) {
+      clearPreviewTimer();
+      terminateWorker();
+      state.requestedGeneration = null;
+      updateStatus();
+      return;
+    }
+    terminateWorker();
+    state.requestedGeneration = null;
+    clearPreviewTimer();
+    updateStatus();
+    const gate = { epoch: state.epoch, projectId: state.snapshot?.projectId, revision: state.snapshot?.revision };
+    state.previewTimer = setTimeout(() => {
+      state.previewTimer = null;
+      if (!state.open || state.epoch !== gate.epoch || state.snapshot?.projectId !== gate.projectId || state.snapshot?.revision !== gate.revision) return;
+      const latest = draftGeneration();
+      if (latest && sameGeneration(latest, generation)) generate(latest);
+    }, 180);
+  }
+
+  function generateRoadPreview(roadGeneration = draftRoadGeneration()) {
+    if (!state.open || !state.snapshot || !state.previewGeneration || !roadGeneration || state.loading || state.saving) return;
+    clearRoadPreviewTimer();
+    terminateRoadWorker();
+    const generation = state.previewGeneration;
+    const cities = [...state.cities];
+    const key = roadPreviewKey(generation, roadGeneration, cities);
+    state.roadError = null;
+    state.roadBusy = true;
+    state.roadRequestedKey = key;
+    const id = ++state.roadRequestId;
+    const gate = { id, epoch: state.epoch, projectId: state.snapshot.projectId, revision: state.snapshot.revision, key };
+    const worker = new Worker(new URL("./world-map-worker.js", import.meta.url), { type: "module", name: "world-map-road-generator" });
+    gate.worker = worker;
+    state.roadWorker = worker;
+    worker.addEventListener("message", async (event) => {
+      if (event.data?.id !== id || event.data?.kind !== "roads" || !currentRoadGate(gate)) return;
+      if (event.data?.error) {
+        terminateRoadWorker();
+        state.roadError = String(event.data.error);
+        markCityRoadPreviewError(state.roadError);
+        notify(state.roadError, true); updateStatus(); draw(); return;
+      }
+      try {
+        const result = validateTerrainRoadResult(event.data?.result, state.cities.map((city) => city.id));
+        const latest = validateSnapshot(await options.read()).value;
+        if (!currentRoadGate(gate)) return;
+        if (latest.projectId !== gate.projectId || latest.revision !== gate.revision) {
+          terminateRoadWorker(); state.roadResult = null; state.roadError = "项目已变化，旧道路预览已丢弃。"; updateStatus(); draw(); return;
+        }
+        terminateRoadWorker();
+        state.roadResult = result;
+        state.previewRoadGeneration = roadGeneration;
+        try {
+          cacheRoadParcels(result, roadGeneration);
+          state.roadParcelError = null;
+        } catch (error) {
+          state.roadParcelLayouts.clear();
+          state.roadParcelError = errorText(error);
+          notify(`地块生成失败，请调整参数/重试：${state.roadParcelError}`, true);
+        }
+        state.roadError = null;
+        completeCityRoadPreview(result);
+        updateStatus(); draw();
+      } catch (error) {
+        if (!currentRoadGate(gate)) return;
+        terminateRoadWorker(); state.roadError = errorText(error); markCityRoadPreviewError(error); notify(state.roadError, true); updateStatus(); draw();
+      }
+    });
+    worker.addEventListener("error", (event) => {
+      if (!currentRoadGate(gate)) return;
+      terminateRoadWorker(); state.roadError = event.message || "道路生成 Worker 失败"; markCityRoadPreviewError(state.roadError); notify(state.roadError, true); updateStatus(); draw();
+    });
+    updateStatus();
+    worker.postMessage({ id, epoch: gate.epoch, kind: "roads", settings: generation, roadGeneration, cities });
+  }
+
+  function scheduleRoadPreview() {
+    updateStatus();
+    if (!state.roadAutoPreviewEnabled || !state.open || !state.previewGeneration || state.loading || state.saving || state.roadSaving) return;
+    const roadGeneration = draftRoadGeneration();
+    if (!roadGeneration) { clearRoadPreviewTimer(); terminateRoadWorker(); return; }
+    terminateRoadWorker();
+    clearRoadPreviewTimer();
+    const key = roadPreviewKey(state.previewGeneration, roadGeneration, state.cities);
+    state.roadPreviewTimer = setTimeout(() => {
+      state.roadPreviewTimer = null;
+      if (!state.open || !state.previewGeneration || state.roadRequestedKey === key && state.roadResult) return;
+      const latest = draftRoadGeneration();
+      if (latest && roadPreviewKey(state.previewGeneration, latest, state.cities) === key) generateRoadPreview(latest);
+    }, ROAD_PREVIEW_DEBOUNCE_MS);
+  }
+
+  async function saveRoadPreview() {
+    if (typeof options.saveRoadGeneration !== "function" || state.roadSaving || state.roadBusy || !state.snapshot || !state.previewGeneration || !state.roadResult) return;
+    const roadGeneration = draftRoadGeneration();
+    if (!roadGeneration || !state.previewRoadGeneration || !sameRoadGeneration(roadGeneration, state.previewRoadGeneration)) { notify("道路参数已变化，请先完成新的预览。", true); return; }
+    const replacing = Boolean(state.savedRoadGeneration && !sameRoadGeneration(state.savedRoadGeneration, roadGeneration));
+    if (replacing && !window.confirm("保存会替换当前道路生成参数；确定继续吗？")) return;
+    const expectedProject = state.snapshot.projectId;
+    const expectedRevision = state.snapshot.revision;
+    const expectedEpoch = state.epoch;
+    const token = ++state.roadSaveToken;
+    state.roadSaving = true; updateStatus();
+    try {
+      // 点击“保存道路参数”本身即为首次保存的明确确认；替换已有参数另给一次确认框。
+      const response = await options.saveRoadGeneration(roadGeneration, expectedRevision, true);
+      const validated = validateSnapshot(response);
+      if (validated.value.projectId !== expectedProject || validated.value.revision <= expectedRevision || !validated.savedRoadGeneration
+        || !sameRoadGeneration(validated.savedRoadGeneration, roadGeneration)) throw new Error("道路参数保存读回无效");
+      if (state.open && state.epoch === expectedEpoch && state.snapshot?.projectId === expectedProject && state.snapshot?.revision === expectedRevision) {
+        state.snapshot = validated.value;
+        state.savedGeneration = validated.savedGeneration;
+        state.savedRoadGeneration = validated.savedRoadGeneration;
+        state.markers = objectMarkers(validated.value.source?.objects, state.previewGeneration);
+        await loadCities(validated.value, state.previewGeneration, () => state.open && state.epoch === expectedEpoch
+          && state.snapshot?.projectId === expectedProject && state.snapshot?.revision === validated.value.revision);
+        notify("道路参数已保存；派生路网保持本地缓存。", false);
+      }
+    } catch (error) {
+      if (state.open && state.epoch === expectedEpoch && state.snapshot?.projectId === expectedProject) { state.roadError = errorText(error); notify(state.roadError, true); }
+    } finally {
+      if (state.roadSaveToken === token) state.roadSaving = false;
+      if (state.open && state.epoch === expectedEpoch) { updateStatus(); draw(); }
+    }
+  }
+
+  async function open() {
+    if (state.destroyed) throw new Error("世界地图已销毁");
+    const epoch = ++state.epoch;
+    const previousSnapshot = state.snapshot;
+    const interruptedGeneration = state.requestedGeneration;
+    state.open = true;
+    shell.hidden = false;
+    terminateWorker();
+    clearTileRuntime(false);
+    clearPreviewTimer();
+    state.loading = true;
+    state.saving = false;
+    state.saveToken += 1;
+    state.errorKind = null;
+    setOverlay("正在读取地图…");
+    status.textContent = "正在读取项目地图…";
+    updateStatus();
+    try {
+      const validated = validateSnapshot(await options.read());
+      if (!state.open || state.epoch !== epoch) return;
+      const sameIdentity = previousSnapshot?.projectId === validated.value.projectId && previousSnapshot?.revision === validated.value.revision;
+      state.snapshot = validated.value;
+      state.savedGeneration = validated.savedGeneration;
+      state.savedRoadGeneration = validated.savedRoadGeneration;
+      updateActorBinding(validated.value);
+      state.autoPreviewEnabled = sameIdentity ? state.autoPreviewEnabled || Boolean(validated.savedGeneration) || Boolean(state.result) : Boolean(validated.savedGeneration);
+      state.loading = false;
+      state.errorKind = null;
+      if (sameIdentity && state.result && state.previewGeneration) {
+        state.markers = objectMarkers(validated.value.source?.objects, state.previewGeneration);
+        if (!await loadCities(validated.value, state.previewGeneration, () => state.open && state.epoch === epoch
+          && state.snapshot?.projectId === validated.value.projectId && state.snapshot?.revision === validated.value.revision)) return;
+        if (state.roadAutoPreviewEnabled) scheduleRoadPreview();
+        setOverlay(""); draw(); updateStatus();
+        const draft = draftGeneration();
+        if (state.autoPreviewEnabled && draft && !sameGeneration(draft, state.previewGeneration)) schedulePreview();
+        return;
+      }
+      if (sameIdentity && interruptedGeneration && state.autoPreviewEnabled) {
+        generate(draftGeneration() ?? interruptedGeneration);
+        return;
+      }
+      if (previousSnapshot && !sameIdentity) notify("项目或 revision 已变化，先前地图草稿已丢弃。", true);
+      const retainedDraft = sameIdentity ? draftGeneration() : null;
+      const generation = retainedDraft ?? initialGeneration(validated.value, validated.savedGeneration);
+      if (!retainedDraft) setFormGeneration(form, generation);
+      // 打开旧图只保留其 identity，不把它替换成当前默认值；升级入口只切换内存草稿。
+      state.roadDraftIdentity = validated.savedRoadGeneration?.identity ?? ROAD_GENERATION_IDENTITY;
+      setFormRoadGeneration(roadForm, validated.savedRoadGeneration ?? DEFAULT_ROAD_GENERATION);
+      state.previewRoadGeneration = null;
+      state.roadResult = null;
+      state.roadError = null;
+      state.roadAutoPreviewEnabled = sameIdentity ? state.roadAutoPreviewEnabled || Boolean(validated.savedRoadGeneration) : Boolean(validated.savedRoadGeneration);
+      state.markers = objectMarkers(validated.value.source?.objects, generation);
+      if (!await loadCities(validated.value, generation, () => state.open && state.epoch === epoch
+        && state.snapshot?.projectId === validated.value.projectId && state.snapshot?.revision === validated.value.revision)) return;
+      // 已保存地形且已有城市时，首次进入默认生成本地未保存路网；不写 source。
+      if (validated.savedGeneration && state.cities.length > 0) state.roadAutoPreviewEnabled = true;
+      state.result = null;
+      state.previewGeneration = null;
+      state.baseCanvas = null;
+      state.baseRenderStats = null;
+      clearTileRuntime(true);
+      state.requestedGeneration = null;
+      if (validated.savedGeneration) {
+        settingsPanel.hidden = false;
+        settingsButton.setAttribute("aria-expanded", "true");
+        generate(generation);
+      } else {
+        settingsPanel.hidden = false;
+        settingsButton.setAttribute("aria-expanded", "true");
+        setOverlay("这张地图还没有地形。先在右侧设置范围与水文参数，再进入预览。", false, "下一步：生成预览", generateFromCurrentForm);
+        draw();
+        updateStatus();
+      }
+    } catch (error) {
+      if (!state.open || state.epoch !== epoch) return;
+      state.loading = false;
+      state.errorKind = "read";
+      setOverlay(errorText(error), true, "重新读取", () => { void open(); });
+      notify(errorText(error), true); updateStatus();
+    }
+  }
+
+  function close() {
+    if (state.destroyed) return;
+    state.open = false;
+    state.epoch += 1;
+    state.saveToken += 1;
+    state.saving = false;
+    state.loading = false;
+    clearPreviewTimer();
+    clearRoadPreviewTimer();
+    terminateWorker();
+    terminateRoadWorker();
+    clearTileRuntime(false);
+    if (!state.creatingCity) closeCityDialog();
+    state.drag = null;
+    shell.hidden = true;
+  }
+
+  function destroy() {
+    if (state.destroyed) return;
+    close();
+    state.destroyed = true;
+    resizeObserver?.disconnect();
+    root.replaceChildren();
+  }
+
+  async function savePreview() {
+    if (state.saving || state.busy || !state.result || !state.previewGeneration || !state.snapshot) return;
+    const currentDraft = draftGeneration();
+    if (!currentDraft || !sameGeneration(currentDraft, state.previewGeneration)) {
+      notify("设置已变化，请先重新生成预览。", true); updateStatus(); return;
+    }
+    const replacing = Boolean(state.savedGeneration && !sameGeneration(state.savedGeneration, currentDraft));
+    if (replacing && !window.confirm("保存会替换当前地图地形生成参数；已有世界对象会保留。确定继续吗？")) return;
+    const expectedProject = state.snapshot.projectId;
+    const expectedRevision = state.snapshot.revision;
+    const saveToken = ++state.saveToken;
+    const saveEpoch = state.epoch;
+    state.saving = true;
+    updateStatus();
+    try {
+      const validated = validateSnapshot(await options.save(currentDraft, expectedRevision, replacing));
+      if (validated.value.projectId !== expectedProject) throw new Error("保存读回属于另一个项目");
+      if (validated.value.revision <= expectedRevision) throw new Error("地图保存读回 revision 未前进");
+      if (!validated.savedGeneration || !sameGeneration(validated.savedGeneration, currentDraft)) throw new Error("地图保存读回与提交参数不一致");
+      if (state.open && state.epoch === saveEpoch && state.snapshot?.projectId === expectedProject && state.snapshot?.revision === expectedRevision) {
+        state.snapshot = validated.value;
+        state.savedGeneration = validated.savedGeneration;
+        state.savedRoadGeneration = validated.savedRoadGeneration;
+        state.markers = objectMarkers(validated.value.source?.objects, currentDraft);
+        updateActorBinding(validated.value);
+        if (!await loadCities(validated.value, currentDraft, () => state.open && state.epoch === saveEpoch
+          && state.snapshot?.projectId === validated.value.projectId && state.snapshot?.revision === validated.value.revision)) return;
+        if (state.roadAutoPreviewEnabled) scheduleRoadPreview();
+        state.errorKind = null;
+        setOverlay("");
+        notify("世界地图已保存。", false);
+      }
+    } catch (error) {
+      if (state.open && state.epoch === saveEpoch && state.snapshot?.projectId === expectedProject) {
+        state.errorKind = "save";
+        setOverlay(errorText(error), true, "重试保存", () => { void savePreview(); });
+        notify(errorText(error), true);
+      }
+    } finally {
+      if (state.saveToken === saveToken) state.saving = false;
+      if (state.open && state.epoch === saveEpoch) { draw(); updateStatus(); }
+    }
+  }
+
+  settingsButton.addEventListener("click", () => {
+    settingsPanel.hidden = !settingsPanel.hidden;
+    settingsButton.setAttribute("aria-expanded", String(!settingsPanel.hidden));
+    if (!settingsPanel.hidden) field(form, "seed").focus();
+  });
+  adjustButton.addEventListener("click", () => {
+    settingsPanel.hidden = false;
+    settingsButton.setAttribute("aria-expanded", "true");
+    field(form, "seed").focus();
+  });
+  generateButton.addEventListener("click", () => {
+    generateFromCurrentForm();
+  });
+  saveButton.addEventListener("click", savePreview);
+  form.addEventListener("input", schedulePreview);
+  form.addEventListener("change", schedulePreview);
+  previewRoadsButton.addEventListener("click", () => {
+    state.roadAutoPreviewEnabled = true;
+    generateRoadPreview();
+  });
+  previewRoadUpgradeButton.addEventListener("click", previewRoadGenerationUpgrade);
+  saveRoadsButton.addEventListener("click", () => { void saveRoadPreview(); });
+  roadForm.addEventListener("input", scheduleRoadPreview);
+  roadForm.addEventListener("change", scheduleRoadPreview);
+  layers.addEventListener("change", (event) => {
+    const terrainLayer = ["showRelief", "showRivers", "showLakes"].includes(event.target?.name);
+    if (terrainLayer && state.result && state.previewGeneration) {
+      try {
+        const rendered = buildBaseMap(state.result, state.previewGeneration);
+        state.baseCanvas = rendered.canvas;
+        state.baseRenderStats = rendered;
+        clearTileRuntime(true);
+        updateStats(rendered, state.result, state.previewGeneration);
+        refreshDetailPlan(true);
+        draw();
+      } catch (error) { notify(errorText(error), true); }
+    } else { updateStatus(); draw(); }
+  });
+  densitySelect.addEventListener("change", () => {
+    state.lodLevelInitialized = false;
+    clearTileRuntime(false);
+    refreshDetailPlan(true);
+    draw();
+  });
+  roadThresholdInput.addEventListener("change", () => { state.cityModes.clear(); draw(); });
+  parcelThresholdInput.addEventListener("change", () => { state.cityModes.clear(); draw(); });
+  actorSelect.addEventListener("change", () => {
+    saveActorButton.disabled = state.savingActor || !actorSelect.value || actorSelect.value === state.snapshot?.source?.topology?.controlledActorId;
+  });
+  saveActorButton.addEventListener("click", () => { void saveActorBinding(); });
+  canvas.addEventListener("contextmenu", (event) => {
+    if (typeof options.createCity !== "function") return;
+    event.preventDefault();
+    void openCityDialogAt(event.clientX, event.clientY).catch((error) => notify(errorText(error), true));
+  });
+  cityForm.addEventListener("submit", createCityFromDialog);
+  cityTemplate.addEventListener("change", () => {
+    if (state.cityPoint) state.cityPoint.cityTemplateTouched = true;
+    const applied = sourceCityTemplate();
+    if (applied?.value === cityTemplate.value) applyCityParameters(applied.parameters);
+    else applyCityTemplate(cityTemplate.value);
+  });
+  citySize.addEventListener("change", () => {
+    const preset = CITY_SIZE_PRESETS.find((candidate) => candidate.id === citySize.value);
+    if (!preset || !state.cityPoint) return;
+    cityForm.elements.namedItem("cityRadius").value = String(Math.min(state.cityPoint.maximumRadius, preset.radiusMeters));
+  });
+  cityForm.elements.namedItem("cityRadius").addEventListener("input", syncCitySize);
+  cityForm.elements.namedItem("cityBlockSize").addEventListener("input", () => {
+    const blockSize = Number(cityForm.elements.namedItem("cityBlockSize").value);
+    if (Number.isFinite(blockSize)) cityForm.elements.namedItem("cityRoadWidth").value = String(Math.max(3, Math.min(40, blockSize * .18)));
+  });
+  cancelCity.addEventListener("click", closeCityDialog);
+  cityDialog.addEventListener("cancel", (event) => { event.preventDefault(); if (!state.creatingCity) closeCityDialog(); });
+  zoomIn.addEventListener("click", () => zoom(1.3));
+  zoomOut.addEventListener("click", () => zoom(1 / 1.3));
+  fit.addEventListener("click", fitMap);
+  canvas.addEventListener("wheel", (event) => {
+    event.preventDefault();
+    const rect = canvas.getBoundingClientRect();
+    zoom(event.deltaY < 0 ? 1.15 : 1 / 1.15, event.clientX - rect.left, event.clientY - rect.top);
+  }, { passive: false });
+  canvas.addEventListener("pointerdown", (event) => {
+    if (!state.baseCanvas) return;
+    state.drag = { id: event.pointerId, x: event.clientX, y: event.clientY, originX: state.view.x, originY: state.view.y };
+    canvas.setPointerCapture?.(event.pointerId);
+    canvas.classList.add("is-panning");
+  });
+  canvas.addEventListener("pointermove", (event) => {
+    if (!state.drag || state.drag.id !== event.pointerId) return;
+    state.view.x = state.drag.originX + event.clientX - state.drag.x;
+    state.view.y = state.drag.originY + event.clientY - state.drag.y;
+    state.fitted = false;
+    refreshDetailPlan();
+    draw();
+  });
+  const endPan = (event) => {
+    if (!state.drag || state.drag.id !== event.pointerId) return;
+    canvas.releasePointerCapture?.(event.pointerId);
+    state.drag = null;
+    canvas.classList.remove("is-panning");
+  };
+  canvas.addEventListener("pointerup", endPan);
+  canvas.addEventListener("pointercancel", endPan);
+  canvas.addEventListener("keydown", (event) => {
+    const amount = event.shiftKey ? 48 : 20;
+    if (event.key === "+" || event.key === "=") zoom(1.2);
+    else if (event.key === "-") zoom(1 / 1.2);
+    else if (event.key === "0") fitMap();
+    else if (event.key === "ArrowLeft") state.view.x += amount;
+    else if (event.key === "ArrowRight") state.view.x -= amount;
+    else if (event.key === "ArrowUp") state.view.y += amount;
+    else if (event.key === "ArrowDown") state.view.y -= amount;
+    else return;
+    event.preventDefault(); refreshDetailPlan(); draw();
+  });
+  const resizeObserver = typeof ResizeObserver === "function" ? new ResizeObserver(() => { if (state.fitted) fitMap(); else { refreshDetailPlan(); draw(); } }) : null;
+  resizeObserver?.observe(stage);
+
+  return { open, close, destroy, focusObject, setCityTemplates };
+}