vis-core 0.33.4 → 0.33.6

package/dist/index.d.ts

@@ -1,36 +1,80 @@
 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 { BufferGeometry } from 'three';
+import { ColorRepresentation } from 'three';
 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 { IUniform } from 'three';
 import { Lead } from 'gl-draw';
 import { LineObject } from 'gl-draw';
 import { Listener } from 'events';
+import { Matrix4 } from 'three';
+import { Mesh } 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 { ResourceRegistry } from 'gl-draw';
 import { RestoreBaseObjectOptions } from 'gl-draw';
+import { ReusableObjectResources } from 'gl-draw';
 import { SceneSnapshot } from 'gl-draw';
+import { ShaderMaterial } from 'three';
+import { sinusoidalInOut } from 'gl-draw';
 import { SpotLightObject } from 'gl-draw';
 import { SpriteObject } from 'gl-draw';
+import { StructureResources } from 'gl-draw';
+import { Texture } from 'three';
 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 { Water } from './Water2';
+import { Tween as Tween_2 } from 'three/examples/jsm/libs/tween.module.js';
+import { TweenOptions } from 'gl-draw';
+import { Vector2 } from 'three';
+import { Vector3 } from 'three';
+import { Vector3Tuple } from 'three';
+
+export declare const adcodeAll: AdcodeRecords;
+
+/** Stable administrative-region data shared by generated records and extensions. */
+export declare interface AdcodeInfo {
+    adcode: number;
+    lng: number;
+    lat: number;
+    name: string;
+    level: string;
+    parent: number;
+    c: number[];
+    b: number[];
+    en_name?: string;
+}
+
+export declare type AdcodeRecords = Record<string, AdcodeInfo>;
 
 declare class AmbientLight extends AmbientLightObject {
     constructor(...options: ConstructorParameters<typeof AmbientLightObject>);
@@ -39,88 +83,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>;
-    /** Internal/local-space curve used for rendering, editor handles and snapshots. */
-    getCurve(): ArcCurve;
-    /** Set four world-space Bézier controls; persisted coordinates remain local. */
-    setControlPoints(points: readonly [ArcPoint, ArcPoint, ArcPoint, ArcPoint]): void;
-    /** Set a world-space path without changing this object or its parent transforms. */
-    setPath(from: ArcPoint, to: ArcPoint, options: ArcPathOptions): void;
-    /** Exact radial lift above the short great circle; preserves every object transform. */
-    setSpherePath(from: ArcPoint, to: ArcPoint, options: ArcSpherePathOptions): void;
-    private worldToLocalMatrix;
-    private validatedNodes;
-    private setWorldControls;
-    private getPickPathOptions;
-    private syncPickPathOptions;
-    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;
 
-declare type ArcCurve = THREE.CubicBezierCurve3 | SphereArcCurve;
+export declare function appendScenesDocument(before: VisSceneDocument, scenes: readonly SceneViewportDocument[], materials?: readonly MaterialAsset[], prefabs?: readonly PrefabAsset[]): VisSceneDocument;
 
-export declare interface ArcPathOptions {
-    /** Maximum displacement from the endpoint segment along `up`, in world units. */
-    height: number;
-    /** World-space lift direction; normalized internally. Defaults to positive Z. */
-    up?: ArcPoint;
-    setPointWidth?: (progress: number) => number;
-}
-
-export declare type ArcPoint = THREE.Vector3 | readonly number[];
+export { ArcPathOptions }
 
-/** A sphere frame in Arc-local coordinates. Its basis retains world-unit lengths. */
-declare interface ArcSpherePath {
-    matrix: number[];
-    angle: number;
-    radius: number;
-    height: number;
-}
+export { ArcPoint }
 
-export declare interface ArcSpherePathOptions {
-    /** World-space sphere center. Both endpoints must lie on the same sphere. */
-    center: ArcPoint;
-    /** Maximum distance above the sphere surface, in world units. Zero follows its surface. */
-    height: number;
-    /** World-space circle-plane normal for coincident or antipodal endpoints. */
-    normal?: ArcPoint;
-    setPointWidth?: (progress: number) => number;
-}
+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;
 }
@@ -137,7 +124,9 @@ export declare function assertSupportedSceneDocument(value: unknown): void;
 
 export declare type Base = Base_2;
 
-declare class Base_2 extends Camera {
+declare type Base_2 = Base_3;
+
+declare class Base_3 extends Camera {
     static VisName: string;
     runtimePolicy: {
         observeParentScale: boolean;
@@ -152,13 +141,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 */
+    /** Internal: 在运行时创建前也可暂停，保证整个初始化过程不提交中间帧。 */
+    suspendRendering(): () => void;
     private acquireRenderingSuspensions;
     publicDir: Record<string, string>;
     private prefabAssets;
@@ -166,7 +155,8 @@ declare class Base_2 extends Camera {
     private prefabOperations;
     /** Inspect SDK-enabled definitions without creating scene objects or resources. */
     getPrefabLibrary(): PrefabAsset[];
-    /* Excluded from this release type: setPrefabLibrary */
+    /** Internal: Update definitions for future instances without rebuilding live content. */
+    setPrefabLibrary(assets?: readonly PrefabAsset[], materials?: MaterialAsset[]): void;
     instantiatePrefab(keyOrAssetId: string, options?: InstantiatePrefabOptions): Promise<BaseObject>;
     private cancelPrefabOperations;
     constructor(options: BaseOptions);
@@ -181,12 +171,14 @@ declare class Base_2 extends Camera {
     private resolveRendererDepthBufferOptions;
     private showDetectRes;
     setOptions(options: Record<string, any>): void;
-    /* Excluded from this release type: fromJSON */
+    /** Internal: Scene documents are loaded through SceneManager. */
+    fromJSON(jsonOrUrl: Record<string, any> | string, hooksE?: Record<string, any>, restoreOptions?: RestoreBaseObjectOptions): Promise<void>;
     private runtimeInitialization?;
     private disposed;
     private readonly handleObjectIdentityChanged;
     private readonly handleMaterialIdentityChanged;
-    /* Excluded from this release type: initializeRuntime */
+    /** Internal: 平台旧模板生成也复用这一步；不创建场景内容、不显示。 */
+    initializeRuntime(): Promise<void>;
     /** 子类扩展点：运行环境只初始化一次，适合建立投影和绑定控制器事件。 */
     protected onRuntimeReady(): Promise<void>;
     /** 子类扩展点：恢复场景引用和运行时派生状态，不生成地图几何或移动相机。 */
@@ -267,46 +259,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;
@@ -338,6 +290,9 @@ export declare interface BindMaterialAssetOptions {
     alias?: string;
 }
 
+/** Bind explicit slots; no render graph is exported to discover the changed rows. */
+export 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;
@@ -345,8 +300,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;
@@ -462,8 +417,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>;
@@ -482,11 +437,17 @@ 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;
 
+/** Reuse only definitions with equal dependency payloads, never a UUID-only cache hit. */
+export declare function collectSceneResourceReuse(target: any, candidates: readonly SceneResourceCandidate[]): Required<ReusableObjectResources>;
+
+/** 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;
-    mapArr: PlaneMap[];
-    constructor(options: Options_8);
+    options: Options_5;
+    mapArr: PlaneMap_2[];
+    constructor(options: Options_5);
     create(): Promise<void>;
     getLocationPosition(location: [number, number], name?: string, height?: number): [number, number, number] | undefined;
     private calculatePosition;
@@ -495,9 +456,22 @@ declare class ContinentsBg extends GroupObject {
     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;
 
+export declare function createMaterialAssetDocument(document: VisSceneDocument, options: CreateMaterialAssetOptions): VisSceneDocument;
+
 export declare interface CreateMaterialAssetOptions {
     id: string;
     name: string;
@@ -519,15 +493,29 @@ export declare function createRuntimeSceneDocument(document: VisSceneDocument):
 /** Convert authored asset aliases to the native catalog expected by graph restoration. */
 export declare function createRuntimeSceneGraph(scene: SceneViewportDocument, options?: {
     omitPrefabPreviews?: boolean;
-    /* Excluded from this release type: consumeInput */
+    /** Internal: Transfer an exclusively owned scene graph instead of copying it. */
+    consumeInput?: boolean;
 }): Record<string, any>;
 
+/** Scan each Vis candidate once, including constructor-only material bindings. */
+export declare function createSceneResourceReuseSession(candidates?: readonly SceneResourceCandidate[]): {
+    add: (candidate: SceneResourceCandidate) => void;
+    collect: (target: any, options?: {
+        environment?: () => any;
+    }) => Required<ReusableObjectResources>;
+};
+
+/** 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;
 }
 
+export 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;
@@ -535,33 +523,52 @@ 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 {
+declare type Earth_2 = Earth_3;
+
+declare class Earth_3 extends Base_3 {
     static VisName: string;
     leftTruck: boolean;
     options: Required<EarthOptions>;
-    map: PlaneMap;
+    map: PlaneMap_2;
     sphere?: BaseObject;
-    secondaryMap?: PlaneMap;
+    secondaryMap?: PlaneMap_2;
     get mapArea(): ExtrudePolygonObject[];
     setOptions(options: EarthOptions): void;
     protected applyControlOptions(controls: SceneControlsOptions): void;
     protected get objectTypes(): {
-        Earth: Earth_3;
+        Earth: Earth_4;
         SphereShadow: SphereShadow;
-        Countries: typeof PlaneMap;
-        PlaneMap: typeof PlaneMap;
+        Countries: typeof PlaneMap_2;
+        PlaneMap: typeof PlaneMap_2;
         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;
@@ -604,7 +611,7 @@ declare class Earth_2 extends Base_2 {
     protected onSceneRestored(): Promise<void>;
 }
 
-declare class Earth_3 extends Sphere {
+declare class Earth_4 extends Sphere {
     objectType: string;
     options: Required<Options_2>;
     constructor(options: Options_2);
@@ -627,6 +634,58 @@ declare interface EarthSceneBindings {
     secondaryMap?: string;
 }
 
+export declare const editorEarthObjects: {
+    Earth: typeof Earth_4;
+    SphereShadow: typeof SphereShadow;
+    Countries: typeof PlaneMap_2;
+    PlaneMap: typeof PlaneMap_2;
+    Point: Point;
+    Arc: ArcObject;
+    Model: ModelObject;
+    Plane: Plane;
+    PlaneShadow: PlaneShadow;
+    Sphere: Sphere;
+    Sprite: Sprite;
+    Box: Box;
+    Circle: Circle;
+    Tube: TubeObject;
+    Ring: Ring;
+    AmbientLight: AmbientLight;
+    DirectionalLight: DirectionalLight;
+    PointLight: PointLight;
+    SpotLight: SpotLight;
+    HemisphereLight: HemisphereLight;
+    RectAreaLight: RectAreaLight;
+    Node: NodeObject;
+    ExtrudePolygon: ExtrudePolygonObject;
+    Line: LineObject;
+    Group: GroupObject;
+};
+
+export declare const editorObjects: {
+    Point: typeof Point;
+    Arc: typeof ArcObject;
+    Model: typeof ModelObject;
+    Plane: typeof Plane;
+    PlaneShadow: typeof PlaneShadow;
+    Sphere: typeof Sphere;
+    Sprite: typeof Sprite;
+    Box: typeof Box;
+    Circle: typeof Circle;
+    Tube: typeof TubeObject;
+    Ring: typeof Ring;
+    AmbientLight: typeof Lights.AmbientLight;
+    DirectionalLight: typeof Lights.DirectionalLight;
+    PointLight: typeof Lights.PointLight;
+    SpotLight: typeof Lights.SpotLight;
+    HemisphereLight: typeof Lights.HemisphereLight;
+    RectAreaLight: typeof Lights.RectAreaLight;
+    Node: typeof NodeObject;
+    ExtrudePolygon: typeof ExtrudePolygonObject;
+    Line: typeof LineObject;
+    Group: typeof GroupObject;
+};
+
 export declare type EmptySceneDefinition = Omit<SceneViewportDocument, 'scene'>;
 
 declare class Event_2 {
@@ -640,26 +699,26 @@ declare class Event_2 {
     dispose(): void;
 }
 
-/* Excluded from this release type: expandOwnedSceneDocumentResources */
+/** Internal: Consume an exclusively owned import copy; pooled slots still get independent payloads. */
+export declare function expandOwnedSceneDocumentResources<T extends VisSceneDocument>(expanded: T): T;
 
 /** 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>;
 
-declare const findAdcodeInfo: (adcode: number) => {
-    adcode: number;
-    lng: number;
-    lat: number;
-    name: string;
-    level: string;
-    parent: number;
-    c: number[];
-    b: number[];
-} | undefined;
+/** 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;
+
+export declare const findAdcodeInfo: (adcode: number) => AdcodeInfo | undefined;
 
 declare type GeoJSON_2 = FeatureCollection<Polygon | MultiPolygon>;
+export { GeoJSON_2 as GeoJSON }
 
 declare type GeoJSON_3 = FeatureCollection<Polygon | MultiPolygon>;
 
@@ -678,9 +737,32 @@ 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 {
 }
 
+declare type IdentityPath = (string | number)[];
+
+export declare function indexedSceneObject(root: any, uuid: string): {
+    node: any;
+    path: readonly number[];
+} | undefined;
+
+/** Property-only immutable copies retain exactly the same UUID paths. */
+export declare function inheritSceneObjectIndex(previous: any, next: any): void;
+
 export declare interface InstantiatePrefabOptions {
     /** Parent in the destination scene. Defaults to the scene root. */
     target?: BaseObject;
@@ -688,6 +770,15 @@ export declare interface InstantiatePrefabOptions {
     cloneMaterial?: boolean;
 }
 
+export declare function invalidateSceneObjectIndex(root: object | undefined): void;
+
+export declare const isLocalSceneObjectField: (field: string) => boolean;
+
+/** Editor integration: avoid applying an explicit host update twice. */
+export declare function isObjectStateUpdateInProgress(object: BaseObject): boolean;
+
+export declare const isSceneCameraField: (key: string) => boolean;
+
 /**
  * 新场景文档以完整场景快照作为恢复基线。
  * 未带标记的 JSON 属于旧格式，仍由编辑器的兼容流程处理。
@@ -696,44 +787,50 @@ export declare function isSceneDocument(value: unknown): value is SceneDocumentM
 
 export declare function isSceneManifest(value: unknown): value is VisSceneManifest;
 
+export declare const isSceneObjectPropertyField: (field: string) => boolean;
+
+declare namespace Lights {
+    export {
+        AmbientLight,
+        DirectionalLight,
+        PointLight,
+        SpotLight,
+        HemisphereLight,
+        RectAreaLight
+    }
+}
+
 /** Copy once and redirect every user in this scene, including its SceneResources aliases. */
 export declare function makeMaterialSceneLocal<T extends VisSceneDocument>(document: T, assetId: string, sceneId: string, newAssetId: string): T;
 
 declare type Map_2 = Map_3;
 export { Map_2 as Map }
 
-declare class Map_3 extends Base_2 {
+declare type Map_3 = Map_4;
+
+declare class Map_4 extends Base_3 {
     static VisName: string;
     options: Required<MapCityOptions>;
     /** 当前唯一主地图的运行时状态。 */
     mapObj: {
-        map: PlaneMap;
+        map: PlaneMap_2;
         mapInfo: NonNullable<ReturnType<typeof findAdcodeInfo>>;
         z: number;
         cX: number;
         cY: number;
         depth: number;
     } | undefined;
-    get map(): PlaneMap | undefined;
-    get mapInfo(): {
-        adcode: number;
-        lng: number;
-        lat: number;
-        name: string;
-        level: string;
-        parent: number;
-        c: number[];
-        b: number[];
-    } | undefined;
+    get map(): PlaneMap_2 | undefined;
+    get mapInfo(): AdcodeInfo | undefined;
     get mapArea(): ExtrudePolygonObject[] | undefined;
     get mapLine(): LineObject[] | undefined;
     /** 当前已恢复或生成的主地图区域；空场景为 undefined。 */
     get adcode(): number | undefined;
-    activePlaneMap: PlaneMap | null;
+    activePlaneMap: PlaneMap_2 | null;
     /** 宿主大屏图表等遮挡形成的运行时安全区；不写入场景 options。 */
     private safeAreaInsets?;
     private safeAreaRefitPending;
-    parentBg: PlaneMap[];
+    parentBg: PlaneMap_2[];
     continentsBg?: ContinentsBg;
     group: GroupObject;
     projection: GeoProjection;
@@ -754,7 +851,7 @@ declare class Map_3 extends Base_2 {
     private _getProjectionRotate;
     private _getSplitPolygons;
     protected get objectTypes(): {
-        PlaneMap: typeof PlaneMap;
+        PlaneMap: typeof PlaneMap_2;
         ContinentsBg: typeof ContinentsBg;
         Mountain: Mountain;
         CityPlane: CityPlane;
@@ -762,15 +859,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;
@@ -786,8 +883,12 @@ 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 */
+    /** Internal: 新生成区域的收尾；完整快照还原由 onSceneRestored 派生标签。 */
+    finalizeRegionGeometry(): Promise<void>;
     private prepareCityVis;
     private preloadCityVis;
     /** Keep at most two cities ahead in the loader; all Lead writes stay ordered. */
@@ -836,7 +937,12 @@ declare class Map_3 extends Base_2 {
     private _loadGeojsonFromConfig;
     private _loadBaseGeojson;
     private getGeojson;
-    /* Excluded from this release type: buildRegion */
+    /** Internal: 生成地图层；导航必须通过 SceneManager。 */
+    buildRegion({ adcode, depth, extrudelineBloom, }: {
+        adcode: number;
+        depth?: number;
+        extrudelineBloom?: boolean;
+    }): Promise<void>;
     /** 流式读取实际世界坐标，不复制或持有地图几何。 */
     private cameraFitPoints;
     private cameraForPose;
@@ -863,22 +969,13 @@ declare class Map_3 extends Base_2 {
         depth: number;
         adcode: number;
         extrudelineBloom?: boolean;
-    }): Promise<PlaneMap>;
+    }): Promise<PlaneMap_2>;
     private getEffectiveSafeAreaPadding;
     /** undefined 表示沿用设计师构图；对象（包括全 0）表示宿主覆盖。 */
     getSafeAreaInsets(): MapSafeAreaInsets | undefined;
     setSafeAreaInsets(insets?: Partial<MapSafeAreaInsets>, options?: MapSafeAreaOptions): Promise<void>;
     refitSafeAreaIfNeeded(options?: MapSafeAreaOptions): Promise<boolean>;
-    findAdcodeInfo(adcode: number): {
-        adcode: number;
-        lng: number;
-        lat: number;
-        name: string;
-        level: string;
-        parent: number;
-        c: number[];
-        b: number[];
-    } | undefined;
+    findAdcodeInfo(adcode: number): AdcodeInfo | undefined;
     /**
      * 根据目标 adcode 更新 options 中依赖 adcode 的字段
      */
@@ -902,7 +999,8 @@ declare class Map_3 extends Base_2 {
      * Apply the region behavior authored on each object.
      */
     private applyRegionObjectState;
-    /* Excluded from this release type: rebuildRegion */
+    /** Internal: 仅由 SceneManager 在隔离页面调用，成功后才对外提交。 */
+    rebuildRegion(targetAdcode: number, switchKey?: string): Promise<void>;
     private rebuildRegionGeometry;
     /** 候选区域提交后的相机过渡，不参与场景序列化。 */
     playRegionEnterTransition({ duration, sourceCamera, preparedCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
@@ -911,6 +1009,19 @@ declare class Map_3 extends Base_2 {
     private setRegionTexture;
     applyRegionTextureRules(adcode: number): Promise<void>;
     protected onDispose(): void;
+    private static mapCameraContext;
+    private static labelsContext;
+    private static cityLayersContext;
+    private static backgroundsContext;
+    private static regionOverlaysContext;
+    private static regionTexturesContext;
+}
+
+export declare interface MapAnchor {
+    longitude: number;
+    latitude: number;
+    /** Must match mapCRS; this API does not convert WGS84/GCJ02/BD09. */
+    crs: string;
 }
 
 declare interface MapAssetSources {
@@ -987,6 +1098,7 @@ declare interface MapOptions extends BaseOptions {
     polarAngle?: number;
     azimuthAngle?: number;
     worldPacificCentre?: boolean;
+    /** 同时限制平移范围、最近缩放距离，以及穿透地图和翻转到背面的视角。默认 true。 */
     mapBoundary?: boolean;
     mergeSide?: boolean;
     /** switchMapRegion 时重建城市建筑、道路、河流等数据层。 */
@@ -1004,6 +1116,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;
@@ -1015,7 +1137,8 @@ export declare interface MapRegionBackInteraction {
 
 declare interface MapRegionEnterTransitionOptions extends SceneEnterTransitionOptions {
     sourceCamera?: [number, number, number, number, number, number];
-    /* Excluded from this release type: preparedCamera */
+    /** 场景管理器已完成地图和宿主准备后的最终姿态。 */
+    preparedCamera?: [number, number, number, number, number, number];
 }
 
 export declare type MapRegionSceneResolver = (document: VisSceneDocument, adcode: number) => string | SceneViewportDocument | null | undefined | Promise<string | SceneViewportDocument | null | undefined>;
@@ -1089,10 +1212,28 @@ 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>;
 
-/* Excluded from this release type: materializeOwnedProjectMaterials */
+/** Project only changed assets. Object trees and unrelated resource payloads stay borrowed. */
+export declare function materializeChangedAssets(document: VisSceneDocument, assets: readonly MaterialAsset[], sceneIds?: ReadonlySet<string>): VisSceneDocument;
+
+/** Internal: Materialize an exclusively owned document while preserving owned geometry tables. */
+export declare function materializeOwnedProjectMaterials<T extends VisSceneDocument>(document: T): T;
 
 /** Mutate a detached working snapshot owned exclusively by the caller. */
 export declare function materializeOwnedSceneMaterials<T extends SceneViewportDocument>(scene: T, library?: MaterialAsset[]): T;
@@ -1120,6 +1261,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;
@@ -1130,6 +1277,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[];
@@ -1141,76 +1293,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;
@@ -1220,11 +1307,24 @@ declare class Mountain extends GroupObject {
     rebuildFromScene(): void;
 }
 
-/* Excluded from this release type: normalizeOwnedProjectMaterials */
+/** 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;
+
+/** Internal: Normalize an exclusively owned import copy without copying its geometry payloads. */
+export declare function normalizeOwnedProjectMaterials<T extends VisSceneDocument>(document: T): T;
 
 /** Bind serialized runtime materials and alias catalogs to authored assets. */
 export declare function normalizeProjectMaterials<T extends VisSceneDocument>(document: T): T;
 
+/** Paths belong to an immutable serialized object tree, never to live Three.js objects. */
+declare type ObjectIndex = Map<string, {
+    path: readonly number[];
+    lengths: readonly number[];
+}>;
+
 declare interface Options {
     /** @deprecated Legacy generation scope, read only when importing old snapshots. */
     uuid?: string;
@@ -1264,44 +1364,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;
@@ -1322,37 +1384,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[];
-    spherePath?: ArcSpherePath;
-    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[][];
-    arcSpherePath?: ArcSpherePath;
-}
-
-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;
@@ -1364,7 +1396,7 @@ declare interface Options_8 {
     geojsonSource: string;
 }
 
-declare interface Options_9 {
+declare interface Options_6 {
     uuid?: string;
     jsonUrl: string;
     projection: {
@@ -1380,20 +1412,80 @@ 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;
 
+/** Clone each affected ancestor/children array once, without visiting other subtrees. */
+export declare function patchIndexedSceneObjects(root: any, updates: ReadonlyMap<string, {
+    state: Record<string, any>;
+    unset?: string[];
+}>): any;
+
+/** Validate only authored scalar fields; the committed baseline already owns the unchanged graph/resources. */
+export declare function patchSceneObjectPropertiesDocument(document: VisSceneDocument, sceneId: string, patches: readonly SceneObjectPropertyPatch[]): VisSceneDocument;
+
 export declare function patchSceneStructureDocument(document: VisSceneDocument, sceneId: string, patch: SceneStructurePatch): VisSceneDocument;
 
 /** Validate every affected scene and both catalogs before exposing any saved state. */
 export declare function patchSceneStructureTransactionDocument(document: VisSceneDocument, transaction: SceneStructureTransaction): VisSceneDocument;
 
+/** Own only the small viewport payload and copy the camera's ancestor path. */
+export declare function patchSceneViewportDocument(document: VisSceneDocument, sceneId: string, patch: SceneViewportPatch): VisSceneDocument;
+
+export declare interface PlanarMap {
+    object3d: Object3D;
+    options: {
+        projection?: ProjectionOptions;
+        conic?: boolean;
+    };
+}
+
 declare class Plane extends MeshObject {
     objectType: string;
     create(): void;
 }
 
-declare class PlaneMap extends GroupObject {
+export declare type PlaneMap = PlaneMap_2;
+
+declare class PlaneMap_2 extends GroupObject {
     objectType: string;
     options: Required<Omit<Options, 'bbox' | 'extrudeLineGeojson' | 'uuid'>> & Pick<Options, 'bbox' | 'extrudeLineGeojson' | 'uuid'>;
     isActive: boolean;
@@ -1462,6 +1554,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;
@@ -1497,12 +1603,28 @@ 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";
+};
+
+export 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 {
 }
 
-declare interface RegionTextureRule {
+export declare interface RegionTextureRule {
     /** 材质 UUID，或显式材质角色，例如 plane#topMat。 */
     material: string;
     /** THREE.Material 上的纹理属性，例如 map、emissiveMap。 */
@@ -1517,6 +1639,15 @@ declare interface RegionTextureRule {
     levels?: string[];
 }
 
+/** Register imported definitions without normalizing or copying the existing project. */
+export 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[];
@@ -1538,8 +1669,31 @@ export declare function remapProjectMaterialIds<T extends VisSceneDocument>(docu
  */
 export declare function remapSceneDocumentIds(document: VisSceneDocument, createSceneId: (scene: SceneViewportDocument, index: number) => string): RemappedSceneDocument;
 
+export declare const remapSceneMaterialReferencesCopy: <T>(scene: T, previous: string, next: string) => T;
+
+export declare const remapSceneObjectReferencesCopy: <T>(scene: T, previous: string, next: string) => T;
+
+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;
+
+export 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;
+
+export declare function replaceMaterialAssetDocument(document: VisSceneDocument, asset: MaterialAsset): VisSceneDocument;
+
+export declare const RESOURCE_SOURCE = "_resourceSource";
+
+/** Stable UUID for an asset's resource instance; content revisions do not change identity. */
+export declare function resourceInstanceUuid(assetId: string, kind: string, sourceUuid: string): string;
+
 declare class Ring extends MeshObject {
     objectType: string;
     create(): void;
@@ -1547,8 +1701,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>;
@@ -1663,6 +1817,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[];
@@ -1719,9 +1878,9 @@ export declare class SceneManager extends Event_2 {
     /** A newly hydrated empty Base seed acquires its own camera/default options once. */
     prepareSceneInitialization(sceneId: string, definition: SceneViewportDocument): PreparedSceneStructure;
     /** Collection edits keep cached pages until their enclosing history transaction accepts. */
-    activateSceneForTransaction(sceneId: string, hooks?: Record<string, any>, signal?: AbortSignal): Promise<Base_2>;
+    activateSceneForTransaction(sceneId: string, hooks?: Record<string, any>, signal?: AbortSignal): Promise<Base_3>;
     /** Retire exactly the detached page; never invalidate other loaded pages or pending resources. */
-    retireSceneForTransaction(sceneId: string, expected: Base_2): void;
+    retireSceneForTransaction(sceneId: string, expected: Base_3): void;
     private ownPreparedStructure;
     private requirePreparedStructure;
     /**
@@ -1733,32 +1892,34 @@ export declare class SceneManager extends Event_2 {
     commitSceneStructure(prepared: PreparedSceneStructure): void;
     /** Commit scalar material history without accepting or copying caller object graphs. */
     patchMaterialDefinitions(assets: MaterialAsset[], scenes: Pick<SceneViewportDocument, 'id'>[], scope?: MaterialDefinitionScope): void;
-    load(documentOrUrl: VisSceneDocument | VisSceneManifest | string, hooks?: Record<string, any>): Promise<Base_2>;
+    load(documentOrUrl: VisSceneDocument | VisSceneManifest | string, hooks?: Record<string, any>): Promise<Base_3>;
     /**
      * 创建一个没有快照输入的运行时页面，并在可选构建步骤完成后将其导出为
      * 标准单场景文档。主要供编辑器新建和旧模板迁移使用。
      */
-    createEmptyScene(definition: EmptySceneDefinition, build?: (scene: Base_2) => void | Promise<void>, materialLibrary?: MaterialAsset[]): Promise<Base_2>;
+    createEmptyScene(definition: EmptySceneDefinition, build?: (scene: Base_3) => void | Promise<void>, materialLibrary?: MaterialAsset[]): Promise<Base_3>;
     /**
      * 以指定地图模板和行政区直接启动，不先加载文档配置的入口场景。
      * 适用于宿主按路由或业务参数决定初始省、市、区的场景。
      */
-    loadMapRegion(documentOrUrl: VisSceneDocument | VisSceneManifest | string, sceneId: string, adcode: number, hooks?: Record<string, any>): Promise<Map_3>;
-    loadMapRegion(documentOrUrl: VisSceneDocument | VisSceneManifest | string, adcode: number, resolveScene: MapRegionSceneResolver, hooks?: Record<string, any>): Promise<Map_3>;
+    loadMapRegion(documentOrUrl: VisSceneDocument | VisSceneManifest | string, sceneId: string, adcode: number, hooks?: Record<string, any>): Promise<Map_4>;
+    loadMapRegion(documentOrUrl: VisSceneDocument | VisSceneManifest | string, adcode: number, resolveScene: MapRegionSceneResolver, hooks?: Record<string, any>): Promise<Map_4>;
     private loadDocument;
     private getSceneMetadata;
     private resolveManifestSource;
     private resolveBundleImages;
     private loadSceneDefinition;
     private createRuntimeSceneDocument;
-    switchScene(sceneId: string, options?: SwitchSceneOptions, hooks?: Record<string, any>): Promise<Base_2 | null>;
+    private definitionLoadingContext;
+    switchScene(sceneId: string, options?: SwitchSceneOptions, hooks?: Record<string, any>): Promise<Base_3 | null>;
     /**
      * 恢复并缓存一个非活动场景，不改变当前场景、导航历史或相机。
+     * 缓存至少保留当前页和本次预加载页；后续导航恢复配置的缓存上限。
      */
-    preloadScene(sceneId: string, hooks?: Record<string, any>): Promise<Base_2>;
+    preloadScene(sceneId: string, hooks?: Record<string, any>): Promise<Base_3>;
     /** 编辑器事务：在独立页面上修改参数并重建快照，成功后一起提交文档和实例。 */
-    editScene(sceneId: string, edit: (scene: Base_2, definition: SceneViewportDocument) => Promise<SceneViewportDocument>, hooks?: Record<string, any>): Promise<Base_2>;
-    back(hooks?: Record<string, any>): Promise<Base_2 | null>;
+    editScene(sceneId: string, edit: (scene: Base_3, definition: SceneViewportDocument) => Promise<SceneViewportDocument>, hooks?: Record<string, any>): Promise<Base_3>;
+    back(hooks?: Record<string, any>): Promise<Base_3 | null>;
     /**
      * 切到目标地图场景，并按 adcode 重建其中的地图。sceneId 不同时，语义等价于
      * switchScene(sceneId) 后 switchMapRegion(adcode)，但候选场景只在两步都成功后提交，
@@ -1766,17 +1927,17 @@ export declare class SceneManager extends Event_2 {
      * 始终从文档基线构建隔离页面，避免对缓存实例反复施加缩放/删除修正。
      * 旧页面在构建期间保持完整；只有所有资源、几何和交互就绪才提交导航。
      */
-    switchMapRegion(sceneId: string, adcode: number, options?: SwitchSceneOptions, hooks?: Record<string, any>): Promise<Map_3 | null>;
+    switchMapRegion(sceneId: string, adcode: number, options?: SwitchSceneOptions, hooks?: Record<string, any>): Promise<Map_4 | null>;
     /** 场景切换与区域切换共享一条返回历史。 */
-    backMapRegion(hooks?: Record<string, any>): Promise<Base_2 | null>;
+    backMapRegion(hooks?: Record<string, any>): Promise<Base_3 | null>;
     getCurrentSceneId(): string;
     getCurrentScene<T extends SceneType>(type: T): SceneTypeMap[T] | null;
-    getCurrentScene(): Base_2 | null;
+    getCurrentScene(): Base_3 | null;
     private getCurrentSceneByType;
     getScene<T extends SceneType>(sceneId: string, type: T): SceneTypeMap[T] | undefined;
-    getScene(sceneId: string): Base_2 | undefined;
+    getScene(sceneId: string): Base_3 | undefined;
     getSceneByName<T extends SceneType>(name: string, type: T): SceneTypeMap[T] | undefined;
-    getSceneByName(name: string): Base_2 | undefined;
+    getSceneByName(name: string): Base_3 | undefined;
     private getSceneByType;
     /** Inspect saved definitions without creating or pinning runtime materials. */
     getMaterialLibrary(): MaterialAsset[];
@@ -1788,7 +1949,7 @@ export declare class SceneManager extends Event_2 {
      * Reacquire Base/Object handles after this call: replaced pages are disposed.
      * Current runtime geometry, options, active page and camera are preserved.
      */
-    updateMaterial(assetId: string, patch: Partial<Pick<MaterialAsset, 'name' | 'material' | 'locked'>>): Promise<Base_2 | null>;
+    updateMaterial(assetId: string, patch: Partial<Pick<MaterialAsset, 'name' | 'material' | 'locked'>>): Promise<Base_3 | null>;
     /** Immutable borrowed snapshot for coordinated COW editing; write through patch APIs. */
     getDocumentSnapshot(): Readonly<VisSceneDocument> | undefined;
     getDocument(): VisSceneDocument | undefined;
@@ -1807,12 +1968,12 @@ export declare interface SceneManagerBehaviorOptions {
     /** 输出射线命中和场景交互诊断，仅用于开发排查。 */
     debugInteractions?: boolean;
     /** 创建场景后、恢复 JSON 前调用。 */
-    prepareScene?: (scene: Base_2) => void;
+    prepareScene?: (scene: Base_3) => void;
     /** 场景与最终相机就绪后、提交和首帧绘制前等待宿主准备。失败时保留原场景。 */
-    beforeSceneDisplay?: (scene: Base_2, context: SceneDisplayContext) => void | Promise<void>;
+    beforeSceneDisplay?: (scene: Base_3, 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>;
@@ -1837,6 +1998,8 @@ export declare interface SceneManifestEntry extends Omit<SceneViewportDocument,
 /** Dependency closure for a selected scene; preserve unused aliases as document uses. */
 export declare function sceneMaterialLibrary(scene: SceneViewportDocument, library?: MaterialAsset[], prefabs?: VisSceneDocument['prefabLibrary']): MaterialAsset[];
 
+export declare function sceneObjectIndex(root: any): ObjectIndex;
+
 export declare interface SceneObjectPatch {
     uuid: string;
     state: {
@@ -1850,7 +2013,9 @@ export declare interface SceneObjectPatch {
     unset?: ('matrix' | 'matrixAutoUpdate' | 'pivot' | 'name' | 'visible' | 'layers')[];
 }
 
-declare interface SceneObjectPropertyPatch {
+export declare const sceneObjectPropertyDefaults: Readonly<Record<string, any>>;
+
+export declare interface SceneObjectPropertyPatch {
     uuid: string;
     state: Record<string, any>;
     unset?: readonly string[];
@@ -1860,6 +2025,12 @@ declare type ScenePropertyField = typeof scenePropertyFields[number];
 
 export declare const scenePropertyFields: readonly ["color", "groundColor", "intensity", "distance", "decay", "angle", "penumbra", "width", "height", "castShadow", "receiveShadow", "frustumCulled", "renderOrder", "up", "center", "shadow", "near", "far", "fov", "aspect", "zoom", "left", "right", "top", "bottom", "focus", "filmGauge", "filmOffset", "view", "backgroundBlurriness", "backgroundIntensity", "environmentIntensity", "backgroundRotation", "environmentRotation"];
 
+export declare interface SceneResourceCandidate {
+    vis: any;
+    graph: any;
+    root?: any;
+}
+
 export declare type SceneStructureGraphKey = 'materialAliases' | 'shapes' | '_sharedOptionsPool' | '_texDataPool';
 
 /** Metadata is part of an owned structure transaction, never a scalar runtime patch. */
@@ -1951,9 +2122,9 @@ export declare interface SceneTransitionOptions {
 export declare type SceneType = keyof SceneTypeMap;
 
 export declare interface SceneTypeMap {
-    base: Base_2;
-    earth: Earth_2;
-    map: Map_3;
+    base: Base_3;
+    earth: Earth_3;
+    map: Map_4;
 }
 
 export declare interface SceneViewportDocument {
@@ -1986,18 +2157,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;
@@ -2006,26 +2165,6 @@ declare class Sphere extends MeshObject {
     create(): void;
 }
 
-/** Exact radial lift above the short great circle, expressed in object-local space. */
-declare class SphereArcCurve extends THREE.Curve<THREE.Vector3> {
-    readonly type = "SphereArcCurve";
-    readonly data: ArcSpherePath;
-    readonly matrix: THREE.Matrix4;
-    constructor(path: ArcSpherePath);
-    get v0(): THREE.Vector3;
-    get v3(): THREE.Vector3;
-    getPoint(t: number, target?: THREE.Vector3): THREE.Vector3;
-    getTangent(t: number, target?: THREE.Vector3): THREE.Vector3;
-    clone(): this;
-    copy(source: THREE.Curve<THREE.Vector3>): this;
-    toJSON(): SphereArcCurveJSON;
-    fromJSON(json: THREE.CurveJSON): this;
-}
-
-declare interface SphereArcCurveJSON extends THREE.CurveJSON {
-    spherePath: ArcSpherePath;
-}
-
 declare class SphereShadow extends MeshObject {
     objectType: string;
     options: Required<Options_3>;
@@ -2067,6 +2206,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;
@@ -2076,30 +2217,16 @@ 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 type Tween<T extends Record<string, any>> = Tween_2<T>;
 
 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.4";
+export declare const VERSION = "0.33.6";
+
+/** Enumerate authored reference fields only; never inspect arbitrary userdata or resource payloads. */
+export declare function visitSceneIdentityReferences(scene: any, objectIdentity: boolean, visit: (path: IdentityPath, value: any, track?: boolean, key?: boolean) => void): void;
 
 export declare interface VisSceneDocument extends SceneDocumentMarker {
     entrySceneId: string;
@@ -2134,4 +2261,34 @@ export declare interface VisSceneManifest {
     s?: string;
 }
 
+declare class Water extends Mesh<BufferGeometry, ShaderMaterial> {
+    static WaterShader: WaterShader;
+    isWater: true;
+    constructor(geometry: BufferGeometry, options: WaterOptions);
+    dispose(): void;
+}
+
+declare interface WaterOptions {
+    resources?: ResourceRegistry;
+    color?: ColorRepresentation;
+    textureWidth?: number;
+    textureHeight?: number;
+    clipBias?: number;
+    flowDirection?: Vector2;
+    flowSpeed?: number;
+    reflectivity?: number;
+    scale?: number;
+    shader?: WaterShader;
+    flowMap?: Texture;
+    normalMap0: Texture;
+    normalMap1: Texture;
+}
+
+declare interface WaterShader {
+    name: string;
+    uniforms: Record<string, IUniform>;
+    vertexShader: string;
+    fragmentShader: string;
+}
+
 export { }