vis-core 0.32.7 → 0.33.0

package/dist/index.d.ts

@@ -17,12 +17,15 @@ import { MeshObject } from 'gl-draw';
 import { MultiPolygon } from 'geojson';
 import { NodeObject } from 'gl-draw';
 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 { RestoreBaseObjectOptions } from 'gl-draw';
 import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
+import { SceneSnapshot } from 'gl-draw';
 import { SpotLightObject } from 'gl-draw';
 import { SpriteObject } from 'gl-draw';
 import * as THREE from 'three';
@@ -37,6 +40,7 @@ declare class AmbientLight extends AmbientLightObject {
 export declare namespace animationUtils {
     export {
         timeOut,
+        TweenOptions,
         sinusoidalInOut,
         baseObjectFadeIn,
         baseObjectFadeOut,
@@ -47,22 +51,21 @@ export declare namespace animationUtils {
 
 declare class Arc extends LineObject {
     objectType: string;
-    options: Options;
-    constructor(options: Options);
+    options: Options_5;
+    constructor(options: Options_5);
     create(): Promise<void>;
-    line: {
-        options: {
-            nodes: THREE.Vector3[];
-        };
-    };
     getCurve(): THREE.CubicBezierCurve3;
     setControlPoints(points: [THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]): void;
     setPath(from: THREE.Vector3 | number[], to: THREE.Vector3 | number[], radius: number, setPointWidth?: (p: number) => number): void;
+    private updatePickTargetGeometry;
     pickTube: Tube | null;
     private pickTargetVersion;
+    private pickBindings;
     addPickTarget(radius?: number, show?: boolean): Promise<Tube | undefined>;
+    /** Restored picking children are adopted instead of allocating a duplicate tube. */
+    rebuildFromScene(): Promise<void>;
     dispose(): void;
-    onPointerEvent(...args: Parameters<BaseObject['onPointerEvent']>): void;
+    protected createPointerBinding(type: PickFunctionsItem['type'], cb: PickFunctionsItem['cb']): () => void;
     setColor(color: string): void;
     animateIn({ duration, delay, repeat, onComplete, onRepeat, }?: {
         duration?: number;
@@ -83,9 +86,14 @@ declare class Area extends GroupObject {
     rebuildFromScene(): void;
 }
 
+/** Validation is read-only and does not materialize or allocate runtime resources. */
+export declare function assertProjectMaterials(document: Pick<VisSceneDocument, 'schemaVersion' | 'scenes' | 'materialLibrary' | 'prefabLibrary'>): void;
+
 /** vis-core 的运行时入口只接受编辑平台导出的完整场景文档。 */
 export declare function assertRuntimeSceneDocument(value: unknown): asserts value is VisSceneDocument & Record<string, any>;
 
+export declare function assertSceneManifest(value: unknown): asserts value is VisSceneManifest;
+
 export declare function assertSupportedSceneDocument(value: unknown): void;
 
 export declare type Base = Base_2;
@@ -96,23 +104,35 @@ declare class Base_2 extends Camera {
         observeParentScale: boolean;
         applyDisabledMouseButtons: boolean;
         cacheCityGeometry: boolean;
+        includePrefabPreviews: boolean;
     };
     leftTruck: boolean;
     options: BaseOptions;
     showState: boolean;
-    settings: Record<string, any>;
     lead: Lead;
-    mList: default_2['mList'];
+    sceneResources: default_2['sceneResources'];
     tier0: boolean;
     pmremGenerator: THREE.PMREMGenerator | null;
     re: RoomEnvironment | null;
     roomEnvMap?: THREE.Texture;
     private roomEnvTarget?;
+    private roomEnvLease?;
     visName: string;
     private detectRes?;
     private ownsPencil;
     publicDir: Record<string, string>;
+    private prefabAssets;
+    private prefabMaterials;
+    private prefabOperations;
+    /** Inspect SDK-enabled definitions without creating scene objects or resources. */
+    getPrefabLibrary(): PrefabAsset[];
+    /* Excluded from this release type: setPrefabLibrary */
+    instantiatePrefab(keyOrAssetId: string, options?: InstantiatePrefabOptions): Promise<BaseObject>;
+    private cancelPrefabOperations;
     constructor(options: BaseOptions);
+    getMaterialGroup(group: string): Record<string, THREE.Material<THREE.MaterialEventMap>> | null;
+    registerMaterialGroup(group: string, materials: Record<string, THREE.Material | null>): void;
+    copyMaterialGroup(source: string, target: string): Record<string, THREE.Material<THREE.MaterialEventMap>>;
     private getDetectRes;
     private getQueryOverrides;
     private getEffectiveLogarithmicDepthBuffer;
@@ -124,6 +144,8 @@ declare class Base_2 extends Camera {
     /* Excluded from this release type: fromJSON */
     private runtimeInitialization?;
     private disposed;
+    private readonly handleObjectIdentityChanged;
+    private readonly handleMaterialIdentityChanged;
     /* Excluded from this release type: initializeRuntime */
     /** 子类扩展点：运行环境只初始化一次，适合建立投影和绑定控制器事件。 */
     protected onRuntimeReady(): Promise<void>;
@@ -133,8 +155,8 @@ declare class Base_2 extends Camera {
     protected onDispose(): void;
     protected get objectTypes(): Record<string, any>;
     protected get defaultCameraUp(): THREE.Vector3;
-    private observeScale;
     private createRuntime;
+    private reportScriptError;
     private sceneActive;
     setSceneActive(): void;
     /**
@@ -152,18 +174,30 @@ declare class Base_2 extends Camera {
     /** 场景页提交后的默认入场动画；地图可覆盖为更有空间感的过渡。 */
     playEnterTransition({ duration, onPrepared, }: SceneEnterTransitionOptions): Promise<void>;
     addCSS3DRenderer(container?: HTMLElement): void;
-    initSettingsObj?: Record<string, any>;
-    mouseButtonsActiveStore: Record<string, any> | null;
-    private initSettings;
-    handleSetting(key: string, value: any): void;
+    private controlsInitialized;
+    private temporaryControls;
+    /** A copy of the authored configuration; temporary input locks are not persisted. */
+    getControls(): Readonly<SceneControlsOptions>;
+    setControls(patch: SceneControlsOptions): void;
+    /** Overrides compose in acquisition order and can be released in any order. */
+    setTemporaryControls(patch: SceneControlsOptions): () => void;
+    private validateControls;
+    private initializeControls;
+    protected applyControls(): void;
+    protected applyControlOptions(controls: SceneControlsOptions): void;
     protected prepareInitialCamera(): Promise<void>;
+    private restoreCameraControlTarget;
     private showing?;
+    private sceneTemporarilyHidden;
+    private authoredSceneVisible;
+    private hideSceneContent;
+    private showSceneContent;
     show(): Promise<void>;
     hide(): void;
-    exportScene(): THREE.Object3DJSON;
-    exportBaseObject(baseObject: BaseObject): THREE.Object3DJSON;
-    restoreBaseObject(data: string | THREE.Object3DJSON, target?: BaseObject, objectsMap?: Record<string, any>, signal?: AbortSignal): Promise<BaseObject<THREE.Object3D<THREE.Object3DEventMap>>>;
-    restoreScene(str: string | THREE.Object3DJSON, objectsMap?: Record<string, any>): Promise<void>;
+    exportScene(): SceneSnapshot;
+    exportBaseObject(baseObject: BaseObject): SceneSnapshot;
+    restoreBaseObject(data: string | THREE.Object3DJSON, target?: BaseObject, objectsMap?: Record<string, any>, signal?: AbortSignal, options?: RestoreBaseObjectOptions): Promise<BaseObject<THREE.Object3D<THREE.Object3DEventMap>>>;
+    restoreScene(str: string | THREE.Object3DJSON, objectsMap?: Record<string, any>, restoreOptions?: RestoreBaseObjectOptions): Promise<void>;
     getClassRefByType(type: string): typeof BaseObject;
     addGroup(): Promise< GroupObject>;
     addCSS2D(dom: HTMLElement, options?: {
@@ -186,10 +220,9 @@ declare class Base_2 extends Camera {
     uuidByObject(object: THREE.Object3D): string | undefined;
     objectByUuid(key: string): THREE.Object3D<THREE.Object3DEventMap>;
     uuidByBaseObject(object: BaseObject): string;
-    baseObjectByUuid(key: `arc${string}`): Arc;
-    baseObjectByUuid(key: `sprite${string}`): Sprite;
-    baseObjectByUuid(key: string): BaseObject;
-    private normalizeBaseObjectKey;
+    baseObjectByUuid(uuid: string): BaseObject;
+    /** Compatibility method name; key is the persisted UUID. */
+    baseObjectByKey(key: string): BaseObject;
     baseObjectByName(name: string): BaseObject<THREE.Object3D<THREE.Object3DEventMap>> | undefined;
     dispose(): void;
 }
@@ -200,7 +233,7 @@ declare const baseObjectBounce: (obj: BaseObject, up: string | undefined, to: nu
         repeat?: number | undefined;
         repeatResolve?: number | undefined;
         repeatDelay?: number | undefined;
-    }) => Promise<any>;
+    }) => Promise<void>;
     stop: () => void;
 };
 
@@ -210,7 +243,7 @@ declare const baseObjectBounceIn: (obj: BaseObject, up?: string) => {
         repeat?: number | undefined;
         repeatResolve?: number | undefined;
         repeatDelay?: number | undefined;
-    }) => Promise<any>;
+    }) => Promise<void>;
     stop: () => void;
 };
 
@@ -220,7 +253,7 @@ declare const baseObjectFadeIn: (obj: BaseObject) => {
         repeat?: number | undefined;
         repeatResolve?: number | undefined;
         repeatDelay?: number | undefined;
-    }) => Promise<any>;
+    }) => Promise<void>;
     stop: () => void;
 };
 
@@ -230,7 +263,7 @@ declare const baseObjectFadeOut: (obj: BaseObject) => {
         repeat?: number | undefined;
         repeatResolve?: number | undefined;
         repeatDelay?: number | undefined;
-    }) => Promise<any>;
+    }) => Promise<void>;
     stop: () => void;
 };
 
@@ -246,11 +279,25 @@ declare interface BaseOptions {
     tier?: number;
     observeParentScale?: boolean;
     createIfNeeded?: boolean;
+    materialBindings?: MaterialBindings;
     /** 相机输入与场景运行控制，由平台随场景参数导出。 */
     controls?: SceneControlsOptions;
     [key: string]: any;
 }
 
+export declare function bindMaterialAsset<T extends VisSceneDocument>(document: T, options: BindMaterialAssetOptions): T;
+
+export declare interface BindMaterialAssetOptions {
+    sceneId: string;
+    assetId: string;
+    /** Scene graph UUID or the managed object's _baseObjectUuid. */
+    objectId?: string;
+    /** A multi-material slot, defaulting to 0. */
+    slot?: number;
+    /** Optional semantic lookup role; the catalog entry uses the material UUID. */
+    alias?: string;
+}
+
 declare class Box extends MeshObject {
     objectType: string;
     create(): void;
@@ -262,6 +309,7 @@ declare class Building extends GroupObject {
     constructor(options: Options_9);
     create(): Promise<void>;
     rebuildFromScene(): void;
+    private gradientMaterials;
     worldPositionZ: {
         value: number;
     };
@@ -309,12 +357,22 @@ declare class City {
     road: Road;
     pencil: Pencil;
     lead: Pencil['lead'];
-    mList: Pencil['mList'];
+    sceneResources: Pencil['sceneResources'];
     constructor(pencil: Pencil);
     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: {
+            building: string | undefined;
+            road: string | undefined;
+            river: string | undefined;
+            grassland: string | undefined;
+        };
+        data: Partial<Record<"building" | "road" | "river" | "grassland", any>>;
+    }>;
     init(existingGroup?: GroupObject): Promise<void>;
     drawCityPlane(adcode: number, target?: BaseObject): Promise<void>;
     drawBuilding(options?: {
@@ -339,6 +397,7 @@ declare class City {
 }
 
 declare interface CityOptions {
+    materialBindings?: MaterialBindings;
     adcode: number;
     jsonName: string;
     cacheKey?: string;
@@ -373,6 +432,13 @@ declare class CityPlane extends MeshObject {
     dispose(): void;
 }
 
+/** Duplicate scene-owned definitions, while retaining references to project assets. */
+export declare function cloneSceneMaterials(document: VisSceneDocument, sourceId: string, newSceneId: string): {
+    scene: SceneViewportDocument;
+    materialLibrary: MaterialAsset[];
+    idMap: Map<string, string>;
+};
+
 /** Rebind internal targets while preserving links to scenes outside the copied set. */
 export declare function cloneSceneWithIds(scene: SceneViewportDocument, ids: Map<string, string>): SceneViewportDocument;
 
@@ -389,12 +455,45 @@ declare class ContinentsBg extends GroupObject {
     dispose(): 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 interface CreateMaterialAssetOptions {
+    id: string;
+    name: string;
+    material: Record<string, any>;
+    scope?: MaterialScope;
+    locked?: boolean;
+}
+
+/**
+ * Share resource indices for one synchronous extraction batch. The scene's
+ * resource tables must remain unchanged until the batch finishes. Each result
+ * owns independent copies of its material and dependencies.
+ */
+export declare function createMaterialDefinitionExtractor(scene: SceneViewportDocument): (materialUuid: string) => Record<string, any>;
+
+/** Runtime delivery boundary shared by single-file, split and IndexedDB exports. */
+export declare function createRuntimeSceneDocument(document: VisSceneDocument): VisSceneDocument;
+
+/** Convert authored asset aliases to the native catalog expected by graph restoration. */
+export declare function createRuntimeSceneGraph(scene: SceneViewportDocument, options?: {
+    omitPrefabPreviews?: boolean;
+}): Record<string, any>;
+
 declare class DirectionalLight extends DirectionalLightObject {
     constructor(...options: ConstructorParameters<typeof DirectionalLightObject>);
     update(delta: number, elapsed: number): void;
     render(): void;
 }
 
+/** 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;
+    newAssetId: string;
+    name?: string;
+}): T;
+
 export declare type Earth = Earth_2;
 
 declare class Earth_2 extends Base_2 {
@@ -406,7 +505,7 @@ declare class Earth_2 extends Base_2 {
     secondaryMap?: PlaneMap;
     get mapArea(): ExtrudePolygonObject[];
     setOptions(options: EarthOptions): void;
-    handleSetting(key: string, value: any): void;
+    protected applyControlOptions(controls: SceneControlsOptions): void;
     protected get objectTypes(): {
         Earth: Earth_3;
         SphereShadow: SphereShadow;
@@ -435,6 +534,7 @@ declare class Earth_2 extends Base_2 {
         Group: GroupObject;
     };
     private rotationControls?;
+    private releaseRotationLock?;
     private readonly stopAutoRotate;
     private readonly resumeAutoRotate;
     protected onRuntimeReady(): Promise<void>;
@@ -456,8 +556,8 @@ declare class Earth_2 extends Base_2 {
 
 declare class Earth_3 extends Sphere {
     objectType: string;
-    options: Required<Options_4>;
-    constructor(options: Options_4);
+    options: Required<Options_2>;
+    constructor(options: Options_2);
     create(): void;
     rebuildFromScene(): void;
 }
@@ -493,6 +593,9 @@ declare class Event_2 {
 /** Expand at the editor import boundary so independently edited scenes own their data. */
 export declare function expandSceneDocumentResources<T extends VisSceneDocument>(document: T): T;
 
+/** 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;
@@ -510,6 +613,15 @@ declare type GeoJSON_3 = FeatureCollection<Polygon | MultiPolygon>;
 
 declare type GeoJSON_4 = FeatureCollection<Polygon | MultiPolygon>;
 
+/** Saved configuration dependencies protect definitions, without representing live usage. */
+export declare function getMaterialDependencies(document: Pick<VisSceneDocument, 'scenes'>, assetId?: string): MaterialUsage[];
+
+/** Includes unloaded scene snapshots, aliases, and every multi-material slot. */
+export declare function getMaterialUsages(document: Pick<VisSceneDocument, 'scenes'>, assetId?: string): MaterialUsage[];
+
+/** Templates remain dependencies even when every scene instance has been removed. */
+export declare function getPrefabMaterialDependencies(document: Pick<VisSceneDocument, 'prefabLibrary'>, assetId: string): PrefabAsset[];
+
 export declare function getSceneDocument(document: VisSceneDocument, sceneId?: string, options?: {
     resolveResources?: boolean;
 }): SceneViewportDocument;
@@ -517,12 +629,24 @@ export declare function getSceneDocument(document: VisSceneDocument, sceneId?: s
 declare class HemisphereLight extends HemisphereLightObject {
 }
 
+export declare interface InstantiatePrefabOptions {
+    /** Parent in the destination scene. Defaults to the scene root. */
+    target?: BaseObject;
+    /** Defaults to true so business style changes cannot edit another instance. */
+    cloneMaterial?: boolean;
+}
+
 /**
  * 新场景文档以完整场景快照作为恢复基线。
  * 未带标记的 JSON 属于旧格式，仍由编辑器的兼容流程处理。
  */
 export declare function isSceneDocument(value: unknown): value is SceneDocumentMarker & Record<string, any>;
 
+export declare function isSceneManifest(value: unknown): value is VisSceneManifest;
+
+/** 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 }
 
@@ -610,6 +734,10 @@ declare class Map_3 extends Base_2 {
     protected prepareInitialCamera(): Promise<void>;
     private updateMapBoundary;
     /* Excluded from this release type: finalizeRegionGeometry */
+    private prepareCityVis;
+    private preloadCityVis;
+    /** Keep at most two cities ahead in the loader; all Lead writes stay ordered. */
+    private initCitySequence;
     initCityVis(adcode: number, grey?: boolean): Promise<City>;
     initCityOnMap(adcode: number): Promise<void>;
     private _getParentBgMetrics;
@@ -711,12 +839,15 @@ declare class Map_3 extends Base_2 {
      */
     private applyOverlayLayers;
     /**
-     * 根据 switchFixConfig 对场景中的对象做位置/缩放修复
+     * Apply the region behavior authored on each object.
      */
-    private applySwitchFixConfig;
+    private applyRegionObjectState;
     /* Excluded from this release type: rebuildRegion */
+    private rebuildRegionGeometry;
     /** 候选区域提交后的相机过渡，不参与场景序列化。 */
     playRegionEnterTransition({ duration, sourceCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
+    /** Region rules are page-local runtime overrides of a saved material asset. */
+    private regionRuleMaterial;
     private setRegionTexture;
     applyRegionTextureRules(adcode: number): Promise<void>;
     protected onDispose(): void;
@@ -778,8 +909,6 @@ declare interface MapOptions extends BaseOptions {
     lineOffset?: number;
     extrudeLineWidth?: number;
     extrudeLine?: boolean;
-    equirectangular?: boolean;
-    winkel3?: boolean;
     projectionType?: 'mercator' | 'equirectangular' | 'winkel3';
     polarAngle?: number;
     azimuthAngle?: number;
@@ -795,7 +924,6 @@ declare interface MapOptions extends BaseOptions {
     geojsonMapReplace?: Record<string, GeoJSON_3 | string | number>;
     extrudeLineGeojsonMapReplace?: Record<string, GeoJSON_3 | string | number>;
     shadowMap?: boolean;
-    switchFixConfig?: SwitchFixConfig;
     /** switchMapRegion 后按场景声明替换区域相关纹理。 */
     regionTextureRules?: RegionTextureRule[];
     /** 动态地图、城市数据和水面纹理的资源地址模板。 */
@@ -844,7 +972,7 @@ export declare interface MapSafeAreaOptions {
     smoothTime?: number;
 }
 
-/** 平台导出的运行时对象绑定，使用 Lead 的完整 key，不依赖命名规则。 */
+/** 平台导出的运行时对象绑定，直接引用 Object3D.uuid。 */
 declare interface MapSceneBindings {
     container: string;
     region: {
@@ -856,6 +984,86 @@ declare interface MapSceneBindings {
     cities: string[];
 }
 
+export declare const MATERIAL_ASSET_ID = "_materialAssetId";
+
+export declare const MATERIAL_ASSET_REVISION = "_materialAssetRevision";
+
+export declare const MATERIAL_RUNTIME_PROPERTIES = "_materialRuntimeProperties";
+
+/** Retained catalog entries are keyed by the native scene material UUID. */
+export declare interface MaterialAlias {
+    assetId: string;
+    locked?: boolean;
+}
+
+export declare interface MaterialAsset {
+    id: string;
+    revision: number;
+    scope: MaterialScope;
+    name: string;
+    /** A complete Material.toJSON() value, including texture and image dependencies. */
+    material: Record<string, any>;
+    locked?: boolean;
+}
+
+declare type MaterialBindings = Record<string, Record<string, string>>;
+
+/** A declared scalar edit; revisions are commit metadata rather than editable properties. */
+export declare interface MaterialDefinitionScope {
+    readonly assetIds: readonly string[];
+    readonly properties: readonly string[];
+}
+
+/** 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>;
+
+/** Mutate a detached working snapshot owned exclusively by the caller. */
+export declare function materializeOwnedSceneMaterials<T extends SceneViewportDocument>(scene: T, library?: MaterialAsset[]): T;
+
+export declare function materializeProjectMaterials<T extends VisSceneDocument>(document: T): T;
+
+/**
+ * Scoped scalar history for already normalized snapshots. Unchanged object,
+ * geometry and texture tables are borrowed; callers must keep snapshots immutable.
+ * Structural/texture changes must use the full materialization entrypoint.
+ */
+export declare function materializeSceneMaterialDefinitions<T extends SceneViewportDocument>(scenes: readonly T[], previousAssets: MaterialAsset[], nextAssets: MaterialAsset[], scope?: MaterialDefinitionScope): T[];
+
+/** Inject authoritative definitions while keeping each scene's material UUIDs stable. */
+export declare function materializeSceneMaterials<T extends SceneViewportDocument>(scene: T, library?: MaterialAsset[]): T;
+
+/** One validation context per batch; never cached across caller mutations. */
+export declare function materializeSceneMaterialsBatch<T extends SceneViewportDocument>(scenes: readonly T[], library?: MaterialAsset[]): T[];
+
+/** Serializable project data. This deliberately contains no THREE instances or GPU ownership. */
+export declare type MaterialScope = {
+    kind: 'project';
+} | {
+    kind: 'scene';
+    sceneId: string;
+};
+
+export declare interface MaterialUsage {
+    assetId: string;
+    sceneId: string;
+    objectId: string;
+    slot: number;
+    /** Constructor input rather than a native mesh material slot. */
+    optionPath?: string[];
+    alias?: string;
+}
+
+/** 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[];
+}): Record<string, any>;
+
+export declare function mergeProjectMaterials(target: VisSceneDocument, incoming: VisSceneDocument): {
+    document: VisSceneDocument;
+    materialLibrary: MaterialAsset[];
+    idMap: Map<string, string>;
+};
+
 declare class Model extends GroupObject {
     options: Options_7;
     mixer: THREE.AnimationMixer | null;
@@ -936,16 +1144,45 @@ declare class Mountain extends GroupObject {
     rebuildFromScene(): void;
 }
 
-declare interface Options extends NonNullable<ConstructorParameters<typeof LineObject>[0]> {
-    from: number[];
-    to: number[];
-    control1?: number[];
-    control2?: number[];
-    radius?: number;
-    globe?: boolean;
-    color?: string;
-    lineWidth?: number;
-    offsetLoop?: boolean;
+/** Bind serialized runtime materials and alias catalogs to authored assets. */
+export declare function normalizeProjectMaterials<T extends VisSceneDocument>(document: T): T;
+
+declare interface Options {
+    /** @deprecated Legacy generation scope, read only when importing old snapshots. */
+    uuid?: string;
+    areaGroup?: boolean;
+    geojson: GeoJSON_2;
+    projection?: {
+        center: [number, number];
+        scale: number;
+        rotate?: [number, number];
+        projectionType?: 'mercator' | 'equirectangular' | 'winkel3';
+    };
+    extrudeLineGeojson?: GeoJSON_2;
+    hasSide?: boolean;
+    hasTop?: boolean;
+    hasLine?: boolean;
+    start?: number;
+    depth?: number;
+    lineOffset?: number;
+    bbox?: number[];
+    topSegments?: number;
+    conic?: boolean;
+    castShadow?: boolean;
+    mergeSide?: boolean;
+    hasExtrudeLine?: boolean;
+    materialOptions: {
+        topMat: THREE.Material;
+        sideMat?: THREE.Material;
+        lineMat?: MeshLineMaterial;
+        extrudeLineMat?: MeshLineMaterial;
+        bgTopMat?: THREE.Material;
+        bgSideMat?: THREE.Material;
+        bgLineMat?: MeshLineMaterial;
+        bgExtrudeLineMat?: MeshLineMaterial;
+    };
+    onTop?: number;
+    bloom?: boolean;
 }
 
 declare interface Options_10 {
@@ -958,6 +1195,7 @@ declare interface Options_10 {
     cacheKey?: string;
     meters?: number;
     grey?: boolean;
+    material?: MeshLineMaterial;
 }
 
 declare interface Options_11 {
@@ -994,59 +1232,36 @@ declare interface Options_13 {
 }
 
 declare interface Options_2 {
-    path?: THREE.Curve<THREE.Vector3>;
     radius?: number;
-    multiplyScalar?: number;
+    rotationY?: number;
 }
 
 declare interface Options_3 {
-    uuid?: string;
-    areaGroup?: boolean;
-    geojson: GeoJSON_2;
-    projection?: {
-        center: [number, number];
-        scale: number;
-        rotate?: [number, number];
-        projectionType?: 'mercator' | 'equirectangular' | 'winkel3';
-    };
-    extrudeLineGeojson?: GeoJSON_2;
-    hasSide?: boolean;
-    hasTop?: boolean;
-    hasLine?: boolean;
-    start?: number;
-    depth?: number;
-    lineOffset?: number;
-    bbox?: number[];
-    topSegments?: number;
-    conic?: boolean;
-    castShadow?: boolean;
-    mergeSide?: boolean;
-    hasExtrudeLine?: boolean;
-    materialOptions: {
-        topMat: THREE.Material;
-        sideMat?: THREE.Material;
-        lineMat?: MeshLineMaterial;
-        extrudeLineMat?: MeshLineMaterial;
-        bgTopMat?: THREE.Material;
-        bgSideMat?: THREE.Material;
-        bgLineMat?: MeshLineMaterial;
-        bgExtrudeLineMat?: MeshLineMaterial;
-    };
-    onTop?: number;
-    bloom?: boolean;
+    radius?: number;
 }
 
 declare interface Options_4 {
-    radius?: number;
-    rotationY?: number;
+    sprite?: boolean;
 }
 
-declare interface Options_5 {
+declare interface Options_5 extends NonNullable<ConstructorParameters<typeof LineObject>[0]> {
+    from: number[];
+    to: number[];
+    control1?: number[];
+    control2?: number[];
     radius?: number;
+    globe?: boolean;
+    color?: string;
+    lineWidth?: number;
+    offsetLoop?: boolean;
 }
 
 declare interface Options_6 {
-    sprite?: boolean;
+    path?: THREE.Curve<THREE.Vector3>;
+    radius?: number;
+    multiplyScalar?: number;
+    /** Compact saved inputs for an Arc's derived picking geometry. */
+    arcControlPoints?: number[][];
 }
 
 declare interface Options_7 {
@@ -1058,6 +1273,11 @@ declare interface Options_7 {
 }
 
 declare interface Options_8 {
+    materialOptions: {
+        topMat: THREE.Material;
+        sideMat: THREE.Material;
+        lineMat: MeshLineMaterial;
+    };
     scale: number;
     depth: number;
     assetsPrefix?: string;
@@ -1077,11 +1297,17 @@ declare interface Options_9 {
     hasSide?: boolean;
     sideGradient?: boolean;
     grey?: boolean;
+    materialOptions?: Record<string, THREE.Material>;
 }
 
 /** Pack an export copy only; preserve the editor's independent scene snapshots. */
 export declare function packSceneDocumentResources<T extends VisSceneDocument>(document: T): T;
 
+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;
+
 declare class Plane extends MeshObject {
     objectType: string;
     create(): void;
@@ -1089,7 +1315,7 @@ declare class Plane extends MeshObject {
 
 declare class PlaneMap extends GroupObject {
     objectType: string;
-    options: Required<Omit<Options_3, 'bbox' | 'extrudeLineGeojson'>> & Pick<Options_3, 'bbox' | 'extrudeLineGeojson'>;
+    options: Required<Omit<Options, 'bbox' | 'extrudeLineGeojson' | 'uuid'>> & Pick<Options, 'bbox' | 'extrudeLineGeojson' | 'uuid'>;
     isActive: boolean;
     groupArr: GroupObject[];
     areaArr: ExtrudePolygonObject[];
@@ -1097,7 +1323,7 @@ declare class PlaneMap extends GroupObject {
     mergeSideArea: ExtrudePolygonObject | null;
     extrudelineArr?: LineObject[];
     splitPolygons: number;
-    constructor(options: Options_3);
+    constructor(options: Options);
     create(): Promise<void>;
     private markGeneratedObjects;
     private ensureExtrudeLineMaterials;
@@ -1120,13 +1346,15 @@ declare class PlaneMap extends GroupObject {
         onTop?: number;
         areaGroup?: boolean;
     }): Promise<LineObject[]>;
+    private shouldUseGeometryWorker;
     getPropertiesKey(properties: Record<string, any>): string;
     geojson2Meta(geojson: GeoJSON_2): {
         coords: Position[][];
         properties: GeoJsonProperties;
     }[];
     update(_delta: number, elapsed: number): void;
-    findGroup(adcode: string | number, fix?: boolean): GroupObject | undefined;
+    findGroup(adcode: string | number, _fix?: boolean): GroupObject | undefined;
+    private batchMaterialChanges;
     useAreaMaterial(key: string): void;
     useLineMaterial(key: string): void;
     useExtrudeLineMaterial(key: string): void;
@@ -1137,7 +1365,6 @@ declare class PlaneMap extends GroupObject {
     deactive(): void;
     render(): void;
     rebuildFromScene(): void;
-    private clearGeneratedRegionProperties;
     /**
      * 场景快照保存的是网格实际材质，options 中的 Material 会被导出器过滤。
      * 恢复完成后从生成对象反推下一次区域重建所需的运行时材质。
@@ -1155,8 +1382,8 @@ declare class PlaneShadow extends MeshObject {
 
 declare class Point extends BaseObject {
     objectType: string;
-    options: Options_6;
-    constructor(options: Options_6);
+    options: Options_4;
+    constructor(options: Options_4);
     get material(): THREE.MeshBasicMaterial | THREE.SpriteMaterial;
     getMaterial(): THREE.MeshBasicMaterial | THREE.SpriteMaterial;
     create(): Promise<void>;
@@ -1170,11 +1397,29 @@ declare class PointLight extends PointLightObject {
     render(): void;
 }
 
+export declare interface PrefabAsset {
+    id: string;
+    name: string;
+    revision: number;
+    /** Stable public SDK identifier. Omit for assets used only by the editor. */
+    sdkKey?: string;
+    snapshot: Record<string, any>;
+}
+
+/** An opaque, single-use topology transaction owned by the SceneManager that prepared it. */
+export declare interface PreparedSceneStructure {
+    readonly [preparedSceneStructure]: true;
+}
+
+declare const preparedSceneStructure: unique symbol;
+
+export declare function promoteMaterialToProject<T extends VisSceneDocument>(document: T, assetId: string): T;
+
 declare class RectAreaLight extends RectAreaLightObject {
 }
 
 declare interface RegionTextureRule {
-    /** mList 中的材质 key，例如 plane#topMat。 */
+    /** 材质 UUID，或显式材质角色，例如 plane#topMat。 */
     material: string;
     /** THREE.Material 上的纹理属性，例如 map、emissiveMap。 */
     property: string;
@@ -1192,14 +1437,25 @@ export declare interface RemappedSceneDocument {
     entrySceneId: string;
     scenes: SceneViewportDocument[];
     idMap: Map<string, string>;
+    materialLibrary?: MaterialAsset[];
+    /** Reusable definitions, independent of scene instances. */
+    prefabLibrary?: PrefabAsset[];
 }
 
+/** A cross-project import remaps identities even if equal JSON happens to collide. */
+export declare function remapProjectMaterialIds<T extends VisSceneDocument>(document: T, createId: (asset: MaterialAsset, index: number) => string): {
+    document: T;
+    idMap: Map<string, string>;
+};
+
 /**
  * 复制一组场景并为它们分配新 ID，同时保持文档内部的场景跳转关系。
  * 用于把完整模板追加到另一个场景文档中。
  */
 export declare function remapSceneDocumentIds(document: VisSceneDocument, createSceneId: (scene: SceneViewportDocument, index: number) => string): RemappedSceneDocument;
 
+export declare function removeProjectMaterial<T extends VisSceneDocument>(document: T, assetId: string): T;
+
 declare class Ring extends MeshObject {
     objectType: string;
     create(): void;
@@ -1216,9 +1472,20 @@ declare class Road extends GroupObject {
     dispose(): void;
 }
 
+/** Only ordinary encoded images are externalized. Typed pixel data, videos and
+ * custom payloads keep their original serialization contract. */
+declare interface RuntimeImageAsset {
+    data: Uint8Array;
+    mimeType: string;
+}
+
 export declare const SCENE_DOCUMENT_FORMAT: "vis-scene";
 
-export declare const SCENE_DOCUMENT_SCHEMA_VERSION: 3;
+export declare const SCENE_DOCUMENT_SCHEMA_VERSION: 5;
+
+export declare const SCENE_MANIFEST_FORMAT: "vis-scene-manifest";
+
+export declare const SCENE_MANIFEST_SCHEMA_VERSION: 2;
 
 export declare interface SceneBackInteraction {
     trigger: 'click' | 'clickOutside';
@@ -1229,10 +1496,18 @@ export declare interface SceneBackInteraction {
     };
 }
 
+/** Scene membership/options delta. Existing authored graphs must use structure patches. */
+export declare interface SceneCollectionTransaction {
+    scenes: readonly SceneViewportDocument[];
+    entrySceneId: string;
+    materialLibrary?: readonly MaterialAsset[];
+    prefabLibrary?: readonly PrefabAsset[];
+}
+
 declare interface SceneControlsOptions {
-    mouseLeft?: number | boolean;
-    mouseRight?: number | boolean;
-    mouseWheel?: number | boolean;
+    mouseLeft?: number;
+    mouseRight?: number;
+    mouseWheel?: number;
     mouseNone?: boolean;
     viewportPadding?: [number, number, number, number];
     autoRotateSpeed?: number;
@@ -1249,6 +1524,11 @@ declare interface SceneEnterTransitionOptions {
     onPrepared?: () => void;
 }
 
+export declare interface SceneInstantiatePrefabOptions extends InstantiatePrefabOptions {
+    /** A scene already loaded by this manager. Defaults to the current scene. */
+    sceneId?: string;
+}
+
 export declare type SceneInteraction = SceneSwitchInteraction | SceneBackInteraction | MapRegionSwitchInteraction | MapRegionBackInteraction;
 
 export declare interface SceneInteractionFilter {
@@ -1263,6 +1543,10 @@ export declare interface SceneInteractionFilter {
 export declare class SceneManager extends Event_2 {
     private options;
     private document?;
+    private manifest?;
+    private manifestUrl?;
+    private loadedDefinitions;
+    private definitionLoads;
     private runtimeHooks?;
     private instances;
     private currentSceneId;
@@ -1271,11 +1555,22 @@ export declare class SceneManager extends Event_2 {
     private isRegionSwitching;
     private pencil?;
     private safeAreaInsets;
+    private generation;
+    private documentIdentityRevision;
+    private preparedStructures;
+    private pendingInstances;
+    private identityTrackedScenes;
+    private prefabOperations;
+    private transactionCacheDepth;
+    private invalidatePendingOperations;
+    private assertGeneration;
     private debugInteraction;
     private enablePickDebug;
     private disposeInactiveScenes;
     constructor(options: SceneManagerInitOptions);
     private prepareScene;
+    /** Publish one identity remap without exporting runtimes or copying other pages/resources. */
+    remapCommittedIdentity(sceneId: string, previous: string, next: string, objectIdentity: boolean): boolean;
     /**
      * 设置宿主界面的运行时地图安全区。该状态不进入场景文档，并会自动传给
      * 当前地图、缓存地图和后续创建的地图区域。
@@ -1286,19 +1581,69 @@ export declare class SceneManager extends Event_2 {
     private playTransition;
     /** 更新可编辑文档，并释放已经不属于文档的非活动场景实例。 */
     setDocument(document: VisSceneDocument): void;
-    load(documentOrUrl: VisSceneDocument | string, hooks?: Record<string, any>): Promise<Base_2>;
+    private syncPrefabLibraries;
+    /**
+     * Replace the complete metadata projection for existing scenes without
+     * recopying assets. Omitted interactions remove the field; own undefined is
+     * preserved, so callers editing only names must include the other metadata.
+     */
+    patchDocumentMetadata(patch: {
+        entrySceneId: string;
+        scenes: Pick<SceneViewportDocument, 'id' | 'name' | 'interactions'>[];
+        s?: string;
+    }): void;
+    /** Commit camera/controls state without validating or cloning authored resources. */
+    patchSceneViewport(sceneId: string, patch: SceneViewportPatch): void;
+    /** Apply validated object properties without copying unrelated nodes or resource tables. */
+    patchSceneObjects(sceneId: string, patches: SceneObjectPatch[]): void;
+    /** Native inspector edits keep the validated topology/resource baseline and its UUID index. */
+    patchSceneObjectProperties(sceneId: string, patches: readonly SceneObjectPropertyPatch[]): void;
+    /** Commit a validated topology delta without cloning unrelated saved scenes or resources. */
+    patchSceneStructure(sceneId: string, patch: SceneStructurePatch): void;
+    /** Commit related topology changes across scenes without exposing intermediate revisions. */
+    patchSceneStructureTransaction(transaction: SceneStructureTransaction): void;
+    private requireStructureDocument;
+    /** Own and validate a topology delta before allocating or moving runtime objects. */
+    prepareSceneStructure(sceneId: string, patch: SceneStructurePatch): PreparedSceneStructure;
+    /** Prepare related edits across scenes and shared catalogs as one atomic transaction. */
+    prepareSceneStructureTransaction(transaction: SceneStructureTransaction): PreparedSceneStructure;
+    /** Own only new pages and changed metadata; retain every existing authored graph. */
+    prepareSceneCollectionTransaction(transaction: SceneCollectionTransaction): PreparedSceneStructure;
+    /** 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>;
+    /** Retire exactly the detached page; never invalidate other loaded pages or pending resources. */
+    retireSceneForTransaction(sceneId: string, expected: Base_2): void;
+    private ownPreparedStructure;
+    private requirePreparedStructure;
+    /**
+     * Check the saved sections affected by topology history without handing out
+     * the private candidate. Editor config/dev metadata is outside this delta.
+     */
+    preparedSceneStructureMatches(prepared: PreparedSceneStructure, target: Pick<VisSceneDocument, 'scenes' | 'materialLibrary' | 'prefabLibrary'>): boolean;
+    /** Commit the already validated candidate once, provided its source is still current. */
+    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>;
     /**
      * 创建一个没有快照输入的运行时页面，并在可选构建步骤完成后将其导出为
      * 标准单场景文档。主要供编辑器新建和旧模板迁移使用。
      */
-    createEmptyScene(definition: EmptySceneDefinition, build?: (scene: Base_2) => void | Promise<void>): Promise<Base_2>;
+    createEmptyScene(definition: EmptySceneDefinition, build?: (scene: Base_2) => void | Promise<void>, materialLibrary?: MaterialAsset[]): Promise<Base_2>;
     /**
      * 以指定地图模板和行政区直接启动，不先加载文档配置的入口场景。
      * 适用于宿主按路由或业务参数决定初始省、市、区的场景。
      */
-    loadMapRegion(documentOrUrl: VisSceneDocument | string, sceneId: string, adcode: number, hooks?: Record<string, any>): Promise<Map_3>;
-    loadMapRegion(documentOrUrl: VisSceneDocument | 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_3>;
+    loadMapRegion(documentOrUrl: VisSceneDocument | VisSceneManifest | string, adcode: number, resolveScene: MapRegionSceneResolver, hooks?: Record<string, any>): Promise<Map_3>;
     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>;
     /**
      * 恢复并缓存一个非活动场景，不改变当前场景、导航历史或相机。
@@ -1328,9 +1673,25 @@ export declare class SceneManager extends Event_2 {
     getSceneByName<T extends SceneType>(name: string, type: T): SceneTypeMap[T] | undefined;
     getSceneByName(name: string): Base_2 | undefined;
     private getSceneByType;
+    /** Inspect saved definitions without creating or pinning runtime materials. */
+    getMaterialLibrary(): MaterialAsset[];
+    /** SDK-enabled definitions stay unloaded until explicitly instantiated. */
+    getPrefabLibrary(): PrefabAsset[];
+    instantiatePrefab(keyOrAssetId: string, options?: SceneInstantiatePrefabOptions): Promise< BaseObject>;
+    /**
+     * Update a saved asset and transactionally rebuild each affected cached page.
+     * 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>;
+    /** Immutable borrowed snapshot for coordinated COW editing; write through patch APIs. */
+    getDocumentSnapshot(): Readonly<VisSceneDocument> | undefined;
     getDocument(): VisSceneDocument | undefined;
+    getManifest(): VisSceneManifest | undefined;
     private bindSceneInteractions;
     canBack(): boolean;
+    /** Release a cached/active page while retaining its document and saved material definitions. */
+    unloadScene(sceneId: string): boolean;
     private disposeInstances;
     dispose(): void;
 }
@@ -1344,6 +1705,8 @@ export declare interface SceneManagerBehaviorOptions {
     prepareScene?: (scene: Base_2) => void;
     /** 是否保留非活动场景实例；编辑器可关闭以限制 GPU/内存占用。 */
     cacheScenes?: boolean;
+    /** 自定义分包场景读取器；可从 IndexedDB 等非 HTTP 存储按需读取。 */
+    loadScene?: (entry: SceneManifestEntry) => Promise<SceneViewportDocument>;
 }
 
 export declare type SceneManagerInitOptions = SceneManagerOptions & SceneManagerBehaviorOptions;
@@ -1355,6 +1718,112 @@ export declare interface SceneManagerOptions extends Pick<BaseOptions, 'containe
     safeAreaInsets?: Partial<MapSafeAreaInsets>;
 }
 
+export declare interface SceneManifestEntry extends Omit<SceneViewportDocument, 'scene'> {
+    /** Relative to the manifest URL unless an absolute URL is supplied. */
+    source: string;
+    /** Uncompressed JSON bytes, used only for diagnostics and progress UI. */
+    bytes?: number;
+}
+
+/** 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 interface SceneObjectPatch {
+    uuid: string;
+    state: {
+        matrix?: number[];
+        matrixAutoUpdate?: boolean;
+        pivot?: number[] | null;
+        name?: string;
+        visible?: boolean;
+        layers?: number;
+    };
+    unset?: ('matrix' | 'matrixAutoUpdate' | 'pivot' | 'name' | 'visible' | 'layers')[];
+}
+
+declare interface SceneObjectPropertyPatch {
+    uuid: string;
+    state: Record<string, any>;
+    unset?: readonly string[];
+}
+
+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 type SceneStructureGraphKey = 'materialAliases' | 'shapes' | '_sharedOptionsPool' | '_texDataPool';
+
+/** Metadata is part of an owned structure transaction, never a scalar runtime patch. */
+export declare interface SceneStructureObjectPatch {
+    uuid: string;
+    state: SceneObjectPatch['state'] & Partial<Record<ScenePropertyField, any>> & {
+        matrixAutoUpdate?: boolean;
+        userData?: Record<string, any>;
+        geometry?: string | null;
+        material?: string | string[];
+        background?: number | string | null;
+        environment?: string | null;
+    };
+    unset?: (NonNullable<SceneObjectPatch['unset']>[number] | ScenePropertyField | 'matrixAutoUpdate' | 'userData' | 'geometry' | 'material' | 'background' | 'environment')[];
+}
+
+export declare interface SceneStructurePatch {
+    /** Final direct-child order. Omitting an old child detaches its subtree. */
+    parents: {
+        uuid: string;
+        children: string[];
+    }[];
+    /** New serialized subtree roots, with UUIDs absent from the current scene. */
+    additions?: Record<string, any>[];
+    /** Replace existing subtree roots, retaining their UUID and owning the supplied descendants. */
+    replacements?: Record<string, any>[];
+    objects?: SceneStructureObjectPatch[];
+    /** Viewport payload participates atomically with object/resource changes. */
+    viewport?: SceneStructureViewportPatch;
+    /** Authored scene aliases; these refer to assets, rather than runtime material UUIDs. */
+    aliases?: {
+        set?: NonNullable<SceneViewportDocument['materialAliases']>;
+        unset?: true;
+    };
+    /** Keep object removals and their authored interaction bindings in one transaction. */
+    interactions?: {
+        set?: SceneViewportDocument['interactions'];
+        unset?: true;
+    };
+    /** Small graph metadata and explicitly changed pools, never an entire scene graph. */
+    graph?: {
+        set?: Partial<Record<SceneStructureGraphKey, any>>;
+        unset?: SceneStructureGraphKey[];
+    };
+    resources?: Partial<Record<SceneStructureResource, {
+        upsert?: Record<string, any>[];
+        remove?: string[];
+        unset?: true;
+    }>>;
+    assets?: {
+        upsert?: MaterialAsset[];
+        remove?: string[];
+    };
+    prefabs?: {
+        upsert?: PrefabAsset[];
+        remove?: string[];
+    };
+}
+
+export declare type SceneStructureResource = 'geometries' | 'materials' | 'textures' | 'images' | 'skeletons' | 'animations';
+
+/** Scene edits and shared catalogs form one atomic project-document transaction. */
+export declare interface SceneStructureTransaction {
+    scenes: {
+        sceneId: string;
+        patch: Omit<SceneStructurePatch, 'assets' | 'prefabs'>;
+    }[];
+    assets?: SceneStructurePatch['assets'];
+    prefabs?: SceneStructurePatch['prefabs'];
+}
+
+export declare type SceneStructureViewportPatch = Partial<SceneViewportPatch>;
+
 export declare interface SceneSwitchInteraction {
     trigger: 'click' | 'clickOutside';
     objectId: string;
@@ -1389,23 +1858,34 @@ export declare interface SceneViewportDocument {
         options: Record<string, any>;
     };
     scene: Record<string, any>;
+    /** Scene-local SceneResources aliases. Locked means retained on export, not GPU residency. */
+    materialAliases?: Record<string, MaterialAlias>;
+}
+
+/** Camera motion and controls do not change authored scene topology/resources. */
+export declare interface SceneViewportPatch {
+    camera: {
+        uuid: string;
+        type: 'PerspectiveCamera' | 'OrthographicCamera';
+        state: Record<string, any>;
+        unset: string[];
+    };
+    cs?: SceneViewportDocument['cs'];
+    csa?: string;
+    controls: Record<string, any>;
 }
 
 export declare function selectSceneDocument(document: VisSceneDocument, sceneId: string): VisSceneDocument;
 
 declare type SerializedClip = ReturnType<(typeof THREE.AnimationClip)['toJSON']>;
 
-declare const sinusoidalInOut: ({ onUpdate, onComplete, backwards, }?: {
-    onUpdate?: ((v: number) => void) | undefined;
-    onComplete?: (() => void) | undefined;
-    backwards?: boolean | undefined;
-}) => {
+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<any>;
+    }) => Promise<void>;
     stop: () => void;
 };
 
@@ -1419,12 +1899,31 @@ declare class Sphere extends MeshObject {
 
 declare class SphereShadow extends MeshObject {
     objectType: string;
-    options: Required<Options_5>;
-    constructor(options: Options_5);
+    options: Required<Options_3>;
+    constructor(options: Options_3);
     create(): Promise<void>;
     rebuildFromScene(): void;
 }
 
+/**
+ * Creates deployable, independently fetchable scene JSON values. Resources are
+ * expanded per scene so loading the entry scene never requires a global pool.
+ */
+export declare function splitSceneDocument(document: VisSceneDocument, options?: {
+    sceneDirectory?: string;
+    extension?: '.json' | '.json.gz';
+    externalizeImages?: boolean;
+    omitEditorAssets?: boolean;
+}): SplitSceneDocumentBundle;
+
+export declare interface SplitSceneDocumentBundle {
+    manifest: VisSceneManifest;
+    /** Keys are the relative source paths written into the manifest. */
+    scenes: Record<string, SceneViewportDocument>;
+    /** Binary files to write alongside the manifest and scene files. */
+    assets?: Record<string, RuntimeImageAsset>;
+}
+
 declare class SpotLight extends SpotLightObject {
     constructor(...options: ConstructorParameters<typeof SpotLightObject>);
     update(delta: number, elapsed: number): void;
@@ -1437,20 +1936,7 @@ declare class Sprite extends SpriteObject {
     setDesiredPixelSize(size: number): void;
 }
 
-declare interface SwitchFixConfig {
-    /** 按参考缩放比缩放，并移到地图中心 */
-    s?: string[];
-    /** z 位置按缩放比缩放 */
-    z?: string[];
-    /** 移到地图顶面 */
-    t?: string[];
-    /** 移到地图底面 */
-    b?: string[];
-    /** 灯光按缩放比调整 */
-    l?: string[];
-    /** 删除对象 */
-    r?: string[];
-}
+export declare function stripMaterialAssetBinding<T extends Record<string, any>>(material: T): T;
 
 export declare interface SwitchSceneOptions {
     /** 返回历史时不再记录当前场景。 */
@@ -1465,8 +1951,8 @@ declare const timeOut: (ms: number) => Promise<any>;
 
 declare class Tube extends MeshObject {
     objectType: string;
-    options: Options_2;
-    constructor(options: Options_2);
+    options: Options_6;
+    constructor(options: Options_6);
     create(): void;
 }
 
@@ -1474,13 +1960,43 @@ export { TWEEN }
 
 export { Tween }
 
-export declare const VERSION = "0.32.7";
+declare interface TweenOptions {
+    owner?: Pick<Pencil, 'animations'>;
+    onUpdate?: (value: number) => void;
+    onComplete?: () => void;
+    onCancel?: () => void;
+    backwards?: boolean;
+}
+
+export declare function updateProjectMaterial<T extends VisSceneDocument>(document: T, assetId: string, patch: Partial<Pick<MaterialAsset, 'name' | 'material' | 'locked'>>): T;
+
+export declare const VERSION = "0.33.0";
 
 export declare interface VisSceneDocument extends SceneDocumentMarker {
     entrySceneId: string;
     scenes: SceneViewportDocument[];
     /** Schema 3: image/video/data payloads shared across scenes, never live textures. */
     _resourcePool?: any[];
+    /** Schema 4: serializable definitions shared by explicit asset identity. */
+    materialLibrary?: MaterialAsset[];
+    /** Reusable definitions. SDK-enabled assets are retained in deployment exports. */
+    prefabLibrary?: PrefabAsset[];
+    c?: Record<string, any>;
+    d?: Record<string, any>;
+    h?: Record<string, any>;
+    s?: string;
+}
+
+export declare interface VisSceneManifest {
+    format: typeof SCENE_MANIFEST_FORMAT;
+    schemaVersion: 1 | typeof SCENE_MANIFEST_SCHEMA_VERSION;
+    entrySceneId: string;
+    scenes: SceneManifestEntry[];
+    materialLibrary?: MaterialAsset[];
+    /** Externalized image files, relative to the manifest URL. */
+    imageAssets?: string[];
+    /** Reusable definitions. Only assets with sdkKey are available for SDK instantiation. */
+    prefabLibrary?: PrefabAsset[];
     c?: Record<string, any>;
     d?: Record<string, any>;
     h?: Record<string, any>;
@@ -1488,15 +2004,3 @@ export declare interface VisSceneDocument extends SceneDocumentMarker {
 }
 
 export { }
-
-
-
-declare module '@turf/turf' {
-  export function point(...args: any[]): any;
-  export function polygon(...args: any[]): any;
-  export function booleanPointInPolygon(...args: any[]): boolean;
-  export function center(...args: any[]): any;
-  export function centroid(...args: any[]): any;
-  export function bbox(...args: any[]): any;
-  export function union(...args: any[]): any;
-}