@jjlmoya/utils-tabletop 1.28.0 → 1.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-tabletop",
-    "version": "1.28.0",
+    "version": "1.30.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -4,6 +4,7 @@ import { dungeonMapGenerator } from '../tool/dungeon-map-generator/entry';
 import { encounterDifficultyCalculator } from '../tool/encounter-difficulty-calculator/entry';
 import { tokenStampStudio } from '../tool/token-stamp-studio/entry';
 import { musScoreboard } from '../tool/mus-scoreboard/entry';
+import { rpgSettlementExplorationMapGenerator } from '../tool/rpg-settlement-exploration-map-generator/entry';
 import type { CategoryLocaleContent, KnownLocale } from '../types';
 
 export const tabletopCategory = {
@@ -15,6 +16,7 @@ export const tabletopCategory = {
     encounterDifficultyCalculator,
     tokenStampStudio,
     musScoreboard,
+    rpgSettlementExplorationMapGenerator,
   ],
   i18n: {
     de: () => import('./i18n/de').then((m) => m.content),

package/src/entries.ts

@@ -20,6 +20,8 @@ export { scatterDirectionSelector } from './tool/scatter-direction-selector/entr
 export type { ScatterSelectorUI, ScatterSelectorLocaleContent } from './tool/scatter-direction-selector/entry';
 export { dungeonMapGenerator } from './tool/dungeon-map-generator/entry';
 export type { DungeonMapGeneratorUI, DungeonMapGeneratorLocaleContent } from './tool/dungeon-map-generator/entry';
+export { rpgSettlementExplorationMapGenerator } from './tool/rpg-settlement-exploration-map-generator/entry';
+export type { SettlementMapUI, SettlementMapLocaleContent } from './tool/rpg-settlement-exploration-map-generator/entry';
 export { tabletopCategory } from './category';
 
 import { diceRollerSimulator } from './tool/dice-roller-simulator/entry';
@@ -37,6 +39,7 @@ import { dungeonMapGenerator } from './tool/dungeon-map-generator/entry';
 import { encounterDifficultyCalculator } from './tool/encounter-difficulty-calculator/entry';
 import { tokenStampStudio } from './tool/token-stamp-studio/entry';
 import { musScoreboard } from './tool/mus-scoreboard/entry';
+import { rpgSettlementExplorationMapGenerator } from './tool/rpg-settlement-exploration-map-generator/entry';
 
 export const ALL_ENTRIES = [
   diceRollerSimulator,
@@ -54,5 +57,6 @@ export const ALL_ENTRIES = [
   encounterDifficultyCalculator,
   tokenStampStudio,
   musScoreboard,
+  rpgSettlementExplorationMapGenerator,
 ];
 

package/src/tests/locale_completeness.test.ts

@@ -10,11 +10,7 @@ describe('Locale Completeness Validation', () => {
           it('bibliography should be defined when faq items exist', async () => {
             const loader = tool.entry.i18n[locale as keyof typeof tool.entry.i18n];
             const content = (await loader?.()) as ToolLocaleContent;
-
-            expect(
-              content.bibliography,
-              `Tool "${tool.entry.id}" locale "${locale}" is missing bibliography`,
-            ).toBeDefined();
+            expect(content.bibliography, `Tool "${tool.entry.id}" locale "${locale}" is missing bibliography`).toBeDefined();
           });
         });
       });
@@ -22,9 +18,6 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(15);
+    expect(ALL_TOOLS.length).toBe(16);
   });
-
-
 });
-

package/src/tests/tool_validation.test.ts

@@ -5,10 +5,9 @@ import { tabletopCategory } from '../data';
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
     it('should have tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(15);
+      expect(ALL_TOOLS.length).toBe(16);
     });
 
-
     it('tabletopCategory should be defined', () => {
       expect(tabletopCategory).toBeDefined();
       expect(tabletopCategory.i18n).toBeDefined();

package/src/tool/mus-scoreboard/component.astro

@@ -2,19 +2,27 @@
 import './online-mus-scoreboard.css';
 import { musScoreboard } from './index';
 import type { KnownLocale } from '../../types';
+import type { MusScoreboardUI } from './ui';
 
 interface Props {
+  ui?: MusScoreboardUI;
   locale?: KnownLocale;
 }
 
-const { locale = 'en' } = Astro.props as Props;
-const loader = musScoreboard.i18n[locale] || musScoreboard.i18n.en;
-const content = await loader?.();
-if (!content) return null;
-const { ui } = content;
+const props = Astro.props as Props;
+let ui = props.ui;
+
+if (!ui) {
+  const locale = props.locale || 'en';
+  const loader = musScoreboard.i18n[locale] || musScoreboard.i18n.en;
+  const content = await loader?.();
+  ui = content?.ui;
+}
+
+if (!ui) return null;
 ---
 
-<div class="mus-scoreboard" data-mus-scoreboard>
+<div class="mus-scoreboard" data-mus-scoreboard data-ui={JSON.stringify(ui)}>
   <div class="mus-board-card">
     <section class="mus-onboarding" aria-labelledby="mus-how-to-use">
       <div class="mus-onboarding-mark" aria-hidden="true">
@@ -24,7 +32,7 @@ const { ui } = content;
         <span></span>
       </div>
       <div>
-        <p class="mus-kicker" id="mus-how-to-use">LIVE TABLE</p>
+        <p class="mus-kicker" id="mus-how-to-use">{ui.liveMatch}</p>
         <p class="mus-onboarding-copy">{ui.onboarding}</p>
       </div>
     </section>
@@ -32,7 +40,7 @@ const { ui } = content;
     <form class="mus-config" data-config-form>
       <div class="mus-config-heading">
         <div>
-          <p class="mus-kicker">SET THE TABLE</p>
+          <p class="mus-kicker">{ui.matchSettings}</p>
           <h2>{ui.matchSettings}</h2>
         </div>
         <span class="mus-rule-seal" aria-hidden="true">MUS</span>
@@ -160,10 +168,12 @@ const { ui } = content;
   </div>
 </div>
 
-<script type="application/json" data-mus-ui set:html={JSON.stringify(ui)}></script>
 <script>
   import { mountMusScoreboard } from './controller';
+
   const root = document.querySelector<HTMLElement>('[data-mus-scoreboard]');
-  const uiNode = document.querySelector<HTMLScriptElement>('[data-mus-ui]');
-  if (root && uiNode) mountMusScoreboard(root, JSON.parse(uiNode.textContent || '{}'));
+  if (root) {
+    const ui = JSON.parse(root.dataset.ui || '{}');
+    mountMusScoreboard(root, ui);
+  }
 </script>

package/src/tool/rpg-settlement-exploration-map-generator/.keep

@@ -0,0 +1 @@
+keep

package/src/tool/rpg-settlement-exploration-map-generator/bibliography.astro

@@ -0,0 +1,11 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { rpgSettlementExplorationMapGenerator } from './index';
+import type { KnownLocale } from '../../types';
+interface Props { locale?: KnownLocale; }
+const { locale = 'en' } = Astro.props as Props;
+const loader = rpgSettlementExplorationMapGenerator.i18n[locale] || rpgSettlementExplorationMapGenerator.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+{content && <SharedBibliography links={content.bibliography} />}

package/src/tool/rpg-settlement-exploration-map-generator/bibliography.ts

@@ -0,0 +1,7 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  { name: 'Hendrikx et al., Procedural Content Generation for Games: A Survey', url: 'https://doi.org/10.1145/2422956.2422957' },
+  { name: 'Smelik et al., A Survey on Procedural Modelling for Virtual Worlds', url: 'https://doi.org/10.1111/cgf.12276' },
+  { name: 'Guzdial et al., Tabletop Roleplaying Games as Procedural Content Generators', url: 'https://doi.org/10.1145/3402942.3409605' },
+];

package/src/tool/rpg-settlement-exploration-map-generator/component.astro

@@ -0,0 +1,66 @@
+---
+import { buildMapSvg } from './dom-views';
+import { evaluateSettlement } from './evaluator';
+import { DEFAULT_CONFIG, generateSettlement } from './logic';
+import type { SettlementMapUI } from './ui';
+import './rpg-settlement-exploration-map-generator.css';
+interface Props { ui: SettlementMapUI; }
+const { ui } = Astro.props;
+const initialMap = generateSettlement(DEFAULT_CONFIG);
+const initialEvaluation = evaluateSettlement(initialMap, ui);
+const builtInServices = ['tavern', 'smithy', 'temple', 'market', 'stable', 'hall'] as const;
+---
+<div class="rsm" data-settlement-tool>
+  <script is:inline type="application/json" data-ui set:html={JSON.stringify(ui)} />
+  <section class="rsm-studio" aria-label={ui.mapRegionLabel}>
+    <div class="rsm-controls">
+      <div class="rsm-intro">{ui.intro}</div>
+      <div class="rsm-separator"></div>
+      <div class="rsm-field">
+        <label for="rsm-seed">{ui.seedLabel}</label>
+        <div class="rsm-seed-row"><input id="rsm-seed" name="seed" type="text" value={DEFAULT_CONFIG.seed} maxlength="48" spellcheck="false" /><button type="button" class="rsm-icon-button" data-random-seed aria-label={ui.randomSeed}>New</button></div>
+        <small>{ui.seedHint}</small>
+      </div>
+      <div class="rsm-field">
+        <span class="rsm-label">{ui.environmentLabel}</span>
+        <div class="rsm-choice-row" data-environments>{(['forest', 'plains', 'coast', 'river', 'mountain'] as const).map((environment) => <button type="button" class:list={{ 'rsm-choice': true, 'is-active': environment === DEFAULT_CONFIG.environment }} data-environment={environment} aria-pressed={environment === DEFAULT_CONFIG.environment}>{ui[environment]}</button>)}</div>
+      </div>
+      <div class="rsm-field">
+        <span class="rsm-label">{ui.styleLabel}</span>
+        <small>{ui.styleHint}</small>
+        <div class="rsm-choice-row" data-styles>{(['medieval', 'edo', 'sahelian', 'timber', 'stone', 'coastal', 'highland'] as const).map((style) => <button type="button" class:list={{ 'rsm-choice': true, 'is-active': style === DEFAULT_CONFIG.style }} data-style={style} aria-pressed={style === DEFAULT_CONFIG.style}>{ui[`style${style.charAt(0).toUpperCase()}${style.slice(1)}`]}</button>)}</div>
+      </div>
+      <div class="rsm-field">
+        <span class="rsm-label">{ui.sizeLabel}</span>
+        <div class="rsm-size-row" data-sizes>
+          <button type="button" class="rsm-size-button" data-size="hamlet" aria-pressed="false"><strong>{ui.hamlet}</strong><span>34 x 24</span><small>{ui.hamletHint}</small></button>
+          <button type="button" class="rsm-size-button is-active" data-size="village" aria-pressed="true"><strong>{ui.village}</strong><span>42 x 28</span><small>{ui.villageHint}</small></button>
+          <button type="button" class="rsm-size-button" data-size="town" aria-pressed="false"><strong>{ui.town}</strong><span>52 x 34</span><small>{ui.townHint}</small></button>
+        </div>
+      </div>
+      <div class="rsm-field rsm-home-field">
+        <label for="rsm-homes">{ui.homesLabel}<output data-homes-output>{DEFAULT_CONFIG.homes}</output></label>
+        <input id="rsm-homes" name="homes" type="range" min="3" max="42" value={DEFAULT_CONFIG.homes} data-homes />
+        <small>{ui.homesHint}</small>
+      </div>
+      <fieldset class="rsm-field rsm-services">
+        <legend>{ui.servicesLabel}</legend>
+        <small>{ui.serviceListHint}</small>
+        <div class="rsm-service-row" data-service-list>{builtInServices.map((service) => <div class="rsm-service-entry" data-service-entry={service}><label class="rsm-service-chip"><input type="checkbox" value={service} data-service-option checked={DEFAULT_CONFIG.services.includes(service)} /><span>{ui[`service${service.charAt(0).toUpperCase()}${service.slice(1)}`]}</span></label></div>)}</div>
+        <div class="rsm-add-service"><input id="rsm-new-service" type="text" data-new-service aria-label={ui.newServicePlaceholder} placeholder={ui.newServicePlaceholder} maxlength="28" /><button type="button" data-add-service>{ui.addService}</button></div>
+      </fieldset>
+      <button type="button" class="rsm-generate" data-generate>{ui.generate}</button>
+    </div>
+    <div class="rsm-map-column">
+      <div class="rsm-map-heading"><div><span class="rsm-eyebrow">{ui.mapSummary}</span><strong data-terrain>{initialEvaluation.terrainLabel}</strong></div><span class="rsm-badge" data-badge>{initialEvaluation.badge}</span></div>
+      <div class="rsm-map-frame"><div class="rsm-map-host" data-map-host set:html={buildMapSvg(initialMap, ui)}></div><div class="rsm-map-help">{ui.clickHint}</div><div class="rsm-context-menu" data-context-menu hidden role="menu" aria-label={ui.contextMenuLabel}><button type="button" data-context-tool="select" role="menuitem">{ui.contextInspect}</button><button type="button" data-context-tool="building" role="menuitem">{ui.contextBuilding}</button><button type="button" data-context-tool="path" role="menuitem">{ui.contextPath}</button><button type="button" data-context-tool="water" role="menuitem">{ui.contextWater}</button><button type="button" data-context-tool="tree" role="menuitem">{ui.contextTree}</button><button type="button" data-context-tool="erase" role="menuitem">{ui.contextErase}</button></div></div>
+      <div class="rsm-stats" aria-live="polite"><div><span>{ui.buildings}</span><strong data-building-count>{initialEvaluation.buildingCount}</strong></div><div><span>{ui.paths}</span><strong data-path-count>{initialEvaluation.pathCount}</strong></div><div><span>{ui.services}</span><strong data-service-count>{initialEvaluation.serviceCount}</strong></div><div><span>{ui.terrain}</span><strong data-water-count>{initialEvaluation.waterCount}</strong></div></div>
+      <div class="rsm-actions"><button type="button" class="rsm-action-primary" data-share>{ui.shareLink}</button><button type="button" data-export-png>{ui.exportPng}</button><button type="button" data-export-svg>{ui.exportSvg}</button><details class="rsm-data-menu"><summary>{ui.mapData}</summary><div><button type="button" data-export-json>{ui.exportJson}</button><label><span>{ui.importJson}</span><input type="file" accept="application/json,.json" data-import-json /></label></div></details></div>
+      <p class="rsm-status" data-status aria-live="polite"></p>
+    </div>
+  </section>
+</div>
+<script>
+  import { mountSettlementMap } from './controller';
+  mountSettlementMap();
+</script>

package/src/tool/rpg-settlement-exploration-map-generator/controller.ts

@@ -0,0 +1,231 @@
+import { addBuilding, addPath, addTree, addWater, DEFAULT_CONFIG, eraseAt, generateSettlement, homeRange, normalizeConfig, settlementPreset, type EditTool, type ServiceType, type SettlementConfig, type SettlementMap, type SettlementSize } from './logic';
+import { buildMapSvg, downloadFile, svgToDataUrl, updateMapHost } from './dom-views';
+import { bindContextEditor } from './editor';
+import { evaluateSettlement } from './evaluator';
+import { configFromMap, decodeShareState, encodeShareState, isSettlementMap, loadSettlement, saveSettlement, type SettlementState } from './storage';
+import type { SettlementMapUI } from './ui';
+
+const BUILT_IN_SERVICES = ['tavern', 'smithy', 'temple', 'market', 'stable', 'hall'];
+const NAME_FIRST = ['Willow', 'Red', 'Cedar', 'Briar', 'Ash', 'Silver', 'Moss', 'Oak', 'Raven', 'Fox', 'Amber', 'Thorn', 'Hollow', 'Maple', 'Stone', 'Meadow'];
+const NAME_SECOND = ['Mere', 'Brook', 'Crossing', 'Hollow', 'Watch', 'Glen', 'Ford', 'Heath', 'Cairn', 'Reach', 'Meadow', 'Vale', 'Ridge', 'Marsh', 'Gate', 'Dell'];
+
+function serviceLabel(service: ServiceType, ui: SettlementMapUI): string {
+  const labels: Record<string, string> = { tavern: ui.serviceTavern, smithy: ui.serviceSmithy, temple: ui.serviceTemple, market: ui.serviceMarket, stable: ui.serviceStable, hall: ui.serviceHall };
+  return labels[service] ?? service;
+}
+
+interface RuntimeState {
+  current: SettlementMap;
+  customServices: string[];
+  regenerationTimer?: number;
+}
+
+function queryMapFromUrl(): SettlementState | null {
+  const params = new URLSearchParams(window.location.search);
+  const value = params.get('settlement') ?? params.get('map');
+  return value ? decodeShareState(value) : null;
+}
+
+function randomName(): string {
+  const values = new Uint32Array(2);
+  crypto.getRandomValues(values);
+  return `${NAME_FIRST[values[0]! % NAME_FIRST.length]} ${NAME_SECOND[values[1]! % NAME_SECOND.length]}`;
+}
+
+function selectedServices(root: HTMLElement): ServiceType[] { return [...root.querySelectorAll<HTMLInputElement>('[data-service-option]:checked')].map((input) => input.value); }
+
+function activeData<T extends string>(root: HTMLElement, attr: string, fallback: T): T {
+  const element = root.querySelector<HTMLElement>(`[data-${attr}].is-active`);
+  return (element?.dataset[attr] as T | undefined) ?? fallback;
+}
+
+function readConfig(root: HTMLElement): SettlementConfig {
+  const seed = root.querySelector<HTMLInputElement>('[name="seed"]')?.value ?? DEFAULT_CONFIG.seed;
+  const environment = activeData(root, 'environment', DEFAULT_CONFIG.environment);
+  const size = activeData(root, 'size', DEFAULT_CONFIG.size);
+  const style = activeData(root, 'style', DEFAULT_CONFIG.style);
+  const homes = Number(root.querySelector<HTMLInputElement>('[data-homes]')?.value ?? DEFAULT_CONFIG.homes);
+  return normalizeConfig({ seed, environment, size, style, homes, services: selectedServices(root) });
+}
+
+function setPressed(root: HTMLElement, selector: string, value: string): void {
+  root.querySelectorAll<HTMLElement>(selector).forEach((element) => {
+    const active = element.dataset.environment === value || element.dataset.size === value || element.dataset.style === value || element.dataset.tool === value;
+    element.classList.toggle('is-active', active);
+    element.setAttribute('aria-pressed', String(active));
+  });
+}
+
+function findServiceEntry(root: HTMLElement, service: ServiceType): HTMLElement | null {
+  return [...root.querySelectorAll<HTMLElement>('[data-service-entry]')].find((entry) => entry.dataset.serviceEntry === service) ?? null;
+}
+
+interface ServiceOption {
+  service: ServiceType;
+  ui: SettlementMapUI;
+  checked: boolean;
+  onRemove: (service: ServiceType) => void;
+}
+
+function appendServiceOption(root: HTMLElement, option: ServiceOption): void {
+  const { service, ui, checked, onRemove } = option;
+  const list = root.querySelector<HTMLElement>('[data-service-list]');
+  if (!list || findServiceEntry(root, service)) return;
+  const entry = document.createElement('div');
+  entry.className = 'rsm-service-entry';
+  entry.dataset.serviceEntry = service;
+  const label = document.createElement('label');
+  label.className = 'rsm-service-chip';
+  const input = document.createElement('input');
+  input.type = 'checkbox';
+  input.value = service;
+  input.checked = checked;
+  input.dataset.serviceOption = '';
+  const text = document.createElement('span');
+  text.textContent = serviceLabel(service, ui);
+  label.append(input, text);
+  entry.append(label);
+  if (!BUILT_IN_SERVICES.includes(service)) {
+    const remove = document.createElement('button');
+    remove.type = 'button';
+    remove.className = 'rsm-remove-service';
+    remove.textContent = 'x';
+    remove.setAttribute('aria-label', `${ui.removeService}: ${serviceLabel(service, ui)}`);
+    remove.addEventListener('click', () => onRemove(service));
+    entry.append(remove);
+  }
+  list.append(entry);
+}
+
+function syncControls(root: HTMLElement, config: SettlementConfig, ui: SettlementMapUI, onRemove: (service: ServiceType) => void): void {
+  const seed = root.querySelector<HTMLInputElement>('[name="seed"]');
+  const homes = root.querySelector<HTMLInputElement>('[data-homes]');
+  const output = root.querySelector<HTMLOutputElement>('[data-homes-output]');
+  if (seed) seed.value = config.seed;
+  if (homes) { homes.min = String(homeRange(config.size).min); homes.max = String(homeRange(config.size).max); homes.value = String(config.homes); }
+  if (output) output.value = String(config.homes);
+  setPressed(root, '[data-environment]', config.environment);
+  setPressed(root, '[data-style]', config.style);
+  setPressed(root, '[data-size]', config.size);
+  config.services.forEach((service) => appendServiceOption(root, { service, ui, checked: true, onRemove }));
+  root.querySelectorAll<HTMLInputElement>('[data-service-option]').forEach((input) => { input.checked = config.services.includes(input.value); });
+}
+
+function updateSummary(root: HTMLElement, map: SettlementMap, ui: SettlementMapUI): void {
+  const evaluation = evaluateSettlement(map, ui);
+  root.querySelector('[data-terrain]')!.textContent = evaluation.terrainLabel;
+  root.querySelector('[data-badge]')!.textContent = evaluation.badge;
+  root.querySelector('[data-building-count]')!.textContent = String(evaluation.buildingCount);
+  root.querySelector('[data-path-count]')!.textContent = String(evaluation.pathCount);
+  root.querySelector('[data-service-count]')!.textContent = String(evaluation.serviceCount);
+  root.querySelector('[data-water-count]')!.textContent = String(evaluation.waterCount);
+}
+
+function setStatus(root: HTMLElement, message: string): void { root.querySelector('[data-status]')!.textContent = message; }
+function render(root: HTMLElement, map: SettlementMap, ui: SettlementMapUI, customServices: string[]): void { updateMapHost(root.querySelector<HTMLElement>('[data-map-host]')!, map, ui); updateSummary(root, map, ui); saveSettlement(map, customServices); }
+
+function applyEdit(map: SettlementMap, tool: EditTool, point: { x: number; y: number }): SettlementMap {
+  const actions: Partial<Record<EditTool, () => SettlementMap>> = {
+    building: () => addBuilding(map, point),
+    path: () => addPath(map, point),
+    water: () => addWater(map, point),
+    tree: () => addTree(map, point),
+    erase: () => eraseAt(map, point),
+  };
+  return actions[tool]?.() ?? map;
+}
+
+function regenerate(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  state.current = generateSettlement(readConfig(root));
+  syncControls(root, state.current.config, ui, (service) => removeCustomService(root, state, ui, service));
+  render(root, state.current, ui, state.customServices);
+}
+
+function scheduleRegenerate(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  if (state.regenerationTimer) window.clearTimeout(state.regenerationTimer);
+  state.regenerationTimer = window.setTimeout(() => { delete state.regenerationTimer; regenerate(root, state, ui); }, 180);
+}
+
+function applySizePreset(root: HTMLElement, size: SettlementSize): void {
+  const homes = root.querySelector<HTMLInputElement>('[data-homes]');
+  if (!homes) return;
+  const range = homeRange(size);
+  const preset = settlementPreset(size);
+  homes.min = String(range.min);
+  homes.max = String(range.max);
+  homes.value = String(Math.min(range.max, Math.max(range.min, preset.homes)));
+  root.querySelector<HTMLOutputElement>('[data-homes-output]')!.value = homes.value;
+  root.querySelectorAll<HTMLInputElement>('[data-service-option]').forEach((input) => {
+    if (BUILT_IN_SERVICES.includes(input.value)) input.checked = preset.services.includes(input.value);
+  });
+}
+
+function addCustomService(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  const input = root.querySelector<HTMLInputElement>('[data-new-service]');
+  const value = input?.value.trim();
+  if (!input || !value || [...root.querySelectorAll<HTMLInputElement>('[data-service-option]')].some((item) => item.value.toLocaleLowerCase() === value.toLocaleLowerCase())) return;
+  state.customServices.push(value);
+  appendServiceOption(root, { service: value, ui, checked: true, onRemove: (service) => removeCustomService(root, state, ui, service) });
+  findServiceEntry(root, value)?.querySelector<HTMLInputElement>('[data-service-option]')?.addEventListener('change', () => scheduleRegenerate(root, state, ui));
+  input.value = '';
+  saveSettlement(state.current, state.customServices);
+  scheduleRegenerate(root, state, ui);
+}
+
+function removeCustomService(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI, service: ServiceType): void {
+  if (BUILT_IN_SERVICES.includes(service)) return;
+  state.customServices = state.customServices.filter((item) => item !== service);
+  findServiceEntry(root, service)?.remove();
+  saveSettlement(state.current, state.customServices);
+  scheduleRegenerate(root, state, ui);
+}
+
+function attachChoiceEvents(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  root.querySelectorAll<HTMLElement>('[data-environment]').forEach((button) => button.addEventListener('click', () => { setPressed(root, '[data-environment]', button.dataset.environment ?? 'forest'); scheduleRegenerate(root, state, ui); }));
+  root.querySelectorAll<HTMLElement>('[data-style]').forEach((button) => button.addEventListener('click', () => { setPressed(root, '[data-style]', button.dataset.style ?? 'timber'); scheduleRegenerate(root, state, ui); }));
+  root.querySelectorAll<HTMLElement>('[data-size]').forEach((button) => button.addEventListener('click', () => { const size = button.dataset.size as SettlementSize ?? 'village'; setPressed(root, '[data-size]', size); applySizePreset(root, size); scheduleRegenerate(root, state, ui); }));
+  root.querySelector<HTMLInputElement>('[data-homes]')?.addEventListener('input', (event) => { root.querySelector<HTMLOutputElement>('[data-homes-output]')!.value = String((event.target as HTMLInputElement).value); scheduleRegenerate(root, state, ui); });
+  root.querySelector<HTMLInputElement>('[name="seed"]')?.addEventListener('input', () => scheduleRegenerate(root, state, ui));
+  root.querySelector('[data-random-seed]')?.addEventListener('click', () => { root.querySelector<HTMLInputElement>('[name="seed"]')!.value = randomName(); scheduleRegenerate(root, state, ui); });
+  root.querySelectorAll<HTMLInputElement>('[data-service-option]').forEach((input) => input.addEventListener('change', () => scheduleRegenerate(root, state, ui)));
+  root.querySelector('[data-add-service]')?.addEventListener('click', () => addCustomService(root, state, ui));
+  root.querySelector<HTMLInputElement>('[data-new-service]')?.addEventListener('keydown', (event) => { if (event.key === 'Enter') addCustomService(root, state, ui); });
+}
+
+function exportPng(map: SettlementMap, ui: SettlementMapUI): void { const image = new Image(); image.onload = () => { const canvas = document.createElement('canvas'); canvas.width = map.width * 32; canvas.height = map.height * 32; const context = canvas.getContext('2d'); if (!context) return; context.fillStyle = '#f8f0df'; context.fillRect(0, 0, canvas.width, canvas.height); context.drawImage(image, 0, 0, canvas.width, canvas.height); canvas.toBlob((blob) => { if (blob) downloadFile(blob, 'settlement-exploration-map.png'); }, 'image/png'); }; image.src = svgToDataUrl(buildMapSvg(map, ui)); }
+function exportJson(map: SettlementMap): void { downloadFile(JSON.stringify(map, null, 2), 'settlement-exploration-map.json', 'application/json'); }
+
+function attachActionEvents(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  root.querySelector('[data-generate]')?.addEventListener('click', () => regenerate(root, state, ui));
+  root.querySelector('[data-share]')?.addEventListener('click', () => { const url = new URL(window.location.href); url.searchParams.set('settlement', encodeShareState(state.current, state.customServices)); window.history.replaceState({}, '', url); void navigator.clipboard?.writeText(url.toString()); setStatus(root, ui.linkCopied); });
+  root.querySelector('[data-export-svg]')?.addEventListener('click', () => downloadFile(buildMapSvg(state.current, ui), 'settlement-exploration-map.svg', 'image/svg+xml'));
+  root.querySelector('[data-export-png]')?.addEventListener('click', () => exportPng(state.current, ui));
+  root.querySelector('[data-export-json]')?.addEventListener('click', () => exportJson(state.current));
+  root.querySelector<HTMLInputElement>('[data-import-json]')?.addEventListener('change', (event) => { void importJson(root, state, ui, event.target as HTMLInputElement); });
+}
+async function importJson(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI, input: HTMLInputElement): Promise<void> { const file = input.files?.[0]; if (!file) return; try { const parsed: unknown = JSON.parse(await file.text()); if (!isSettlementMap(parsed)) throw new Error('invalid'); state.current = parsed; state.customServices = [...new Set([...state.customServices, ...parsed.config.services.filter((service) => !BUILT_IN_SERVICES.includes(service))])]; state.customServices.forEach((service) => appendServiceOption(root, { service, ui, checked: parsed.config.services.includes(service), onRemove: (item) => removeCustomService(root, state, ui, item) })); syncControls(root, configFromMap(parsed), ui, (service) => removeCustomService(root, state, ui, service)); render(root, state.current, ui, state.customServices); } catch { setStatus(root, ui.importError); } finally { input.value = ''; } }
+function runtimeStateFromStorage(): RuntimeState { const loaded = queryMapFromUrl() ?? loadSettlement(); const initialMap = loaded?.map ?? generateSettlement(DEFAULT_CONFIG); const customServices = [...new Set([...(loaded?.customServices ?? []), ...initialMap.config.services.filter((service) => !BUILT_IN_SERVICES.includes(service))])]; return { current: initialMap, customServices }; }
+function prepareControls(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  state.customServices.forEach((service) => appendServiceOption(root, { service, ui, checked: state.current.config.services.includes(service), onRemove: (item) => removeCustomService(root, state, ui, item) }));
+  syncControls(root, state.current.config, ui, (service) => removeCustomService(root, state, ui, service));
+  render(root, state.current, ui, state.customServices);
+}
+
+function bindEditor(root: HTMLElement, state: RuntimeState, ui: SettlementMapUI): void {
+  bindContextEditor(root, (point, tool) => {
+    state.current = applyEdit(state.current, tool, point);
+    render(root, state.current, ui, state.customServices);
+  });
+}
+
+export function mountSettlementMap(): void {
+  const root = document.querySelector<HTMLElement>('[data-settlement-tool]');
+  if (!root || root.dataset.mounted === 'true') return;
+  root.dataset.mounted = 'true';
+  const ui = JSON.parse(root.querySelector<HTMLScriptElement>('[data-ui]')?.textContent ?? '{}') as SettlementMapUI;
+  const state = runtimeStateFromStorage();
+  prepareControls(root, state, ui);
+  attachChoiceEvents(root, state, ui);
+  bindEditor(root, state, ui);
+  attachActionEvents(root, state, ui);
+}