@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/world/cityGeometry.d.ts

@@ -63,6 +63,26 @@ export declare function insetRingUniform(ring: readonly Vec2[], distance: number
 export declare function polygonMeanWidth(ring: readonly Vec2[]): number;
 /** All four corners of a rotated rect (center, half-extents, yaw in engine rotationY convention). */
 export declare function rectCorners(cx: number, cz: number, hw: number, hd: number, rotationY: number): Vec2[];
+/** A rotated rectangle: center, half-extents, and yaw in the engine rotationY convention. */
+export interface OrientedRect {
+    x: number;
+    z: number;
+    hw: number;
+    hd: number;
+    angle: number;
+}
+/**
+ * Separating-axis test for two rotated rectangles: true when a gap exists (no overlap).
+ * @capability city-district exact overlap test between two rotated rectangles (plots, lots, footprints)
+ */
+export declare function rectsSeparated(a: OrientedRect, b: OrientedRect): boolean;
+/**
+ * True when a rotated rect stays at least `clearance` away from every segment of a polyline —
+ * the plot-contract test that keeps building plots off road corridors (pass the road half-width
+ * as the clearance). Exact segment-vs-expanded-rect intersection, not corner sampling.
+ * @capability city-district keep a rotated rect (plot/footprint) clear of a road corridor polyline
+ */
+export declare function rectClearsPolyline(rect: OrientedRect, path: readonly Vec2[], clearance: number): boolean;
 /** True when the whole rotated rect (corners + edge midpoints) sits inside the ring. */
 export declare function rectInsidePolygon(ring: readonly Vec2[], cx: number, cz: number, hw: number, hd: number, rotationY: number): boolean;
 /**

package/dist/world/cityGeometry.js

@@ -328,6 +328,97 @@ export function rectCorners(cx, cz, hw, hd, rotationY) {
     }
     return out;
 }
+/**
+ * Separating-axis test for two rotated rectangles: true when a gap exists (no overlap).
+ * @capability city-district exact overlap test between two rotated rectangles (plots, lots, footprints)
+ */
+export function rectsSeparated(a, b) {
+    const axes = [];
+    for (const angle of [a.angle, b.angle]) {
+        axes.push([Math.cos(angle), -Math.sin(angle)], [Math.sin(angle), Math.cos(angle)]);
+    }
+    const ca = rectCorners(a.x, a.z, a.hw, a.hd, a.angle);
+    const cb = rectCorners(b.x, b.z, b.hw, b.hd, b.angle);
+    for (const [ax, az] of axes) {
+        let minA = Infinity;
+        let maxA = -Infinity;
+        let minB = Infinity;
+        let maxB = -Infinity;
+        for (const [x, z] of ca) {
+            const p = x * ax + z * az;
+            if (p < minA)
+                minA = p;
+            if (p > maxA)
+                maxA = p;
+        }
+        for (const [x, z] of cb) {
+            const p = x * ax + z * az;
+            if (p < minB)
+                minB = p;
+            if (p > maxB)
+                maxB = p;
+        }
+        if (maxA < minB || maxB < minA)
+            return true; // gap on this axis → no overlap
+    }
+    return false;
+}
+/** True when a segment touches an axis-aligned box (separating-axis: x, z, and the segment normal). */
+function segmentTouchesAabb(ax, az, bx, bz, minX, minZ, maxX, maxZ) {
+    if (Math.max(ax, bx) < minX || Math.min(ax, bx) > maxX)
+        return false;
+    if (Math.max(az, bz) < minZ || Math.min(az, bz) > maxZ)
+        return false;
+    const nx = -(bz - az);
+    const nz = bx - ax;
+    const d0 = nx * (minX - ax) + nz * (minZ - az);
+    const d1 = nx * (maxX - ax) + nz * (minZ - az);
+    const d2 = nx * (maxX - ax) + nz * (maxZ - az);
+    const d3 = nx * (minX - ax) + nz * (maxZ - az);
+    if (d0 > 0 && d1 > 0 && d2 > 0 && d3 > 0)
+        return false;
+    if (d0 < 0 && d1 < 0 && d2 < 0 && d3 < 0)
+        return false;
+    return true;
+}
+/**
+ * True when a rotated rect stays at least `clearance` away from every segment of a polyline —
+ * the plot-contract test that keeps building plots off road corridors (pass the road half-width
+ * as the clearance). Exact segment-vs-expanded-rect intersection, not corner sampling.
+ * @capability city-district keep a rotated rect (plot/footprint) clear of a road corridor polyline
+ */
+export function rectClearsPolyline(rect, path, clearance) {
+    if (path.length < 2)
+        return true;
+    const c = Math.cos(rect.angle);
+    const s = Math.sin(rect.angle);
+    const ex = rect.hw + clearance;
+    const ez = rect.hd + clearance;
+    // Cheap world-space bbox reject before transforming segments into the rect frame.
+    const reach = Math.hypot(ex, ez);
+    const minX = rect.x - reach;
+    const maxX = rect.x + reach;
+    const minZ = rect.z - reach;
+    const maxZ = rect.z + reach;
+    let px = path[0][0];
+    let pz = path[0][1];
+    let plx = (px - rect.x) * c - (pz - rect.z) * s;
+    let plz = (px - rect.x) * s + (pz - rect.z) * c;
+    for (let i = 1; i < path.length; i += 1) {
+        const qx = path[i][0];
+        const qz = path[i][1];
+        const inside = !(Math.max(px, qx) < minX || Math.min(px, qx) > maxX || Math.max(pz, qz) < minZ || Math.min(pz, qz) > maxZ);
+        const qlx = (qx - rect.x) * c - (qz - rect.z) * s;
+        const qlz = (qx - rect.x) * s + (qz - rect.z) * c;
+        if (inside && segmentTouchesAabb(plx, plz, qlx, qlz, -ex, -ez, ex, ez))
+            return false;
+        px = qx;
+        pz = qz;
+        plx = qlx;
+        plz = qlz;
+    }
+    return true;
+}
 /** True when the whole rotated rect (corners + edge midpoints) sits inside the ring. */
 export function rectInsidePolygon(ring, cx, cz, hw, hd, rotationY) {
     const corners = rectCorners(cx, cz, hw, hd, rotationY);

package/dist/world/cityKind.js

@@ -32,9 +32,10 @@ import { parseParams, registerSceneKind, } from "../scene/sceneKinds.js";
 import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_STYLE } from "./buildings.js";
 import { buildLotPieces, pickClass, pickSpecies, rollClassPlacement, zoneBand, zoneMetric, } from "./cityContent.js";
 import { furnitureSpots } from "./streets.js";
+import { CITY_BUILDING_BUDGET, budgetWarning, placedCoverage } from "./scatterCoverage.js";
 import { generateStreets, streetNetworkMode, } from "./streetGenerator.js";
 import { buildablePolygon, carveCorridors, conformPolygonToRing, cutParcel, extractBlocks, isSliverBlock, pointsInPolygon, RingWalker, } from "./cityBlocks.js";
-import { fitRectInPolygon, rayDistanceToRing, pointInPolygon, polygonArea, polygonCentroid, polygonMeanWidth, polygonsOverlap, insetRingUniform, ringBounds, } from "./cityGeometry.js";
+import { fitRectInPolygon, rayDistanceToRing, pointInPolygon, polygonArea, polygonCentroid, polygonMeanWidth, polygonsOverlap, insetRingUniform, rectsSeparated, ringBounds, } from "./cityGeometry.js";
 /** The editor volume kind marking a box as a procedural city district. */
 export const CITY_KIND = "city";
 /** The editor volume kind that locally overrides a city's zone band/mix — a district in a district. */
@@ -567,7 +568,8 @@ export function readCityRules(meta) {
 }
 /** Bounded-work caps so a huge volume can never generate unbounded content. */
 const MAX_STREETS = 320;
-const MAX_LOTS = 2600;
+/** Building budget — the shared scatterable cap so the inspector's "capped at N (budget)" note is truthful. */
+const MAX_LOTS = CITY_BUILDING_BUDGET;
 const MAX_INTERSECTIONS = 600;
 const MAX_TREES = 3200;
 const MAX_LIGHTS = 1200;
@@ -664,49 +666,6 @@ class StreetIndex {
         return null;
     }
 }
-/** Separating-axis test for two rotated rectangles (center, half-extents, yaw): true when a gap exists. */
-function rectsSeparated(a, b) {
-    const axes = [];
-    for (const angle of [a.angle, b.angle]) {
-        axes.push([Math.cos(angle), -Math.sin(angle)], [Math.sin(angle), Math.cos(angle)]);
-    }
-    const corners = (r) => {
-        const c = Math.cos(r.angle);
-        const s = Math.sin(r.angle);
-        const out = [];
-        for (const [dx, dz] of [
-            [r.hw, r.hd],
-            [r.hw, -r.hd],
-            [-r.hw, r.hd],
-            [-r.hw, -r.hd],
-        ]) {
-            out.push([r.x + dx * c + dz * s, r.z - dx * s + dz * c]);
-        }
-        return out;
-    };
-    const ca = corners(a);
-    const cb = corners(b);
-    for (const [ax, az] of axes) {
-        let minA = Infinity, maxA = -Infinity, minB = Infinity, maxB = -Infinity;
-        for (const [x, z] of ca) {
-            const p = x * ax + z * az;
-            if (p < minA)
-                minA = p;
-            if (p > maxA)
-                maxA = p;
-        }
-        for (const [x, z] of cb) {
-            const p = x * ax + z * az;
-            if (p < minB)
-                minB = p;
-            if (p > maxB)
-                maxB = p;
-        }
-        if (maxA < minB || maxB < minA)
-            return true; // gap on this axis → no overlap
-    }
-    return false;
-}
 /** Broadphase grid over placed lots so overlap tests only touch neighbors. */
 class LotIndex {
     cells = new Map();
@@ -1530,6 +1489,7 @@ export function registerCityKind() {
         addCategory: "Studios",
         accent: "#8fa8c9",
         schema: CITY_SCHEMA,
+        coverage: { spec: "city", densityKey: "roadsideOccupancy" },
         resolve: (object, _params, context) => resolveCityObject(object, context),
         note: (object) => {
             const resolved = resolveCityObject(object);
@@ -1558,7 +1518,10 @@ export function registerCityKind() {
                 resolved.tunnels.length > 0 ? `${resolved.tunnels.length} tunnels` : "",
             ].filter((s) => s.length > 0);
             const head = mode === "circuit" ? `circuit · ${resolved.streets.length} streets` : `${resolved.streets.length} streets`;
-            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings · ${resolved.parks.length} parks` : " · no fabric";
+            // Shared clamp-and-warn: when the block/parcel pipeline hits the building budget, surface it in
+            // the same "capped at N (budget)" wording grass and scatter use.
+            const buildingCap = resolved.rules.fabric ? budgetWarning(placedCoverage("city", 0, resolved.lots.length)) : "";
+            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings${buildingCap} · ${resolved.parks.length} parks` : " · no fabric";
             return `${head}${fabric}${feats.length > 0 ? ` · ${feats.join(" · ")}` : ""}`;
         },
     });

package/dist/world/fastTravel.d.ts

@@ -0,0 +1,64 @@
+import type { WorldXZ } from "./minimap.js";
+/** A fast-travel destination the game defines. Discovery is tracked separately. */
+export interface TravelPointDef<TMeta = unknown> {
+    id: string;
+    name: string;
+    /** World-XZ location — feeds distance sorting and map markers. */
+    position: WorldXZ;
+    region?: string;
+    icon?: string;
+    /** Discovered from the start (a home base / starting waypoint). */
+    initial?: boolean;
+    meta?: TMeta;
+}
+/** A destination plus its discovery state (and distance from a query origin, when given). */
+export interface TravelPointView<TMeta = unknown> extends TravelPointDef<TMeta> {
+    discovered: boolean;
+    discoveredAt: number | null;
+    /** XZ distance from the query origin passed to `list`/`destinations`/`nearest`, else undefined. */
+    distance?: number;
+}
+/** Serializable discovery state. */
+export interface FastTravelSnapshot {
+    discovered: Record<string, number>;
+}
+/** A network of fast-travel points with per-player discovery + distance queries. */
+export interface FastTravelNetwork<TMeta = unknown> {
+    /** Unlock a point; returns the newly-discovered view, or null if unknown or already discovered. */
+    discover(id: string): TravelPointView<TMeta> | null;
+    isDiscovered(id: string): boolean;
+    get(id: string): TravelPointView<TMeta> | null;
+    /** All points (discovery state + optional distance), in definition order — or by distance when `from` is given. */
+    list(from?: WorldXZ): readonly TravelPointView<TMeta>[];
+    /** Discovered points only (distance-sorted when `from` is given). */
+    destinations(from?: WorldXZ): readonly TravelPointView<TMeta>[];
+    /** Nearest discovered point to `from` (optionally excluding an id — e.g. the one you're standing on). */
+    nearest(from: WorldXZ, options?: {
+        exclude?: string;
+    }): TravelPointView<TMeta> | null;
+    /** Whether a destination can be traveled to (discovered). Combat/cost gates are the game's to add. */
+    canTravel(id: string): boolean;
+    discoveredCount(): number;
+    total(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): FastTravelSnapshot;
+    restore(snapshot: FastTravelSnapshot): void;
+}
+/** Options for {@link createFastTravelNetwork}. */
+export interface FastTravelOptions<TMeta = unknown> {
+    points: readonly TravelPointDef<TMeta>[];
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Fires when a point is discovered for the first time — wire to a toast/notification. */
+    onDiscover?: (point: TravelPointView<TMeta>) => void;
+}
+/**
+ * A fast-travel network: defined destinations plus per-player discovery, with
+ * distance-sorted queries, a `nearest` lookup, a `canTravel` gate, an
+ * `onDiscover` seam, and serializable `snapshot`/`restore`. Travel itself is a
+ * teleport the game applies to `TravelPointView.position`; this owns the
+ * unlock/where-can-I-go state. Points marked `initial` start discovered.
+ *
+ * @capability fast-travel network of fast-travel destinations with discovery, distance-sorted queries, nearest lookup, a travel gate, and serializable state
+ */
+export declare function createFastTravelNetwork<TMeta = unknown>(options: FastTravelOptions<TMeta>): FastTravelNetwork<TMeta>;

package/dist/world/fastTravel.js

@@ -0,0 +1,108 @@
+function distanceXZ(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1]);
+}
+/**
+ * A fast-travel network: defined destinations plus per-player discovery, with
+ * distance-sorted queries, a `nearest` lookup, a `canTravel` gate, an
+ * `onDiscover` seam, and serializable `snapshot`/`restore`. Travel itself is a
+ * teleport the game applies to `TravelPointView.position`; this owns the
+ * unlock/where-can-I-go state. Points marked `initial` start discovered.
+ *
+ * @capability fast-travel network of fast-travel destinations with discovery, distance-sorted queries, nearest lookup, a travel gate, and serializable state
+ */
+export function createFastTravelNetwork(options) {
+    const now = options.now ?? Date.now;
+    const order = [];
+    const defs = new Map();
+    const discoveredAt = new Map();
+    for (const def of options.points) {
+        if (defs.has(def.id))
+            continue;
+        defs.set(def.id, def);
+        order.push(def.id);
+        if (def.initial === true)
+            discoveredAt.set(def.id, 0);
+    }
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function viewOf(id, from) {
+        const def = defs.get(id);
+        const at = discoveredAt.get(id) ?? null;
+        return {
+            ...def,
+            discovered: at !== null,
+            discoveredAt: at,
+            ...(from !== undefined ? { distance: distanceXZ(def.position, from) } : {}),
+        };
+    }
+    function views(from) {
+        const all = order.map((id) => viewOf(id, from));
+        if (from !== undefined)
+            all.sort((a, b) => (a.distance ?? 0) - (b.distance ?? 0));
+        return all;
+    }
+    const network = {
+        discover(id) {
+            if (!defs.has(id) || discoveredAt.has(id))
+                return null;
+            discoveredAt.set(id, now());
+            const view = viewOf(id);
+            options.onDiscover?.(view);
+            notify();
+            return view;
+        },
+        isDiscovered(id) {
+            return discoveredAt.has(id);
+        },
+        get(id) {
+            return defs.has(id) ? viewOf(id) : null;
+        },
+        list(from) {
+            return views(from);
+        },
+        destinations(from) {
+            return views(from).filter((view) => view.discovered);
+        },
+        nearest(from, opts = {}) {
+            let best = null;
+            for (const view of views(from)) {
+                if (!view.discovered || view.id === opts.exclude)
+                    continue;
+                if (best === null || (view.distance ?? 0) < (best.distance ?? 0))
+                    best = view;
+            }
+            return best;
+        },
+        canTravel(id) {
+            return discoveredAt.has(id);
+        },
+        discoveredCount() {
+            return discoveredAt.size;
+        },
+        total() {
+            return order.length;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { discovered: Object.fromEntries(discoveredAt) };
+        },
+        restore(snapshot) {
+            discoveredAt.clear();
+            for (const id of order)
+                if (defs.get(id).initial === true)
+                    discoveredAt.set(id, 0);
+            for (const [id, at] of Object.entries(snapshot.discovered)) {
+                if (defs.has(id))
+                    discoveredAt.set(id, at);
+            }
+            notify();
+        },
+    };
+    return network;
+}

package/dist/world/features.d.ts

@@ -76,6 +76,14 @@ export interface TerrainDetailMaterialConfig {
     repeat?: number;
     /** Blend strength of the texture over the procedural/vertex-colour base, 0..1. Default 1. */
     strength?: number;
+    /**
+     * How much of the map's OWN colour replaces the terrain's authored colour, 0..1. Default 1 —
+     * at which the map's albedo wins and the biome tint, macro sweeps, and slope-rock blend under it
+     * are painted over, so a whole region flattens to the texture's single hue. Drop toward 0 to keep
+     * the authored colour and take only the map's grain (its light and shade), which is what a
+     * hand-tinted world wants from a stock PBR set.
+     */
+    tint?: number;
 }
 export interface TerrainFlattenMask {
     center: EnvironmentVec2;
@@ -283,6 +291,14 @@ export interface SkyEnvironmentConfig {
     hazeStrength?: number;
     /** Sun-glow brightness multiplier around the sun disc. Default 1. */
     sunGlowStrength?: number;
+    /**
+     * How fast the gradient reaches `zenithColor` off the horizon. Below 1 pulls the zenith hue down
+     * into the frame — the difference between a sky an eye-level camera actually sees and a horizon
+     * wash; above 1 keeps colour banked overhead. Default 0.65.
+     */
+    gradientExponent?: number;
+    /** Procedural cloud-band opacity over the gradient: 0 is a clear sky, 1 is heavy overcast. Default 0.35. */
+    cloudiness?: number;
     fog?: {
         color?: string;
         near?: number;

package/dist/world/features.js

@@ -122,6 +122,8 @@ export function sky(config = {}) {
         ...(config.radius === undefined ? {} : { radius: config.radius }),
         ...(config.hazeStrength === undefined ? {} : { hazeStrength: config.hazeStrength }),
         ...(config.sunGlowStrength === undefined ? {} : { sunGlowStrength: config.sunGlowStrength }),
+        ...(config.gradientExponent === undefined ? {} : { gradientExponent: config.gradientExponent }),
+        ...(config.cloudiness === undefined ? {} : { cloudiness: config.cloudiness }),
         ...(config.fog === undefined ? {} : { fog: config.fog }),
         ...(config.volumetricClouds === undefined ? {} : { volumetricClouds: config.volumetricClouds }),
     });

package/dist/world/grassKind.js

@@ -8,6 +8,7 @@
  * @capability grass-field editor-authorable GPU grass patch
  */
 import { registerSceneKind } from "../scene/sceneKinds.js";
+import { budgetWarning, densityCoverage } from "./scatterCoverage.js";
 /** The editor volume kind marking a box as a GPU grass patch. */
 export const GRASS_FIELD_KIND = "grass_field";
 /** Grass defaults: a lush, lightly-swaying meadow. */
@@ -89,13 +90,15 @@ export function registerGrassKind() {
         addCategory: "Studios",
         accent: "#7fbf4d",
         schema: GRASS_SCHEMA,
+        coverage: { spec: "grass_field", densityKey: "density" },
         resolve: (object) => resolveGrassObject(object),
         note: (object) => {
             const resolved = resolveGrassObject(object);
             if (resolved === null)
                 return "Give the volume a box footprint.";
             const area = resolved.size[0] * resolved.size[1];
-            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈${Math.round(area * resolved.rules.density).toLocaleString()} blades`;
+            const coverage = densityCoverage("grass_field", area, resolved.rules.density);
+            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈ ${coverage.count.toLocaleString()} blades${budgetWarning(coverage)}`;
         },
     });
 }

package/dist/world/grounded.d.ts

@@ -0,0 +1,11 @@
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * Ground an XZ point onto the live world surface as `[x, groundY, z]`.
+ *
+ * The one-line pose pattern every game re-derives as
+ * `[x, ctx.world.groundHeightAt(x, z), z]` — use this instead so spawn,
+ * placement, and AI pose sites stay consistent.
+ *
+ * @capability grounded ground an XZ point onto the world surface as a pose triple
+ */
+export declare function grounded(ctx: Pick<GameContext, "world">, x: number, z: number): readonly [number, number, number];

package/dist/world/grounded.js

@@ -0,0 +1,12 @@
+/**
+ * Ground an XZ point onto the live world surface as `[x, groundY, z]`.
+ *
+ * The one-line pose pattern every game re-derives as
+ * `[x, ctx.world.groundHeightAt(x, z), z]` — use this instead so spawn,
+ * placement, and AI pose sites stay consistent.
+ *
+ * @capability grounded ground an XZ point onto the world surface as a pose triple
+ */
+export function grounded(ctx, x, z) {
+    return [x, ctx.world.groundHeightAt(x, z), z];
+}

package/dist/world/mapAnnotations.d.ts

@@ -0,0 +1,75 @@
+import type { WorldXZ } from "./minimap.js";
+import type { MapLayerTone, MapRoute, MapZone, MapZoneShape } from "./mapLayers.js";
+/** A freehand drawn line on the map — a world-XZ polyline. */
+export interface MapStroke {
+    id: string;
+    points: readonly WorldXZ[];
+    tone?: MapLayerTone;
+    /** Line width in map pixels. */
+    width?: number;
+}
+/** A drawn area annotation (circle/rect/polygon), reusing the map-zone shape vocabulary. */
+export interface MapShapeAnnotation {
+    id: string;
+    shape: MapZoneShape;
+    tone?: MapLayerTone;
+    label?: string;
+}
+/** A text note pinned at a world point. */
+export interface MapNote {
+    id: string;
+    position: WorldXZ;
+    text: string;
+    tone?: MapLayerTone;
+}
+/** Whole serializable state of an annotation layer — drop into a save blob. */
+export interface AnnotationSnapshot {
+    strokes: readonly MapStroke[];
+    shapes: readonly MapShapeAnnotation[];
+    notes: readonly MapNote[];
+}
+/** Player-drawn map annotation layer — strokes, shapes, and notes over caller-owned map data. */
+export interface AnnotationLayer {
+    /** Add a freehand stroke; returns its id. Ignored (returns "") when fewer than 2 points. */
+    addStroke(points: readonly WorldXZ[], options?: {
+        id?: string;
+        tone?: MapLayerTone;
+        width?: number;
+    }): string;
+    addShape(shape: MapZoneShape, options?: {
+        id?: string;
+        tone?: MapLayerTone;
+        label?: string;
+    }): string;
+    addNote(position: WorldXZ, text: string, options?: {
+        id?: string;
+        tone?: MapLayerTone;
+    }): string;
+    remove(id: string): boolean;
+    clear(): void;
+    strokes(): readonly MapStroke[];
+    shapes(): readonly MapShapeAnnotation[];
+    notes(): readonly MapNote[];
+    /** Project strokes into `MapRoute`s for a map's `routes` prop. Stable identity between changes. */
+    routes(): readonly MapRoute[];
+    /** Project shapes into `MapZone`s for a map's `zones` prop. Stable identity between changes. */
+    zones(): readonly MapZone[];
+    subscribe(listener: () => void): () => void;
+    snapshot(): AnnotationSnapshot;
+    restore(snapshot: AnnotationSnapshot): void;
+}
+/** Options for {@link createAnnotationLayer}. */
+export interface AnnotationLayerOptions {
+    /** Default tone applied to strokes/shapes/notes added without an explicit one. Default `"info"`. */
+    defaultTone?: MapLayerTone;
+}
+/**
+ * Player-drawn map annotation layer: freehand `strokes`, area `shapes`, and
+ * pinned `notes`, all world-XZ and serializable. `routes()`/`zones()` project
+ * strokes/shapes into the exact shapes `Minimap`/`WorldMap`/`FullscreenMap`
+ * already render via their `routes`/`zones` props, so drawing needs no new
+ * renderer. State is plain data; `snapshot`/`restore` round-trip through a save.
+ *
+ * @capability map-annotations player-drawn map annotation layer — freehand strokes, area shapes, and pinned notes, projected into the map's routes/zones props and serializable
+ */
+export declare function createAnnotationLayer(options?: AnnotationLayerOptions): AnnotationLayer;