@jgengine/core 0.10.0 → 0.11.0

package/dist/editor/document.d.ts

@@ -1,31 +1,177 @@
-import type { EditorDocument, EditorLayersInput, EditorMarker, EditorNote, EditorPath, EditorVolume } from "./types.js";
-/** Builds a fresh, empty editor document to start authoring a scene from scratch. */
+import { type EditorGridLayer } from "./grid.js";
+import type { EditorCatalogData, EditorCatalogDefinition, EditorCatalogEntry, EditorCollection, EditorDocument, EditorFragmentContent, EditorLayersInput, EditorMarker, EditorNote, EditorPath, EditorPrefab, EditorTerrain, EditorVolume } from "./types.js";
+/** Spread-ready non-placeable fields preserved across document rebuilds. @internal */
+export declare function editorDocumentExtras(doc: EditorDocument): {
+    prefabs: EditorPrefab[];
+    collections: EditorCollection[];
+    catalogs: EditorCatalogData[];
+    grids?: EditorGridLayer[];
+    terrain?: EditorTerrain;
+    ui?: EditorDocument["ui"];
+};
+/** 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. */
+/**
+ * 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. */
+/** 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;
-/** Combines multiple editor documents' markers, volumes, paths, and notes into one. */
+/**
+ * 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;
-/** Looks up a marker by id in an editor document. */
+/** 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 id is a member of any locked collection — blocks move/delete on it.
+ * @internal
+ */
+export declare function isEditorObjectLocked(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 volume by id in an editor document. */
+/** 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. */
+/** 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. */
+/** 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. */
+/** 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[];
 };
-/** Serializes an editor document to JSON text for saving or export. */
+/** 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;
-/** Parses JSON text back into a normalized editor document. */
+/** 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;
-/** Computes the world-space min/max bounds spanning every object in a document, or null if empty. */
+/**
+ * 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;