vis-core 0.33.5 → 0.33.7

package/dist/index.d.ts

@@ -8,6 +8,8 @@ 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';
@@ -18,10 +20,12 @@ 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';
@@ -35,21 +39,42 @@ 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 { 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';
-import { Water } from './Water2';
+
+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>);
@@ -99,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;
@@ -119,7 +146,8 @@ declare class Base_2 extends Camera {
     private detectRes?;
     private ownsPencil;
     private renderingSuspensions;
-    /* Excluded from this release type: suspendRendering */
+    /** Internal: 在运行时创建前也可暂停，保证整个初始化过程不提交中间帧。 */
+    suspendRendering(): () => void;
     private acquireRenderingSuspensions;
     publicDir: Record<string, string>;
     private prefabAssets;
@@ -127,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);
@@ -142,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>;
     /** 子类扩展点：恢复场景引用和运行时派生状态，不生成地图几何或移动相机。 */
@@ -260,7 +291,7 @@ export declare interface BindMaterialAssetOptions {
 }
 
 /** 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;
+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;
@@ -326,7 +357,6 @@ declare class City {
     setOptions(options: CityOptions): void;
     multiplyScalar: number;
     private getProjectionOptions;
-    fixNearFar(n?: number, f?: number): void;
     /** Load and validate only; prefetching must never mutate shared Lead state. */
     preloadResources(): Promise<{
         sources: {
@@ -406,13 +436,16 @@ 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_5;
-    mapArr: PlaneMap[];
+    mapArr: PlaneMap_2[];
     constructor(options: Options_5);
     create(): Promise<void>;
     getLocationPosition(location: [number, number], name?: string, height?: number): [number, number, number] | undefined;
@@ -436,7 +469,7 @@ export declare function copySnapshotGeometries(snapshot: any, source: BaseObject
 /** 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 function createMaterialAssetDocument(document: VisSceneDocument, options: CreateMaterialAssetOptions): VisSceneDocument;
 
 export declare interface CreateMaterialAssetOptions {
     id: string;
@@ -459,9 +492,18 @@ 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;
 
@@ -471,7 +513,7 @@ declare class DirectionalLight extends DirectionalLightObject {
     render(): void;
 }
 
-declare function duplicateMaterialAssetDocument(document: VisSceneDocument, id: string, newId: string, mode: 'asset' | 'object' | 'scene', sceneId: string, objectId?: string, slot?: number): VisSceneDocument;
+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'> & {
@@ -499,21 +541,23 @@ export declare function duplicateSceneDocument(before: VisSceneDocument, sceneId
 
 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: ArcObject;
         Model: ModelObject;
@@ -566,7 +610,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);
@@ -589,6 +633,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 {
@@ -602,7 +698,8 @@ 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;
@@ -617,18 +714,10 @@ export declare function extractMaterialDefinition(scene: SceneViewportDocument,
  * 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;
-    lat: number;
-    name: string;
-    level: string;
-    parent: number;
-    c: number[];
-    b: number[];
-} | undefined;
+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>;
 
@@ -663,6 +752,16 @@ export declare interface GroupObjectsDocumentOptions {
 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;
@@ -670,6 +769,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 属于旧格式，仍由编辑器的兼容流程处理。
@@ -678,44 +786,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;
@@ -736,7 +850,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;
@@ -772,7 +886,8 @@ declare class Map_3 extends Base_2 {
     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. */
@@ -821,7 +936,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;
@@ -848,22 +968,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 的字段
      */
@@ -887,7 +998,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>;
@@ -896,6 +1008,12 @@ 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 {
@@ -979,7 +1097,7 @@ declare interface MapOptions extends BaseOptions {
     polarAngle?: number;
     azimuthAngle?: number;
     worldPacificCentre?: boolean;
-    /** 同时限制平移范围、最近缩放距离，以及穿透地图和翻转到背面的视角。默认 true。 */
+    /** 限制平移范围，防止相机及近裁剪面穿透地图或翻到背面；允许贴近表面。默认 true。 */
     mapBoundary?: boolean;
     mergeSide?: boolean;
     /** switchMapRegion 时重建城市建筑、道路、河流等数据层。 */
@@ -1018,7 +1136,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>;
@@ -1110,9 +1229,10 @@ export declare const materialDocumentOperations: Readonly<{
 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;
+export declare function materializeChangedAssets(document: VisSceneDocument, assets: readonly MaterialAsset[], sceneIds?: ReadonlySet<string>): VisSceneDocument;
 
-/* Excluded from this release type: materializeOwnedProjectMaterials */
+/** 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;
@@ -1192,11 +1312,18 @@ export declare function moveObjectsDocument(before: VisSceneDocument, sceneId: s
 /** 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 */
+/** 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;
@@ -1325,11 +1452,23 @@ declare interface Options_9 {
 /** 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: {
@@ -1343,7 +1482,9 @@ declare class Plane extends MeshObject {
     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;
@@ -1475,14 +1616,14 @@ export declare function projectLocation(map: PlanarMap, anchor: MapAnchor, mapCR
     scaleBasis: "local spherical approximation";
 };
 
-declare function promoteMaterialAssetDocument(document: VisSceneDocument, id: string): VisSceneDocument;
+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。 */
@@ -1498,7 +1639,7 @@ declare interface RegionTextureRule {
 }
 
 /** Register imported definitions without normalizing or copying the existing project. */
-declare function registerSceneMaterials(document: VisSceneDocument, sceneId: string, onlyIds?: ReadonlySet<string>): VisSceneDocument;
+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;
@@ -1527,12 +1668,16 @@ 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;
 
-declare function removeMaterialAssetDocument(document: VisSceneDocument, id: string): VisSceneDocument;
+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;
@@ -1541,7 +1686,12 @@ export declare function removeProjectMaterial<T extends VisSceneDocument>(docume
 
 export declare function removeSceneDocument(before: VisSceneDocument, sceneId: string): VisSceneDocument;
 
-declare function replaceMaterialAssetDocument(document: VisSceneDocument, asset: MaterialAsset): 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;
@@ -1727,9 +1877,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;
     /**
@@ -1741,33 +1891,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)，但候选场景只在两步都成功后提交，
@@ -1775,17 +1926,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[];
@@ -1797,7 +1948,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;
@@ -1816,9 +1967,9 @@ 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 (default 8), including the active page; oldest inactive pages retire first. */
@@ -1846,6 +1997,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: {
@@ -1859,7 +2012,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[];
@@ -1869,6 +2024,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. */
@@ -1960,9 +2121,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 {
@@ -2057,11 +2218,14 @@ export { THREE }
 
 export { TWEEN }
 
-export { Tween }
+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.5";
+export declare const VERSION = "0.33.7";
+
+/** 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;
@@ -2096,4 +2260,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 { }