import { type EditorSimulation } from "./simulation.js";
import { type MaterialAsset } from "../material/materialAsset.js";
import { type EditorGridLayer } from "./grid.js";
import type { EditorCatalogData, EditorBake, EditorCatalogDefinition, EditorCatalogEntry, EditorCollection, EditorDirective, EditorDocument, EditorEnvironment, EditorFragmentContent, EditorLayersInput, EditorMarker, EditorMinimapBake, EditorNote, EditorPath, EditorPrefab, EditorTerrain, EditorVolume } from "./types.js";
/** Spread-ready non-placeable fields preserved across document rebuilds. @internal */
export declare function editorDocumentExtras(doc: EditorDocument): {
    materialAssets?: MaterialAsset[];
    prefabs: EditorPrefab[];
    collections: EditorCollection[];
    catalogs: EditorCatalogData[];
    grids?: EditorGridLayer[];
    terrain?: EditorTerrain;
    ui?: EditorDocument["ui"];
    directives?: EditorDirective[];
    minimap?: EditorMinimapBake;
    bakes?: EditorBake[];
    environment?: EditorEnvironment;
    simulation?: EditorSimulation;
};
/** Builds a fresh, empty editor document to start authoring a scene from scratch.
 * @internal
 */
export declare function createEmptyEditorDocument(): EditorDocument;
/**
 * Deep-copies an editor document so edits never mutate the source. The terrain snapshot is
 * shared by reference: sculpt commands replace it wholesale (copy-on-write), never mutate it in
 * place, so history snapshots stay cheap even on large heightfields.
  * @internal
  */
export declare function cloneEditorDocument(doc: EditorDocument): EditorDocument;
/** Resolves a game's `editorLayers` export — document, partial data, or factory — into a full document.
 * @internal
 */
export declare function normalizeEditorLayers(input: EditorLayersInput | undefined | null): EditorDocument;
/**
 * Reserves `id` in `taken` and returns it unchanged when free; otherwise mints the next free
 * `<id>_copy`/`<id>_copyN` suffix and reserves that instead. The one place object ids are made
 * unique across a document's markers/volumes/paths/annotations as a single global namespace, so a
 * merged-in or imported object can never silently shadow an existing object in another collection.
 * @internal
 */
export declare function ensureUniqueEditorId(id: string, taken: Set<string>): string;
/** Combines multiple editor documents' markers, volumes, paths, notes, prefabs, and collections
 * into one, re-idding any placeable object whose id collides with one already merged in — across
 * all four collections, since selection/parenting/removal treat those ids as one document-global
 * namespace.
 * @internal
 */
export declare function mergeEditorDocuments(...docs: readonly EditorDocument[]): EditorDocument;
/** Extracts the subset of a document matching the given ids — the clipboard fragment for copy/paste.
 * @internal
 */
export declare function extractEditorFragment(doc: EditorDocument, ids: readonly string[]): EditorDocument;
/** Counts every object in a document across markers, volumes, paths, and notes.
 * @internal
 */
export declare function editorDocumentSize(doc: EditorDocument): number;
/** Looks up a prefab by id in an editor document.
 * @internal
 */
export declare function findEditorPrefab(doc: EditorDocument, id: string): EditorPrefab | undefined;
/** Looks up a named collection / selection set by id in an editor document.
 * @internal
 */
export declare function findEditorCollection(doc: EditorDocument, id: string): EditorCollection | undefined;
/**
 * Looks up a gameplay data catalog by id on the scene document.
 * @capability editor-catalogs Find a persisted catalog bag by id.
 */
export declare function findEditorCatalog(doc: EditorDocument, id: string): EditorCatalogData | undefined;
/**
 * Looks up one entry inside a gameplay data catalog.
 * @capability editor-catalogs Find a catalog entry's meta bag by catalog + entry id.
 */
export declare function findEditorCatalogEntry(doc: EditorDocument, catalogId: string, entryId: string): EditorCatalogEntry | undefined;
/**
 * Seeds default catalog rows from game-exported definitions into a document: missing catalogs and
 * missing entries are filled from the definition; existing document values win (overlay already applied).
 * @capability editor-catalogs Seed scene-document catalogs from game-exported schemas.
 */
export declare function seedEditorCatalogs(doc: EditorDocument, definitions: readonly EditorCatalogDefinition[]): EditorDocument;
/**
 * True when an object carries a per-object `locked` flag (hierarchy lock toggle).
 * Collection membership is checked separately by {@link isEditorObjectLocked}.
 * @internal
 */
export declare function isEditorObjectSelfLocked(doc: EditorDocument, id: string): boolean;
/**
 * True when an object is a member of any locked collection (production group lock).
 * @internal
 */
export declare function isEditorObjectCollectionLocked(doc: EditorDocument, id: string): boolean;
/**
 * True when an object id is locked for edit — either its own `locked` flag or membership in a
 * locked collection. Blocks move/delete via session mutations.
 * @internal
 */
export declare function isEditorObjectLocked(doc: EditorDocument, id: string): boolean;
/**
 * True when an object carries `hidden: true` — omitted from editor viewport overlays and picking
 * while remaining in the hierarchy and document.
 * @internal
 */
export declare function isEditorObjectHidden(doc: EditorDocument, id: string): boolean;
/**
 * Extracts the selected ids into a prefab fragment centered on their own bounds centroid, so the
 * same prefab reinserts consistently regardless of where in the scene (or which game) it lands.
  * @internal
  */
export declare function createPrefabFragment(doc: EditorDocument, ids: readonly string[]): EditorFragmentContent;
/** Looks up a marker by id in an editor document.
 * @internal
 */
export declare function findEditorMarker(doc: EditorDocument, id: string): EditorMarker | undefined;
/** Looks up a marker by id and throws when it is absent — for scene contracts where a
 * missing marker is an authoring error to surface loudly, not a runtime branch to handle.
 * @internal
 */
export declare function requireEditorMarker(doc: EditorDocument, id: string): EditorMarker;
/** A marker's world position as an `[x, y, z]` tuple — the shared shape gameplay tables read.
 * @internal
 */
export declare function editorMarkerPosition(marker: EditorMarker): readonly [x: number, y: number, z: number];
/** A marker's ground position as an `[x, z]` tuple, dropping the vertical axis.
 * @internal
 */
export declare function editorMarkerXZ(marker: EditorMarker): readonly [x: number, z: number];
/** Looks up a volume by id in an editor document.
 * @internal
 */
export declare function findEditorVolume(doc: EditorDocument, id: string): EditorVolume | undefined;
/** Looks up a path by id in an editor document.
 * @internal
 */
export declare function findEditorPath(doc: EditorDocument, id: string): EditorPath | undefined;
/** Looks up an annotation note by id in an editor document.
 * @internal
 */
export declare function findEditorNote(doc: EditorDocument, id: string): EditorNote | undefined;
/** Lists the distinct marker, volume, and path kinds authored in a document.
 * @internal
 */
export declare function listEditorKinds(doc: EditorDocument): {
    markers: string[];
    volumes: string[];
    paths: string[];
};
/** The id of an object's parent, or undefined when it is a root (or unknown).
 * @internal
 */
export declare function editorParentOf(doc: EditorDocument, id: string): string | undefined;
/** The direct child ids of an object (empty when it has none).
 * @internal
 */
export declare function editorChildren(doc: EditorDocument, parentId: string): string[];
/** Object ids with no parent (or whose parent no longer exists) — the roots of the hierarchy.
 * @internal
 */
export declare function editorRoots(doc: EditorDocument): string[];
/** Every descendant id of the given ids (children, grandchildren, …), excluding the inputs.
 * @internal
 */
export declare function collectDescendants(doc: EditorDocument, ids: Iterable<string>): Set<string>;
/** True when parenting `id` under `parentId` would form a cycle (or parent itself to itself).
 * @internal
 */
export declare function wouldCreateCycle(doc: EditorDocument, id: string, parentId: string | null): boolean;
/** Serializes an editor document to JSON text for saving or export.
 * @internal
 */
export declare function exportEditorDocumentJson(doc: EditorDocument, pretty?: boolean): string;
/** One field-level failure surfaced while decoding an untrusted editor document, `path` pointing
 * at the exact field that failed (e.g. `$.markers[2].position`).
 * @internal
 */
export interface EditorDocumentDiagnostic {
    path: string;
    message: string;
}
/** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while
 * decoding it.
 * @internal
 */
export type DecodeEditorDocumentResult = {
    ok: true;
    document: EditorDocument;
} | {
    ok: false;
    errors: EditorDocumentDiagnostic[];
};
/**
 * The authoritative decoder/migrator for an editor document arriving from outside this process
 * (disk, network, an agent's `import_document` RPC): validates every field with a path-specific
 * diagnostic on failure instead of trusting the shape, then migrates forward — routes any embedded
 * terrain through {@link migrateTerrainSnapshot} and normalizes `version` to the one this build
 * understands. Every other loader in this module funnels through here.
 * @internal
 */
export declare function decodeEditorDocument(raw: unknown): DecodeEditorDocumentResult;
/** Parses JSON text back into a normalized editor document, throwing a message that names every
 * field that failed to decode when the shape is malformed.
 * @internal
 */
export declare function importEditorDocumentJson(raw: string): EditorDocument;
/**
 * Applies a saved editor document on top of a game's derived layers: overlay objects replace
 * same-id base objects and new overlay objects are appended, so editor saves win over source
 * data until they are folded back in.
  * @internal
  */
export declare function applyEditorDocumentOverlay(base: EditorDocument, overlay: EditorDocument): EditorDocument;
/** Computes the world-space min/max bounds spanning every object in a document, or null if empty.
 * @internal
 */
export declare function editorDocumentBounds(doc: EditorDocument): {
    min: {
        x: number;
        y: number;
        z: number;
    };
    max: {
        x: number;
        y: number;
        z: number;
    };
} | null;