@fps-games/editor 0.1.6-beta.1 → 0.1.7-beta.1

package/node_modules/@fps-games/editor-playable-sdk/dist/document/helpers.js

@@ -1,5 +1,8 @@
 import { mergeArtistMaterialProfiles, } from '@fps-games/editor-protocol';
 import { isEditorSceneArtistMaterialPatchPath, normalizeEditorSceneMaterialSlotOwnerPath, readEditorSceneChildMaterialBindingOwnerPath, readEditorSceneMaterialSlotBindingSlotId, } from '../material-binding/paths.js';
+export const EDITOR_SCENE_PREFAB_COMPOSITION_VERSION = 1;
+export const EDITOR_SCENE_PREFAB_LEGACY_ROOT_NODE_ID = 'prefab-root';
+export const EDITOR_SCENE_PREFAB_LEGACY_MODEL_NODE_ID = 'prefab-model';
 const EDITOR_SCENE_PREFAB_OVERRIDE_FIELD_PATH_PREFIX = 'prefab.';
 const EDITOR_SCENE_PREFAB_CORE_MATERIAL_OVERRIDE_PROFILE_FIELD_PATHS = new Set([
     'profile.baseColor.color',
@@ -30,6 +33,512 @@ export function isEditorScenePrefabInstance(gameObject) {
 export function resolveEditorScenePrefabSourceAssetId(prefabAsset) {
     return readEditorSceneNonEmptyString(prefabAsset?.prefab?.sourceAssetId);
 }
+export function readEditorScenePrefabRootNodeId(prefabAsset) {
+    if (!prefabAsset?.prefab)
+        return null;
+    const nodes = readEditorScenePrefabExplicitNodes(prefabAsset.prefab);
+    const explicitRootNodeId = readEditorSceneNonEmptyString(prefabAsset.prefab.rootNodeId);
+    if (explicitRootNodeId && nodes.some(node => node.id === explicitRootNodeId))
+        return explicitRootNodeId;
+    const explicitRoot = nodes.find(node => node.kind === 'root' && !node.parentId);
+    if (explicitRoot)
+        return explicitRoot.id;
+    if (nodes.length > 0)
+        return null;
+    const legacyRoot = createEditorScenePrefabLegacyRootNode(prefabAsset);
+    return legacyRoot ? legacyRoot.id : null;
+}
+export function readEditorScenePrefabNodes(prefabAsset) {
+    if (!prefabAsset?.prefab)
+        return [];
+    const explicitNodes = readEditorScenePrefabExplicitNodes(prefabAsset.prefab);
+    if (explicitNodes.length > 0)
+        return explicitNodes;
+    return createEditorScenePrefabLegacyCompositionNodes(prefabAsset);
+}
+export function findEditorScenePrefabNode(prefabAsset, nodeId) {
+    const normalizedNodeId = readEditorSceneNonEmptyString(nodeId);
+    if (!normalizedNodeId)
+        return null;
+    return readEditorScenePrefabNodes(prefabAsset).find(node => node.id === normalizedNodeId) ?? null;
+}
+export function readEditorScenePrefabNodeChildren(prefabAsset, parentNodeId) {
+    const normalizedParentId = readEditorSceneNonEmptyString(parentNodeId);
+    return readEditorScenePrefabNodes(prefabAsset).filter((node) => {
+        const parentId = readEditorSceneNonEmptyString(node.parentId);
+        return normalizedParentId ? parentId === normalizedParentId : !parentId;
+    });
+}
+export function ensureEditorScenePrefabComposition(prefabAsset) {
+    if (!isEditorScenePrefabAsset(prefabAsset)) {
+        return createEditorScenePrefabMutationResult(prefabAsset, false, null, [{
+                code: 'prefab.invalidDefinition',
+                severity: 'error',
+                message: `Asset "${prefabAsset.id}" is not a valid prefab definition.`,
+                assetId: prefabAsset.id,
+            }]);
+    }
+    const next = cloneEditorScenePrefabAssetWithComposition(prefabAsset);
+    return createEditorScenePrefabMutationResult(next, JSON.stringify(next.prefab) !== JSON.stringify(prefabAsset.prefab));
+}
+export function selectEditorScenePrefabNode(prefabAsset, nodeId) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    const normalizedNodeId = readEditorSceneNonEmptyString(nodeId);
+    const node = normalizedNodeId ? findEditorScenePrefabNode(prepared.prefabAsset, normalizedNodeId) : null;
+    if (!node) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.nodeNotFound',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" was not found.`,
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, node, [], {
+        selectedNodeId: node.id,
+    });
+}
+export function renameEditorScenePrefabAsset(document, assetId, displayName) {
+    const normalizedAssetId = readEditorSceneNonEmptyString(assetId);
+    const prefabAsset = normalizedAssetId
+        ? document.assets.find(asset => asset.id === normalizedAssetId && isEditorScenePrefabAsset(asset))
+        : null;
+    if (!prefabAsset) {
+        return createEditorScenePrefabMutationResult({
+            id: normalizedAssetId ?? String(assetId ?? ''),
+            type: 'prefab',
+            prefab: { sourceAssetId: '' },
+        }, false, null, [{
+                code: 'prefab.invalidDefinition',
+                severity: 'error',
+                message: `Prefab asset "${assetId}" was not found.`,
+                assetId,
+            }]);
+    }
+    const nameResult = normalizeEditorScenePrefabEditableName(displayName);
+    if (!nameResult.ok) {
+        return createEditorScenePrefabMutationResult(prefabAsset, false, null, [{
+                code: 'prefab.invalidName',
+                severity: 'error',
+                message: nameResult.message,
+                assetId: prefabAsset.id,
+            }]);
+    }
+    const normalizedDisplayName = nameResult.name;
+    const lowerName = normalizedDisplayName.toLowerCase();
+    const conflict = document.assets.find(candidate => (candidate.id !== prefabAsset.id
+        && isEditorScenePrefabAsset(candidate)
+        && readEditorSceneNonEmptyString(candidate.displayName)?.toLowerCase() === lowerName));
+    if (conflict) {
+        return createEditorScenePrefabMutationResult(prefabAsset, false, null, [{
+                code: 'prefab.nameConflict',
+                severity: 'error',
+                message: `Prefab asset name "${normalizedDisplayName}" is already used by "${conflict.id}".`,
+                assetId: prefabAsset.id,
+            }]);
+    }
+    if (prefabAsset.displayName === normalizedDisplayName) {
+        return createEditorScenePrefabMutationResult(prefabAsset, false);
+    }
+    const next = cloneEditorScenePrefabAssetWithComposition({
+        ...structuredClone(prefabAsset),
+        displayName: normalizedDisplayName,
+    });
+    const rootNodeId = readEditorScenePrefabRootNodeId(next);
+    if (rootNodeId && Array.isArray(next.prefab?.nodes)) {
+        const rootIndex = next.prefab.nodes.findIndex(node => node.id === rootNodeId);
+        if (rootIndex >= 0) {
+            next.prefab.nodes = [...next.prefab.nodes];
+            next.prefab.nodes[rootIndex] = {
+                ...structuredClone(next.prefab.nodes[rootIndex]),
+                name: normalizedDisplayName,
+            };
+        }
+    }
+    return createEditorScenePrefabMutationResult(next, true);
+}
+export function renameEditorScenePrefabNode(prefabAsset, nodeId, name) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    const normalizedNodeId = readEditorSceneNonEmptyString(nodeId);
+    const node = normalizedNodeId ? findEditorScenePrefabNode(prepared.prefabAsset, normalizedNodeId) : null;
+    if (!node) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.nodeNotFound',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" was not found.`,
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    const rootNodeId = readEditorScenePrefabRootNodeId(prepared.prefabAsset);
+    if (node.id === rootNodeId) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, node, [{
+                code: 'prefab.rootRenameRejected',
+                severity: 'error',
+                message: 'Prefab root node name follows the prefab asset displayName; use prefab.asset.rename instead.',
+                assetId: prefabAsset.id,
+                nodeId: node.id,
+            }]);
+    }
+    const nameResult = normalizeEditorScenePrefabEditableName(name);
+    if (!nameResult.ok) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, node, [{
+                code: 'prefab.invalidName',
+                severity: 'error',
+                message: nameResult.message,
+                assetId: prefabAsset.id,
+                nodeId: node.id,
+            }]);
+    }
+    const normalizedName = nameResult.name;
+    const siblings = readEditorScenePrefabNodeChildren(prepared.prefabAsset, node.parentId);
+    const conflict = siblings.find(candidate => (candidate.id !== node.id
+        && readEditorSceneNonEmptyString(candidate.name)?.toLowerCase() === normalizedName.toLowerCase()));
+    if (conflict) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, node, [{
+                code: 'prefab.nameConflict',
+                severity: 'error',
+                message: `Prefab node name "${normalizedName}" is already used by sibling "${conflict.id}".`,
+                assetId: prefabAsset.id,
+                nodeId: node.id,
+                parentId: node.parentId,
+            }]);
+    }
+    return updateEditorScenePrefabNode(prepared.prefabAsset, node.id, (candidate) => ({
+        ...candidate,
+        name: normalizedName,
+    }));
+}
+export function createEditorScenePrefabNodeFromAsset(prefabAsset, asset, options = {}) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    if (asset.id === prefabAsset.id) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.selfReferenceRejected',
+                severity: 'error',
+                message: `Prefab "${prefabAsset.id}" cannot contain itself directly.`,
+                assetId: asset.id,
+            }]);
+    }
+    const parentResult = resolveEditorScenePrefabMutationParent(prepared.prefabAsset, options.parentId);
+    if (!parentResult.ok)
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, parentResult.diagnostics);
+    const nodes = readEditorScenePrefabNodes(prepared.prefabAsset);
+    const isChildPrefab = isEditorScenePrefabAsset(asset);
+    const isModel = asset.type !== 'prefab' && (asset.type === 'glb' || asset.type === 'model' || asset.type === 'gltf');
+    if (!isChildPrefab && !isModel) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.assetUnsupported',
+                severity: 'error',
+                message: `Asset "${asset.id}" cannot be added to a prefab composition.`,
+                assetId: asset.id,
+            }]);
+    }
+    const node = {
+        id: options.id ?? createUniqueEditorScenePrefabNodeId(nodes, `${isChildPrefab ? 'prefab' : 'model'}-${asset.id}`),
+        ...(options.guid ? { guid: options.guid } : {}),
+        name: options.name ?? asset.displayName ?? asset.id,
+        parentId: parentResult.parentId,
+        kind: isChildPrefab ? 'prefabInstance' : 'model',
+        ...(options.transform ? { transform: structuredClone(options.transform) } : {}),
+        ...(isChildPrefab ? { childPrefabId: asset.id } : { sourceAssetId: asset.id }),
+        ...(readEditorSceneNonEmptyString(options.sourceNodePath) ? { sourceNodePath: readEditorSceneNonEmptyString(options.sourceNodePath) } : {}),
+    };
+    return appendEditorScenePrefabNode(prepared.prefabAsset, node);
+}
+export function createEditorScenePrefabPrimitiveNode(prefabAsset, options) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    const parentResult = resolveEditorScenePrefabMutationParent(prepared.prefabAsset, options.parentId);
+    if (!parentResult.ok)
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, parentResult.diagnostics);
+    const shape = readEditorSceneNonEmptyString(options.shape);
+    if (!shape) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.assetUnsupported',
+                severity: 'error',
+                message: 'Prefab primitive shape must be a non-empty string.',
+                assetId: prefabAsset.id,
+            }]);
+    }
+    const nodes = readEditorScenePrefabNodes(prepared.prefabAsset);
+    const node = {
+        id: options.id ?? createUniqueEditorScenePrefabNodeId(nodes, `primitive-${shape}`),
+        ...(options.guid ? { guid: options.guid } : {}),
+        name: options.name ?? `${shape[0].toUpperCase()}${shape.slice(1)}`,
+        parentId: parentResult.parentId,
+        kind: 'primitive',
+        primitive: { shape },
+        ...(options.transform ? { transform: structuredClone(options.transform) } : {}),
+    };
+    return appendEditorScenePrefabNode(prepared.prefabAsset, node);
+}
+export function createEditorScenePrefabGroupNode(prefabAsset, options = {}) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    const parentResult = resolveEditorScenePrefabMutationParent(prepared.prefabAsset, options.parentId);
+    if (!parentResult.ok)
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, parentResult.diagnostics);
+    const nodes = readEditorScenePrefabNodes(prepared.prefabAsset);
+    const node = {
+        id: options.id ?? createUniqueEditorScenePrefabNodeId(nodes, 'group'),
+        ...(options.guid ? { guid: options.guid } : {}),
+        name: options.name ?? 'Empty',
+        parentId: parentResult.parentId,
+        kind: 'group',
+        ...(options.transform ? { transform: structuredClone(options.transform) } : {}),
+    };
+    return appendEditorScenePrefabNode(prepared.prefabAsset, node);
+}
+export function setEditorScenePrefabNodeTransform(prefabAsset, nodeId, transform) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    if (!transform || transform.type !== 'Transform') {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.invalidTransform',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" requires a Transform component payload.`,
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    return updateEditorScenePrefabNode(prepared.prefabAsset, nodeId, (node) => ({
+        ...node,
+        transform: structuredClone(transform),
+    }));
+}
+export function setEditorScenePrefabNodeShadow(prefabAsset, nodeId, shadow) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    return updateEditorScenePrefabNode(prepared.prefabAsset, nodeId, (node) => {
+        const defaults = { ...(node.defaults ?? {}) };
+        if (shadow && Object.keys(shadow).length > 0)
+            defaults.shadow = structuredClone(shadow);
+        else
+            delete defaults.shadow;
+        if (Object.keys(defaults).length > 0)
+            return { ...node, defaults };
+        const { defaults: _defaults, ...rest } = node;
+        return rest;
+    });
+}
+export function reparentEditorScenePrefabNode(prefabAsset, nodeId, parentId) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    const rootNodeId = readEditorScenePrefabRootNodeId(prepared.prefabAsset);
+    if (nodeId === rootNodeId) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.rootReparentRejected',
+                severity: 'error',
+                message: 'Prefab root node cannot be reparented.',
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    const nodes = readEditorScenePrefabNodes(prepared.prefabAsset);
+    if (!nodes.some(node => node.id === nodeId)) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.nodeNotFound',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" was not found.`,
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    if (!nodes.some(node => node.id === parentId)) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.parentNotFound',
+                severity: 'error',
+                message: `Prefab parent node "${parentId}" was not found.`,
+                assetId: prefabAsset.id,
+                nodeId,
+                parentId,
+            }]);
+    }
+    if (nodeId === parentId || isEditorScenePrefabNodeDescendant(nodes, parentId, nodeId)) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.cycleReparentRejected',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" cannot be parented under its own descendant "${parentId}".`,
+                assetId: prefabAsset.id,
+                nodeId,
+                parentId,
+            }]);
+    }
+    return updateEditorScenePrefabNode(prepared.prefabAsset, nodeId, (node) => ({
+        ...node,
+        parentId,
+    }));
+}
+export function deleteEditorScenePrefabNode(prefabAsset, nodeId) {
+    const prepared = ensureEditorScenePrefabComposition(prefabAsset);
+    if (!prepared.ok)
+        return prepared;
+    const rootNodeId = readEditorScenePrefabRootNodeId(prepared.prefabAsset);
+    if (nodeId === rootNodeId) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.rootDeleteRejected',
+                severity: 'error',
+                message: 'Prefab root node cannot be deleted.',
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    const nodes = readEditorScenePrefabNodes(prepared.prefabAsset);
+    const target = nodes.find(node => node.id === nodeId);
+    if (!target) {
+        return createEditorScenePrefabMutationResult(prepared.prefabAsset, false, null, [{
+                code: 'prefab.nodeNotFound',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" was not found.`,
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    const deleted = new Set();
+    collectEditorScenePrefabNodeSubtree(nodes, nodeId, deleted);
+    const next = structuredClone(prepared.prefabAsset);
+    next.prefab = structuredClone(next.prefab);
+    next.prefab.nodes = nodes.filter(node => !deleted.has(node.id));
+    return createEditorScenePrefabMutationResult(next, true, target, [], {
+        deletedNodeIds: [...deleted],
+    });
+}
+function createEditorScenePrefabMutationResult(prefabAsset, changed, node = null, diagnostics = [], extra = {}) {
+    return {
+        ok: diagnostics.every(diagnostic => diagnostic.severity !== 'error'),
+        changed,
+        prefabAsset,
+        ...(extra.selectedNodeId ? { selectedNodeId: extra.selectedNodeId } : {}),
+        ...(extra.createdNodeId ? { createdNodeId: extra.createdNodeId } : {}),
+        ...(extra.deletedNodeIds ? { deletedNodeIds: [...extra.deletedNodeIds] } : {}),
+        ...(node ? { node: structuredClone(node) } : {}),
+        diagnostics: diagnostics.map(diagnostic => ({ ...diagnostic })),
+    };
+}
+function cloneEditorScenePrefabAssetWithComposition(prefabAsset) {
+    const next = structuredClone(prefabAsset);
+    const nodes = readEditorScenePrefabNodes(prefabAsset);
+    next.prefab = structuredClone(next.prefab);
+    next.prefab.compositionVersion = EDITOR_SCENE_PREFAB_COMPOSITION_VERSION;
+    next.prefab.nodes = nodes;
+    const rootNodeId = readEditorScenePrefabRootNodeId({ ...prefabAsset, prefab: { ...prefabAsset.prefab, nodes } });
+    if (rootNodeId)
+        next.prefab.rootNodeId = rootNodeId;
+    else
+        delete next.prefab.rootNodeId;
+    return next;
+}
+function resolveEditorScenePrefabMutationParent(prefabAsset, parentId) {
+    const rootNodeId = readEditorScenePrefabRootNodeId(prefabAsset);
+    const normalizedParentId = readEditorSceneNonEmptyString(parentId) ?? rootNodeId;
+    if (!normalizedParentId || !findEditorScenePrefabNode(prefabAsset, normalizedParentId)) {
+        return {
+            ok: false,
+            diagnostics: [{
+                    code: 'prefab.parentNotFound',
+                    severity: 'error',
+                    message: `Prefab parent node "${normalizedParentId ?? parentId ?? 'root'}" was not found.`,
+                    assetId: prefabAsset.id,
+                    ...(normalizedParentId ? { parentId: normalizedParentId } : {}),
+                }],
+        };
+    }
+    return { ok: true, parentId: normalizedParentId };
+}
+function appendEditorScenePrefabNode(prefabAsset, node) {
+    const next = structuredClone(prefabAsset);
+    const nodes = readEditorScenePrefabNodes(prefabAsset);
+    const nodeId = createUniqueEditorScenePrefabNodeId(nodes, node.id);
+    const nextNode = {
+        ...structuredClone(node),
+        id: nodeId,
+    };
+    next.prefab = structuredClone(next.prefab);
+    next.prefab.compositionVersion = EDITOR_SCENE_PREFAB_COMPOSITION_VERSION;
+    const rootNodeId = readEditorScenePrefabRootNodeId(prefabAsset);
+    if (rootNodeId)
+        next.prefab.rootNodeId = rootNodeId;
+    else
+        delete next.prefab.rootNodeId;
+    next.prefab.nodes = [...nodes, nextNode];
+    return createEditorScenePrefabMutationResult(next, true, nextNode, [], {
+        createdNodeId: nextNode.id,
+        selectedNodeId: nextNode.id,
+    });
+}
+function updateEditorScenePrefabNode(prefabAsset, nodeId, update) {
+    const nodes = readEditorScenePrefabNodes(prefabAsset);
+    const index = nodes.findIndex(node => node.id === nodeId);
+    if (index < 0) {
+        return createEditorScenePrefabMutationResult(prefabAsset, false, null, [{
+                code: 'prefab.nodeNotFound',
+                severity: 'error',
+                message: `Prefab node "${nodeId}" was not found.`,
+                assetId: prefabAsset.id,
+                nodeId,
+            }]);
+    }
+    const updated = update(structuredClone(nodes[index]));
+    const nextNodes = [...nodes];
+    nextNodes[index] = updated;
+    const next = structuredClone(prefabAsset);
+    next.prefab = structuredClone(next.prefab);
+    next.prefab.compositionVersion = EDITOR_SCENE_PREFAB_COMPOSITION_VERSION;
+    const rootNodeId = readEditorScenePrefabRootNodeId(prefabAsset);
+    if (rootNodeId)
+        next.prefab.rootNodeId = rootNodeId;
+    else
+        delete next.prefab.rootNodeId;
+    next.prefab.nodes = nextNodes;
+    return createEditorScenePrefabMutationResult(next, JSON.stringify(nodes[index]) !== JSON.stringify(updated), updated, [], {
+        selectedNodeId: updated.id,
+    });
+}
+function createUniqueEditorScenePrefabNodeId(nodes, preferredId) {
+    const used = new Set(nodes.map(node => node.id));
+    const base = normalizeEditorScenePrefabIdentifierPart(preferredId) ?? 'prefab_node';
+    if (!used.has(base))
+        return base;
+    let suffix = 1;
+    let candidate = `${base}_${suffix}`;
+    while (used.has(candidate)) {
+        suffix += 1;
+        candidate = `${base}_${suffix}`;
+    }
+    return candidate;
+}
+function isEditorScenePrefabNodeDescendant(nodes, candidateNodeId, ancestorNodeId) {
+    let current = nodes.find(node => node.id === candidateNodeId);
+    const visited = new Set();
+    while (current?.parentId) {
+        if (current.parentId === ancestorNodeId)
+            return true;
+        if (visited.has(current.parentId))
+            return false;
+        visited.add(current.parentId);
+        current = nodes.find(node => node.id === current?.parentId);
+    }
+    return false;
+}
+function collectEditorScenePrefabNodeSubtree(nodes, nodeId, output) {
+    if (output.has(nodeId))
+        return;
+    output.add(nodeId);
+    for (const child of nodes.filter(node => node.parentId === nodeId)) {
+        collectEditorScenePrefabNodeSubtree(nodes, child.id, output);
+    }
+}
 export function createEditorScenePrefabDefinitionFromAsset(sourceAsset, options = {}) {
     return {
         id: options.id ?? `${sourceAsset.id}-prefab`,
@@ -41,10 +550,98 @@ export function createEditorScenePrefabDefinitionFromAsset(sourceAsset, options
             sourceAssetId: sourceAsset.id,
             ...(sourceAsset.guid ? { sourceAssetGuid: sourceAsset.guid } : {}),
             ...(options.defaults ? { defaults: { ...options.defaults } } : {}),
+            compositionVersion: EDITOR_SCENE_PREFAB_COMPOSITION_VERSION,
+            rootNodeId: EDITOR_SCENE_PREFAB_LEGACY_ROOT_NODE_ID,
+            nodes: [
+                {
+                    id: EDITOR_SCENE_PREFAB_LEGACY_ROOT_NODE_ID,
+                    name: options.displayName ?? createEditorScenePrefabDisplayName(sourceAsset),
+                    kind: 'root',
+                    ...(options.defaults ? { defaults: { ...options.defaults } } : {}),
+                },
+                {
+                    id: EDITOR_SCENE_PREFAB_LEGACY_MODEL_NODE_ID,
+                    name: sourceAsset.displayName ?? sourceAsset.id,
+                    parentId: EDITOR_SCENE_PREFAB_LEGACY_ROOT_NODE_ID,
+                    kind: 'model',
+                    sourceAssetId: sourceAsset.id,
+                },
+            ],
         },
         ...(options.metadata ? { metadata: { ...options.metadata } } : {}),
     };
 }
+function readEditorScenePrefabExplicitNodes(prefab) {
+    if (!Array.isArray(prefab.nodes))
+        return [];
+    const nodes = [];
+    for (const rawNode of prefab.nodes) {
+        const node = readEditorScenePrefabNode(rawNode);
+        if (node && !nodes.some(existing => existing.id === node.id))
+            nodes.push(node);
+    }
+    return structuredClone(nodes);
+}
+function readEditorScenePrefabNode(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const id = readEditorSceneNonEmptyString(record.id);
+    if (!id || !isEditorScenePrefabNodeKind(record.kind))
+        return null;
+    return {
+        id,
+        ...(readEditorSceneNonEmptyString(record.guid) ? { guid: readEditorSceneNonEmptyString(record.guid) } : {}),
+        ...(readEditorSceneNonEmptyString(record.name) ? { name: readEditorSceneNonEmptyString(record.name) } : {}),
+        ...(readEditorSceneNonEmptyString(record.parentId) ? { parentId: readEditorSceneNonEmptyString(record.parentId) } : {}),
+        kind: record.kind,
+        ...(record.transform ? { transform: structuredClone(record.transform) } : {}),
+        ...(readEditorSceneNonEmptyString(record.sourceAssetId) ? { sourceAssetId: readEditorSceneNonEmptyString(record.sourceAssetId) } : {}),
+        ...(readEditorSceneNonEmptyString(record.sourceNodePath) ? { sourceNodePath: readEditorSceneNonEmptyString(record.sourceNodePath) } : {}),
+        ...(readEditorSceneNonEmptyString(record.childPrefabId) ? { childPrefabId: readEditorSceneNonEmptyString(record.childPrefabId) } : {}),
+        ...(record.primitive ? { primitive: structuredClone(record.primitive) } : {}),
+        ...(record.light ? { light: structuredClone(record.light) } : {}),
+        ...(record.defaults ? { defaults: structuredClone(record.defaults) } : {}),
+        ...(record.overrides ? { overrides: structuredClone(record.overrides) } : {}),
+        ...(record.metadata ? { metadata: structuredClone(record.metadata) } : {}),
+    };
+}
+function isEditorScenePrefabNodeKind(value) {
+    return value === 'root'
+        || value === 'group'
+        || value === 'model'
+        || value === 'primitive'
+        || value === 'light'
+        || value === 'prefabInstance'
+        || value === 'collision';
+}
+function createEditorScenePrefabLegacyCompositionNodes(prefabAsset) {
+    const root = createEditorScenePrefabLegacyRootNode(prefabAsset);
+    const sourceAssetId = resolveEditorScenePrefabSourceAssetId(prefabAsset);
+    if (!root || !sourceAssetId)
+        return [];
+    return [
+        root,
+        {
+            id: EDITOR_SCENE_PREFAB_LEGACY_MODEL_NODE_ID,
+            name: readEditorSceneNonEmptyString(prefabAsset.displayName) ?? sourceAssetId,
+            parentId: root.id,
+            kind: 'model',
+            sourceAssetId,
+        },
+    ];
+}
+function createEditorScenePrefabLegacyRootNode(prefabAsset) {
+    if (!resolveEditorScenePrefabSourceAssetId(prefabAsset))
+        return null;
+    return {
+        id: EDITOR_SCENE_PREFAB_LEGACY_ROOT_NODE_ID,
+        name: readEditorSceneNonEmptyString(prefabAsset.displayName) ?? 'Prefab',
+        kind: 'root',
+        ...(prefabAsset.prefab?.defaults ? { defaults: structuredClone(prefabAsset.prefab.defaults) } : {}),
+        ...(prefabAsset.prefab?.overrides ? { overrides: structuredClone(prefabAsset.prefab.overrides) } : {}),
+    };
+}
 export function createEditorScenePrefabInstanceGameObject(input) {
     const sourceAssetId = resolveEditorScenePrefabSourceAssetId(input.prefabAsset);
     if (!sourceAssetId) {
@@ -59,6 +656,7 @@ export function createEditorScenePrefabInstanceGameObject(input) {
         ...(input.parentId ? { parentId: input.parentId } : {}),
         active: input.active ?? defaults?.active ?? true,
         ...(input.shadowMode ?? defaults?.shadowMode ? { shadowMode: input.shadowMode ?? defaults?.shadowMode } : {}),
+        ...(input.shadow ?? defaults?.shadow ? { shadow: structuredClone(input.shadow ?? defaults?.shadow) } : {}),
         prefab: {
             prefabId: input.prefabAsset.id,
             ...(input.prefabAsset.guid ? { prefabGuid: input.prefabAsset.guid } : {}),
@@ -374,8 +972,7 @@ export function resolveEditorSceneGameObjectRendering(gameObject) {
         ? gameObject.rendering
         : undefined;
     const renderingGroupId = readEditorSceneGameObjectRenderingGroupId(rendering?.renderingGroupId);
-    const alphaIndex = readEditorSceneFiniteNumber(rendering?.alphaIndex)
-        ?? readEditorSceneLegacyGroundDecalAlphaIndex(gameObject);
+    const alphaIndex = readEditorSceneFiniteNumber(rendering?.alphaIndex);
     const resolved = {};
     if (renderingGroupId != null)
         resolved.renderingGroupId = renderingGroupId;
@@ -395,18 +992,25 @@ function isEditorSceneTransformComponent(component) {
 function isEditorSceneModelRendererComponent(component) {
     return component.type === 'ModelRenderer';
 }
-function readEditorSceneLegacyGroundDecalAlphaIndex(gameObject) {
-    const groundDecal = gameObject.groundDecal;
-    if (!groundDecal || typeof groundDecal !== 'object' || Array.isArray(groundDecal))
-        return null;
-    return readEditorSceneFiniteNumber(groundDecal.alphaIndex);
-}
 function readEditorSceneFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
 function readEditorSceneNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
 }
+function normalizeEditorScenePrefabEditableName(value) {
+    if (typeof value !== 'string')
+        return { ok: false, message: 'Prefab name must be a string.' };
+    const name = value.trim();
+    if (!name)
+        return { ok: false, message: 'Prefab name cannot be empty.' };
+    if (name.length > 80)
+        return { ok: false, message: 'Prefab name cannot be longer than 80 characters.' };
+    if (/[\u0000-\u001f\u007f/\\]/u.test(name)) {
+        return { ok: false, message: 'Prefab name cannot contain control characters, /, or \\.' };
+    }
+    return { ok: true, name };
+}
 function findEditorSceneGameObject(document, gameObjectId) {
     return document.scene.gameObjects.find(gameObject => gameObject.id === gameObjectId) ?? null;
 }