@jgengine/core 0.11.0 → 0.13.0

package/dist/editor/entityCatalog.js

@@ -0,0 +1,101 @@
+import { parseParams } from "../scene/sceneKinds.js";
+/**
+ * Well-known catalog id for authored entity definitions. A `mob`/`boss` marker's `catalogId`
+ * references an entry (row) in this catalog, and {@link entityEntryFromCatalog} turns that row into
+ * the runtime {@link GameContextEntityEntry} a spawn consumes — so an entity's stats and speed are
+ * authored in the editor Data tab, not hardcoded in game TS.
+ */
+export const ENTITY_CATALOG_ID = "entities";
+const ENTITY_ROLES = ["player", "enemy", "hostile", "npc", "vehicle"];
+/**
+ * The default {@link ParamSchema} for an authored entity definition — role, health, movement speed,
+ * and visual scale. Drives the editor Data-tab inspector for the `entities` catalog and is the shape
+ * {@link entityEntryFromCatalog} reads. A game exports it as an `editorCatalogs` schema; the scaffold
+ * ships a starter one so the tab is never empty.
+ * @capability editor-entities Author entity stats/movement per catalog row instead of hardcoding TS.
+ */
+export const entityDefinitionSchema = {
+    fields: [
+        {
+            key: "role",
+            type: "select",
+            label: "Role",
+            default: "enemy",
+            options: ENTITY_ROLES.map((role) => ({ value: role })),
+        },
+        { key: "maxHealth", type: "number", label: "Max health", default: 20, min: 1, max: 100000, step: 1 },
+        { key: "walkSpeed", type: "range", label: "Walk speed", default: 3, min: 0, max: 20, step: 0.1, unit: "m/s" },
+        { key: "scale", type: "range", label: "Scale", default: 1, min: 0.1, max: 10, step: 0.1 },
+    ],
+};
+function entityCatalogDefinition(definitions) {
+    return definitions?.find((definition) => definition.id === ENTITY_CATALOG_ID);
+}
+/**
+ * Resolves the merged `meta` for one entity row: game-exported defaults (from `definitions`, if
+ * given) overlaid by the values persisted on the scene document. Returns `undefined` when neither
+ * source carries the row, so callers can distinguish "no such entity" from "default entity".
+ */
+function mergedEntityMeta(document, entityId, definitions) {
+    const defaultEntry = entityCatalogDefinition(definitions)?.entries.find((entry) => entry.id === entityId);
+    const authored = document.catalogs
+        .find((catalog) => catalog.id === ENTITY_CATALOG_ID)
+        ?.entries.find((entry) => entry.id === entityId);
+    if (defaultEntry === undefined && authored === undefined)
+        return undefined;
+    return { ...defaultEntry?.meta, ...authored?.meta };
+}
+/**
+ * Turns an authored entity row into the runtime {@link GameContextEntityEntry} a spawn consumes:
+ * looks up `entityId` in the document's {@link ENTITY_CATALOG_ID} catalog (falling back to the
+ * game-exported `definitions` defaults), parses it against {@link entityDefinitionSchema}, and maps
+ * the fields onto stats/movement/role. Returns `null` when no row defines the entity, so the default
+ * `content.ts` path can chain other resolvers. The single seam that makes "place a mob, tune its
+ * stats/speed in the editor, save — it spawns with those stats" work with zero game code.
+ * @capability editor-entities Consume authored entity definitions from the scene document at runtime.
+ */
+export function entityEntryFromCatalog(document, entityId, definitions) {
+    const meta = mergedEntityMeta(document, entityId, definitions);
+    if (meta === undefined)
+        return null;
+    // Prefer a document-carried schema for the entities catalog (an editor-authored schema) over the
+    // hardcoded default, so a game that re-authored the entity fields in the editor drives the parse.
+    const schema = document.catalogs.find((catalog) => catalog.id === ENTITY_CATALOG_ID)?.schema ?? entityDefinitionSchema;
+    const params = parseParams(schema, meta);
+    const role = params.role;
+    const maxHealth = params.maxHealth;
+    const walkSpeed = params.walkSpeed;
+    const scale = params.scale;
+    const entry = {
+        role,
+        stats: { health: { max: maxHealth, min: 0 } },
+        receive: { damage: { order: ["health"] } },
+        movement: { walkSpeed },
+    };
+    if (scale !== 1)
+        entry.scale = scale;
+    return entry;
+}
+/**
+ * Merges game-exported catalog definitions with editor-authored ones carried on the scene document.
+ * A document catalog that carries its own `schema` and has no matching game definition is synthesized
+ * into a full {@link EditorCatalogDefinition} (label falls back to the id) so the Data panel, the
+ * `list_catalogs` RPC, and the count all see it. A game definition always wins on id collision — its
+ * schema lives in code and is authoritative. Document catalogs without a schema (plain value bags for
+ * a game-declared catalog) are ignored here; they are addressed through their game definition.
+ * @capability editor-catalogs Merge game-exported and editor-authored catalogs into one addressable set.
+ */
+export function resolveCatalogDefinitions(document, gameDefinitions) {
+    const byId = new Map(gameDefinitions.map((definition) => [definition.id, definition]));
+    for (const catalog of document.catalogs) {
+        if (catalog.schema === undefined || byId.has(catalog.id))
+            continue;
+        byId.set(catalog.id, {
+            id: catalog.id,
+            label: catalog.label ?? catalog.id,
+            schema: catalog.schema,
+            entries: catalog.entries,
+        });
+    }
+    return [...byId.values()];
+}

package/dist/editor/environment.d.ts

@@ -0,0 +1,74 @@
+import type { SkyEnvironmentConfig, WorldBounds } from "../world/features.js";
+import type { AvoidZone } from "../world/geometry.js";
+import { type ClearanceOptions } from "../world/scatterRegion.js";
+import type { TerraformSnapshot } from "../world/terraform.js";
+import type { EditorDocument, EditorEnvironment } from "./types.js";
+/**
+ * World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement**
+ * content of an `environment()` world from the scene document, so a game with an authored document
+ * needs no coordinate arrays in `world.ts` — the remaining `world.ts` surface is engine tuning
+ * (noise, materials, sky preset, physics). Terrain footprint follows the authored objects, ground
+ * clearings come from authored spawns/POIs (`clearanceZonesFrom`), and the sculpt snapshot is the
+ * document's own terrain overlay. Pure and serializable; consumers pass the result straight to
+ * `environment({ terrain: terrain({ bounds }), clearings, sculpt })`.
+ */
+/** Options controlling how {@link environmentContentFromDocument} sizes and clears the world. */
+export interface EnvironmentContentOptions extends ClearanceOptions {
+    /** Padding (m) added around the authored objects' extent when sizing the terrain. Default 24. */
+    padding?: number;
+    /** Minimum terrain footprint so a sparse document still yields a walkable world. Default 64×64. */
+    minBounds?: WorldBounds;
+}
+/** The coordinate/placement content of a world, derived from its scene document. */
+export interface EnvironmentContent {
+    /** Terrain footprint (origin-centered) sized to cover every authored object plus padding. */
+    bounds: WorldBounds;
+    /** Ground-flatten discs under authored spawns/plots/POIs — feed `environment({ clearings })`. */
+    clearings: AvoidZone[];
+    /** The document's authored sculpt snapshot, when it has one — feed `environment({ sculpt })`. */
+    sculpt?: TerraformSnapshot;
+    /**
+     * Scene-document sky/fog/lighting (#1110), when authored. Feed into `environment({ sky: sky(sky) })`
+     * so the lighting workspace owns the look without hardcoding coordinates in world.ts.
+     */
+    sky?: SkyEnvironmentConfig;
+}
+/**
+ * Maps the scene document's serializable environment bag onto the runtime sky config consumed by
+ * `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field
+ * so callers can fall back to a world.ts default without inventing values.
+ * @capability editor-environment project document lighting onto the runtime sky descriptor
+ */
+export declare function skyFromDocument(doc: EditorDocument): SkyEnvironmentConfig | undefined;
+/**
+ * Projects a validated {@link EditorEnvironment} bag onto {@link SkyEnvironmentConfig}.
+ *
+ * @internal
+ */
+export declare function skyConfigFromEnvironment(env: EditorEnvironment): SkyEnvironmentConfig;
+/**
+ * The origin-centered terrain footprint that covers every authored object in a document, padded and
+ * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`
+ * terrain is centered on the origin, the footprint is sized symmetrically to the farthest object on
+ * each axis, so no authored object falls off the ground.
+ * @capability world-convergence size terrain to the authored document instead of a hardcoded bounds
+ */
+export declare function terrainBoundsFromDocument(doc: EditorDocument, options?: EnvironmentContentOptions): WorldBounds;
+/**
+ * Derives a terrain-depression sculpt snapshot from the document's authored `water` volumes: each
+ * water box carves a lake bed that ramps from the shoreline down to below the box's bottom face, so
+ * an editor-authored pond/lake sits *in* the ground instead of floating as a sheet on top of it (and
+ * ground-sampled vegetation sinks below the surface rather than growing through it). Returns
+ * `undefined` when the document has no water volumes.
+ * @capability world-convergence carve lake beds under authored water volumes
+ */
+export declare function lakebedFromWaterVolumes(doc: EditorDocument): TerraformSnapshot | undefined;
+/**
+ * Derives the coordinate/placement content of an `environment()` world from its scene document:
+ * terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored
+ * spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that
+ * lets a game author its world footprint and flatten regions in the editor instead of hardcoding
+ * them — the `world.ts` that consumes it carries only engine tuning.
+ * @capability world-convergence derive environment coordinate content from the scene document
+ */
+export declare function environmentContentFromDocument(doc: EditorDocument, options?: EnvironmentContentOptions): EnvironmentContent;

package/dist/editor/environment.js

@@ -0,0 +1,169 @@
+import { clearanceZonesFrom, DEFAULT_CLEARANCE_KINDS } from "../world/scatterRegion.js";
+import { editorDocumentBounds } from "./document.js";
+/**
+ * Maps the scene document's serializable environment bag onto the runtime sky config consumed by
+ * `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field
+ * so callers can fall back to a world.ts default without inventing values.
+ * @capability editor-environment project document lighting onto the runtime sky descriptor
+ */
+export function skyFromDocument(doc) {
+    const env = doc.environment;
+    if (env === undefined)
+        return undefined;
+    return skyConfigFromEnvironment(env);
+}
+/**
+ * Projects a validated {@link EditorEnvironment} bag onto {@link SkyEnvironmentConfig}.
+ *
+ * @internal
+ */
+export function skyConfigFromEnvironment(env) {
+    return {
+        ...(env.preset === undefined ? {} : { preset: env.preset }),
+        ...(env.timeOfDay === undefined ? {} : { timeOfDay: env.timeOfDay }),
+        ...(env.horizonColor === undefined ? {} : { horizonColor: env.horizonColor }),
+        ...(env.zenithColor === undefined ? {} : { zenithColor: env.zenithColor }),
+        ...(env.sunIntensity === undefined ? {} : { sunIntensity: env.sunIntensity }),
+        ...(env.ambientIntensity === undefined ? {} : { ambientIntensity: env.ambientIntensity }),
+        ...(env.fog === undefined ? {} : { fog: { ...env.fog } }),
+    };
+}
+/**
+ * The origin-centered terrain footprint that covers every authored object in a document, padded and
+ * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`
+ * terrain is centered on the origin, the footprint is sized symmetrically to the farthest object on
+ * each axis, so no authored object falls off the ground.
+ * @capability world-convergence size terrain to the authored document instead of a hardcoded bounds
+ */
+export function terrainBoundsFromDocument(doc, options = {}) {
+    const padding = options.padding ?? 24;
+    const min = options.minBounds ?? { w: 64, d: 64 };
+    const bounds = editorDocumentBounds(doc);
+    if (bounds === null)
+        return { w: min.w, d: min.d };
+    const halfX = Math.max(Math.abs(bounds.min.x), Math.abs(bounds.max.x));
+    const halfZ = Math.max(Math.abs(bounds.min.z), Math.abs(bounds.max.z));
+    return {
+        w: Math.max(min.w, halfX * 2 + padding * 2),
+        d: Math.max(min.d, halfZ * 2 + padding * 2),
+    };
+}
+const LAKEBED_CELL = 1.5;
+/** Meters the bed drops below the water box's bottom face at full depth. */
+const LAKEBED_UNDERCUT = 1.2;
+/** Meters from the shoreline over which the bed ramps to full depth. */
+const LAKEBED_SHORE_RAMP = 4;
+/** Wavelength (m) of the seeded shore-ramp modulation that keeps the waterline organic. */
+const LAKEBED_SHORE_NOISE_SCALE = 5.5;
+/** Deterministic 2D value noise in [0,1] — the shoreline wobble must be stable across runs. */
+function lakebedShoreNoise(x, z) {
+    const lattice = (ix, iz) => {
+        let h = (Math.imul(ix, 374761393) + Math.imul(iz, 668265263)) ^ 0x5bf03635;
+        h = Math.imul(h ^ (h >>> 13), 1274126177);
+        return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+    };
+    const ix = Math.floor(x);
+    const iz = Math.floor(z);
+    const fx = x - ix;
+    const fz = z - iz;
+    const ux = fx * fx * (3 - 2 * fx);
+    const uz = fz * fz * (3 - 2 * fz);
+    const a = lattice(ix, iz);
+    const b = lattice(ix + 1, iz);
+    const c = lattice(ix, iz + 1);
+    const d = lattice(ix + 1, iz + 1);
+    return a + (b - a) * ux + (c - a) * uz + (a - b - c + d) * ux * uz;
+}
+/**
+ * Derives a terrain-depression sculpt snapshot from the document's authored `water` volumes: each
+ * water box carves a lake bed that ramps from the shoreline down to below the box's bottom face, so
+ * an editor-authored pond/lake sits *in* the ground instead of floating as a sheet on top of it (and
+ * ground-sampled vegetation sinks below the surface rather than growing through it). Returns
+ * `undefined` when the document has no water volumes.
+ * @capability world-convergence carve lake beds under authored water volumes
+ */
+export function lakebedFromWaterVolumes(doc) {
+    const waters = doc.volumes.filter((volume) => volume.kind === "water" && volume.halfExtents !== undefined);
+    if (waters.length === 0)
+        return undefined;
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const water of waters) {
+        const he = water.halfExtents;
+        minX = Math.min(minX, water.center.x - he.x - LAKEBED_SHORE_RAMP);
+        minZ = Math.min(minZ, water.center.z - he.z - LAKEBED_SHORE_RAMP);
+        maxX = Math.max(maxX, water.center.x + he.x + LAKEBED_SHORE_RAMP);
+        maxZ = Math.max(maxZ, water.center.z + he.z + LAKEBED_SHORE_RAMP);
+    }
+    const cols = Math.max(1, Math.ceil((maxX - minX) / LAKEBED_CELL));
+    const rows = Math.max(1, Math.ceil((maxZ - minZ) / LAKEBED_CELL));
+    const vertsX = cols + 1;
+    const vertsZ = rows + 1;
+    const offsets = new Array(vertsX * vertsZ).fill(0);
+    for (let iz = 0; iz < vertsZ; iz += 1) {
+        for (let ix = 0; ix < vertsX; ix += 1) {
+            const x = minX + (ix / cols) * (maxX - minX);
+            const z = minZ + (iz / rows) * (maxZ - minZ);
+            let offset = 0;
+            for (const water of waters) {
+                const he = water.halfExtents;
+                // Rounded-rectangle signed distance on XZ (negative inside): the carve — and with it the
+                // waterline — rounds the box corners instead of stamping a sharp rectangle in the ground.
+                const rr = Math.min(he.x, he.z) * 0.3;
+                const ax = Math.abs(x - water.center.x) - he.x + rr;
+                const az = Math.abs(z - water.center.z) - he.z + rr;
+                const raw = Math.hypot(Math.max(ax, 0), Math.max(az, 0)) + Math.min(Math.max(ax, az), 0) - rr;
+                if (raw >= 0)
+                    continue;
+                // Seeded wobble wanders the shoreline up to ±0.8 m, ramped in from the box edge so the
+                // carve never escapes the authored footprint.
+                const wobble = (lakebedShoreNoise(x / LAKEBED_SHORE_NOISE_SCALE, z / LAKEBED_SHORE_NOISE_SCALE) - 0.5) * 1.6;
+                const dist = raw + wobble * Math.min(1, -raw / 1.5);
+                if (dist >= 0)
+                    continue;
+                const depth = he.y * 2 + LAKEBED_UNDERCUT;
+                const t = Math.min(1, -dist / LAKEBED_SHORE_RAMP);
+                // Smoothstep the shore ramp so the bed curves like a basin, not a funnel.
+                const w = t * t * (3 - 2 * t);
+                offset = Math.min(offset, -depth * w);
+            }
+            offsets[iz * vertsX + ix] = offset;
+        }
+    }
+    return {
+        bounds: { minX, minZ, maxX, maxZ },
+        cellSize: LAKEBED_CELL,
+        cols,
+        rows,
+        offsets,
+        surfaces: new Array(cols * rows).fill(null),
+    };
+}
+/**
+ * Derives the coordinate/placement content of an `environment()` world from its scene document:
+ * terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored
+ * spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that
+ * lets a game author its world footprint and flatten regions in the editor instead of hardcoding
+ * them — the `world.ts` that consumes it carries only engine tuning.
+ * @capability world-convergence derive environment coordinate content from the scene document
+ */
+export function environmentContentFromDocument(doc, options = {}) {
+    const clearanceOptions = {
+        kinds: options.kinds ?? DEFAULT_CLEARANCE_KINDS,
+        ...(options.ids === undefined ? {} : { ids: options.ids }),
+        ...(options.defaultClearance === undefined ? {} : { defaultClearance: options.defaultClearance }),
+        ...(options.feather === undefined ? {} : { feather: options.feather }),
+    };
+    // The authored sculpt snapshot wins outright when the document carries one (the author owns the
+    // ground); otherwise water volumes derive their own lake-bed depression.
+    const sculpt = doc.terrain ?? lakebedFromWaterVolumes(doc);
+    const sky = skyFromDocument(doc);
+    return {
+        bounds: terrainBoundsFromDocument(doc, options),
+        clearings: clearanceZonesFrom(doc, clearanceOptions),
+        ...(sculpt === undefined ? {} : { sculpt }),
+        ...(sky === undefined ? {} : { sky }),
+    };
+}

package/dist/editor/index.d.ts

@@ -2,6 +2,10 @@
 export type { EditorDocument } from "./types.js";
 /** A sculpted heightfield overlay stored on a document ΓÇö the terraform snapshot of offset deltas. */
 export type { EditorTerrain } from "./types.js";
+/** A baked top-down minimap (PNG data URI + world bounds) persisted on the scene document. */
+export type { EditorMinimapBake } from "./types.js";
+/** Scene-document sky/fog/lighting bag edited by the lighting workspace. */
+export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset } from "./types.js";
 /** Per-kind show/hide flags for the editor's layer panel. */
 export type { EditorKindVisibility } from "./types.js";
 /** The four placeable-object collections a prefab fragment or clipboard fragment carries. */
@@ -29,6 +33,10 @@ export type { EditorCatalogData } from "./types.js";
 export type { EditorCatalogDefinition } from "./types.js";
 /** Accepted shape for a game's `editorCatalogs` export: definitions, or a factory. */
 export type { EditorCatalogsInput } from "./types.js";
+/** Well-known catalog id for authored entity definitions consumed by the default content path. */
+export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, resolveCatalogDefinitions } from "./entityCatalog.js";
+/** Minimal document shape {@link entityEntryFromCatalog} reads — any `EditorDocument` satisfies it. */
+export type { EntityCatalogDocumentLike } from "./entityCatalog.js";
 /** Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory. */
 export type { EditorLayersInput } from "./types.js";
 /** A placeable point object in the scene ΓÇö spawn, mob, chest, POI, etc. */
@@ -46,11 +54,28 @@ export type { EditorVolumeShape } from "./types.js";
 /** HUD layout section on the scene document — panel id → anchor/offset/size/visibility. */
 export type { EditorUiDocument, EditorUiPanelLayout, HudPanelTypeDef, HudResizeAxes } from "./types.js";
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
-export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
+export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
 /** One field-level failure surfaced while decoding an untrusted editor document. */
 export type { EditorDocumentDiagnostic } from "./document.js";
+export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
+/** A sharded world manifest (`world.json`): grid + shard list + streaming config. */
+export type { DecodeWorldManifestResult, SplitWorldOptions, SplitWorldResult, WorldGrid, WorldManifest, WorldManifestShard, WorldQuery, WorldShardBounds, WorldShardResidency, WorldShardResolver, WorldStreamingConfig, } from "./world.js";
 /** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while decoding it. */
 export type { DecodeEditorDocumentResult } from "./document.js";
+export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+/** Coordinate/placement content of an `environment()` world derived from the scene document. */
+export type { EnvironmentContent, EnvironmentContentOptions } from "./environment.js";
+export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
+/** Editor-side minimap bake from the scene document (footprint + biome-tint zones). */
+export type { DocumentBakeOptions } from "./minimap.js";
+export { createWorldStreamer, shardDistance } from "./streamer.js";
+/** A stateful proximity streamer that schedules shard load/unload as the camera moves. */
+export type { StreamUpdate, StreamerShard, WorldStreamer, WorldStreamerConfig } from "./streamer.js";
+/** A procedural directive on the scene document — scatter props or a mob population. */
+export type { EditorDirective, EditorDirectiveArea, EditorDirectiveKind, EditorPopulationDirective, EditorPopulationSpecies, EditorScatterDirective, } from "./types.js";
+export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";
+/** The deterministic bake of scene directives into per-instance placements + sparse overlays. */
+export type { DirectiveFootprint, DirectiveInstancePatch, EditorDirectiveOverlay, MaterializedInstance, } from "./directives.js";
 /** Creates an editor session with undo/redo history seeded from an initial document. */
 export { createEditorSession } from "./commands.js";
 /** Compact snapshot of a session state ΓÇö counts, selection, and the selected object. */

package/dist/editor/index.js

@@ -1,5 +1,12 @@
+/** Well-known catalog id for authored entity definitions consumed by the default content path. */
+export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, resolveCatalogDefinitions } from "./entityCatalog.js";
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
-export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
+export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
+export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
+export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
+export { createWorldStreamer, shardDistance } from "./streamer.js";
+export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";
 /** Creates an editor session with undo/redo history seeded from an initial document. */
 export { createEditorSession } from "./commands.js";
 /** Compact snapshot of a session state ΓÇö counts, selection, and the selected object. */

package/dist/editor/minimap.d.ts

@@ -0,0 +1,31 @@
+import { type MinimapBakeBounds, type MinimapBakeOptions, type MinimapBakeZone } from "../world/minimapBake.js";
+import type { EditorDocument } from "./types.js";
+/**
+ * The biome-tint zones a document contributes to a bake: every volume carrying a `color` becomes a
+ * polygon tint over its footprint. (The optional stretch from #1036 — a bare bake still reads as
+ * terrain without any.)
+ * @capability minimap-bake derive biome-tint zones for a bake from the scene document
+ */
+export declare function documentBakeZones(doc: EditorDocument): MinimapBakeZone[];
+/** Options for {@link bakeMinimapFromDocument}. */
+export interface DocumentBakeOptions extends MinimapBakeOptions {
+    /** Explicit bounds; default = the document's object bounds padded by `padding`. */
+    bounds?: MinimapBakeBounds;
+    /** Padding (m) around the derived bounds when `bounds` is omitted. Default 16. */
+    padding?: number;
+    /** Ground normal sampler for slope shading (optional). */
+    sampleNormal?: (x: number, z: number) => readonly [number, number, number];
+    /** Water level — ground at or below renders as water. */
+    waterLevel?: number;
+}
+/**
+ * Bakes a minimap image from a scene document plus a terrain height sampler: sizes the footprint to
+ * the authored objects (or an explicit `bounds`), tints biome-colored volumes, and rasterizes the
+ * terrain top-down. Returns `{ background, mapBounds }` for the `Minimap` props. The editor runs this
+ * as its bake action and stores the result on the document.
+ * @capability minimap-bake bake a minimap PNG + bounds from the authored scene document
+ */
+export declare function bakeMinimapFromDocument(doc: EditorDocument, sampleHeight: (x: number, z: number) => number, options?: DocumentBakeOptions): {
+    background: string;
+    mapBounds: MinimapBakeBounds;
+};

package/dist/editor/minimap.js

@@ -0,0 +1,73 @@
+import { bakeMinimapImage, minimapBakeToPngDataUri, } from "../world/minimapBake.js";
+import { editorDocumentBounds } from "./document.js";
+/**
+ * The editor-side minimap bake (#1036): bake a top-down terrain image straight from the authored
+ * scene document. The document owns the zones (biome-tinted volumes) and the footprint; the caller
+ * supplies the composed `sampleHeight` (base terrain + the document's sculpt), since the sculpt on
+ * the document is a delta over the game's base terrain. Returns the `{ background, mapBounds }` the
+ * `Minimap`/`WorldMap` props take, so the editor stores that on the document and runtime consumes it
+ * with no new render path. Deterministic for a fixed scene — safe for verify/CI.
+ */
+/** A volume that carries a `color` tints the bake over its XZ footprint. */
+function volumeFootprint(volume) {
+    const half = volume.halfExtents !== undefined
+        ? { x: volume.halfExtents.x, z: volume.halfExtents.z }
+        : volume.radius !== undefined
+            ? { x: volume.radius, z: volume.radius }
+            : null;
+    if (half === null)
+        return null;
+    const { x, z } = volume.center;
+    return [
+        [x - half.x, z - half.z],
+        [x + half.x, z - half.z],
+        [x + half.x, z + half.z],
+        [x - half.x, z + half.z],
+    ];
+}
+/**
+ * The biome-tint zones a document contributes to a bake: every volume carrying a `color` becomes a
+ * polygon tint over its footprint. (The optional stretch from #1036 — a bare bake still reads as
+ * terrain without any.)
+ * @capability minimap-bake derive biome-tint zones for a bake from the scene document
+ */
+export function documentBakeZones(doc) {
+    const zones = [];
+    for (const volume of doc.volumes) {
+        if (volume.color === undefined)
+            continue;
+        const polygon = volumeFootprint(volume);
+        if (polygon === null)
+            continue;
+        zones.push({ polygon, color: volume.color, alpha: 0.4 });
+    }
+    return zones;
+}
+/** Falls back to a small square when the document has no spatial objects. */
+function boundsFromDocument(doc, padding) {
+    const b = editorDocumentBounds(doc);
+    if (b === null)
+        return { minX: -32, minZ: -32, maxX: 32, maxZ: 32 };
+    return { minX: b.min.x - padding, minZ: b.min.z - padding, maxX: b.max.x + padding, maxZ: b.max.z + padding };
+}
+/**
+ * Bakes a minimap image from a scene document plus a terrain height sampler: sizes the footprint to
+ * the authored objects (or an explicit `bounds`), tints biome-colored volumes, and rasterizes the
+ * terrain top-down. Returns `{ background, mapBounds }` for the `Minimap` props. The editor runs this
+ * as its bake action and stores the result on the document.
+ * @capability minimap-bake bake a minimap PNG + bounds from the authored scene document
+ */
+export function bakeMinimapFromDocument(doc, sampleHeight, options = {}) {
+    const bounds = options.bounds ?? boundsFromDocument(doc, options.padding ?? 16);
+    const bake = bakeMinimapImage({
+        bounds,
+        sampleHeight,
+        ...(options.sampleNormal === undefined ? {} : { sampleNormal: options.sampleNormal }),
+        ...(options.waterLevel === undefined ? {} : { waterLevel: options.waterLevel }),
+        zones: documentBakeZones(doc),
+    }, {
+        ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+        ...(options.palette === undefined ? {} : { palette: options.palette }),
+    });
+    return { background: minimapBakeToPngDataUri(bake), mapBounds: bake.bounds };
+}

package/dist/editor/streamer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides,
+ * as the camera moves, which shards enter and leave residency. It is pure scheduling — actually
+ * reading/merging the shard documents stays the caller's job (compose with
+ * `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has
+ * no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a
+ * shard on a boundary from thrashing load/unload every frame.
+ */
+/** The minimal shard shape the streamer schedules on — any world-manifest shard satisfies it. */
+export interface StreamerShard {
+    /** Stable shard id (the load/unload unit). */
+    id: string;
+    /** XZ footprint `[minX, minZ]`..`[maxX, maxZ]`; absent = always resident. */
+    bounds?: {
+        min: [number, number];
+        max: [number, number];
+    };
+    /** `"always"` keeps the shard resident regardless of distance; default `"streamed"` when bounded. */
+    residency?: "always" | "streamed";
+}
+/** Configuration for {@link createWorldStreamer}. */
+export interface WorldStreamerConfig {
+    shards: readonly StreamerShard[];
+    /** Load a shard when the camera comes within this distance (m) of its footprint. */
+    loadRadius: number;
+    /** Keep a loaded shard resident until the camera is farther than this (m) — hysteresis band. */
+    keepRadius: number;
+}
+/** The residency change produced by one {@link WorldStreamer.update}. */
+export interface StreamUpdate {
+    /** Shard ids that became resident on this update. */
+    load: string[];
+    /** Shard ids that left residency on this update. */
+    unload: string[];
+    /** The full resident shard-id set after this update (sorted, stable order). */
+    resident: string[];
+}
+/** A stateful proximity streamer over a fixed shard set. */
+export interface WorldStreamer {
+    /** Advances the streamer to a new camera position, returning the residency delta. */
+    update(center: {
+        x: number;
+        z: number;
+    }): StreamUpdate;
+    /** The current resident shard-id set (sorted). */
+    resident(): string[];
+    /** Clears all residency (next update reloads from scratch). */
+    reset(): void;
+}
+/**
+ * Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
+ * @capability world-streaming distance from a camera to a shard footprint
+ */
+export declare function shardDistance(shard: StreamerShard, center: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Creates a proximity streamer over a world's shards. Always-resident shards are resident from the
+ * first update onward; each bounded shard loads when the camera comes within `loadRadius` of its
+ * footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up),
+ * giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the
+ * caller wires each delta to `loadWorldDocument`.
+ * @capability world-streaming schedule shard load/unload by camera proximity
+ */
+export declare function createWorldStreamer(config: WorldStreamerConfig): WorldStreamer;