@fps-games/editor 0.2.0-beta.4 → 0.2.1-beta.2

package/dist/local-editor-harness.d.ts

@@ -1,14 +1,39 @@
-import { type AuthoringCommandResult, type AuthoringSourceDescriptor, type DocumentCommand, type EditorPlacementHit, type EditorProjectionImpact, type EditorSelectionState, type EditorSession, type EditorTransformBatchCommit, type EditorTransformCanonicalConstraint, type EditorTransformDocumentCapabilities, type EditorTransformSnapshot, type EditorTransformSpace, type EditorTransformTool, type EditorViewportGroundMeasurement, type EditorViewportToolState, type SceneGraphCreateGroupIntent, type SceneGraphCreatePrimitiveIntent, type SceneGraphDeleteIntent, type SceneGraphDropIntent, type SceneGraphGroupSelectionIntent, type SceneGraphMoveIntent, type SceneGraphRenameIntent, type SceneGraphValidationResult, type InspectorControlKind, type InspectorCommitMode, type InspectorComponentRegistration, type InspectorEditPayload, type InspectorObject, type InspectorPersistenceMode, type InspectorProperty, type InspectorRegistry, type InspectorRegistryConflictStrategy, type InspectorSection, type InspectorSelectionContext, type EditorHostServices, type EditorAgentBridge, type ProjectAuthoringHost } from '@fps-games/editor-core';
-import { type ArtistMaterialTextureRef, type SpatialMarkerGraph, type SpatialMarkerNode, type SpatialMarkerTypeDefinition, type SpatialRelation, type SpatialRelationTypeDefinition } from '@fps-games/editor-protocol';
-import { type LocalEditorBrowserAssetActionInput, type LocalEditorBrowserUiAssetItem, type LocalEditorBrowserHierarchyContextActionContext, type LocalEditorBrowserHierarchyContextActionRegistration, type LocalEditorBrowserInspectorOptions, type LocalEditorBrowserRenderingPanelState, type LocalEditorBrowserRenderingActionInput, type LocalEditorBrowserRenderingPropertyChangeInput, type LocalEditorBrowserUiHierarchyItem, type LocalEditorBrowserUiState, type LocalEditorThemeController, type LocalEditorThemeName } from '@fps-games/editor-browser';
-import type { FpsEditorPluginHost } from '@fps-games/editor-core/plugin-host';
-import { type BabylonEnvironmentTextureProfile, type BabylonDefaultPostProcessProfile } from '@fps-games/babylon-renderer';
-import { type BabylonEditorProjection, type BabylonEditorProjectionBatchStatus, type BabylonEditorProjectionImportStructureSnapshot, type BabylonSceneViewMeasurementController, type BabylonEditorShadowPreviewOptions, type BabylonEditorProjectionImportContext, type BabylonEditorProjectionImportResult, type BabylonEditorProjectionNode, type BabylonEditorProjectionSelectionEdgesPrewarm, type BabylonSceneCameraPreviewRig, type BabylonEditorGridController, type BabylonEditorGridColorOptions, type BabylonEditorWorldAppearanceOptions, type BabylonEditorSkyOptions, type BabylonRuntimeGlobal, type RuntimeScene } from '@fps-games/editor-babylon';
-import { type LocalEditorAgentBridgeSessionMetadata } from './local-editor-agent-bridge-transport.js';
-import type { PlayableLocalEditorInteractionPolicy, PlayableLocalEditorSaveFailureState, PlayableLocalEditorUnsavedChangesState } from '@fps-games/editor-playable-sdk';
+import { type AuthoringCommandResult, type AuthoringSourceDescriptor, type DocumentCommand, type EditorPlacementHit, type EditorProjectionImpact, type EditorSelectionState, type EditorSession, type EditorSessionChange, type EditorTransformBatchCommit, type EditorTransformCanonicalConstraint, type EditorTransformDocumentCapabilities, type EditorTransformOperationSettings, type EditorTransformSnapshot, type EditorTransformSpace, type EditorTransformTool, type EditorTransformVec3, type EditorViewportGroundMeasurement, type EditorViewportSpatialOverlayState, type EditorViewportToolState, type SelectionCommand, type SceneGraphCreateGroupIntent, type SceneGraphCreatePrimitiveIntent, type SceneGraphDeleteIntent, type SceneGraphDropIntent, type SceneGraphGroupSelectionIntent, type SceneGraphMoveIntent, type SceneGraphRenameIntent, type SceneGraphTreeItem, type SceneGraphValidationResult, type InspectorControlKind, type InspectorCommitMode, type InspectorComponentRegistration, type InspectorEditPayload, type InspectorObject, type InspectorPersistenceMode, type InspectorProperty, type InspectorRegistry, type InspectorRegistryConflictStrategy, type InspectorSection, type InspectorSelectionContext, type EditorHostServices, type EditorAgentBridge, type ProjectAuthoringHost } from '@fps-games/editor-core';
+import { type EditingContextProvider, type EditingContextSnapshot, type EditorToolManager } from '@fps-games/editor-core/tools';
+import { type EditorDiagnosticStore } from '@fps-games/editor-core/diagnostics';
+import { type EditorDiagnostic, type EditorDiagnosticLocator, type EditorDiagnosticPhase, type ArtistMaterialTextureRef, type SpatialMarkerGraph, type SpatialMarkerNode, type SpatialMarkerTypeDefinition, type SpatialRelation, type SpatialRelationTypeDefinition } from '@fps-games/editor-protocol';
+import { type LocalEditorBrowserAssetActionInput, type LocalEditorBrowserUiAssetItem, type LocalEditorBrowserProjectFileContent, type LocalEditorBrowserProjectFileSnapshot, type LocalEditorBrowserProjectEntryAgentInput, type LocalEditorBrowserProjectMediaSource, type LocalEditorBrowserInspectorOptions, type LocalEditorBrowserPerformanceStats, type LocalEditorBrowserRenderingPanelState, type LocalEditorBrowserRenderingActionInput, type LocalEditorBrowserRenderingPropertyChangeInput, type LocalEditorBrowserUiPropertyInput, type LocalEditorBrowserUiState, type LocalEditorThemeController, type LocalEditorThemeName } from '@fps-games/editor-browser';
+import { type FpsEditorPluginHost } from '@fps-games/editor-core/plugin-host';
+import { LocalEditorPrefabStageTransactionController } from './local-editor-prefab-stage-transaction.js';
+import { type BabylonEnvironmentTextureController, type BabylonEnvironmentTextureProfile, type BabylonDefaultPostProcessPipelineController, type BabylonDefaultPostProcessProfile } from '@fps-games/babylon-renderer';
+import { type BabylonEditorProjection, type BabylonEditorMarkerOverlayController, type BabylonEditorProjectionBatchStatus, type BabylonEditorProjectionImportStructureSnapshot, type BabylonProjectionSelectionBox, type BabylonProjectionSelectionController, type BabylonSceneViewCameraController, type BabylonSceneViewCameraState, type BabylonSceneViewInputController, type BabylonSceneViewMeasurementController, type BabylonSceneViewSpatialOverlayController, type BabylonEditorShadowPreviewController, type BabylonEditorShadowPreviewOptions, type BabylonEditorProjectionImportContext, type BabylonEditorProjectionImportResult, type BabylonEditorProjectionMaterialProfileDiagnostic, type BabylonEditorProjectionNode, type BabylonEditorProjectionSelectionEdgesPrewarm, type BabylonSceneCameraPreviewController, type BabylonSceneCameraPreviewRig, type BabylonEditorGridController, type BabylonEditorGridColorOptions, type BabylonTransformGizmoCommit, type BabylonTransformGizmoController, type BabylonTransformGizmoDuplicateDragInput, type BabylonTransformGizmoDuplicateDragResult, type BabylonEditorWorld, type BabylonEditorWorldAppearanceOptions, type BabylonEditorSkyOptions, type BabylonEditorPerformanceMonitor, type BabylonRuntimeGlobal, type RuntimeScene } from '@fps-games/editor-babylon';
+import { type LocalEditorSceneRenderScheduler, type LocalEditorSceneRenderStats } from './local-editor-scene-render-scheduler.js';
+import { type LocalEditorViewportRenderCoordinator } from './local-editor-viewport-render-coordinator.js';
+import { type LocalEditorSceneViewInteractionRuntime } from './local-editor-scene-view-interaction-runtime.js';
+import { type HierarchyOperationContext, type HierarchyOperationDescriptor, type HierarchyOperationInvocation, type HierarchyOperationResult, type HierarchySelectionChange, type HierarchyScopeSnapshot, type HierarchyScopeProvider, type HierarchySurfaceContribution, type HierarchyTreeSnapshot } from '@fps-games/plugin-hierarchy';
+import { type LocalEditorAgentBridgeSessionMetadata, type LocalEditorAgentBridgeTransportController, type LocalEditorAgentBridgeTransportStatus } from './local-editor-agent-bridge-transport.js';
+import type { PlayableLocalEditorInteractionPolicy, PlayableLocalEditorDocumentOperationExecutor, PlayableLocalEditorSaveOptions, PlayableLocalEditorSaveFailureState, PlayableLocalEditorUnsavedChangesState } from '@fps-games/editor-playable-sdk';
+import { type PlayableLocalEditorLifecycleController } from '@fps-games/editor-playable-sdk/internal/local-harness';
 import type { FpsEditorLifecycleService } from '@fps-games/editor-core/lifecycle';
 export type LocalEditorHarnessMode = 'game' | 'editor';
 type LocalEditorMaybePromise<T> = T | Promise<T>;
+interface LocalEditorMarkerRelationEndpointInput {
+    kind: string;
+    id: string;
+}
+interface LocalEditorMarkerRelationPickState {
+    active: boolean;
+    type?: string;
+    typeLabel?: string;
+    directed?: boolean;
+    from?: LocalEditorMarkerRelationEndpointInput | null;
+    status?: string;
+    statusTone?: 'default' | 'success' | 'warning' | 'error';
+}
+interface LocalEditorMarkerCreateReservations {
+    ids: Set<string>;
+    labels: Set<string>;
+}
 export interface LocalEditorAuthoringFailureStatus {
     status: string;
     details: string;
@@ -27,7 +52,9 @@ export interface LocalEditorHarnessAssetItem {
     };
     origin?: string;
     dedupeKey?: string;
+    contentHash?: string;
     displayName?: string;
+    relativePath?: string;
     meta?: string;
     placeable?: boolean;
     preview?: LocalEditorBrowserUiAssetItem['preview'];
@@ -157,36 +184,38 @@ export interface LocalEditorHarnessPlacedAssetInput<TDocument = unknown, TAsset
     asset: TAsset;
     hit: EditorPlacementHit;
 }
-export interface LocalEditorHarnessHierarchyContextActionContext<TDocument = unknown> {
+export interface LocalEditorHarnessHierarchyOperationContext<TDocument = unknown> {
+    /**
+     * `visible` and `disabled` receive a deeply frozen, revision-cached document
+     * for plain structured data, or an isolated clone for non-plain documents.
+     * `run` always receives an isolated mutable clone. Treat availability input as read-only.
+     */
     document: TDocument;
+    scope: HierarchyScopeSnapshot;
     contextNodeId: string | null;
     targetIds: string[];
     activeId: string | null;
-    hierarchyItem: LocalEditorBrowserUiHierarchyItem | null;
-    projectionNode: BabylonEditorProjectionNode | null;
-    hostServices: EditorHostServices | null;
-    payload?: Record<string, unknown>;
-    browserContext: LocalEditorBrowserHierarchyContextActionContext<TDocument>;
+    resolveTarget(rowId: string): LocalEditorHierarchyResolvedTarget | null;
+    input?: Readonly<Record<string, import('@fps-games/plugin-hierarchy').HierarchyJsonValue>>;
 }
-export interface LocalEditorHarnessHierarchyContextActionRegistration<TDocument = unknown, TPatch = unknown> {
+export interface LocalEditorHarnessHierarchyOperationRegistration<TDocument = unknown, TPatch = unknown> {
     id: string;
     label: string;
+    description?: string;
+    effect?: 'selection' | 'authoring' | 'view' | 'runtime-transient';
+    targetPolicy?: 'none' | 'single' | 'multiple';
+    menu?: HierarchyOperationDescriptor['menu'];
+    /**
+     * @deprecated Use `menu` for nested context menu presentation. Kept as a
+     * compatibility bridge so existing project-side Hierarchy operations do not
+     * need an immediate migration when upgrading the editor.
+     */
+    placement?: HierarchyOperationDescriptor['placement'];
     shortcut?: string;
     danger?: boolean;
-    placement?: LocalEditorBrowserHierarchyContextActionRegistration<TDocument>['placement'];
-    separatorBefore?: boolean;
-    children?: readonly LocalEditorHarnessHierarchyContextActionChildRegistration<TDocument>[] | ((context: LocalEditorHarnessHierarchyContextActionContext<TDocument>) => readonly LocalEditorHarnessHierarchyContextActionChildRegistration<TDocument>[]);
-    visible?(context: LocalEditorHarnessHierarchyContextActionContext<TDocument>): boolean;
-    disabled?(context: LocalEditorHarnessHierarchyContextActionContext<TDocument>): boolean | string;
-    run(context: LocalEditorHarnessHierarchyContextActionContext<TDocument>): LocalEditorMaybePromise<boolean | void | LocalEditorHarnessPatchResult<TPatch>>;
-}
-export interface LocalEditorHarnessHierarchyContextActionChildRegistration<TDocument = unknown> {
-    id: string;
-    label: string;
-    shortcut?: string;
-    danger?: boolean;
-    disabled?(context: LocalEditorHarnessHierarchyContextActionContext<TDocument>): boolean | string;
-    payload?(context: LocalEditorHarnessHierarchyContextActionContext<TDocument>): Record<string, unknown> | undefined;
+    visible?(context: LocalEditorHarnessHierarchyOperationContext<TDocument>): boolean;
+    disabled?(context: LocalEditorHarnessHierarchyOperationContext<TDocument>): boolean | string;
+    run(context: LocalEditorHarnessHierarchyOperationContext<TDocument>): LocalEditorMaybePromise<boolean | void | LocalEditorHarnessPatchResult<TPatch>>;
 }
 export interface LocalEditorHarnessPatchResult<TPatch> {
     patch: TPatch;
@@ -247,6 +276,7 @@ export interface LocalEditorHarnessDuplicateSelectionPatch<TPatch> {
     patch: TPatch;
     label?: string;
     createdIds: string[];
+    selectedIds?: string[];
     activeId?: string | null;
     changedIds?: string[];
     reprojectIds?: string[];
@@ -271,6 +301,7 @@ export interface LocalEditorHarnessAssetReloadResult {
     ok: boolean;
     assetCount: number;
     status: string;
+    refreshedAssetIds?: string[];
     error?: string;
 }
 export interface LocalEditorHarnessUpdatedAssetWarning {
@@ -304,6 +335,7 @@ export interface LocalEditorHarnessUpdatedAssetApplyResult<TDocument> {
 export interface LocalEditorHarnessUpdatedAssetProjectionState {
     pending: boolean;
 }
+export declare function findLocalEditorUpdatedAssetIds(previousAssets: readonly LocalEditorHarnessUpdatedAssetSnapshot[], nextAssets: readonly LocalEditorHarnessUpdatedAssetSnapshot[]): string[];
 export declare function assertLocalEditorUpdatedAssetSnapshotFreshness(snapshot: LocalEditorHarnessUpdatedAssetSnapshot | null, input: {
     assetId: string;
     expectedContentHash: string;
@@ -318,6 +350,15 @@ export declare function applyLocalEditorUpdatedAssetRefresh<TDocument, TPatch, T
     }): LocalEditorHarnessUpdatedAssetReconcileResult<TDocument>;
     compareDocuments?(left: TDocument, right: TDocument): boolean;
 }): LocalEditorHarnessUpdatedAssetApplyResult<TDocument>;
+export declare function applyLocalEditorUpdatedAssetsRefresh<TDocument, TPatch, TAsset>(session: EditorSession<TDocument, TPatch>, input: {
+    assetIds: readonly string[];
+    assets: TAsset[];
+    hydrateDocumentAssets(document: TDocument, assets: TAsset[]): TDocument;
+    reconcileUpdatedAsset?(document: TDocument, input: {
+        assetId: string;
+    }): LocalEditorHarnessUpdatedAssetReconcileResult<TDocument>;
+    compareDocuments?(left: TDocument, right: TDocument): boolean;
+}): LocalEditorHarnessUpdatedAssetApplyResult<TDocument>;
 export interface LocalEditorHarnessAssetCreationResult {
     ok: boolean;
     assetId: string;
@@ -367,6 +408,7 @@ export interface LocalEditorHarnessAssetActionPatchInput<TDocument, TAsset = Loc
     asset: TAsset | null;
     activeId: string | null;
     selectedIds: string[];
+    markerTypes?: readonly SpatialMarkerTypeDefinition[];
 }
 export interface LocalEditorHarnessPrefabStageInput<TAsset = LocalEditorHarnessAssetItem> {
     assetId: string;
@@ -402,7 +444,7 @@ export interface LocalEditorHarnessPreviewTarget {
     readonly?: boolean;
     disabledReason?: string;
 }
-export type LocalEditorHarnessPrefabStageStructureItemKind = 'root' | 'source' | 'group' | 'mesh' | 'material' | 'texture' | 'animation' | 'info';
+export type LocalEditorHarnessPrefabStageStructureItemKind = 'root' | 'source' | 'group' | 'marker' | 'mesh' | 'material' | 'texture' | 'animation' | 'info';
 export interface LocalEditorHarnessPrefabStageStructureItem {
     id: string;
     label: string;
@@ -423,8 +465,21 @@ export interface LocalEditorHarnessPrefabStageStructureItem {
     sourceMaterialIndices?: number[];
     sourceMaterialName?: string;
     sourceMaterialNames?: string[];
+    transform?: EditorTransformSnapshot;
     children?: LocalEditorHarnessPrefabStageStructureItem[];
 }
+interface LocalEditorHarnessPrefabStageRuntimeState<TDocument, TPatch, TAsset> {
+    editingAuthority: object;
+    transaction: LocalEditorPrefabStageTransactionController<TDocument, TPatch>;
+    descriptor: LocalEditorHarnessPrefabStageDescriptor<TDocument>;
+    asset: TAsset | null;
+    documentScopeId: string | null;
+    sessionScopeId: string | null;
+    previewScopeId: string | null;
+    selectedItemId: string | null;
+    selectedItemIds: readonly string[];
+    restoreSceneCameraPreviewEnabled: boolean;
+}
 export interface LocalEditorHarnessRenderingPanelStateContext {
     scene: RuntimeScene | null;
     projection: BabylonEditorProjection | null;
@@ -478,6 +533,7 @@ export interface LocalEditorHarnessDocumentAdapter<TDocument, TPatch, TAsset = L
     resolveUpdatedAssetSnapshot?(assets: TAsset[], input: {
         assetId: string;
     }): LocalEditorHarnessUpdatedAssetSnapshot | null;
+    listAssetSnapshots?(assets: TAsset[]): LocalEditorHarnessUpdatedAssetSnapshot[];
     reconcileUpdatedAsset?(document: TDocument, input: {
         assetId: string;
     }): LocalEditorHarnessUpdatedAssetReconcileResult<TDocument>;
@@ -485,16 +541,37 @@ export interface LocalEditorHarnessDocumentAdapter<TDocument, TPatch, TAsset = L
     getInspectorObject?(document: TDocument, activeId: string): InspectorObject<TDocument> | null;
     getInspectorMultiObject?(document: TDocument, selectedIds: string[], activeId: string | null): InspectorObject<TDocument> | null;
     getRuntimeInspectorSections?(context: LocalEditorHarnessRuntimeInspectorContext<TDocument>): InspectorSection<TDocument>[];
-    getHierarchyItems(document: TDocument): LocalEditorBrowserUiHierarchyItem[];
+    getHierarchyItems(document: TDocument): SceneGraphTreeItem[];
+    isHierarchyStructureChange?(command: DocumentCommand<TDocument, TPatch>): boolean;
     getMarkerGraph?(document: TDocument): SpatialMarkerGraph | null;
     getMarkerTypeCatalog?(document: TDocument): SpatialMarkerTypeDefinition[];
     getRelationTypeCatalog?(document: TDocument): SpatialRelationTypeDefinition[];
+    getPrefabInstanceMarkerOverlays?(document: TDocument): Array<{
+        ownerInstanceId: string;
+        localNodeId: string;
+        marker: SpatialMarkerNode;
+    }>;
+    getPrefabStageMarkerOverlays?(document: TDocument, prefabAssetId: string, previewInstanceId: string): Array<{
+        ownerInstanceId: string;
+        localNodeId: string;
+        marker: SpatialMarkerNode;
+    }>;
     getBrowserAssetItems?(document: TDocument): LocalEditorBrowserUiAssetItem[];
     getProjectionNodes(document: TDocument): BabylonEditorProjectionNode[];
     getProjectionNode(document: TDocument, id: string): BabylonEditorProjectionNode | null;
+    getProjectionNodesForTarget?(document: TDocument, targetId: string): BabylonEditorProjectionNode[];
+    resolveProjectionTargetId?(document: TDocument, projectionNodeId: string): string | null;
+    getProjectionSelectionNodeIds?(document: TDocument, targetId: string): string[];
     getSceneCameraPreviewRig?(document: TDocument): BabylonSceneCameraPreviewRig | null;
     getWorldAppearance?(document: TDocument): LocalEditorHarnessWorldAppearance | null;
     getWorldRendering?(document: TDocument): LocalEditorHarnessWorldRendering | null;
+    getShadowMapExperimentConfig?(): unknown | null;
+    getShadowMapExperimentPlan?(document: TDocument): unknown | null;
+    createShadowMapExperimentProfilesPatch?(input: {
+        document: TDocument;
+        qualityProfile?: string | null;
+        behaviorProfile?: string | null;
+    }): LocalEditorHarnessPatchResult<TPatch> | null;
     getPrefabStageDescriptor?(document: TDocument, input: LocalEditorHarnessPrefabStageInput<TAsset>): LocalEditorHarnessPrefabStageDescriptor<TDocument> | null;
     getPrefabStageProjectionNodes?(document: TDocument, descriptor: LocalEditorHarnessPrefabStageDescriptor<TDocument>): BabylonEditorProjectionNode[];
     getPrefabStageStructure?(document: TDocument, descriptor: LocalEditorHarnessPrefabStageDescriptor<TDocument>, context: LocalEditorHarnessPrefabStageContext): LocalEditorHarnessPrefabStageStructureItem[];
@@ -528,6 +605,13 @@ export interface LocalEditorHarnessDocumentAdapter<TDocument, TPatch, TAsset = L
     createSceneGraphMovePatch?(document: TDocument, intent: SceneGraphMoveIntent): LocalEditorHarnessSceneGraphMovePatch<TPatch> | null;
     validateSceneGraphGroupSelection?(document: TDocument, intent: SceneGraphGroupSelectionIntent): SceneGraphValidationResult;
     createSceneGraphGroupSelectionPatch?(document: TDocument, intent: SceneGraphGroupSelectionIntent): LocalEditorHarnessSceneGraphGroupSelectionPatch<TPatch> | null;
+    validateDocument?(document: TDocument, context: {
+        phase: EditorDiagnosticPhase;
+        scopeId: string;
+        documentRevision: number;
+        projectionRevision: number;
+    }): readonly EditorDiagnostic[];
+    resolveDiagnosticLocator?(document: TDocument, diagnostic: EditorDiagnostic): EditorDiagnosticLocator | null;
     summarize?(document: TDocument): string;
 }
 export interface LocalEditorHarnessPersistenceAdapter<TDocument, TAsset = LocalEditorHarnessAssetItem> {
@@ -539,6 +623,9 @@ export interface LocalEditorHarnessPersistenceAdapter<TDocument, TAsset = LocalE
     }>;
     loadDocument?(): LocalEditorMaybePromise<TDocument>;
     loadAssets(): LocalEditorMaybePromise<TAsset[]>;
+    loadProjectFiles?(): LocalEditorMaybePromise<LocalEditorBrowserProjectFileSnapshot>;
+    loadProjectFile?(path: string): LocalEditorMaybePromise<LocalEditorBrowserProjectFileContent>;
+    resolveProjectMedia?(path: string): LocalEditorMaybePromise<LocalEditorBrowserProjectMediaSource | null>;
     saveAuthoringSource?(input: {
         source: AuthoringSourceDescriptor;
         document: TDocument;
@@ -585,6 +672,7 @@ export interface LocalEditorHarnessOptions<TDocument, TPatch, TAsset = LocalEdit
     root?: HTMLElement;
     theme?: LocalEditorThemeName;
     localTestActions?: boolean;
+    gameModeEntryVisible?: boolean;
     pluginHost?: FpsEditorPluginHost;
     authoringHost?: ProjectAuthoringHost;
     hostServices?: EditorHostServices;
@@ -613,7 +701,13 @@ export interface LocalEditorHarnessOptions<TDocument, TPatch, TAsset = LocalEdit
     };
     inspector?: LocalEditorHarnessInspectorOptions<TDocument>;
     hierarchy?: {
-        contextActions?: readonly LocalEditorHarnessHierarchyContextActionRegistration<TDocument, TPatch>[];
+        /** Explicit first-party contribution for isolated harness fixtures without a Plugin Host. */
+        surface?: HierarchySurfaceContribution;
+        providers?: readonly HierarchyScopeProvider[];
+        operations?: readonly LocalEditorHarnessHierarchyOperationRegistration<TDocument, TPatch>[];
+    };
+    agentContext?: {
+        sendProjectEntry(input: LocalEditorBrowserProjectEntryAgentInput): LocalEditorMaybePromise<unknown>;
     };
     agentBridge?: {
         sessionMetadata?: LocalEditorAgentBridgeSessionMetadata;
@@ -628,10 +722,19 @@ export interface LocalEditorHarness<TDocument = unknown> {
     getHostServices(): EditorHostServices | null;
     getAgentBridge(): EditorAgentBridge | null;
     getWorkingDocument(): TDocument | null;
+    projectAssetDropPoint(point: {
+        x: number;
+        y: number;
+    } | null): EditorTransformVec3 | null;
+    getDocumentRevision(): number;
     getUnsavedChangesState(): PlayableLocalEditorUnsavedChangesState;
     getSaveFailureState(): PlayableLocalEditorSaveFailureState | null;
     getDefaultInteractionPolicy?(): PlayableLocalEditorInteractionPolicy | undefined;
     getLifecycleService(): FpsEditorLifecycleService | null;
+    validateOperation(phase: 'save' | 'run' | 'export'): boolean;
+    validateOperationSettled(phase: 'save' | 'run' | 'export'): Promise<boolean>;
+    validateOperationSettledForCurrentDocument(phase: 'save' | 'run' | 'export'): Promise<boolean>;
+    runExclusiveDocumentOperation<TResult>(operation: (executor: PlayableLocalEditorDocumentOperationExecutor) => Promise<TResult>, executor?: PlayableLocalEditorDocumentOperationExecutor): Promise<TResult>;
     reloadAssets(): Promise<LocalEditorHarnessAssetReloadResult>;
     refreshUpdatedAsset(input: {
         assetId: string;
@@ -641,16 +744,231 @@ export interface LocalEditorHarness<TDocument = unknown> {
     undo(options?: LocalEditorHarnessHistoryOperationOptions): Promise<LocalEditorHarnessHistoryOperationResult<TDocument>>;
     redo(options?: LocalEditorHarnessHistoryOperationOptions): Promise<LocalEditorHarnessHistoryOperationResult<TDocument>>;
     enterEditor(): Promise<void>;
-    saveScene(): Promise<boolean>;
-    saveAndRunGame(): Promise<boolean>;
-    discardAndRunGame(): Promise<void>;
+    saveScene(executor?: PlayableLocalEditorDocumentOperationExecutor, options?: PlayableLocalEditorSaveOptions): Promise<boolean>;
+    saveAndRunGame(executor?: PlayableLocalEditorDocumentOperationExecutor): Promise<boolean>;
+    discardAndRunGame(executor?: PlayableLocalEditorDocumentOperationExecutor): Promise<void>;
     dispose(): void;
 }
+interface LocalEditorHarnessState<TDocument, TPatch, TAsset> {
+    editorStateRevision: number;
+    hierarchyRevision: number;
+    hierarchyRevisionOffset: number;
+    hierarchyRevisionSession: EditorSession<TDocument, TPatch> | null;
+    prefabStageStructureRevision: number;
+    hierarchyItemsCacheSession: EditorSession<TDocument, TPatch> | null;
+    hierarchyItemsCacheRevision: number;
+    hierarchyItemsCache: readonly SceneGraphTreeItem[];
+    diagnosticStore: EditorDiagnosticStore;
+    diagnosticPhase: EditorDiagnosticPhase;
+    reuseDiagnosticSnapshotOnNextRender: boolean;
+    markerGraphVisibilityRevision: number;
+    prefabStageStructureCache: {
+        session: EditorSession<TDocument, TPatch> | null;
+        documentStructureRevision: number;
+        stageStructureRevision: number;
+        descriptorKey: string;
+        context: LocalEditorHarnessPrefabStageContext;
+        items: LocalEditorHarnessPrefabStageStructureItem[];
+    } | null;
+    sceneArtifactRevision: number;
+    readonly mode: LocalEditorHarnessMode;
+    readonly lifecycle: FpsEditorLifecycleService | null;
+    scopeOperations: Pick<PlayableLocalEditorLifecycleController, 'openScope' | 'addScopeResource' | 'closeScope'> | null;
+    nextPrefabScopeRevision: number;
+    busy: boolean;
+    documentOperationActive: boolean;
+    session: EditorSession<TDocument, TPatch> | null;
+    createSessionChangeObserver: (getSession: () => EditorSession<TDocument, TPatch>, scopeIds: {
+        document: string;
+        session: string;
+    }) => (change: EditorSessionChange) => void;
+    handleSessionObserverError: (error: unknown) => void;
+    source: AuthoringSourceDescriptor | null;
+    assets: TAsset[];
+    projectFiles: LocalEditorBrowserProjectFileSnapshot | null;
+    projectFilesWarning: string | null;
+    assetFilter: string;
+    updatedAssetProjection: LocalEditorHarnessUpdatedAssetProjectionState;
+    selectedAssetId: string | null;
+    babylon: (BabylonRuntimeGlobal & Record<string, any>) | null;
+    engine: any | null;
+    world: BabylonEditorWorld | null;
+    grid: LocalEditorHarnessGridController | null;
+    gridVisible: boolean;
+    projection: BabylonEditorProjection | null;
+    materialProfileDiagnostics: EditorDiagnostic[];
+    previewVisibility: {
+        overrides: Record<string, boolean>;
+        isolatedObjectIds: string[];
+        reason?: string;
+    };
+    markerOverlay: BabylonEditorMarkerOverlayController | null;
+    prefabDerivedMarkerOwners: Map<string, string>;
+    markerGraphVisibility: LocalEditorMarkerGraphVisibilityState;
+    activeMarkerRelationId: string | null;
+    markerRelationPick: LocalEditorMarkerRelationPickState | null;
+    markerRelationHighlightContinuous: boolean;
+    markerCreateReservations: LocalEditorMarkerCreateReservations;
+    shadowPreview: BabylonEditorShadowPreviewController | null;
+    environmentTexture: BabylonEnvironmentTextureController | null;
+    postProcess: BabylonDefaultPostProcessPipelineController | null;
+    projectionShadowPreviewRebuildFrame: number | null;
+    projectionShadowPreviewRefreshFrame: number | null;
+    gizmo: BabylonTransformGizmoController | null;
+    sceneCameraPreview: BabylonSceneCameraPreviewController | null;
+    sceneCameraPreviewEnabled: boolean;
+    sceneViewInput: BabylonSceneViewInputController | null;
+    sceneViewCamera: BabylonSceneViewCameraController | null;
+    sceneViewInteraction: LocalEditorSceneViewInteractionRuntime | null;
+    sceneViewMeasurement: BabylonSceneViewMeasurementController | null;
+    sceneViewSpatialOverlay: BabylonSceneViewSpatialOverlayController | null;
+    selectionController: BabylonProjectionSelectionController | null;
+    selectionInspectorRefreshGeneration: number;
+    selectionInspectorRefreshFrame: number | null;
+    selectionInspectorRefreshTimeout: ReturnType<typeof globalThis.setTimeout> | null;
+    sceneRenderScheduler: LocalEditorSceneRenderScheduler | null;
+    viewportRenderCoordinator: LocalEditorViewportRenderCoordinator | null;
+    sceneFrameStats: LocalEditorSceneRenderStats | null;
+    performanceMonitor: BabylonEditorPerformanceMonitor | null;
+    performanceMonitorOpen: boolean;
+    performanceObjectCount: number | null;
+    performanceStats: LocalEditorBrowserPerformanceStats | null;
+    editingContextProviders: readonly LocalEditorEditingContextProvider<TDocument, TPatch, TAsset>[];
+    toolManager: EditorToolManager | null;
+    toolManagerRenderSuppression: number;
+    sceneViewCameraStates: Map<string, BabylonSceneViewCameraState>;
+    activeSceneViewContextKey: string;
+    sceneViewContextGeneration: number;
+    pendingSceneViewAutoFrame: {
+        key: string;
+        generation: number;
+    } | null;
+    autoFramedSceneViewContexts: Set<string>;
+    worldAppearanceKey: string;
+    worldRenderingKey: string;
+    boxSelection: BabylonProjectionSelectionBox | null;
+    transformTool: EditorTransformTool;
+    transformSpace: EditorTransformSpace;
+    transformConstraint: EditorTransformCanonicalConstraint;
+    transformOperationSettings: EditorTransformOperationSettings;
+    viewportTools: LocalEditorHarnessViewportToolState;
+    viewportMeasurement: EditorViewportGroundMeasurement;
+    viewportSpatialOverlay: EditorViewportSpatialOverlayState;
+    prefabStage: LocalEditorHarnessPrefabStageRuntimeState<TDocument, TPatch, TAsset> | null;
+    duplicateDrag: {
+        originalSelection: EditorSelectionState;
+        createdIds: string[];
+        activeId: string | null;
+    } | null;
+    activeTransformPreview: LocalEditorHarnessTransformPreview | null;
+    armedPlacement: {
+        assetId: string;
+        asset: TAsset;
+    } | null;
+    resizeHandler: (() => void) | null;
+    status: string;
+    statusTone: LocalEditorBrowserUiState<TDocument>['statusTone'];
+    statusToneStatus: string;
+    statusDetails: string;
+    renderingAction: LocalEditorHarnessRenderingActionProgress | null;
+    summary: string;
+    agentBridge: EditorAgentBridge;
+    unregisterAgentBridgeCapabilities: (() => void) | null;
+    agentBridgeTransport: LocalEditorAgentBridgeTransportController | null;
+    agentBridgeStatus: LocalEditorAgentBridgeTransportStatus;
+}
+interface LocalEditorEditingContextAdapter<TDocument, TPatch, TAsset> {
+    readonly id: string;
+    getSnapshot(): EditingContextSnapshot;
+    getViewStateKey(): string;
+    getProjectionNodes(document: TDocument): BabylonEditorProjectionNode[];
+    handleProjectionReady(nodeId: string): void;
+    handleProjectionBatchSettled(batchId: number): void;
+    getSelection(): EditorSelectionState;
+    isSelectable(nodeId: string): boolean;
+    isLocked(nodeId: string): boolean;
+    dispatchSelection(command: SelectionCommand): boolean;
+    focus(nodeId: string): boolean;
+    focusSelection(): boolean;
+    commitTransform(event: BabylonTransformGizmoCommit): boolean;
+    beginDuplicateDrag(input: BabylonTransformGizmoDuplicateDragInput): BabylonTransformGizmoDuplicateDragResult | null;
+    getInspectorObject(document: TDocument, targetId?: string): InspectorObject<TDocument> | null;
+    getInspectorMultiObject(document: TDocument, targetIds?: readonly string[], activeId?: string | null): InspectorObject<TDocument> | null;
+    patchInspectorProperty(input: LocalEditorBrowserUiPropertyInput): boolean;
+    resolveInspectorPreviewTransform(document: TDocument | null, targetId: string, transform: EditorTransformSnapshot, preview: LocalEditorHarnessTransformPreview): EditorTransformSnapshot | null;
+}
+interface LocalEditorEditingContextProvider<TDocument, TPatch, TAsset> extends EditingContextProvider {
+    getAdapter(): LocalEditorEditingContextAdapter<TDocument, TPatch, TAsset>;
+}
+interface LocalEditorHarnessViewportToolState extends EditorViewportToolState {
+    showAllPrefabMarkers: boolean;
+}
+interface LocalEditorMarkerGraphVisibilityState {
+    rootVisible: boolean;
+    hiddenMarkerIds: Set<string>;
+}
+interface LocalEditorHarnessTransformPreview {
+    targetIds: string[];
+    activeId: string | null;
+    transforms: Record<string, EditorTransformSnapshot>;
+}
 export declare function createLocalEditorHarness<TDocument, TPatch, TAsset = LocalEditorHarnessAssetItem>(options: LocalEditorHarnessOptions<TDocument, TPatch, TAsset>): LocalEditorHarness<TDocument> & LocalEditorThemeController;
 export declare function mergeLocalEditorHarnessInspectorComponentSections<TDocument>(input: LocalEditorHarnessInspectorComponentMergeInput<TDocument>): InspectorObject<TDocument>;
 export declare function applyLocalEditorHarnessViewportMeasurementPointerStart(state: LocalEditorHarnessViewportMeasurementState, event: Pick<PointerEvent, 'clientX' | 'clientY'>): boolean;
 export declare function applyLocalEditorHarnessViewportMeasurementPointerMove(state: LocalEditorHarnessViewportMeasurementState, event: Pick<PointerEvent, 'clientX' | 'clientY'>): boolean;
 export declare function applyLocalEditorHarnessViewportMeasurementPointerEnd(_state: LocalEditorHarnessViewportMeasurementState): boolean;
+interface LocalEditorDocumentOperationExecutorState {
+    execute<TResult>(operation: (executor: PlayableLocalEditorDocumentOperationExecutor) => Promise<TResult>): Promise<TResult>;
+    revoke(): void;
+}
+type LocalEditorDocumentOperationExecutorRegistry = WeakMap<PlayableLocalEditorDocumentOperationExecutor, LocalEditorDocumentOperationExecutorState>;
+interface LocalEditorHierarchyTreeCache {
+    readonly structureKey: string;
+    readonly tree: HierarchyTreeSnapshot;
+    readonly snapshot: HierarchyScopeSnapshot;
+    readonly nextStructureRevision: number;
+}
+interface LocalEditorHierarchyResolvedTarget {
+    readonly rowId: string;
+    readonly authoredId: string;
+    readonly focusId: string;
+    readonly targetKind: 'scene-object' | 'prefab-node' | 'hierarchy-only';
+}
+interface LocalEditorHierarchyAdapterOperationContext<TDocument, TPatch, TAsset> {
+    readonly snapshot: HierarchyScopeSnapshot;
+    readonly context: HierarchyOperationContext;
+    readonly state: LocalEditorHarnessState<TDocument, TPatch, TAsset>;
+    readonly options: LocalEditorHarnessOptions<TDocument, TPatch, TAsset>;
+}
+interface LocalEditorHierarchyAdapterExecutionContext<TDocument, TPatch, TAsset> extends LocalEditorHierarchyAdapterOperationContext<TDocument, TPatch, TAsset> {
+    readonly invocation: HierarchyOperationInvocation;
+    readonly operation: HierarchyOperationDescriptor;
+    readonly render: () => void;
+    readonly getSnapshot: () => HierarchyScopeSnapshot;
+    readonly executorStates: LocalEditorDocumentOperationExecutorRegistry;
+}
+export interface LocalEditorHierarchyScopeAdapter<TDocument, TPatch, TAsset> {
+    readonly id: string;
+    readonly priority?: number;
+    canProvide(): boolean;
+    getTree(cache: LocalEditorHierarchyTreeCache | null): LocalEditorHierarchyTreeCache;
+    getSelection(): Readonly<{
+        selectedIds: readonly string[];
+        activeId: string | null;
+    }>;
+    applySelection(input: HierarchySelectionChange, snapshot: HierarchyScopeSnapshot): boolean;
+    resolveTarget(snapshot: HierarchyScopeSnapshot, rowId: string): LocalEditorHierarchyResolvedTarget | null;
+    listOperations(context: LocalEditorHierarchyAdapterOperationContext<TDocument, TPatch, TAsset>): readonly HierarchyOperationDescriptor[];
+    executeOperation(context: LocalEditorHierarchyAdapterExecutionContext<TDocument, TPatch, TAsset>): HierarchyOperationResult | Promise<HierarchyOperationResult>;
+}
+export interface LocalEditorHierarchyScopeProvider extends HierarchyScopeProvider {
+    resolveTarget(rowId: string, expectedRevision?: number): LocalEditorHierarchyResolvedTarget | null;
+}
+export declare function createLocalEditorSceneHierarchyScopeAdapter<TDocument, TPatch, TAsset>(state: LocalEditorHarnessState<TDocument, TPatch, TAsset>, options: LocalEditorHarnessOptions<TDocument, TPatch, TAsset>): LocalEditorHierarchyScopeAdapter<TDocument, TPatch, TAsset>;
+export declare function createLocalEditorPrefabHierarchyScopeAdapter<TDocument, TPatch, TAsset>(state: LocalEditorHarnessState<TDocument, TPatch, TAsset>, options: LocalEditorHarnessOptions<TDocument, TPatch, TAsset>): LocalEditorHierarchyScopeAdapter<TDocument, TPatch, TAsset>;
+export declare function createLocalEditorHarnessHierarchyScopeProvider<TDocument, TPatch, TAsset>(state: LocalEditorHarnessState<TDocument, TPatch, TAsset>, options: LocalEditorHarnessOptions<TDocument, TPatch, TAsset>, render: () => void, adapter: LocalEditorHierarchyScopeAdapter<TDocument, TPatch, TAsset>, executorStates?: LocalEditorDocumentOperationExecutorRegistry, renderSelection?: () => void): LocalEditorHierarchyScopeProvider;
+export declare function updateLocalEditorMaterialOwnerDiagnostics(current: readonly EditorDiagnostic[], item: BabylonEditorProjectionMaterialProfileDiagnostic): EditorDiagnostic[];
+export declare function createLocalEditorMaterialOwnerDiagnostic(item: BabylonEditorProjectionMaterialProfileDiagnostic): EditorDiagnostic | null;
 export declare function summarizeLocalEditorAuthoringFailure(result: AuthoringCommandResult<unknown>): LocalEditorAuthoringFailureStatus;
 export declare function dedupeLocalEditorBrowserAssetItems(items: LocalEditorBrowserUiAssetItem[]): LocalEditorBrowserUiAssetItem[];
 export {};