@jgengine/core 0.11.0 → 0.12.0

package/dist/world/features.d.ts

@@ -1,6 +1,7 @@
 import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
 import type { AvoidZone } from "./geometry.js";
 import type { TerrainPathProfile } from "./pathTerrain.js";
+import type { PlaceWorldFeature } from "./place.js";
 import type { TerraformSnapshot } from "./terraform.js";
 import type { VolumetricCloudsConfig } from "./volumetricClouds.js";
 export interface WorldBounds {
@@ -464,8 +465,13 @@ export interface PlotsWorldConfig extends WorldGridConfig {
 export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
 }
-/** A declared world shape — biomes, voxel grid, plots, tilemap, environment, or flat — passed to `defineGame`. */
-export type WorldFeature = ({
+/**
+ * A declared world shape passed to `defineGame`. The preferred model is the place feature from
+ * `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the
+ * editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the
+ * legacy code-declared shapes kept for existing games.
+ */
+export type WorldFeature = PlaceWorldFeature | ({
     kind: "biomes";
 } & BiomesWorldConfig) | ({
     kind: "voxel";
@@ -478,7 +484,16 @@ export type WorldFeature = ({
 };
 /** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. Elevated pads (absolute `elevation`) float free and carve nothing. */
 export declare function padFlattenMasks(pads: readonly PadEnvironmentDescriptor[]): readonly TerrainFlattenMask[];
-/** Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads. */
+/** Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+ *
+ * Legacy dressing-in-code path — not how a world is defined. A world is the place you play in
+ * (`world()` from `world/place`: ground + laws); sky look, foliage scatter, props, and sculpt are
+ * scene content authored in the editor. Reach for `environment()` only when consuming
+ * editor/preset-written scene data (`environmentContentFromDocument`) or maintaining an existing
+ * game; never scaffold new worlds from it.
+ *
+ * @capability world-environment compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+ */
 export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
 /** Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks. */
 export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;

package/dist/world/features.js

@@ -43,7 +43,16 @@ function bandWeatherDescriptors(terrainDescriptor) {
     }
     return out;
 }
-/** Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads. */
+/** Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+ *
+ * Legacy dressing-in-code path — not how a world is defined. A world is the place you play in
+ * (`world()` from `world/place`: ground + laws); sky look, foliage scatter, props, and sculpt are
+ * scene content authored in the editor. Reach for `environment()` only when consuming
+ * editor/preset-written scene data (`environmentContentFromDocument`) or maintaining an existing
+ * game; never scaffold new worlds from it.
+ *
+ * @capability world-environment compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+ */
 export function environment(config = {}) {
     const explicitWeather = list(config.weather);
     const bandWeather = bandWeatherDescriptors(config.terrain);

package/dist/world/grassKind.js

@@ -12,7 +12,7 @@ import { registerSceneKind } from "../scene/sceneKinds.js";
 export const GRASS_FIELD_KIND = "grass_field";
 /** Grass defaults: a lush, lightly-swaying meadow. */
 export const GRASS_DEFAULTS = {
-    density: 4,
+    density: 12,
     bladeHeight: 0.6,
     colorBase: "#3f6f37",
     colorTip: "#9ac25a",
@@ -26,7 +26,7 @@ export const GRASS_DEFAULTS = {
 /** The grass parameter schema — drives the inspector and `meta` parse via the studio seam. */
 export const GRASS_SCHEMA = {
     fields: [
-        { type: "range", key: "density", label: "density", min: 0.5, max: 16, step: 0.5, default: GRASS_DEFAULTS.density, unit: "/m²" },
+        { type: "range", key: "density", label: "density", min: 0.5, max: 160, step: 0.5, default: GRASS_DEFAULTS.density, unit: "/m²" },
         { type: "range", key: "bladeHeight", label: "blade height", min: 0.1, max: 2, step: 0.05, default: GRASS_DEFAULTS.bladeHeight, unit: "m" },
         { type: "color", key: "colorBase", label: "base color", default: GRASS_DEFAULTS.colorBase },
         { type: "color", key: "colorTip", label: "tip color", default: GRASS_DEFAULTS.colorTip },

package/dist/world/markers.d.ts

@@ -1,19 +1,32 @@
 export type MarkerPosition = readonly [number, number, number];
-export interface MapMarker<TMeta = unknown> {
+/**
+ * Small, display-only marker shape consumed by map renderers. Existing games
+ * can project their own entities to this view without adopting marker
+ * lifecycle storage or duplicating them into a {@link MarkerSet}.
+ */
+export interface MarkerView<TMeta = unknown> {
     id: string;
-    kind: string;
     position: MarkerPosition;
+    kind?: string;
     label?: string;
+    /** Optional world heading in radians for presentations that draw directional markers. */
+    heading?: number;
+    meta?: TMeta;
+}
+/** A marker owned by {@link MarkerSet}, including its lifecycle and query fields. */
+export interface MapMarker<TMeta = unknown> extends MarkerView<TMeta> {
+    kind: string;
     owner?: string;
     createdAt: number;
     expiresAt?: number;
-    meta?: TMeta;
 }
 export interface MarkerInput<TMeta = unknown> {
     id?: string;
     kind: string;
     position: MarkerPosition;
     label?: string;
+    /** Optional world heading in radians for directional map presentations. */
+    heading?: number;
     owner?: string;
     createdAt?: number;
     expiresAt?: number;
@@ -37,7 +50,7 @@ export interface MarkerKindStyle {
     priority: number;
 }
 export declare const DEFAULT_MARKER_KINDS: Record<string, MarkerKindStyle>;
-export declare function markerKindStyle(kind: string, styles?: Record<string, MarkerKindStyle>): MarkerKindStyle;
+export declare function markerKindStyle(kind: string | undefined, styles?: Record<string, MarkerKindStyle>): MarkerKindStyle;
 export interface MarkerSet<TMeta = unknown> {
     add(marker: MarkerInput<TMeta>): string;
     remove(id: string): boolean;
@@ -49,4 +62,37 @@ export interface MarkerSet<TMeta = unknown> {
     subscribe(listener: () => void): () => void;
     snapshot(): readonly MapMarker<TMeta>[];
 }
+/**
+ * Observable marker snapshots owned by an external project. `getSnapshot`
+ * must return the same array identity until the source changes and calls its
+ * subscribers, matching React's external-store contract.
+ */
+export interface MarkerSource<TMarker extends MarkerView = MarkerView> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): readonly TMarker[];
+    /** Optional hydration snapshot; omit when the client snapshot is also valid during SSR. */
+    getServerSnapshot?: () => readonly TMarker[];
+}
+/** Marker data accepted by portable consumers: static views, an external source, or a native set. */
+export type MarkerCollection<TMarker extends MarkerView = MarkerView> = readonly TMarker[] | MarkerSource<TMarker> | MarkerSet;
+/** Configuration for projecting a caller-owned collection into display-only markers. */
+export interface MarkerSourceOptions<TEntity, TMarker extends MarkerView = MarkerView> {
+    /** Subscribe to changes in the caller-owned collection. Static collections may omit this. */
+    subscribe?: (listener: () => void) => () => void;
+    /** Read the current caller-owned collection. Keep its identity stable between changes. */
+    getSnapshot: () => readonly TEntity[];
+    /** Optional server collection used to keep hydration output deterministic. */
+    getServerSnapshot?: () => readonly TEntity[];
+    /** Project one caller-owned record into the minimal marker view. */
+    project: (value: TEntity, index: number) => TMarker;
+}
+/**
+ * Adapt a caller-owned array/store to an observable marker source. Projection
+ * is cached between source changes, so React reads do not copy the collection
+ * per frame. The caller retains ownership of entities, updates, persistence,
+ * and subscription scheduling.
+ *
+ * @capability portable-marker-source project caller-owned arrays or subscribable stores into cached minimap marker snapshots without a MarkerSet
+ */
+export declare function createMarkerSource<TEntity, TMarker extends MarkerView = MarkerView>(options: MarkerSourceOptions<TEntity, TMarker>): MarkerSource<TMarker>;
 export declare function createMarkerSet<TMeta = unknown>(now?: () => number): MarkerSet<TMeta>;

package/dist/world/markers.js

@@ -10,8 +10,55 @@ export const DEFAULT_MARKER_KINDS = {
     ping: { id: "ping", color: "#22d3ee", glyph: "◎", priority: 65 },
 };
 export function markerKindStyle(kind, styles = DEFAULT_MARKER_KINDS) {
+    if (kind === undefined)
+        return { id: "marker", color: "#e2e8f0", glyph: "\u2022", priority: 30 };
     return styles[kind] ?? { id: kind, color: "#e2e8f0", glyph: "•", priority: 30 };
 }
+function projectedSnapshot(readSource, project) {
+    let dirty = true;
+    let source;
+    let snapshot = [];
+    return {
+        invalidate() {
+            dirty = true;
+        },
+        read() {
+            const next = readSource();
+            if (dirty || next !== source) {
+                source = next;
+                snapshot = next.map(project);
+                dirty = false;
+            }
+            return snapshot;
+        },
+    };
+}
+/**
+ * Adapt a caller-owned array/store to an observable marker source. Projection
+ * is cached between source changes, so React reads do not copy the collection
+ * per frame. The caller retains ownership of entities, updates, persistence,
+ * and subscription scheduling.
+ *
+ * @capability portable-marker-source project caller-owned arrays or subscribable stores into cached minimap marker snapshots without a MarkerSet
+ */
+export function createMarkerSource(options) {
+    const client = projectedSnapshot(options.getSnapshot, options.project);
+    const server = options.getServerSnapshot === undefined
+        ? client
+        : projectedSnapshot(options.getServerSnapshot, options.project);
+    return {
+        subscribe(listener) {
+            if (options.subscribe === undefined)
+                return () => undefined;
+            return options.subscribe(() => {
+                client.invalidate();
+                listener();
+            });
+        },
+        getSnapshot: client.read,
+        getServerSnapshot: server.read,
+    };
+}
 function distanceXZ(a, b) {
     return Math.hypot(a[0] - b[0], a[2] - b[2]);
 }
@@ -38,6 +85,8 @@ export function createMarkerSet(now = Date.now) {
             };
             if (input.label !== undefined)
                 marker.label = input.label;
+            if (input.heading !== undefined)
+                marker.heading = input.heading;
             if (input.owner !== undefined)
                 marker.owner = input.owner;
             if (input.expiresAt !== undefined)

package/dist/world/massing.js

@@ -1,3 +1,4 @@
+import { clamp } from "../math/scalar.js";
 export const MASSING_COMPOSITIONS = [
     "bar",
     "split",
@@ -17,7 +18,6 @@ export const MASSING_PROFILES = [
     "offset",
     "twisted",
 ];
-const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 export const hashMassingSeed = (text) => [...text].reduce((sum, ch) => sum + ch.charCodeAt(0), 0);
 export const massingBase = (spec, cap = 0.28) => Math.min(Math.max(0, spec.pilotis), Math.max(0, spec.height) * cap);
 export const isVillageMassing = (spec) => spec.composition === "cluster" && spec.height < 36 && spec.articulation > 56 && spec.moduleDensity > 2;

package/dist/world/minimapBake.d.ts

@@ -0,0 +1,78 @@
+import type { Vec2 } from "./geometry.js";
+/**
+ * Deterministic minimap terrain bake (#1036): rasterize an authored world's terrain (plus optional
+ * biome zones and water) into a top-down RGBA image and a matching world-bounds rectangle, then
+ * encode it as a PNG data URI. The editor runs this as a bake action and stores the result on the
+ * scene document; runtime feeds it straight into the existing `Minimap` / `WorldMap` `background` +
+ * `mapBounds` props — no new runtime render path, and the same authored world always bakes the same
+ * image (safe for verify/CI). Pure: no canvas, no DOM, `core` still imports nothing external.
+ */
+/** World-space rectangle the bake spans (matches the react `MapBounds` shape structurally). */
+export interface MinimapBakeBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/** One biome/region tint painted over the terrain shade where the ground falls inside its polygon. */
+export interface MinimapBakeZone {
+    /** Closed XZ polygon in world space. */
+    polygon: readonly Vec2[];
+    /** `#rgb` / `#rrggbb` tint. */
+    color: string;
+    /** Blend strength 0..1. Default 0.5. */
+    alpha?: number;
+}
+/** The authored world a bake reads — a height sampler, its bounds, and optional zones/water. */
+export interface MinimapBakeSource {
+    bounds: MinimapBakeBounds;
+    sampleHeight(x: number, z: number): number;
+    /** Optional surface normal for slope shading; flat shading when omitted. */
+    sampleNormal?(x: number, z: number): readonly [number, number, number];
+    zones?: readonly MinimapBakeZone[];
+    /** Ground at or below this height renders as water. */
+    waterLevel?: number;
+}
+/** The height→color ramp and water color used by the bake. */
+export interface MinimapBakePalette {
+    low: string;
+    high: string;
+    water: string;
+}
+/** The built-in height→color ramp and water color a bake uses when no palette override is given. */
+export declare const DEFAULT_MINIMAP_PALETTE: MinimapBakePalette;
+/** Options for {@link bakeMinimapImage}. */
+export interface MinimapBakeOptions {
+    /** Pixel resolution of the longer axis; the shorter axis keeps world aspect. Default 128. */
+    resolution?: number;
+    palette?: Partial<MinimapBakePalette>;
+}
+/** A baked minimap image: RGBA pixels plus the world bounds they span. */
+export interface MinimapBake {
+    width: number;
+    height: number;
+    /** Row-major RGBA, length `width * height * 4`. */
+    pixels: Uint8ClampedArray;
+    bounds: MinimapBakeBounds;
+}
+/**
+ * Rasterizes a top-down terrain image: height maps onto a low→high color ramp (normalized over the
+ * sampled height range), slope darkens the shade, water fills below `waterLevel`, and each zone
+ * polygon tints the ground it covers. Deterministic for a fixed source. The bounds are preserved so
+ * a player-centered minimap pans the image correctly.
+ * @capability minimap-bake rasterize authored terrain + zones into a top-down minimap image
+ */
+export declare function bakeMinimapImage(source: MinimapBakeSource, options?: MinimapBakeOptions): MinimapBake;
+/** Encodes an RGBA bake to raw PNG bytes (pure; stored DEFLATE, valid for any decoder). */
+export declare function encodeBakePng(bake: MinimapBake): Uint8Array;
+/**
+ * Encodes a bake as a `data:image/png;base64,...` URI — the exact string the `Minimap` /
+ * `WorldMap` `background` prop takes. Deterministic for a fixed bake.
+ * @capability minimap-bake encode a baked minimap as a PNG data URI for the Minimap background
+ */
+export declare function minimapBakeToPngDataUri(bake: MinimapBake): string;
+/** One-call convenience: rasterize a source and return `{ background, mapBounds }` for a minimap. */
+export declare function bakeMinimapBackground(source: MinimapBakeSource, options?: MinimapBakeOptions): {
+    background: string;
+    mapBounds: MinimapBakeBounds;
+};

package/dist/world/minimapBake.js

@@ -0,0 +1,208 @@
+import { pointInPolygon } from "./scatterRegion.js";
+/** The built-in height→color ramp and water color a bake uses when no palette override is given. */
+export const DEFAULT_MINIMAP_PALETTE = {
+    low: "#3f5d34",
+    high: "#cdbb93",
+    water: "#2f5d78",
+};
+function parseHex(hex) {
+    let value = hex.trim().replace(/^#/, "");
+    if (value.length === 3)
+        value = value.split("").map((c) => c + c).join("");
+    const int = Number.parseInt(value, 16);
+    if (!Number.isFinite(int) || value.length !== 6)
+        return { r: 0, g: 0, b: 0 };
+    return { r: (int >> 16) & 0xff, g: (int >> 8) & 0xff, b: int & 0xff };
+}
+function mix(a, b, t) {
+    const k = Math.max(0, Math.min(1, t));
+    return {
+        r: Math.round(a.r + (b.r - a.r) * k),
+        g: Math.round(a.g + (b.g - a.g) * k),
+        b: Math.round(a.b + (b.b - a.b) * k),
+    };
+}
+/**
+ * Rasterizes a top-down terrain image: height maps onto a low→high color ramp (normalized over the
+ * sampled height range), slope darkens the shade, water fills below `waterLevel`, and each zone
+ * polygon tints the ground it covers. Deterministic for a fixed source. The bounds are preserved so
+ * a player-centered minimap pans the image correctly.
+ * @capability minimap-bake rasterize authored terrain + zones into a top-down minimap image
+ */
+export function bakeMinimapImage(source, options = {}) {
+    const resolution = Math.max(8, Math.floor(options.resolution ?? 128));
+    const palette = { ...DEFAULT_MINIMAP_PALETTE, ...options.palette };
+    const low = parseHex(palette.low);
+    const high = parseHex(palette.high);
+    const water = parseHex(palette.water);
+    const { minX, minZ, maxX, maxZ } = source.bounds;
+    const spanX = Math.max(1e-6, maxX - minX);
+    const spanZ = Math.max(1e-6, maxZ - minZ);
+    // Longer world axis gets `resolution` pixels; the other keeps aspect.
+    const width = spanX >= spanZ ? resolution : Math.max(8, Math.round((spanX / spanZ) * resolution));
+    const height = spanZ >= spanX ? resolution : Math.max(8, Math.round((spanZ / spanX) * resolution));
+    const worldX = (px) => minX + ((px + 0.5) / width) * spanX;
+    const worldZ = (py) => minZ + ((py + 0.5) / height) * spanZ;
+    // First pass: height range for a stable ramp.
+    let hMin = Infinity;
+    let hMax = -Infinity;
+    const heights = new Float64Array(width * height);
+    for (let py = 0; py < height; py += 1) {
+        for (let px = 0; px < width; px += 1) {
+            const h = source.sampleHeight(worldX(px), worldZ(py));
+            heights[py * width + px] = h;
+            if (h < hMin)
+                hMin = h;
+            if (h > hMax)
+                hMax = h;
+        }
+    }
+    const hSpan = Math.max(1e-6, hMax - hMin);
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    const zones = source.zones ?? [];
+    for (let py = 0; py < height; py += 1) {
+        for (let px = 0; px < width; px += 1) {
+            const wx = worldX(px);
+            const wz = worldZ(py);
+            const h = heights[py * width + px];
+            let color;
+            if (source.waterLevel !== undefined && h <= source.waterLevel) {
+                color = water;
+            }
+            else {
+                color = mix(low, high, (h - hMin) / hSpan);
+                if (source.sampleNormal !== undefined) {
+                    const n = source.sampleNormal(wx, wz);
+                    const shade = 0.62 + 0.38 * Math.max(0, Math.min(1, n[1]));
+                    color = { r: Math.round(color.r * shade), g: Math.round(color.g * shade), b: Math.round(color.b * shade) };
+                }
+            }
+            for (const zone of zones) {
+                if (pointInPolygon([wx, wz], zone.polygon)) {
+                    color = mix(color, parseHex(zone.color), zone.alpha ?? 0.5);
+                }
+            }
+            const index = (py * width + px) * 4;
+            pixels[index] = color.r;
+            pixels[index + 1] = color.g;
+            pixels[index + 2] = color.b;
+            pixels[index + 3] = 255;
+        }
+    }
+    return { width, height, pixels, bounds: { minX, minZ, maxX, maxZ } };
+}
+// --- Minimal pure PNG encoder (RGBA, stored/uncompressed DEFLATE) ------------------------------
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i += 1)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function adler32(bytes) {
+    let a = 1;
+    let b = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+        a = (a + bytes[i]) % 65521;
+        b = (b + a) % 65521;
+    }
+    return ((b << 16) | a) >>> 0;
+}
+/** Wraps raw bytes in a zlib stream using only stored (uncompressed) DEFLATE blocks. */
+function zlibStore(data) {
+    const blocks = [0x78, 0x01]; // zlib header (no compression)
+    let offset = 0;
+    while (offset < data.length) {
+        const chunk = Math.min(0xffff, data.length - offset);
+        const final = offset + chunk >= data.length ? 1 : 0;
+        blocks.push(final, chunk & 0xff, (chunk >> 8) & 0xff, ~chunk & 0xff, (~chunk >> 8) & 0xff);
+        for (let i = 0; i < chunk; i += 1)
+            blocks.push(data[offset + i]);
+        offset += chunk;
+    }
+    const checksum = adler32(data);
+    blocks.push((checksum >>> 24) & 0xff, (checksum >>> 16) & 0xff, (checksum >>> 8) & 0xff, checksum & 0xff);
+    return Uint8Array.from(blocks);
+}
+function chunk(type, data) {
+    const typeBytes = Uint8Array.from([...type].map((c) => c.charCodeAt(0)));
+    const body = new Uint8Array(typeBytes.length + data.length);
+    body.set(typeBytes, 0);
+    body.set(data, typeBytes.length);
+    const crc = crc32(body);
+    const out = new Uint8Array(4 + body.length + 4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, data.length);
+    out.set(body, 4);
+    view.setUint32(4 + body.length, crc);
+    return out;
+}
+function base64(bytes) {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        out += chars[b0 >> 2];
+        out += chars[((b0 & 3) << 4) | (b1 >> 4)];
+        out += i + 1 < bytes.length ? chars[((b1 & 15) << 2) | (b2 >> 6)] : "=";
+        out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
+    }
+    return out;
+}
+/** Encodes an RGBA bake to raw PNG bytes (pure; stored DEFLATE, valid for any decoder). */
+export function encodeBakePng(bake) {
+    const { width, height, pixels } = bake;
+    const ihdr = new Uint8Array(13);
+    const ihdrView = new DataView(ihdr.buffer);
+    ihdrView.setUint32(0, width);
+    ihdrView.setUint32(4, height);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 6; // color type RGBA
+    // 10,11,12 = compression/filter/interlace = 0
+    // Filtered scanlines: filter byte 0 (none) per row.
+    const raw = new Uint8Array(height * (1 + width * 4));
+    for (let y = 0; y < height; y += 1) {
+        const rowStart = y * (1 + width * 4);
+        raw[rowStart] = 0;
+        raw.set(pixels.subarray(y * width * 4, (y + 1) * width * 4), rowStart + 1);
+    }
+    const signature = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const parts = [
+        signature,
+        chunk("IHDR", ihdr),
+        chunk("IDAT", zlibStore(raw)),
+        chunk("IEND", new Uint8Array(0)),
+    ];
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/**
+ * Encodes a bake as a `data:image/png;base64,...` URI — the exact string the `Minimap` /
+ * `WorldMap` `background` prop takes. Deterministic for a fixed bake.
+ * @capability minimap-bake encode a baked minimap as a PNG data URI for the Minimap background
+ */
+export function minimapBakeToPngDataUri(bake) {
+    return `data:image/png;base64,${base64(encodeBakePng(bake))}`;
+}
+/** One-call convenience: rasterize a source and return `{ background, mapBounds }` for a minimap. */
+export function bakeMinimapBackground(source, options = {}) {
+    const bake = bakeMinimapImage(source, options);
+    return { background: minimapBakeToPngDataUri(bake), mapBounds: bake.bounds };
+}

package/dist/world/minimapTrack.d.ts

@@ -0,0 +1,17 @@
+import type { WorldXZ } from "./minimap.js";
+/** A world-space segment defining a linear "track" minimap — points are projected onto the `from`→`to` axis. */
+export interface TrackAxis {
+    from: WorldXZ;
+    to: WorldXZ;
+}
+/**
+ * Project a world point onto the `from`→`to` segment of `axis` and return the
+ * clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at
+ * `to`). The linear analogue of `projectToMinimap` — feeds a horizontal
+ * corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`)
+ * points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length
+ * axis returns 0.
+ *
+ * @capability minimap-track project a world point to a 0..1 fraction along a linear track axis
+ */
+export declare function trackFraction(point: WorldXZ | readonly [number, number, number], axis: TrackAxis): number;

package/dist/world/minimapTrack.js

@@ -0,0 +1,22 @@
+/**
+ * Project a world point onto the `from`→`to` segment of `axis` and return the
+ * clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at
+ * `to`). The linear analogue of `projectToMinimap` — feeds a horizontal
+ * corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`)
+ * points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length
+ * axis returns 0.
+ *
+ * @capability minimap-track project a world point to a 0..1 fraction along a linear track axis
+ */
+export function trackFraction(point, axis) {
+    const px = point[0];
+    const pz = point.length === 3 ? point[2] : point[1];
+    const ax = axis.to[0] - axis.from[0];
+    const az = axis.to[1] - axis.from[1];
+    const lengthSq = ax * ax + az * az;
+    if (lengthSq === 0)
+        return 0;
+    const dot = (px - axis.from[0]) * ax + (pz - axis.from[1]) * az;
+    const fraction = dot / lengthSq;
+    return fraction < 0 ? 0 : fraction > 1 ? 1 : fraction;
+}