@jgengine/core 0.10.0 → 0.12.0

package/dist/editor/entityCatalog.d.ts

@@ -0,0 +1,42 @@
+import type { GameContextEntityEntry } from "../runtime/gameContext.js";
+import { type ParamSchema } from "../scene/sceneKinds.js";
+import type { EditorCatalogData, EditorCatalogDefinition } from "./types.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 declare const ENTITY_CATALOG_ID = "entities";
+/**
+ * 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 declare const entityDefinitionSchema: ParamSchema;
+/** Minimal document shape {@link entityEntryFromCatalog} reads — any `EditorDocument` satisfies it. */
+export interface EntityCatalogDocumentLike {
+    catalogs: readonly EditorCatalogData[];
+}
+/**
+ * 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 declare function entityEntryFromCatalog(document: EntityCatalogDocumentLike, entityId: string, definitions?: readonly EditorCatalogDefinition[]): GameContextEntityEntry | null;
+/**
+ * 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 declare function resolveCatalogDefinitions(document: EntityCatalogDocumentLike, gameDefinitions: readonly EditorCatalogDefinition[]): EditorCatalogDefinition[];

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/grid.d.ts

@@ -0,0 +1,229 @@
+import type { EditorVec3 } from "./types.js";
+/**
+ * How a grid layer's columns and rows map onto world axes.
+ * - `"xz"` (default): columns advance +X, rows advance +Z — a top-down floor plan / board.
+ * - `"xy"`: columns advance +X, rows advance +Y — a vertical slice / side-view board.
+ * @capability editor-grids Choose how grid columns/rows project onto world axes.
+ */
+export type EditorGridAxes = "xz" | "xy";
+/**
+ * One selectable value in a grid layer's palette: the cell value id plus how it reads (label,
+ * color) and how ASCII import/export maps it (`glyph`). Games register these so the editor and
+ * the import adapters share one legend. `meta` carries the typed payload (cost, damage, tags, …)
+ * a runtime attaches to every cell holding this value.
+ * @capability editor-grids Register a cell value's legend, glyph, color, and typed payload.
+ */
+export interface EditorGridPaletteEntry {
+    id: string;
+    label?: string;
+    /** Single character this value maps to for ASCII/glyph import/export. */
+    glyph?: string;
+    color?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * A sparse, editor-owned tile grid serialized on the scene document. Only non-empty cells are
+ * stored (a `col,row` → value-id map), so a mostly empty grid stays small no matter how large its
+ * declared `cols`/`rows` bounds are. `kind` names the game schema the cells belong to (`room`,
+ * `tactics`, `nav`, `farm`, …); `palette` carries the typed cell payloads by value id; `empty`
+ * is the value id treated as background (cells holding it are dropped from `cells`). Runtime and
+ * rendering both read the same layer through the query helpers in this module — renderers are
+ * registered adapters over this data, never baked into it.
+ * @capability editor-grids Serialize grid-addressed tile content on the scene document.
+ */
+export interface EditorGridLayer {
+    id: string;
+    kind: string;
+    label?: string;
+    /** World position of cell (0, 0)'s center; `cellSize` and `axes` place every other cell. */
+    origin: EditorVec3;
+    /** Column/row → world-axis mapping; defaults to `"xz"` when absent. */
+    axes?: EditorGridAxes;
+    /** World size of one cell along both grid axes. */
+    cellSize: number;
+    cols: number;
+    rows: number;
+    /** Value id treated as empty/background; cells holding it are omitted from `cells`. Default `""`. */
+    empty?: string;
+    /** Sparse cells keyed `"col,row"` → palette value id. Only non-empty, in-bounds cells appear. */
+    cells: Record<string, string>;
+    palette?: EditorGridPaletteEntry[];
+    visible?: boolean;
+    /** Id of the object this layer is parented under (mirrors marker/volume/path parenting). */
+    parentId?: string;
+    meta?: Record<string, unknown>;
+    /** Cell-semantics schema version; {@link migrateGridLayer} normalizes older layers forward. */
+    schemaVersion?: number;
+}
+/** One resolved cell of a grid layer — its column, row, and value id. */
+export interface EditorGridCell {
+    col: number;
+    row: number;
+    value: string;
+}
+/** A single paint/erase edit: set cell `col,row` to `value` (the layer's empty value erases it). */
+export interface EditorGridCellEdit {
+    col: number;
+    row: number;
+    value: string;
+}
+/** The grid-layer cell-schema version this build writes and migrates toward. */
+export declare const CURRENT_GRID_SCHEMA_VERSION = 1;
+/**
+ * The value id a layer treats as empty/background (default `""`). Cells holding this value are
+ * never stored, so it is what {@link getGridCell} returns for any unset cell.
+ * @capability editor-grids Resolve a grid layer's empty/background value id.
+ */
+export declare function gridEmptyValue(layer: EditorGridLayer): string;
+/** Builds the sparse-map key for a cell. @internal */
+export declare function gridCellKey(col: number, row: number): string;
+/**
+ * Parses a `"col,row"` sparse-map key back into integer coordinates, or `null` when malformed.
+ * @capability editor-grids Decode a grid layer's sparse cell key.
+ */
+export declare function parseGridCellKey(key: string): {
+    col: number;
+    row: number;
+} | null;
+/**
+ * True when `col,row` falls inside the layer's declared bounds.
+ * @capability editor-grids Bounds-check a grid coordinate before reading or writing it.
+ */
+export declare function inGridBounds(layer: EditorGridLayer, col: number, row: number): boolean;
+/**
+ * Reads the value id at `col,row`, returning the layer's empty value for any unset or
+ * out-of-bounds cell. The one read path both gameplay and rendering share.
+ * @capability editor-grids Read a grid cell's value id.
+ */
+export declare function getGridCell(layer: EditorGridLayer, col: number, row: number): string;
+/**
+ * Samples the value id at `col,row` — the eyedropper. Identical to {@link getGridCell}, named for
+ * the authoring op that picks up a cell's value to paint with.
+ * @capability editor-grids Eyedrop (sample) a grid cell's value for painting.
+ */
+export declare function eyedropGridCell(layer: EditorGridLayer, col: number, row: number): string;
+/**
+ * Returns a copy of the layer with `col,row` set to `value`, dropping the cell when `value` is the
+ * empty value (that is the erase op). Out-of-bounds writes and no-op writes return the layer
+ * unchanged, so callers can diff by identity.
+ * @capability editor-grids Paint or erase a single grid cell (immutable).
+ */
+export declare function setGridCell(layer: EditorGridLayer, col: number, row: number, value: string): EditorGridLayer;
+/**
+ * Erases `col,row` back to the layer's empty value — {@link setGridCell} with the empty value.
+ * @capability editor-grids Erase a single grid cell (immutable).
+ */
+export declare function eraseGridCell(layer: EditorGridLayer, col: number, row: number): EditorGridLayer;
+/**
+ * Applies a batch of cell edits in one pass, returning the same layer when nothing changed. The
+ * op the editor uses for a drag stroke, a paste, or any multi-cell paint/erase.
+ * @capability editor-grids Paint or erase many grid cells in one immutable update.
+ */
+export declare function paintGridCells(layer: EditorGridLayer, edits: readonly EditorGridCellEdit[]): EditorGridLayer;
+/**
+ * Fills the inclusive rectangle spanning the two corners with `value` (the rectangle tool). Corners
+ * may be given in any order; the clamped in-bounds portion is painted.
+ * @capability editor-grids Fill a grid rectangle with one value (immutable).
+ */
+export declare function fillGridRect(layer: EditorGridLayer, col0: number, row0: number, col1: number, row1: number, value: string): EditorGridLayer;
+/**
+ * Flood-fills the 4-connected region of cells sharing the seed cell's value, replacing it with
+ * `value` (the bucket tool). Bounded by the layer's declared bounds, so it never scans the world.
+ * @capability editor-grids Bucket flood-fill a contiguous grid region (immutable).
+ */
+export declare function floodFillGrid(layer: EditorGridLayer, col: number, row: number, value: string): EditorGridLayer;
+/**
+ * Resizes the layer's bounds to `cols`×`rows`, dropping any cells that fall outside the new extent
+ * (values are anchored at the origin corner). Negative or fractional sizes are floored to `≥ 0`.
+ * @capability editor-grids Resize a grid layer's bounds, trimming out-of-range cells (immutable).
+ */
+export declare function resizeGridLayer(layer: EditorGridLayer, cols: number, rows: number): EditorGridLayer;
+/**
+ * Every non-empty, in-bounds cell of a layer, sorted row-major (rendering-independent iteration).
+ * @capability editor-grids Iterate a grid layer's non-empty cells, row-major.
+ */
+export declare function gridCellEntries(layer: EditorGridLayer): EditorGridCell[];
+/**
+ * Visits every non-empty cell of a layer row-major. Allocation-light convenience over
+ * {@link gridCellEntries} for runtime scans that only need a callback.
+ * @capability editor-grids Walk a grid layer's non-empty cells with a callback.
+ */
+export declare function forEachGridCell(layer: EditorGridLayer, visit: (cell: EditorGridCell) => void): void;
+/**
+ * Counts the non-empty, in-bounds cells of a layer.
+ * @capability editor-grids Count a grid layer's non-empty cells.
+ */
+export declare function gridCellCount(layer: EditorGridLayer): number;
+/**
+ * Every in-bounds cell holding `value`, sorted row-major — the query gameplay uses to find all
+ * spawns, hazards, gates, etc. of one kind without touching a renderer.
+ * @capability editor-grids Query all grid cells holding a given value.
+ */
+export declare function gridCellsOfValue(layer: EditorGridLayer, value: string): EditorGridCell[];
+/**
+ * World-space center of cell `col,row`, honoring the layer's origin, cell size, and axis mapping.
+ * The shared cell→world map for both placement and rendering.
+ * @capability editor-grids Map a grid cell to its world-space center.
+ */
+export declare function gridCellToWorld(layer: EditorGridLayer, col: number, row: number): EditorVec3;
+/**
+ * Inverse of {@link gridCellToWorld}: the nearest cell to a world point (may be out of bounds).
+ * The shared world→cell map runtime uses to answer "which cell is the player standing on".
+ * @capability editor-grids Map a world-space point to its nearest grid cell.
+ */
+export declare function worldToGridCell(layer: EditorGridLayer, x: number, y: number, z: number): {
+    col: number;
+    row: number;
+};
+/**
+ * The value id at the grid cell nearest a world point — {@link worldToGridCell} then
+ * {@link getGridCell}. Answers "what tile is here" straight from a world position.
+ * @capability editor-grids Read the grid value at a world-space point.
+ */
+export declare function getGridCellAtWorld(layer: EditorGridLayer, x: number, y: number, z: number): string;
+/**
+ * Looks up a palette entry by value id.
+ * @capability editor-grids Find a grid palette entry by value id.
+ */
+export declare function findGridPaletteEntry(layer: EditorGridLayer, value: string): EditorGridPaletteEntry | undefined;
+/**
+ * Builds the value-id → glyph map from a layer's palette, for ASCII/glyph export.
+ * @capability editor-grids Derive a value→glyph legend from a grid layer's palette.
+ */
+export declare function gridGlyphMap(layer: EditorGridLayer): Record<string, string>;
+/** Fields accepted when constructing a grid layer; sensible defaults fill the rest. */
+export interface CreateGridLayerInit {
+    id: string;
+    kind: string;
+    cols: number;
+    rows: number;
+    label?: string;
+    cellSize?: number;
+    origin?: EditorVec3;
+    axes?: EditorGridAxes;
+    empty?: string;
+    cells?: Record<string, string>;
+    palette?: readonly EditorGridPaletteEntry[];
+    visible?: boolean;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Creates a grid layer from a partial init, defaulting cell size to `1`, origin to the world
+ * origin, and axes to `"xz"`. Runs the result through {@link migrateGridLayer} so it is normalized
+ * and bounds-clean.
+ * @capability editor-grids Create a normalized, empty grid layer to author into.
+ */
+export declare function createGridLayer(init: CreateGridLayerInit): EditorGridLayer;
+/**
+ * Normalizes a grid layer forward to the current cell-schema version: clamps `cols`/`rows` to
+ * non-negative integers, drops out-of-bounds and empty-valued cells, and stamps `schemaVersion`.
+ * The single migration seam every loader and authoring op funnels new/old layers through, so a
+ * layer from an older document or an import adapter always lands in a valid, minimal shape.
+ * @capability editor-grids Migrate/normalize a grid layer to the current cell schema.
+ */
+export declare function migrateGridLayer(layer: EditorGridLayer): EditorGridLayer;
+/**
+ * Deep-clones a grid layer so authoring edits and history snapshots never alias source cells.
+ * @capability editor-grids Deep-clone a grid layer.
+ */
+export declare function cloneGridLayer(layer: EditorGridLayer): EditorGridLayer;