vis-core 0.33.3 → 0.33.5

package/dist/index.d.ts

@@ -1,35 +1,54 @@
 import { AmbientLightObject } from 'gl-draw';
+import { ArcObject } from 'gl-draw';
+import { ArcPathOptions } from 'gl-draw';
+import { ArcPoint } from 'gl-draw';
+import { ArcSpherePathOptions } from 'gl-draw';
 import { BaseObject } from 'gl-draw';
+import { baseObjectBounce } from 'gl-draw';
+import { baseObjectBounceIn } from 'gl-draw';
+import { baseObjectFadeIn } from 'gl-draw';
+import { baseObjectFadeOut } from 'gl-draw';
 import { default as default_2 } from 'gl-draw';
 import { DirectionalLightObject } from 'gl-draw';
 import { EventEmitter } from 'events';
 import { ExtrudePolygonObject } from 'gl-draw';
 import { FeatureCollection } from 'geojson';
 import { GeoJsonProperties } from 'geojson';
+import { GeometryDefinition } from 'gl-draw';
 import { GeoProjection } from 'd3-geo';
 import { GroupObject } from 'gl-draw';
 import { HemisphereLightObject } from 'gl-draw';
 import { Lead } from 'gl-draw';
 import { LineObject } from 'gl-draw';
 import { Listener } from 'events';
+import { Matrix4 } from 'three';
 import { MeshLineMaterial } from 'gl-draw';
 import { MeshObject } from 'gl-draw';
+import { ModelObject } from 'gl-draw';
 import { MultiPolygon } from 'geojson';
 import { NodeObject } from 'gl-draw';
+import { Object3D } from 'three';
 import { Pencil } from 'gl-draw';
-import { PickFunctionsItem } from 'gl-draw';
 import { PointLightObject } from 'gl-draw';
 import { Polygon } from 'geojson';
 import { Position } from 'geojson';
 import { ProjectionOptions } from 'gl-draw';
 import { RectAreaLightObject } from 'gl-draw';
+import { remapSnapshotAnimationTracks } from 'gl-draw';
 import { RestoreBaseObjectOptions } from 'gl-draw';
 import { SceneSnapshot } from 'gl-draw';
+import { sinusoidalInOut } from 'gl-draw';
 import { SpotLightObject } from 'gl-draw';
 import { SpriteObject } from 'gl-draw';
+import { StructureResources } from 'gl-draw';
 import * as THREE from 'three';
+import { timeOut } from 'gl-draw';
+import { TubeObject } from 'gl-draw';
 import { default as TWEEN } from 'three/examples/jsm/libs/tween.module.js';
 import { Tween } from 'three/examples/jsm/libs/tween.module.js';
+import { TweenOptions } from 'gl-draw';
+import { Vector3 } from 'three';
+import { Vector3Tuple } from 'three';
 import { Water } from './Water2';
 
 declare class AmbientLight extends AmbientLightObject {
@@ -39,48 +58,31 @@ declare class AmbientLight extends AmbientLightObject {
 export declare namespace animationUtils {
     export {
         timeOut,
-        TweenOptions,
         sinusoidalInOut,
         baseObjectFadeIn,
         baseObjectFadeOut,
         baseObjectBounceIn,
-        baseObjectBounce
+        baseObjectBounce,
+        TweenOptions
     }
 }
 
-declare class Arc extends LineObject {
-    objectType: string;
-    options: Options_5;
-    constructor(options: Options_5);
-    create(): Promise<void>;
-    getCurve(): THREE.CubicBezierCurve3;
-    setControlPoints(points: [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]): void;
-    setPath(from: THREE.Vector3 | number[], to: THREE.Vector3 | number[], radius: number, setPointWidth?: (p: number) => number): void;
-    private updatePickTargetGeometry;
-    pickTube: Tube | null;
-    private pickTargetVersion;
-    private pickBindings;
-    addPickTarget(radius?: number, show?: boolean): Promise<Tube | undefined>;
-    /** Restored picking children are adopted instead of allocating a duplicate tube. */
-    rebuildFromScene(): Promise<void>;
-    dispose(): void;
-    protected createPointerBinding(type: PickFunctionsItem['type'], cb: PickFunctionsItem['cb']): () => void;
-    setColor(color: string): void;
-    animateIn({ duration, delay, repeat, onComplete, onRepeat, }?: {
-        duration?: number;
-        delay?: number;
-        repeat?: number;
-        onComplete?: (...args: any[]) => void;
-        onRepeat?: (count: number) => void;
-    }): void;
-    render(): void;
-}
+/** Merge a privately prepared clipboard subtree; existing equal rows remain shared. */
+export declare function appendObjectDocument(before: VisSceneDocument, sceneId: string, snapshot: any, parentUuid: string, materialAdditions?: readonly MaterialAsset[]): VisSceneDocument;
+
+export declare function appendScenesDocument(before: VisSceneDocument, scenes: readonly SceneViewportDocument[], materials?: readonly MaterialAsset[], prefabs?: readonly PrefabAsset[]): VisSceneDocument;
+
+export { ArcPathOptions }
+
+export { ArcPoint }
+
+export { ArcSpherePathOptions }
 
 declare class Area extends GroupObject {
     objectType: string;
-    options: Options_11;
+    options: Options_8;
     area: ExtrudePolygonObject[];
-    constructor(options: Options_11);
+    constructor(options: Options_8);
     create(): Promise<void>;
     rebuildFromScene(): void;
 }
@@ -112,11 +114,13 @@ declare class Base_2 extends Camera {
     sceneResources: default_2['sceneResources'];
     tier0: boolean;
     roomEnvMap?: THREE.Texture;
-    private roomEnvTarget?;
     private roomEnvLease?;
     visName: string;
     private detectRes?;
     private ownsPencil;
+    private renderingSuspensions;
+    /* Excluded from this release type: suspendRendering */
+    private acquireRenderingSuspensions;
     publicDir: Record<string, string>;
     private prefabAssets;
     private prefabMaterials;
@@ -224,46 +228,6 @@ declare class Base_2 extends Camera {
     dispose(): void;
 }
 
-declare const baseObjectBounce: (obj: BaseObject, up: string | undefined, to: number) => {
-    start: ({ duration, repeat, repeatResolve, repeatDelay, }?: {
-        duration?: number | undefined;
-        repeat?: number | undefined;
-        repeatResolve?: number | undefined;
-        repeatDelay?: number | undefined;
-    }) => Promise<void>;
-    stop: () => void;
-};
-
-declare const baseObjectBounceIn: (obj: BaseObject, up?: string) => {
-    start: ({ duration, repeat, repeatResolve, repeatDelay, }?: {
-        duration?: number | undefined;
-        repeat?: number | undefined;
-        repeatResolve?: number | undefined;
-        repeatDelay?: number | undefined;
-    }) => Promise<void>;
-    stop: () => void;
-};
-
-declare const baseObjectFadeIn: (obj: BaseObject) => {
-    start: ({ duration, repeat, repeatResolve, repeatDelay, }?: {
-        duration?: number | undefined;
-        repeat?: number | undefined;
-        repeatResolve?: number | undefined;
-        repeatDelay?: number | undefined;
-    }) => Promise<void>;
-    stop: () => void;
-};
-
-declare const baseObjectFadeOut: (obj: BaseObject) => {
-    start: ({ duration, repeat, repeatResolve, repeatDelay, }?: {
-        duration?: number | undefined;
-        repeat?: number | undefined;
-        repeatResolve?: number | undefined;
-        repeatDelay?: number | undefined;
-    }) => Promise<void>;
-    stop: () => void;
-};
-
 declare interface BaseOptions {
     container: HTMLElement;
     assetsPrefix?: string;
@@ -295,6 +259,9 @@ export declare interface BindMaterialAssetOptions {
     alias?: string;
 }
 
+/** Bind explicit slots; no render graph is exported to discover the changed rows. */
+declare function bindMaterialSlots(document: VisSceneDocument, sceneId: string, assignments: readonly MaterialSlotAssignment[], optionReplacements?: ReadonlyMap<string, ReadonlyMap<string, string>>, optionAssetId?: string): VisSceneDocument;
+
 declare class Box extends MeshObject {
     objectType: string;
     create(): void;
@@ -302,8 +269,8 @@ declare class Box extends MeshObject {
 
 declare class Building extends GroupObject {
     objectType: string;
-    options: Options_9;
-    constructor(options: Options_9);
+    options: Options_6;
+    constructor(options: Options_6);
     create(): Promise<void>;
     rebuildFromScene(): void;
     private gradientMaterials;
@@ -419,8 +386,8 @@ declare interface CityOptions {
 
 declare class CityPlane extends MeshObject {
     objectType: string;
-    options: Options_13;
-    constructor(options: Options_13);
+    options: Options_10;
+    constructor(options: Options_10);
     plane: THREE.PlaneGeometry;
     water?: Water;
     create(): Promise<void>;
@@ -439,22 +406,38 @@ export declare function cloneSceneMaterials(document: VisSceneDocument, sourceId
 /** Rebind internal targets while preserving links to scenes outside the copied set. */
 export declare function cloneSceneWithIds(scene: SceneViewportDocument, ids: Map<string, string>): SceneViewportDocument;
 
+/** Configuration and alias values are additional conservative resource roots. */
+export declare function collectStructureResources(graph: Record<string, any>, roots: readonly Record<string, any>[], additionalReferences?: readonly unknown[]): StructureResources;
+
 declare class ContinentsBg extends GroupObject {
     objectType: string;
-    options: Options_8;
+    options: Options_5;
     mapArr: PlaneMap[];
-    constructor(options: Options_8);
+    constructor(options: Options_5);
     create(): Promise<void>;
-    getLocationPosition(location: [number, number], name?: string): [number, number, number] | undefined;
+    getLocationPosition(location: [number, number], name?: string, height?: number): [number, number, number] | undefined;
     private calculatePosition;
     render(): void;
     rebuildFromScene(): void;
     dispose(): void;
 }
 
+/** Copy only the copied branches; source nodes and existing resource rows keep
+ * their identity, including when several copies share one procedural geometry. */
+export declare function copyNativeGeometries(document: VisSceneDocument, sceneId: string, pairs: readonly {
+    sourceUuid: string;
+    copyUuid: string;
+}[], lead: BaseObject['lead']): VisSceneDocument;
+
+/** The clipboard already owns its subtree. Capture the exact geometry shown in
+ * the editor so procedural create() cannot silently replace it after paste. */
+export declare function copySnapshotGeometries(snapshot: any, source: BaseObject): void;
+
 /** Explicit creation persists even with no aliases or object users. */
 export declare function createMaterialAsset<T extends VisSceneDocument>(document: T, options: CreateMaterialAssetOptions): T;
 
+declare function createMaterialAssetDocument(document: VisSceneDocument, options: CreateMaterialAssetOptions): VisSceneDocument;
+
 export declare interface CreateMaterialAssetOptions {
     id: string;
     name: string;
@@ -479,12 +462,17 @@ export declare function createRuntimeSceneGraph(scene: SceneViewportDocument, op
     /* Excluded from this release type: consumeInput */
 }): Record<string, any>;
 
+/** Reuse renderer indexes while retaining material asset aliases and prefab dependencies. */
+export declare function createStructureResourceCollector(graph: Record<string, any>): (roots: readonly Record<string, any>[], additionalReferences?: readonly unknown[]) => StructureResources;
+
 declare class DirectionalLight extends DirectionalLightObject {
     constructor(...options: ConstructorParameters<typeof DirectionalLightObject>);
     update(delta: number, elapsed: number): void;
     render(): void;
 }
 
+declare function duplicateMaterialAssetDocument(document: VisSceneDocument, id: string, newId: string, mode: 'asset' | 'object' | 'scene', sceneId: string, objectId?: string, slot?: number): VisSceneDocument;
+
 /** One-click copy and apply; preserve the source's user-visible scope. */
 export declare function duplicateMaterialForObject<T extends VisSceneDocument>(document: T, options: Omit<BindMaterialAssetOptions, 'alias'> & {
     objectId: string;
@@ -492,6 +480,23 @@ export declare function duplicateMaterialForObject<T extends VisSceneDocument>(d
     name?: string;
 }): T;
 
+/** Duplicate object identities and their rig bindings, while borrowing immutable content resources. */
+export declare function duplicateObjectsDocument(before: VisSceneDocument, sceneId: string, targets: readonly {
+    uuid: string;
+    parentUuid: string;
+    matrix?: number[];
+    matrixAutoUpdate?: boolean;
+}[]): {
+    document: VisSceneDocument;
+    uuids: string[];
+};
+
+/** Duplicate only the selected page and its own material assets. */
+export declare function duplicateSceneDocument(before: VisSceneDocument, sceneId: string, id: string, name?: string): {
+    document: VisSceneDocument;
+    id: string;
+};
+
 export declare type Earth = Earth_2;
 
 declare class Earth_2 extends Base_2 {
@@ -510,15 +515,15 @@ declare class Earth_2 extends Base_2 {
         Countries: typeof PlaneMap;
         PlaneMap: typeof PlaneMap;
         Point: Point;
-        Arc: Arc;
-        Model: Model;
+        Arc: ArcObject;
+        Model: ModelObject;
         Plane: Plane;
         PlaneShadow: PlaneShadow;
         Sphere: Sphere;
         Sprite: Sprite;
         Box: Box;
         Circle: Circle;
-        Tube: Tube;
+        Tube: TubeObject;
         Ring: Ring;
         AmbientLight: AmbientLight;
         DirectionalLight: DirectionalLight;
@@ -533,19 +538,28 @@ declare class Earth_2 extends Base_2 {
     };
     private rotationControls?;
     private releaseRotationLock?;
+    private visibilityChecks?;
     private readonly stopAutoRotate;
     private readonly resumeAutoRotate;
     protected onRuntimeReady(): Promise<void>;
     protected onDispose(): void;
-    getLocationPosition(location: [number, number], dr?: number): [number, number, number];
+    private getLocationFrame;
+    /** 球体表面的世界坐标；height 沿真实表面法线偏移，单位为世界单位。 */
+    getLocationPosition(location: [number, number], height?: number): [number, number, number];
+    /** 球对象原点对应的世界球心。 */
+    getCenter(): [number, number, number];
+    /** 几何的本地半径，用于创建同坐标空间的地图图层。 */
     getRadius(): number;
-    checkBehindEarth(objArr: () => BaseObject[], cb: (obj: BaseObject[], res: boolean[]) => any): void;
+    /** 真球的世界半径；非均匀缩放或剪切形成椭球时不能用于球面路径。 */
+    getWorldRadius(): number;
+    private requireSurfaceTransform;
+    checkBehindEarth(objArr: () => BaseObject[], cb: (obj: BaseObject[], res: boolean[]) => any): () => void;
     /**
      * 设置物体在球面上的位置和旋转，使其垂直于球面
      * @param object - 要设置的物体
      * @param location - 经纬度 [经度, 纬度]
-     * @param height - 距离球面的高度，默认为0
-     * @param upAxis - 物体的up轴方向，默认为Y轴 [0, 1, 0]
+     * @param height - 沿球面世界法线的距离，默认为0
+     * @param upAxis - Plane 的本地面法线（默认 -Z，正面朝球心）；其他对象的本地朝向轴（默认 Y）
      */
     setObjectOnSphere(baseObject: BaseObject, location: [number, number], height?: number, upAxis?: [number, number, number]): void;
     getSceneBindings(): EarthSceneBindings;
@@ -593,9 +607,16 @@ declare class Event_2 {
 /** Expand at the editor import boundary so independently edited scenes own their data. */
 export declare function expandSceneDocumentResources<T extends VisSceneDocument>(document: T): T;
 
+/** Expand renderer pools, including snapshots retained as prefab baselines. */
+export declare function expandStructureSnapshot<T extends Record<string, any>>(input: T): T;
+
 /** Extract only this material's dependencies, without mutating the scene snapshot. */
 export declare function extractMaterialDefinition(scene: SceneViewportDocument, materialUuid: string): Record<string, any>;
 
+/** Extract current object resources without treating prefab baseline metadata as
+ * dependencies of the live object. Baselines remain in the copied metadata. */
+export declare function extractObjectResourceGraph(graph: any, object: any): any;
+
 declare const findAdcodeInfo: (adcode: number) => {
     adcode: number;
     lng: number;
@@ -626,6 +647,19 @@ export declare function getSceneDocument(document: VisSceneDocument, sceneId?: s
     resolveResources?: boolean;
 }): SceneViewportDocument;
 
+/** An identity group shell keeps selected sibling objects and their transforms untouched. */
+export declare function groupObjectsDocument(before: VisSceneDocument, sceneId: string, ids: readonly string[], options?: GroupObjectsDocumentOptions): {
+    document: VisSceneDocument;
+    uuid: string;
+};
+
+export declare interface GroupObjectsDocumentOptions {
+    /** Display name; hosts may supply their localized default. */
+    name?: string;
+    /** Authored BaseObject user data, separate from generated constructor metadata. */
+    userData?: Record<string, any>;
+}
+
 declare class HemisphereLight extends HemisphereLightObject {
 }
 
@@ -710,15 +744,15 @@ declare class Map_3 extends Base_2 {
         Building: Building;
         Road: Road;
         Point: Point;
-        Arc: Arc;
-        Model: Model;
+        Arc: ArcObject;
+        Model: ModelObject;
         Plane: Plane;
         PlaneShadow: PlaneShadow;
         Sphere: Sphere;
         Sprite: Sprite;
         Box: Box;
         Circle: Circle;
-        Tube: Tube;
+        Tube: TubeObject;
         Ring: Ring;
         AmbientLight: AmbientLight;
         DirectionalLight: DirectionalLight;
@@ -734,6 +768,9 @@ declare class Map_3 extends Base_2 {
     protected get defaultCameraUp(): THREE.Vector3;
     protected onRuntimeReady(): Promise<void>;
     protected prepareInitialCamera(): Promise<void>;
+    private mapBoundaryMatrix?;
+    private mapBoundaryEnabled?;
+    private refreshMapBoundary;
     private updateMapBoundary;
     /* Excluded from this release type: finalizeRegionGeometry */
     private prepareCityVis;
@@ -759,12 +796,15 @@ declare class Map_3 extends Base_2 {
     private labelGroupObject3dUserData;
     eraseLabels(): void;
     geAdcodePosition(adcode: number): [number, number, number] | undefined;
-    getLocationPosition(location: [number, number]): [number, number, number];
+    /** 地图顶面的世界坐标；height 沿顶面世界法线偏移，单位为世界单位。 */
+    getLocationPosition(location: [number, number], height?: number): [number, number, number];
+    private getMainMapLocationPosition;
+    private worldToObjectParent;
     /**
      * 设置物体在平面地图上的位置
      * @param object - 要设置的物体
      * @param location - 经纬度 [经度, 纬度]
-     * @param height - 距离地图平面的高度，默认为0
+     * @param height - 沿地图顶面法线的世界距离，默认为0
      */
     setObjectOnMap(object: BaseObject, location: [number, number], height?: number): void;
     setObjectOnMapAreaByProperty(object: BaseObject, key: string, value: any, height?: number): void;
@@ -813,7 +853,7 @@ declare class Map_3 extends Base_2 {
     /** undefined 表示沿用设计师构图；对象（包括全 0）表示宿主覆盖。 */
     getSafeAreaInsets(): MapSafeAreaInsets | undefined;
     setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
-    refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<void>;
+    refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<boolean>;
     findAdcodeInfo(adcode: number): {
         adcode: number;
         lng: number;
@@ -850,7 +890,7 @@ declare class Map_3 extends Base_2 {
     /* Excluded from this release type: rebuildRegion */
     private rebuildRegionGeometry;
     /** 候选区域提交后的相机过渡，不参与场景序列化。 */
-    playRegionEnterTransition({ duration, sourceCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
+    playRegionEnterTransition({ duration, sourceCamera, preparedCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
     /** Region rules are page-local runtime overrides of a saved material asset. */
     private regionRuleMaterial;
     private setRegionTexture;
@@ -858,6 +898,13 @@ declare class Map_3 extends Base_2 {
     protected onDispose(): void;
 }
 
+export declare interface MapAnchor {
+    longitude: number;
+    latitude: number;
+    /** Must match mapCRS; this API does not convert WGS84/GCJ02/BD09. */
+    crs: string;
+}
+
 declare interface MapAssetSources {
     worldGeojson: string;
     worldLiteGeojson: string;
@@ -932,6 +979,7 @@ declare interface MapOptions extends BaseOptions {
     polarAngle?: number;
     azimuthAngle?: number;
     worldPacificCentre?: boolean;
+    /** 同时限制平移范围、最近缩放距离，以及穿透地图和翻转到背面的视角。默认 true。 */
     mapBoundary?: boolean;
     mergeSide?: boolean;
     /** switchMapRegion 时重建城市建筑、道路、河流等数据层。 */
@@ -949,6 +997,16 @@ declare interface MapOptions extends BaseOptions {
     assetSources?: MapAssetSources;
 }
 
+export declare interface MapPlacementOptions {
+    mapCRS: string;
+    /** Explicit ground meshes only. Exclude the model, roofs, helpers and hidden surfaces. */
+    surfaces: Object3D[];
+    /** Model's physical height; optional if already in map units. Z is model/map up. */
+    heightMeters?: number;
+    /** Clearance in map units along map Z. */
+    clearance?: number;
+}
+
 export declare interface MapRegionBackInteraction {
     trigger: 'click' | 'clickOutside';
     objectId: string;
@@ -960,6 +1018,7 @@ export declare interface MapRegionBackInteraction {
 
 declare interface MapRegionEnterTransitionOptions extends SceneEnterTransitionOptions {
     sourceCamera?: [number, number, number, number, number, number];
+    /* Excluded from this release type: preparedCamera */
 }
 
 export declare type MapRegionSceneResolver = (document: VisSceneDocument, adcode: number) => string | SceneViewportDocument | null | undefined | Promise<string | SceneViewportDocument | null | undefined>;
@@ -1033,9 +1092,26 @@ export declare interface MaterialDefinitionScope {
     readonly properties: readonly string[];
 }
 
+/** Copy-on-write operations for committed documents; callers own validation and transactions.
+ * The normalization-aware project APIs use the same implementation after preparing their inputs.
+ */
+export declare const materialDocumentOperations: Readonly<{
+    materialize: typeof materializeChangedAssets;
+    create: typeof createMaterialAssetDocument;
+    replace: typeof replaceMaterialAssetDocument;
+    registerSceneMaterials: typeof registerSceneMaterials;
+    bindSlots: typeof bindMaterialSlots;
+    duplicate: typeof duplicateMaterialAssetDocument;
+    promote: typeof promoteMaterialAssetDocument;
+    remove: typeof removeMaterialAssetDocument;
+}>;
+
 /** One explicit mapping from an asset's authored resource UUIDs to runtime resource UUIDs. */
 export declare function materializeAssetDefinition(asset: MaterialAsset, materialUuid?: string): Record<string, any>;
 
+/** Project only changed assets. Object trees and unrelated resource payloads stay borrowed. */
+declare function materializeChangedAssets(document: VisSceneDocument, assets: readonly MaterialAsset[], sceneIds?: ReadonlySet<string>): VisSceneDocument;
+
 /* Excluded from this release type: materializeOwnedProjectMaterials */
 
 /** Mutate a detached working snapshot owned exclusively by the caller. */
@@ -1064,6 +1140,12 @@ export declare type MaterialScope = {
     sceneId: string;
 };
 
+export declare type MaterialSlotAssignment = {
+    uuid: string;
+    slot: number;
+    assetId: string;
+};
+
 export declare interface MaterialUsage {
     assetId: string;
     sceneId: string;
@@ -1074,6 +1156,11 @@ export declare interface MaterialUsage {
     alias?: string;
 }
 
+declare type MatrixState = {
+    matrix: number[];
+    matrixAutoUpdate?: boolean;
+};
+
 /** Save author edits without promoting page-local region textures into a shared definition. */
 export declare function mergeAuthoredMaterialDefinition(savedDefinition: Record<string, any>, runtimeDefinition: Record<string, any>, options?: {
     editedProperties?: string[];
@@ -1085,76 +1172,11 @@ export declare function mergeProjectMaterials(target: VisSceneDocument, incoming
     idMap: Map<string, string>;
 };
 
-declare class Model extends GroupObject {
-    options: Options_7;
-    mixer: THREE.AnimationMixer | null;
-    clips: THREE.AnimationClip[];
-    actions: THREE.AnimationAction[];
-    actionStates: Record<string, boolean>;
-    objectType: string;
-    constructor(options: Options_7);
-    create(): Promise<void>;
-    render(): void;
-    /**
-     * Set animation clips for the model
-     * @param clips Array of animation clips from GLTF
-     */
-    setClips(clips: THREE.AnimationClip[]): void;
-    /**
-     * Play all animation clips
-     */
-    playAllClips(): void;
-    /**
-     * Play a specific animation clip by name
-     * @param clipName Name of the animation clip to play
-     */
-    playClip(clipName: string): void;
-    /**
-     * Stop a specific animation clip by name
-     * @param clipName Name of the animation clip to stop
-     */
-    stopClip(clipName: string): void;
-    /**
-     * Stop all animation clips
-     */
-    stopAllClips(): void;
-    /**
-     * Set the playback speed for all animations
-     * @param speed Playback speed (1.0 = normal speed)
-     */
-    setPlaybackSpeed(speed: number): void;
-    /**
-     * Get the current playback speed
-     */
-    getPlaybackSpeed(): number;
-    /**
-     * Check if a specific animation is playing
-     * @param clipName Name of the animation clip
-     */
-    isPlaying(clipName: string): boolean;
-    /**
-     * Get all available animation clip names
-     */
-    getClipNames(): string[];
-    rebuildFromScene(): Promise<void>;
-    instantiate(ops?: Parameters<GroupObject['instantiate']>[0]): Promise<this>;
-    /**
-     * Update animations - should be called in render loop
-     * @param deltaTime Time elapsed since last frame
-     */
-    update(deltaTime: number): void;
-    /**
-     * Dispose of resources including animation mixer
-     */
-    dispose(): void;
-    private syncPlayingClipNames;
-}
-
 declare class Mountain extends GroupObject {
     objectType: string;
-    options: Required<Omit<Options_12, 'bbox'>> & Pick<Options_12, 'bbox'>;
+    options: Required<Omit<Options_9, 'bbox'>> & Pick<Options_9, 'bbox'>;
     extrudePolygon: ExtrudePolygonObject;
-    constructor(options: Options_12);
+    constructor(options: Options_9);
     geojson2Meta(geojson: GeoJSON_4): {
         coords: Position[][];
         properties: GeoJsonProperties;
@@ -1164,6 +1186,12 @@ declare class Mountain extends GroupObject {
     rebuildFromScene(): void;
 }
 
+/** Reparent/reorder roots with caller-computed local matrices, without copying their descendants. */
+export declare function moveObjectsDocument(before: VisSceneDocument, sceneId: string, ids: readonly string[], parentUuid: string, order: readonly string[], matrices: ReadonlyMap<string, MatrixState>): VisSceneDocument;
+
+/** Keep saved texture/image identities stable across runtime namespace and revision changes. */
+export declare function normalizeMaterialDefinition<T extends Record<string, any>>(input: T): T;
+
 /* Excluded from this release type: normalizeOwnedProjectMaterials */
 
 /** Bind serialized runtime materials and alias catalogs to authored assets. */
@@ -1208,44 +1236,6 @@ declare interface Options {
 }
 
 declare interface Options_10 {
-    uuid?: string;
-    jsonUrl: string;
-    projection: {
-        center: [number, number];
-        scale: number;
-    };
-    cacheKey?: string;
-    meters?: number;
-    grey?: boolean;
-    material?: MeshLineMaterial;
-}
-
-declare interface Options_11 {
-    uuid?: string;
-    jsonUrl: string;
-    projection: {
-        center: [number, number];
-        scale: number;
-    };
-    material: THREE.Material;
-    type: string;
-    cacheKey?: string;
-    oArr?: number[];
-}
-
-declare interface Options_12 {
-    geojson: GeoJSON_4;
-    projection: {
-        center: [number, number];
-        scale: number;
-        rotate?: [number, number];
-        projectionType?: 'mercator' | 'equirectangular' | 'winkel3';
-    };
-    depth?: number;
-    bbox?: number[];
-}
-
-declare interface Options_13 {
     width: number;
     height: number;
     material?: THREE.Material;
@@ -1266,35 +1256,7 @@ declare interface Options_4 {
     sprite?: boolean;
 }
 
-declare interface Options_5 extends NonNullable<ConstructorParameters<typeof LineObject>[0]> {
-    from: number[];
-    to: number[];
-    control1?: number[];
-    control2?: number[];
-    radius?: number;
-    globe?: boolean;
-    color?: string;
-    lineWidth?: number;
-    offsetLoop?: boolean;
-}
-
-declare interface Options_6 {
-    path?: THREE.Curve<THREE.Vector3>;
-    radius?: number;
-    multiplyScalar?: number;
-    /** Compact saved inputs for an Arc's derived picking geometry. */
-    arcControlPoints?: number[][];
-}
-
-declare interface Options_7 {
-    src?: string;
-    autoPlay?: boolean;
-    playbackSpeed?: number;
-    serializedClips?: SerializedClip[];
-    playingClipNames?: string[];
-}
-
-declare interface Options_8 {
+declare interface Options_5 {
     materialOptions: {
         topMat: THREE.Material;
         sideMat: THREE.Material;
@@ -1306,7 +1268,7 @@ declare interface Options_8 {
     geojsonSource: string;
 }
 
-declare interface Options_9 {
+declare interface Options_6 {
     uuid?: string;
     jsonUrl: string;
     projection: {
@@ -1322,6 +1284,44 @@ declare interface Options_9 {
     materialOptions?: Record<string, THREE.Material>;
 }
 
+declare interface Options_7 {
+    uuid?: string;
+    jsonUrl: string;
+    projection: {
+        center: [number, number];
+        scale: number;
+    };
+    cacheKey?: string;
+    meters?: number;
+    grey?: boolean;
+    material?: MeshLineMaterial;
+}
+
+declare interface Options_8 {
+    uuid?: string;
+    jsonUrl: string;
+    projection: {
+        center: [number, number];
+        scale: number;
+    };
+    material: THREE.Material;
+    type: string;
+    cacheKey?: string;
+    oArr?: number[];
+}
+
+declare interface Options_9 {
+    geojson: GeoJSON_4;
+    projection: {
+        center: [number, number];
+        scale: number;
+        rotate?: [number, number];
+        projectionType?: 'mercator' | 'equirectangular' | 'winkel3';
+    };
+    depth?: number;
+    bbox?: number[];
+}
+
 /** Pack an export copy only; preserve the editor's independent scene snapshots. */
 export declare function packSceneDocumentResources<T extends VisSceneDocument>(document: T): T;
 
@@ -1330,6 +1330,14 @@ export declare function patchSceneStructureDocument(document: VisSceneDocument,
 /** Validate every affected scene and both catalogs before exposing any saved state. */
 export declare function patchSceneStructureTransactionDocument(document: VisSceneDocument, transaction: SceneStructureTransaction): VisSceneDocument;
 
+export declare interface PlanarMap {
+    object3d: Object3D;
+    options: {
+        projection?: ProjectionOptions;
+        conic?: boolean;
+    };
+}
+
 declare class Plane extends MeshObject {
     objectType: string;
     create(): void;
@@ -1404,6 +1412,20 @@ declare class PlaneShadow extends MeshObject {
     create(): Promise<void>;
 }
 
+/** Read-only plan. Aligns the model bounds center in XY and lowest vertex to actual ground.
+ * Apply the returned local matrix to a detached candidate, serialize, then import/replace once.
+ */
+export declare function planPlacement(model: Object3D, map: PlanarMap, anchor: MapAnchor, options: MapPlacementOptions): {
+    localMatrix: Matrix4;
+    worldMatrix: Matrix4;
+    groundPoint: Vector3Tuple;
+    groundObjectUuid: string;
+    mapPosition: number[];
+    scaleBasis: "local spherical approximation";
+    xUnitsPerMeter: number;
+    yUnitsPerMeter: number;
+};
+
 declare class Point extends BaseObject {
     objectType: string;
     options: Options_4;
@@ -1439,6 +1461,22 @@ export declare interface PreparedSceneStructure {
 
 declare const preparedSceneStructure: unique symbol;
 
+export declare function prepareGeometryBinding(before: VisSceneDocument, sceneId: string, uuid: string, input: GeometryDefinition | null, override: boolean): VisSceneDocument;
+
+/** Change one binding; a conflicting borrowed UUID must not overwrite its other users. */
+export declare function prepareGeometryEdit(before: VisSceneDocument, sceneId: string, uuid: string, input: GeometryDefinition | null): VisSceneDocument;
+
+/** Uses the same projection and Y sign as PlaneMap geometry, then its world matrix. */
+export declare function projectLocation(map: PlanarMap, anchor: MapAnchor, mapCRS: string): {
+    local: Vector3;
+    world: Vector3;
+    xUnitsPerMeter: number;
+    yUnitsPerMeter: number;
+    scaleBasis: "local spherical approximation";
+};
+
+declare function promoteMaterialAssetDocument(document: VisSceneDocument, id: string): VisSceneDocument;
+
 export declare function promoteMaterialToProject<T extends VisSceneDocument>(document: T, assetId: string): T;
 
 declare class RectAreaLight extends RectAreaLightObject {
@@ -1459,6 +1497,15 @@ declare interface RegionTextureRule {
     levels?: string[];
 }
 
+/** Register imported definitions without normalizing or copying the existing project. */
+declare function registerSceneMaterials(document: VisSceneDocument, sceneId: string, onlyIds?: ReadonlySet<string>): VisSceneDocument;
+
+/** Imported data is owned separately; scanning occupied IDs never copies current graphs. */
+export declare function remapImportedMaterials(before: VisSceneDocument, incoming: VisSceneDocument): VisSceneDocument;
+
+/** Detached authored snapshots keep their copy links and relinquish source-asset resource identities. */
+export declare function remapOwnedSnapshotIdentity(snapshot: any, rootUuid?: string, sharedResourceIds?: ReadonlyMap<string, string>): any;
+
 export declare interface RemappedSceneDocument {
     entrySceneId: string;
     scenes: SceneViewportDocument[];
@@ -1480,8 +1527,22 @@ export declare function remapProjectMaterialIds<T extends VisSceneDocument>(docu
  */
 export declare function remapSceneDocumentIds(document: VisSceneDocument, createSceneId: (scene: SceneViewportDocument, index: number) => string): RemappedSceneDocument;
 
+export { remapSnapshotAnimationTracks }
+
+/** Copy an authored snapshot with fresh native and authored reference identities. */
+export declare function remapSnapshotIdentity(input: any, rootUuid?: string, sharedResourceIds?: ReadonlyMap<string, string>): any;
+
+declare function removeMaterialAssetDocument(document: VisSceneDocument, id: string): VisSceneDocument;
+
+/** Remove selected roots and prune only the authored rules that referred to them. */
+export declare function removeObjectsDocument(before: VisSceneDocument, sceneId: string, ids: readonly string[]): VisSceneDocument;
+
 export declare function removeProjectMaterial<T extends VisSceneDocument>(document: T, assetId: string): T;
 
+export declare function removeSceneDocument(before: VisSceneDocument, sceneId: string): VisSceneDocument;
+
+declare function replaceMaterialAssetDocument(document: VisSceneDocument, asset: MaterialAsset): VisSceneDocument;
+
 declare class Ring extends MeshObject {
     objectType: string;
     create(): void;
@@ -1489,8 +1550,8 @@ declare class Ring extends MeshObject {
 
 declare class Road extends GroupObject {
     objectType: string;
-    options: Options_10;
-    constructor(options: Options_10);
+    options: Options_7;
+    constructor(options: Options_7);
     linePrimary: LineObject[];
     lineSecondary: LineObject[];
     create(): Promise<void>;
@@ -1542,6 +1603,14 @@ declare interface SceneControlsOptions {
     autoRotateSpeed?: number;
 }
 
+export declare interface SceneDisplayContext {
+    sceneId: string;
+    /** 本次准备前已重新适配地图相机；false 的缓存页保留此前视角。 */
+    cameraRefitted: boolean;
+    /** 文档替换或 manager 销毁时取消准备。 */
+    signal: AbortSignal;
+}
+
 export declare interface SceneDocumentMarker {
     format: typeof SCENE_DOCUMENT_FORMAT;
     schemaVersion: number;
@@ -1585,6 +1654,7 @@ export declare class SceneManager extends Event_2 {
     private pencil?;
     private safeAreaInsets?;
     private generation;
+    private displayPreparationAbort;
     private documentIdentityRevision;
     private preparedStructures;
     private pendingInstances;
@@ -1596,6 +1666,11 @@ export declare class SceneManager extends Event_2 {
     private assertGeneration;
     private debugInteraction;
     private enablePickDebug;
+    private retireScenes;
+    private discardSceneCandidates;
+    /** Notifications cannot invalidate a transaction that has already committed. */
+    private notifySceneObservers;
+    private finishNavigation;
     private disposeInactiveScenes;
     /** Retire inactive pages after the host accepts navigation; failures never undo the active page. */
     trimInactiveScenes(): unknown[];
@@ -1613,6 +1688,7 @@ export declare class SceneManager extends Event_2 {
     setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
     getSafeAreaInsets(): MapSafeAreaInsets | undefined;
     private captureCamera;
+    private prepareSceneDisplay;
     private playTransition;
     /** 更新可编辑文档，并释放已经不属于文档的非活动场景实例。 */
     setDocument(document: VisSceneDocument): void;
@@ -1686,6 +1762,7 @@ export declare class SceneManager extends Event_2 {
     switchScene(sceneId: string, options?: SwitchSceneOptions, hooks?: Record<string, any>): Promise<Base_2 | null>;
     /**
      * 恢复并缓存一个非活动场景，不改变当前场景、导航历史或相机。
+     * 缓存至少保留当前页和本次预加载页；后续导航恢复配置的缓存上限。
      */
     preloadScene(sceneId: string, hooks?: Record<string, any>): Promise<Base_2>;
     /** 编辑器事务：在独立页面上修改参数并重建快照，成功后一起提交文档和实例。 */
@@ -1740,9 +1817,11 @@ export declare interface SceneManagerBehaviorOptions {
     debugInteractions?: boolean;
     /** 创建场景后、恢复 JSON 前调用。 */
     prepareScene?: (scene: Base_2) => void;
+    /** 场景与最终相机就绪后、提交和首帧绘制前等待宿主准备。失败时保留原场景。 */
+    beforeSceneDisplay?: (scene: Base_2, context: SceneDisplayContext) => void | Promise<void>;
     /** 是否保留非活动场景实例；编辑器可关闭以限制 GPU/内存占用。 */
     cacheScenes?: boolean;
-    /** Pages retained after navigation, including the active page; oldest inactive pages retire first. */
+    /** Pages retained after navigation (default 8), including the active page; oldest inactive pages retire first. */
     maxCachedScenes?: number;
     /** 自定义分包场景读取器；可从 IndexedDB 等非 HTTP 存储按需读取。 */
     loadScene?: (entry: SceneManifestEntry) => Promise<SceneViewportDocument>;
@@ -1916,18 +1995,6 @@ export declare interface SceneViewportPatch {
 
 export declare function selectSceneDocument(document: VisSceneDocument, sceneId: string): VisSceneDocument;
 
-declare type SerializedClip = ReturnType<(typeof THREE.AnimationClip)['toJSON']>;
-
-declare const sinusoidalInOut: ({ owner, onUpdate, onComplete, onCancel, backwards, }?: TweenOptions) => {
-    start: ({ duration, repeat, repeatResolve, repeatDelay, }?: {
-        duration?: number | undefined;
-        repeat?: number | undefined;
-        repeatResolve?: number | undefined;
-        repeatDelay?: number | undefined;
-    }) => Promise<void>;
-    stop: () => void;
-};
-
 declare class Sphere extends MeshObject {
     radius: number;
     options: any;
@@ -1977,6 +2044,8 @@ declare class Sprite extends SpriteObject {
 
 export declare function stripMaterialAssetBinding<T extends Record<string, any>>(material: T): T;
 
+export { StructureResources }
+
 export declare interface SwitchSceneOptions {
     /** 返回历史时不再记录当前场景。 */
     recordHistory?: boolean;
@@ -1986,30 +2055,13 @@ export declare interface SwitchSceneOptions {
 
 export { THREE }
 
-declare const timeOut: (ms: number) => Promise<any>;
-
-declare class Tube extends MeshObject {
-    objectType: string;
-    options: Options_6;
-    constructor(options: Options_6);
-    create(): void;
-}
-
 export { TWEEN }
 
 export { Tween }
 
-declare interface TweenOptions {
-    owner?: Pick<Pencil, 'animations'>;
-    onUpdate?: (value: number) => void;
-    onComplete?: () => void;
-    onCancel?: () => void;
-    backwards?: boolean;
-}
-
 export declare function updateProjectMaterial<T extends VisSceneDocument>(document: T, assetId: string, patch: Partial<Pick<MaterialAsset, 'name' | 'material' | 'locked'>>): T;
 
-export declare const VERSION = "0.33.3";
+export declare const VERSION = "0.33.5";
 
 export declare interface VisSceneDocument extends SceneDocumentMarker {
     entrySceneId: string;