@connected-web/terrain-editor 0.1.3 → 0.1.5

package/dist/index.cjs

@@ -34,11 +34,13 @@ __export(index_exports, {
   buildRimMesh: () => buildRimMesh,
   buildWynArchive: () => buildWynArchive,
   createHeightSampler: () => createHeightSampler,
+  createIconUrlMap: () => createIconUrlMap,
   createLayerBrowserStore: () => createLayerBrowserStore,
   createMaskEditor: () => createMaskEditor,
   createProjectStore: () => createProjectStore,
   createTerrainViewerHost: () => createTerrainViewerHost,
   createViewerOverlay: () => createViewerOverlay,
+  enhanceLocationsWithIconUrls: () => enhanceLocationsWithIconUrls,
   getDefaultTerrainTheme: () => getDefaultTerrainTheme,
   initTerrainViewer: () => initTerrainViewer,
   loadWynArchive: () => loadWynArchive,
@@ -939,10 +941,16 @@ async function initTerrainViewer(container, dataset, options = {}) {
   let viewportWidth = width;
   let viewportHeight = height;
   let viewOffsetPixels = 0;
+  const maxPixelRatio = Math.max(1, options.maxPixelRatio ?? 1.5);
+  let currentPixelRatio = 1;
+  function resolvePixelRatio() {
+    return Math.max(1, Math.min(window.devicePixelRatio || 1, maxPixelRatio));
+  }
   const renderer = new THREE2.WebGLRenderer({ antialias: true, alpha: true });
   renderer.toneMapping = THREE2.ACESFilmicToneMapping;
   renderer.toneMappingExposure = 1.08;
-  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  currentPixelRatio = resolvePixelRatio();
+  renderer.setPixelRatio(currentPixelRatio);
   const hostStyle = window.getComputedStyle(container);
   if (hostStyle.position === "static") {
     container.style.position = "relative";
@@ -1469,6 +1477,11 @@ async function initTerrainViewer(container, dataset, options = {}) {
     viewOffsetPixels = shiftTarget;
     camera.aspect = clientWidth / clientHeight;
     camera.updateProjectionMatrix();
+    const nextPixelRatio = resolvePixelRatio();
+    if (nextPixelRatio !== currentPixelRatio) {
+      currentPixelRatio = nextPixelRatio;
+      renderer.setPixelRatio(currentPixelRatio);
+    }
     renderer.setSize(clientWidth, clientHeight, false);
     applyViewOffset();
   });
@@ -1495,6 +1508,8 @@ async function initTerrainViewer(container, dataset, options = {}) {
     const markerId = pickMarkerId();
     if (markerId !== hoveredLocationId) {
       hoveredLocationId = markerId;
+      const hoveredLocation = markerId ? currentLocations.find((location) => location.id === markerId) : void 0;
+      renderer.domElement.title = hoveredLocation?.name || hoveredLocation?.id || "";
       options.onLocationHover?.(markerId);
       updateMarkerVisuals();
     }
@@ -1655,6 +1670,9 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     setCameraOffset: (offset, focusId) => {
       cameraOffset.target = THREE2.MathUtils.clamp(offset, -0.45, 0.45);
+      if (cameraTween) {
+        return;
+      }
       const targetId = focusId ?? currentFocusId;
       if (targetId) {
         const loc = currentLocations.find((item) => item.id === targetId);
@@ -3244,17 +3262,76 @@ function createMaskEditor(options) {
     markClean
   };
 }
+
+// src/iconHelpers.ts
+function inferMimeType(path, fallback = "image/png") {
+  const extension = path.split(".").pop()?.toLowerCase();
+  if (!extension) return fallback;
+  if (extension === "png") return "image/png";
+  if (extension === "jpg" || extension === "jpeg") return "image/jpeg";
+  if (extension === "webp") return "image/webp";
+  if (extension === "gif") return "image/gif";
+  if (extension === "svg") return "image/svg+xml";
+  return fallback;
+}
+function toObjectUrl(entry) {
+  const type = entry.type ?? inferMimeType(entry.path);
+  const blob = new Blob([entry.data], { type });
+  return URL.createObjectURL(blob);
+}
+function createIconUrlMap(files, options = {}) {
+  const urls = /* @__PURE__ */ new Map();
+  const prefix = options.prefix ?? "icons/";
+  if (!files?.length) {
+    return {
+      urls,
+      cleanup: () => void 0
+    };
+  }
+  for (const entry of files) {
+    if (!entry.path) continue;
+    if (prefix && !entry.path.startsWith(prefix)) continue;
+    const url = toObjectUrl(entry);
+    urls.set(entry.path, url);
+  }
+  const cleanup = () => {
+    for (const url of urls.values()) {
+      URL.revokeObjectURL(url);
+    }
+    urls.clear();
+  };
+  return { urls, cleanup };
+}
+function enhanceLocationsWithIconUrls(locations, files, options) {
+  const { urls, cleanup } = createIconUrlMap(files, options);
+  const enhanced = locations.map((location) => {
+    if (!location.icon) {
+      return { ...location };
+    }
+    const iconUrl = urls.get(location.icon);
+    if (!iconUrl) {
+      return { ...location };
+    }
+    return {
+      ...location,
+      iconUrl
+    };
+  });
+  return { locations: enhanced, cleanup };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   applyHeightField,
   buildRimMesh,
   buildWynArchive,
   createHeightSampler,
+  createIconUrlMap,
   createLayerBrowserStore,
   createMaskEditor,
   createProjectStore,
   createTerrainViewerHost,
   createViewerOverlay,
+  enhanceLocationsWithIconUrls,
   getDefaultTerrainTheme,
   initTerrainViewer,
   loadWynArchive,

package/dist/index.d.cts

@@ -82,6 +82,7 @@ type TerrainLocation = {
     id: string;
     name?: string;
     icon?: string;
+    description?: string;
     showBorder?: boolean;
     pixel: {
         x: number;
@@ -119,6 +120,7 @@ type TerrainInitOptions = {
     onLifecycleChange?: (state: ViewerLifecycleState) => void;
     heightScale?: number;
     waterLevelPercent?: number;
+    maxPixelRatio?: number;
     layers?: LayerToggleState;
     interactive?: boolean;
     onLocationPick?: (payload: LocationPickPayload) => void;
@@ -406,4 +408,34 @@ type MaskEditorOptions = {
 };
 declare function createMaskEditor(options: MaskEditorOptions): MaskEditorHandle;
 
-export { type BuildWynArchiveOptions, type Cleanup, type DeepPartial, type HeightSampler, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };
+type CreateIconUrlMapOptions = {
+    /**
+     * Directory prefix to match when building the icon map.
+     * Defaults to `icons/`, matching standard .wyn archives.
+     */
+    prefix?: string;
+};
+type IconUrlEntry = {
+    path: string;
+    url: string;
+};
+type IconUrlMapResult = {
+    /**
+     * Map of file paths (relative to the archive root) to object URLs.
+     */
+    urls: Map<string, string>;
+    /**
+     * Revoke all allocated object URLs.
+     */
+    cleanup: () => void;
+};
+type EnhancedLocationsResult<T extends TerrainLocation = TerrainLocation> = {
+    locations: Array<T & {
+        iconUrl?: string;
+    }>;
+    cleanup: () => void;
+};
+declare function createIconUrlMap(files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): IconUrlMapResult;
+declare function enhanceLocationsWithIconUrls<T extends TerrainLocation = TerrainLocation>(locations: T[], files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): EnhancedLocationsResult<T>;
+
+export { type BuildWynArchiveOptions, type Cleanup, type CreateIconUrlMapOptions, type DeepPartial, type EnhancedLocationsResult, type HeightSampler, type IconUrlEntry, type IconUrlMapResult, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createIconUrlMap, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, enhanceLocationsWithIconUrls, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };

package/dist/index.d.ts

@@ -82,6 +82,7 @@ type TerrainLocation = {
     id: string;
     name?: string;
     icon?: string;
+    description?: string;
     showBorder?: boolean;
     pixel: {
         x: number;
@@ -119,6 +120,7 @@ type TerrainInitOptions = {
     onLifecycleChange?: (state: ViewerLifecycleState) => void;
     heightScale?: number;
     waterLevelPercent?: number;
+    maxPixelRatio?: number;
     layers?: LayerToggleState;
     interactive?: boolean;
     onLocationPick?: (payload: LocationPickPayload) => void;
@@ -406,4 +408,34 @@ type MaskEditorOptions = {
 };
 declare function createMaskEditor(options: MaskEditorOptions): MaskEditorHandle;
 
-export { type BuildWynArchiveOptions, type Cleanup, type DeepPartial, type HeightSampler, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };
+type CreateIconUrlMapOptions = {
+    /**
+     * Directory prefix to match when building the icon map.
+     * Defaults to `icons/`, matching standard .wyn archives.
+     */
+    prefix?: string;
+};
+type IconUrlEntry = {
+    path: string;
+    url: string;
+};
+type IconUrlMapResult = {
+    /**
+     * Map of file paths (relative to the archive root) to object URLs.
+     */
+    urls: Map<string, string>;
+    /**
+     * Revoke all allocated object URLs.
+     */
+    cleanup: () => void;
+};
+type EnhancedLocationsResult<T extends TerrainLocation = TerrainLocation> = {
+    locations: Array<T & {
+        iconUrl?: string;
+    }>;
+    cleanup: () => void;
+};
+declare function createIconUrlMap(files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): IconUrlMapResult;
+declare function enhanceLocationsWithIconUrls<T extends TerrainLocation = TerrainLocation>(locations: T[], files?: TerrainProjectFileEntry[], options?: CreateIconUrlMapOptions): EnhancedLocationsResult<T>;
+
+export { type BuildWynArchiveOptions, type Cleanup, type CreateIconUrlMapOptions, type DeepPartial, type EnhancedLocationsResult, type HeightSampler, type IconUrlEntry, type IconUrlMapResult, type LayerBrowserEntry, type LayerBrowserState, type LayerBrowserStore, type LayerToggleState, type LegendLayer, type LoadWynArchiveOptions, type LoadedWynFile, type LocationPickPayload, type LocationViewState, type MarkerSpriteStateStyle, type MarkerSpriteTheme, type MarkerStemGeometryShape, type MarkerStemStateStyle, type MarkerStemTheme, type MaskEditorHandle, type MaskEditorState, type MaskImage, type MaskStroke, type MaskStrokeMode, type MaskStrokePoint, type TerrainDataset, type TerrainHandle, type TerrainLegend, type TerrainLocation, type TerrainProjectFileEntry, type TerrainProjectMetadata, type TerrainProjectSnapshot, type TerrainProjectStore, type TerrainTheme, type TerrainThemeOverrides, type TerrainViewMode, type TerrainViewerHostHandle, type TerrainViewerHostOptions, type ViewerLifecycleState, type ViewerOverlayCustomButton, type ViewerOverlayHandle, type ViewerOverlayLoadingState, type ViewerOverlayOptions, type WynArchiveProgressEvent, applyHeightField, buildRimMesh, buildWynArchive, createHeightSampler, createIconUrlMap, createLayerBrowserStore, createMaskEditor, createProjectStore, createTerrainViewerHost, createViewerOverlay, enhanceLocationsWithIconUrls, getDefaultTerrainTheme, initTerrainViewer, loadWynArchive, loadWynArchiveFromArrayBuffer, loadWynArchiveFromFile, resolveTerrainTheme, sampleHeightValue };

package/dist/index.js

@@ -888,10 +888,16 @@ async function initTerrainViewer(container, dataset, options = {}) {
   let viewportWidth = width;
   let viewportHeight = height;
   let viewOffsetPixels = 0;
+  const maxPixelRatio = Math.max(1, options.maxPixelRatio ?? 1.5);
+  let currentPixelRatio = 1;
+  function resolvePixelRatio() {
+    return Math.max(1, Math.min(window.devicePixelRatio || 1, maxPixelRatio));
+  }
   const renderer = new THREE2.WebGLRenderer({ antialias: true, alpha: true });
   renderer.toneMapping = THREE2.ACESFilmicToneMapping;
   renderer.toneMappingExposure = 1.08;
-  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  currentPixelRatio = resolvePixelRatio();
+  renderer.setPixelRatio(currentPixelRatio);
   const hostStyle = window.getComputedStyle(container);
   if (hostStyle.position === "static") {
     container.style.position = "relative";
@@ -1418,6 +1424,11 @@ async function initTerrainViewer(container, dataset, options = {}) {
     viewOffsetPixels = shiftTarget;
     camera.aspect = clientWidth / clientHeight;
     camera.updateProjectionMatrix();
+    const nextPixelRatio = resolvePixelRatio();
+    if (nextPixelRatio !== currentPixelRatio) {
+      currentPixelRatio = nextPixelRatio;
+      renderer.setPixelRatio(currentPixelRatio);
+    }
     renderer.setSize(clientWidth, clientHeight, false);
     applyViewOffset();
   });
@@ -1444,6 +1455,8 @@ async function initTerrainViewer(container, dataset, options = {}) {
     const markerId = pickMarkerId();
     if (markerId !== hoveredLocationId) {
       hoveredLocationId = markerId;
+      const hoveredLocation = markerId ? currentLocations.find((location) => location.id === markerId) : void 0;
+      renderer.domElement.title = hoveredLocation?.name || hoveredLocation?.id || "";
       options.onLocationHover?.(markerId);
       updateMarkerVisuals();
     }
@@ -1604,6 +1617,9 @@ async function initTerrainViewer(container, dataset, options = {}) {
     },
     setCameraOffset: (offset, focusId) => {
       cameraOffset.target = THREE2.MathUtils.clamp(offset, -0.45, 0.45);
+      if (cameraTween) {
+        return;
+      }
       const targetId = focusId ?? currentFocusId;
       if (targetId) {
         const loc = currentLocations.find((item) => item.id === targetId);
@@ -3193,16 +3209,75 @@ function createMaskEditor(options) {
     markClean
   };
 }
+
+// src/iconHelpers.ts
+function inferMimeType(path, fallback = "image/png") {
+  const extension = path.split(".").pop()?.toLowerCase();
+  if (!extension) return fallback;
+  if (extension === "png") return "image/png";
+  if (extension === "jpg" || extension === "jpeg") return "image/jpeg";
+  if (extension === "webp") return "image/webp";
+  if (extension === "gif") return "image/gif";
+  if (extension === "svg") return "image/svg+xml";
+  return fallback;
+}
+function toObjectUrl(entry) {
+  const type = entry.type ?? inferMimeType(entry.path);
+  const blob = new Blob([entry.data], { type });
+  return URL.createObjectURL(blob);
+}
+function createIconUrlMap(files, options = {}) {
+  const urls = /* @__PURE__ */ new Map();
+  const prefix = options.prefix ?? "icons/";
+  if (!files?.length) {
+    return {
+      urls,
+      cleanup: () => void 0
+    };
+  }
+  for (const entry of files) {
+    if (!entry.path) continue;
+    if (prefix && !entry.path.startsWith(prefix)) continue;
+    const url = toObjectUrl(entry);
+    urls.set(entry.path, url);
+  }
+  const cleanup = () => {
+    for (const url of urls.values()) {
+      URL.revokeObjectURL(url);
+    }
+    urls.clear();
+  };
+  return { urls, cleanup };
+}
+function enhanceLocationsWithIconUrls(locations, files, options) {
+  const { urls, cleanup } = createIconUrlMap(files, options);
+  const enhanced = locations.map((location) => {
+    if (!location.icon) {
+      return { ...location };
+    }
+    const iconUrl = urls.get(location.icon);
+    if (!iconUrl) {
+      return { ...location };
+    }
+    return {
+      ...location,
+      iconUrl
+    };
+  });
+  return { locations: enhanced, cleanup };
+}
 export {
   applyHeightField,
   buildRimMesh,
   buildWynArchive,
   createHeightSampler,
+  createIconUrlMap,
   createLayerBrowserStore,
   createMaskEditor,
   createProjectStore,
   createTerrainViewerHost,
   createViewerOverlay,
+  enhanceLocationsWithIconUrls,
   getDefaultTerrainTheme,
   initTerrainViewer,
   loadWynArchive,

package/documentation/WYN-FILE-FORMAT.md

@@ -0,0 +1,198 @@
+# WYN File Format
+
+## Overview
+
+`.wyn` files are ZIP archives containing terrain data, layer masks, and optional metadata used by
+`@connected-web/terrain-editor`. The loader expects JSON descriptors plus referenced PNG assets.
+All asset paths are relative to the archive root.
+
+## Archive Layout
+
+Required:
+
+```
+legend.json
+```
+
+Common (referenced by `legend.json`):
+
+```
+layers/
+icons/
+```
+
+Optional:
+
+```
+locations.json
+theme.json
+metadata.json
+thumbnails/
+```
+
+The archive can include any additional assets as long as paths match the JSON references.
+
+## legend.json (required)
+
+Describes terrain dimensions, height/topology maps, and per-layer masks.
+
+Schema: `schemas/legend.schema.json`
+
+```json
+{
+  "size": [1024, 1536],
+  "sea_level": 0.35,
+  "heightmap": "layers/heightmap.png",
+  "topology": "layers/topology.png",
+  "biomes": {
+    "forest": { "mask": "layers/forest_mask.png", "rgb": [48, 92, 54], "label": "Forest" }
+  },
+  "overlays": {
+    "water": { "mask": "layers/water_mask.png", "rgb": [34, 92, 124], "label": "Water" }
+  }
+}
+```
+
+Schema:
+
+- `size`: `[width, height]` in pixels for the map and mask assets.
+- `sea_level`: Optional float in 0-1 heightmap range; used to offset terrain vertically.
+- `heightmap`: Path to a PNG. The viewer samples the **red channel** (0-255) as height data.
+- `topology`: Optional path to a PNG used for shaded legend/composite rendering. Falls back to
+  `heightmap` when omitted.
+- `biomes`: Record of biome layers. Keys are layer ids used by the editor/viewer.
+- `overlays`: Record of overlay layers. Keys are layer ids used by the editor/viewer.
+
+Each layer entry:
+
+- `mask`: Path to a PNG mask. The viewer converts the max RGB channel into alpha.
+- `rgb`: `[r, g, b]` integers (0-255) used to colorize the legend composite.
+- `label`: Optional display name in the editor UI.
+
+## locations.json (optional)
+
+Array of location markers. Coordinates are expressed in legend pixel space.
+
+Schema: `schemas/locations.schema.json`
+
+```json
+[
+  {
+    "id": "loc-123",
+    "name": "Castle",
+    "icon": "icons/icon_castle.png",
+    "description": "Seat of power.",
+    "pixel": { "x": 514, "y": 728 },
+    "showBorder": true,
+    "view": {
+      "distance": 1.82,
+      "polar": 0.96,
+      "azimuth": 1.87,
+      "targetPixel": { "x": 514, "y": 728 }
+    }
+  }
+]
+```
+
+Fields:
+
+- `id`: Stable unique id string.
+- `name`: Optional label for markers.
+- `icon`: Optional icon source. If the value looks like a file path or image filename, the viewer
+  loads it as a texture; otherwise the first character is rendered as a glyph.
+- `description`: Optional freeform text (ignored by the viewer, preserved by the editor).
+- `pixel`: `{ x, y }` in legend pixel space. The viewer converts to UV/world coordinates.
+- `showBorder`: Optional boolean for marker label border visibility.
+- `view`: Optional camera view state:
+  - `distance`: Camera distance from target in world units.
+  - `polar`: Polar angle in radians.
+  - `azimuth`: Azimuthal angle in radians.
+  - `targetPixel`: Optional pixel coordinate to orbit around.
+
+## theme.json (optional)
+
+Overrides for the default terrain marker theme.
+
+Schema: `schemas/theme.schema.json`
+
+```json
+{
+  "locationMarkers": {
+    "sprite": {
+      "fontFamily": "\"DM Sans\", sans-serif",
+      "fontWeight": "600",
+      "maxFontSize": 52,
+      "minFontSize": 22,
+      "paddingX": 20,
+      "paddingY": 10,
+      "borderRadius": 4,
+      "states": {
+        "default": {
+          "textColor": "#ffffff",
+          "backgroundColor": "rgba(8, 10, 18, 0.78)",
+          "borderColor": "rgba(255, 255, 255, 0.35)",
+          "borderThickness": 2,
+          "opacity": 0.85
+        },
+        "hover": { "backgroundColor": "#3c49af" },
+        "focus": { "backgroundColor": "#cb811a" }
+      }
+    },
+    "stem": {
+      "shape": "triangle",
+      "radius": 0.02,
+      "states": {
+        "default": { "color": "#d9c39c", "opacity": 0.2 },
+        "focus": { "color": "#c00c0c", "opacity": 0.75 }
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `theme.json` is a partial override; any missing values fall back to the default theme.
+- `stem.shape` supports: `cylinder`, `triangle`, `square`, `pentagon`, `hexagon`.
+
+## metadata.json (optional)
+
+Basic project metadata stored by the editor.
+
+Schema: `schemas/metadata.schema.json`
+
+```json
+{
+  "label": "wynnal-terrain.wyn",
+  "author": "J. Markavian",
+  "source": "archive"
+}
+```
+
+Fields:
+
+- `label`: Display name for the project.
+- `author`: Optional author string.
+- `source`: `archive` or `scratch`.
+
+## Assets and Conventions
+
+- Use PNGs for all image assets. The loader infers mime types by file extension.
+- All referenced assets must exist inside the archive.
+- The editor stores arbitrary files referenced by the JSON in the ZIP (see `buildWynArchive`).
+- `legend.size` should match the pixel dimensions of mask assets.
+
+## Example Archive
+
+```
+legend.json
+locations.json
+theme.json
+metadata.json
+layers/heightmap.png
+layers/topology.png
+layers/forest_mask.png
+layers/water_mask.png
+icons/icon_castle.png
+thumbnails/thumbnail.png
+```

package/documentation/schemas/legend.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://connected-web.github.io/terrain-editor/schemas/legend.schema.json",
+  "title": "WYN Legend",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["size", "heightmap", "biomes", "overlays"],
+  "properties": {
+    "size": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "items": {
+        "type": "integer",
+        "minimum": 1
+      }
+    },
+    "sea_level": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "heightmap": {
+      "type": "string",
+      "minLength": 1
+    },
+    "topology": {
+      "type": "string",
+      "minLength": 1
+    },
+    "biomes": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/definitions/legendLayer" }
+    },
+    "overlays": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/definitions/legendLayer" }
+    }
+  },
+  "definitions": {
+    "legendLayer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mask", "rgb"],
+      "properties": {
+        "mask": {
+          "type": "string",
+          "minLength": 1
+        },
+        "rgb": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 255
+          }
+        },
+        "label": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/documentation/schemas/locations.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://connected-web.github.io/terrain-editor/schemas/locations.schema.json",
+  "title": "WYN Locations",
+  "type": "array",
+  "items": { "$ref": "#/definitions/location" },
+  "definitions": {
+    "location": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "pixel"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "icon": { "type": "string" },
+        "description": { "type": "string" },
+        "showBorder": { "type": "boolean" },
+        "pixel": { "$ref": "#/definitions/pixel" },
+        "uv": { "$ref": "#/definitions/uv" },
+        "world": { "$ref": "#/definitions/world" },
+        "view": { "$ref": "#/definitions/view" }
+      }
+    },
+    "pixel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" }
+      }
+    },
+    "uv": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["u", "v"],
+      "properties": {
+        "u": { "type": "number" },
+        "v": { "type": "number" }
+      }
+    },
+    "world": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "z"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "z": { "type": "number" }
+      }
+    },
+    "view": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["distance", "polar", "azimuth"],
+      "properties": {
+        "distance": { "type": "number" },
+        "polar": { "type": "number" },
+        "azimuth": { "type": "number" },
+        "targetPixel": { "$ref": "#/definitions/pixel" }
+      }
+    }
+  }
+}

package/documentation/schemas/metadata.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://connected-web.github.io/terrain-editor/schemas/metadata.schema.json",
+  "title": "WYN Metadata",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "label": { "type": "string" },
+    "author": { "type": "string" },
+    "source": { "type": "string", "enum": ["archive", "scratch"] }
+  }
+}

package/documentation/schemas/theme.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://connected-web.github.io/terrain-editor/schemas/theme.schema.json",
+  "title": "WYN Theme Overrides",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "locationMarkers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sprite": { "$ref": "#/definitions/sprite" },
+        "stem": { "$ref": "#/definitions/stem" }
+      }
+    }
+  },
+  "definitions": {
+    "sprite": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "fontFamily": { "type": "string" },
+        "fontWeight": { "type": "string" },
+        "maxFontSize": { "type": "number" },
+        "minFontSize": { "type": "number" },
+        "paddingX": { "type": "number" },
+        "paddingY": { "type": "number" },
+        "borderRadius": { "type": "number" },
+        "states": { "$ref": "#/definitions/spriteStates" }
+      }
+    },
+    "spriteStates": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default": { "$ref": "#/definitions/spriteState" },
+        "hover": { "$ref": "#/definitions/spriteState" },
+        "focus": { "$ref": "#/definitions/spriteState" }
+      }
+    },
+    "spriteState": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "textColor": { "type": "string" },
+        "backgroundColor": { "type": "string" },
+        "borderColor": { "type": "string" },
+        "borderThickness": { "type": "number" },
+        "opacity": { "type": "number" }
+      }
+    },
+    "stem": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "shape": {
+          "type": "string",
+          "enum": ["cylinder", "triangle", "square", "pentagon", "hexagon"]
+        },
+        "radius": { "type": "number" },
+        "scale": { "type": "number" },
+        "states": { "$ref": "#/definitions/stemStates" }
+      }
+    },
+    "stemStates": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default": { "$ref": "#/definitions/stemState" },
+        "hover": { "$ref": "#/definitions/stemState" },
+        "focus": { "$ref": "#/definitions/stemState" }
+      }
+    },
+    "stemState": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "color": { "type": "string" },
+        "opacity": { "type": "number" }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connected-web/terrain-editor",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Reusable viewer/editor utilities for Wyn terrain files.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -11,14 +11,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./documentation/*": "./documentation/*",
+    "./schemas/*": "./documentation/schemas/*"
   },
   "files": [
     "dist",
+    "documentation",
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --dts --format cjs,esm --out-dir dist --clean --tsconfig tsconfig.json"
+    "build": "node ./scripts/copy-docs.mjs && tsup src/index.ts --dts --format cjs,esm --out-dir dist --clean --tsconfig tsconfig.json"
   },
   "dependencies": {
     "jszip": "^3.10.1",