@jgengine/core 0.14.0 → 0.15.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

@@ -35,7 +35,7 @@ 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. */
@@ -666,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();

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/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;

package/dist/world/mapAnnotations.js

@@ -0,0 +1,139 @@
+/**
+ * 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 function createAnnotationLayer(options = {}) {
+    const defaultTone = options.defaultTone ?? "info";
+    const strokeStore = new Map();
+    const shapeStore = new Map();
+    const noteStore = new Map();
+    const listeners = new Set();
+    let counter = 0;
+    let strokeCache = null;
+    let shapeCache = null;
+    let noteCache = null;
+    let routeCache = null;
+    let zoneCache = null;
+    function invalidate() {
+        strokeCache = null;
+        shapeCache = null;
+        noteCache = null;
+        routeCache = null;
+        zoneCache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function generateId() {
+        let id = `annotation-${counter}`;
+        while (strokeStore.has(id) || shapeStore.has(id) || noteStore.has(id)) {
+            counter += 1;
+            id = `annotation-${counter}`;
+        }
+        counter += 1;
+        return id;
+    }
+    const layer = {
+        addStroke(points, opts = {}) {
+            if (points.length < 2)
+                return "";
+            const id = opts.id ?? generateId();
+            const stroke = {
+                id,
+                points: points.map((p) => [p[0], p[1]]),
+                tone: opts.tone ?? defaultTone,
+                ...(opts.width !== undefined ? { width: opts.width } : {}),
+            };
+            strokeStore.set(id, stroke);
+            invalidate();
+            return id;
+        },
+        addShape(shape, opts = {}) {
+            const id = opts.id ?? generateId();
+            shapeStore.set(id, { id, shape, tone: opts.tone ?? defaultTone, ...(opts.label !== undefined ? { label: opts.label } : {}) });
+            invalidate();
+            return id;
+        },
+        addNote(position, text, opts = {}) {
+            const id = opts.id ?? generateId();
+            noteStore.set(id, { id, position: [position[0], position[1]], text, tone: opts.tone ?? defaultTone });
+            invalidate();
+            return id;
+        },
+        remove(id) {
+            const existed = strokeStore.delete(id) || shapeStore.delete(id) || noteStore.delete(id);
+            if (existed)
+                invalidate();
+            return existed;
+        },
+        clear() {
+            if (strokeStore.size === 0 && shapeStore.size === 0 && noteStore.size === 0)
+                return;
+            strokeStore.clear();
+            shapeStore.clear();
+            noteStore.clear();
+            invalidate();
+        },
+        strokes() {
+            if (strokeCache === null)
+                strokeCache = [...strokeStore.values()];
+            return strokeCache;
+        },
+        shapes() {
+            if (shapeCache === null)
+                shapeCache = [...shapeStore.values()];
+            return shapeCache;
+        },
+        notes() {
+            if (noteCache === null)
+                noteCache = [...noteStore.values()];
+            return noteCache;
+        },
+        routes() {
+            if (routeCache === null) {
+                routeCache = layer.strokes().map((stroke) => ({
+                    id: stroke.id,
+                    points: stroke.points,
+                    ...(stroke.tone !== undefined ? { tone: stroke.tone } : {}),
+                    ...(stroke.width !== undefined ? { width: stroke.width } : {}),
+                }));
+            }
+            return routeCache;
+        },
+        zones() {
+            if (zoneCache === null) {
+                zoneCache = layer.shapes().map((annotation) => ({
+                    id: annotation.id,
+                    shape: annotation.shape,
+                    ...(annotation.tone !== undefined ? { tone: annotation.tone } : {}),
+                    ...(annotation.label !== undefined ? { label: annotation.label } : {}),
+                }));
+            }
+            return zoneCache;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { strokes: layer.strokes(), shapes: layer.shapes(), notes: layer.notes() };
+        },
+        restore(snapshot) {
+            strokeStore.clear();
+            shapeStore.clear();
+            noteStore.clear();
+            for (const stroke of snapshot.strokes)
+                strokeStore.set(stroke.id, stroke);
+            for (const shape of snapshot.shapes)
+                shapeStore.set(shape.id, shape);
+            for (const note of snapshot.notes)
+                noteStore.set(note.id, note);
+            invalidate();
+        },
+    };
+    return layer;
+}

package/dist/world/markers.js

@@ -8,6 +8,7 @@ export const DEFAULT_MARKER_KINDS = {
     enemy: { id: "enemy", color: "#f87171", glyph: "✖", priority: 80 },
     danger: { id: "danger", color: "#fb923c", glyph: "⚠", priority: 85 },
     ping: { id: "ping", color: "#22d3ee", glyph: "◎", priority: 65 },
+    waypoint: { id: "waypoint", color: "#f59e0b", glyph: "⚑", priority: 95 },
 };
 export function markerKindStyle(kind, styles = DEFAULT_MARKER_KINDS) {
     if (kind === undefined)

package/dist/world/resourceNode.d.ts

@@ -71,7 +71,7 @@ export interface ResourceNodeState {
 /** Construction options for {@link createResourceNodeField}: node definitions and an optional RNG/suppression hook. */
 export interface ResourceNodeFieldConfig {
     nodes: readonly ResourceNodeDef[];
-    /** Injected [0,1) generator for deterministic yield variance; defaults to `Math.random`. */
+    /** Injected [0,1) generator for deterministic yield variance. Omitting it falls back to `Math.random` and warns once. */
     rng?: () => number;
     /**
      * Freeze respawn for a node while this returns true — a structure within radius, a nearby occupant.

package/dist/world/resourceNode.js

@@ -1,4 +1,5 @@
 import { clamp } from "../math/scalar.js";
+import { resolveRng } from "../random/resolveRng.js";
 function resolveQuantity(quantity, rng) {
     if (typeof quantity === "number")
         return quantity;
@@ -29,7 +30,7 @@ function toState(node) {
  * @capability resource-node depletable, respawning harvest nodes with tool-dependent yields
  */
 export function createResourceNodeField(config) {
-    const rng = config.rng ?? Math.random;
+    const rng = resolveRng(config.rng, "createResourceNode");
     const nodes = new Map();
     const order = [];
     for (const def of config.nodes) {