vis-core 0.33.16 → 0.33.18

package/dist/index.d.ts

@@ -22,22 +22,18 @@ import { GeoProjection } from 'd3-geo';
 import { Group } from 'three';
 import { HemisphereLight as HemisphereLight_2 } from 'three';
 import { Intersection } from 'three';
-import { IUniform } from 'three';
 import { Layers } from 'three/webgpu';
-import { Listener } from 'events';
 import { LoadingManager } from 'three';
 import { Material } from 'three';
 import { MaterialEventMap } from 'three';
 import { MaterialParameters } from 'three';
 import { Matrix4 } from 'three';
 import { Mesh } from 'three';
-import { Mesh as Mesh_2 } from 'three/webgpu';
 import { MultiPolygon } from 'geojson';
-import { Node as Node_2 } from 'three/webgpu';
 import { NodeMaterial } from 'three/webgpu';
 import { NormalBufferAttributes } from 'three';
-import { Object3D } from 'three';
-import { Object3D as Object3D_2 } from 'three/webgpu';
+import { Object3D } from 'three/webgpu';
+import { Object3D as Object3D_2 } from 'three';
 import { Object3DEventMap } from 'three';
 import { Object3DJSON } from 'three';
 import { OrthographicCamera } from 'three';
@@ -246,7 +242,7 @@ declare class Area extends GroupObject {
 }
 
 /** Validation is read-only and does not materialize or allocate runtime resources. */
-export declare function assertProjectMaterials(document: Pick<VisSceneDocument, 'schemaVersion' | 'scenes' | 'materialLibrary' | 'prefabLibrary' | '_resourcePool'>): void;
+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>;
@@ -350,6 +346,7 @@ declare class Base_3 extends Camera {
         applyDisabledMouseButtons: boolean;
         cacheCityGeometry: boolean;
         includePrefabPreviews: boolean;
+        strictBundleAssets: boolean;
     };
     leftTruck: boolean;
     options: BaseOptions;
@@ -387,6 +384,13 @@ declare class Base_3 extends Camera {
     private resolveRendererDepthBufferOptions;
     private showDetectRes;
     setOptions(options: Record<string, any>): void;
+    private assetResolver?;
+    /** Internal: Keep authoring transactions and their rollback on the same resource catalog. */
+    setRuntimeAssets(catalog?: RuntimeAssetCatalog): void;
+    /** Resolve static dependencies within the currently loaded project. */
+    resolveAssetUrl: (url: string) => string;
+    /** Internal: Map overrides this before any authored geometry is hydrated. */
+    protected authorizeSceneOptions(_options: Record<string, any>): Promise<void>;
     /** Internal: Scene documents are loaded through SceneManager. */
     fromJSON(jsonOrUrl: Record<string, any> | string, hooksE?: Record<string, any>, restoreOptions?: RestoreBaseObjectOptions): Promise<void>;
     private runtimeInitialization?;
@@ -475,7 +479,7 @@ declare class Base_3 extends Camera {
     dispose(): void;
 }
 
-declare class BaseObject<T extends Object3D = Object3D> extends UseMaterial {
+declare class BaseObject<T extends Object3D_2 = Object3D_2> extends UseMaterial {
     /** One persisted identity, owned by the underlying Three.js object. */
     get key(): string;
     set key(value: string);
@@ -502,15 +506,15 @@ declare class BaseObject<T extends Object3D = Object3D> extends UseMaterial {
         ownership?: ResourceOwnership;
     });
     get parent(): BaseObject | null;
-    get children(): BaseObject<Object3D< Object3DEventMap>>[];
+    get children(): BaseObject<Object3D_2< Object3DEventMap>>[];
     get position(): Vector3;
     get rotation(): Euler;
     get scale(): Vector3;
     lookAt(vector: Vector3): void;
     lookAt(x: number, y: number, z: number): void;
     draw<C extends new (...args: any[]) => BaseObject>(ClassRef: C, ...args: ConstructorParameters<C>): Promise<InstanceType<C>>;
-    add(...objects: (Object3D | BaseObject)[]): void;
-    remove(...object: Object3D[]): void;
+    add(...objects: (Object3D_2 | BaseObject)[]): void;
+    remove(...object: Object3D_2[]): void;
     get visible(): boolean;
     /**
      * 检查是否实际可见（自己和所有祖先都 visible）
@@ -660,10 +664,6 @@ declare class Building extends GroupObject {
     constructor(options: Options_19);
     create(): Promise<void>;
     rebuildFromScene(): void;
-    private gradientMaterials;
-    worldPositionZ: THREE.UniformNode<"float", number>;
-    sideGradient(color?: string, maxGradientHeight?: number): void;
-    update(): void;
 }
 
 declare class CacheManager {
@@ -1811,7 +1811,6 @@ declare class City {
         jsonUrl?: string;
         meters?: number;
         grey?: boolean;
-        sideGradient?: boolean;
         hasSide?: boolean;
     }): Promise<Building | undefined>;
     drawArea(options?: {
@@ -1838,12 +1837,10 @@ declare interface CityOptions {
     plane?: boolean;
     grey?: boolean;
     showBuilding?: boolean;
-    buildingSideGradient?: boolean;
     buildingHasSide?: boolean;
     showRoad?: boolean;
     showGrassland?: boolean;
     showRiver?: boolean;
-    setWaterMaterial?: boolean;
     dataSources?: {
         building?: string;
         road?: string;
@@ -1857,13 +1854,12 @@ declare class CityPlane extends MeshObject {
     options: Options_23;
     constructor(options: Options_23);
     plane: _THREE.BufferGeometry;
-    water?: Water;
     create(): Promise<void>;
     rebuildFromScene(): void;
-    addWater(normalMaps: [_THREE.Texture, _THREE.Texture]): void;
-    dispose(): void;
 }
 
+export declare function cloneSceneDocument<T extends VisSceneDocument>(document: T): T;
+
 /** Duplicate scene-owned definitions, while retaining references to project assets. */
 export declare function cloneSceneMaterials(document: VisSceneDocument, sourceId: string, newSceneId: string): {
     scene: SceneViewportDocument;
@@ -2027,7 +2023,7 @@ declare class Composer {
             };
         };
     };
-    bloomSelection: Set<BaseObject< Object3D<Object3DEventMap>>>;
+    bloomSelection: Set<BaseObject< Object3D_2<Object3DEventMap>>>;
     bloomLayer: Layers;
     active: boolean;
     options: Options_3;
@@ -2178,6 +2174,7 @@ export declare interface CreateMaterialAssetOptions {
     material: Record<string, any>;
     scope?: MaterialScope;
     locked?: boolean;
+    alwaysExport?: boolean;
 }
 
 /**
@@ -2465,8 +2462,8 @@ export declare type EmptySceneDefinition = Omit<SceneViewportDocument, 'scene'>;
 declare class Event_2 {
     event: EventEmitter;
     private eventHandlers;
-    on: (type: string | number, listener: Listener) => EventEmitter;
-    emit: (type: string | number, ...args: any[]) => boolean;
+    on: EventEmitter['on'];
+    emit: EventEmitter['emit'];
     addListener(node: HTMLElement, event: string, handler: (e: MouseEvent) => void, capture?: boolean): void;
     removeListener(targetNode: HTMLElement | '', event: string): void;
     removeAllListeners(): void;
@@ -2481,21 +2478,21 @@ declare class EventDispatcher {
      * @param listener handler function
      * @category Methods
      */
-    addEventListener(type: string, listener: Listener_2): void;
+    addEventListener(type: string, listener: Listener): void;
     /**
      * Presence of the specified event listener.
      * @param type event name
      * @param listener handler function
      * @category Methods
      */
-    hasEventListener(type: string, listener: Listener_2): boolean;
+    hasEventListener(type: string, listener: Listener): boolean;
     /**
      * Removes the specified event listener
      * @param type event name
      * @param listener handler function
      * @category Methods
      */
-    removeEventListener(type: string, listener: Listener_2): void;
+    removeEventListener(type: string, listener: Listener): void;
     /**
      * Removes all event listeners
      * @param type event name
@@ -2510,12 +2507,6 @@ declare class EventDispatcher {
     dispatchEvent(event: DispatcherEvent): void;
 }
 
-/** Internal: Consume an exclusively owned import copy; pooled slots still get independent payloads. */
-export declare function expandOwnedSceneDocumentResources<T extends VisSceneDocument>(expanded: T): T;
-
-/** Expand at the editor import boundary so independently edited scenes own their data. */
-export declare function expandSceneDocumentResources<T extends VisSceneDocument>(document: T): T;
-
 /** Expand renderer pools, including snapshots retained as prefab baselines. */
 export declare function expandStructureSnapshot<T extends Record<string, any>>(input: T): T;
 
@@ -2738,13 +2729,13 @@ declare const KNOWN_ASSET_TYPES: {
 declare type Lead = Lead_2;
 
 declare class Lead_2 extends Pick_2 {
-    objMap: Map<Object3D< Object3DEventMap>, BaseObject<Object3D< Object3DEventMap>>>;
-    objects: Map<string, BaseObject<Object3D< Object3DEventMap>>>;
+    objMap: Map<Object3D_2< Object3DEventMap>, BaseObject<Object3D_2< Object3DEventMap>>>;
+    objects: Map<string, BaseObject<Object3D_2< Object3DEventMap>>>;
     /** Compatibility name for the same UUID index, never a second identity map. */
-    get objectsByUuid(): Map<string, BaseObject<Object3D< Object3DEventMap>>>;
+    get objectsByUuid(): Map<string, BaseObject<Object3D_2< Object3DEventMap>>>;
     private registeredUuids;
     private disposing;
-    objectsPm: Map<BaseObject<Object3D< Object3DEventMap>>, Promise<void>>;
+    objectsPm: Map<BaseObject<Object3D_2< Object3DEventMap>>, Promise<void>>;
     scene: BaseObject;
     sceneResources: SceneResources_2;
     get objectsPromise(): MapIterator<Promise<void>>;
@@ -2757,7 +2748,7 @@ declare class Lead_2 extends Pick_2 {
      * 包含：依赖注入、Key 生成、Map 存储。
      * 已注册对象可再次调用，以刷新替换骨骼后的资源引用。
      */
-    register(baseObject: BaseObject): BaseObject<Object3D< Object3DEventMap>>;
+    register(baseObject: BaseObject): BaseObject<Object3D_2< Object3DEventMap>>;
     /** Update identity and its only index atomically; never rename children. */
     setObjectUuid(baseObject: BaseObject, uuid: string): void;
     /**
@@ -2780,7 +2771,7 @@ declare class Lead_2 extends Pick_2 {
      * 将原生 Object3D 包装为 BaseObject (Wrapper Pattern)
      * 如果已存在包装器，则返回现有实例
      */
-    wrap(object3d: Object3D): BaseObject;
+    wrap(object3d: Object3D_2): BaseObject;
     private wrapObject;
     /**
      * 统一的添加入口
@@ -2804,7 +2795,7 @@ declare class Lead_2 extends Pick_2 {
     eraseAll(): void;
     private _serializer;
     exportBaseObject(...args: Parameters<SceneSerializer['exportBaseObject']>): SceneSnapshot;
-    restoreBaseObject(...args: Parameters<SceneSerializer['restoreBaseObject']>): Promise<BaseObject<Object3D< Object3DEventMap>>>;
+    restoreBaseObject(...args: Parameters<SceneSerializer['restoreBaseObject']>): Promise<BaseObject<Object3D_2< Object3DEventMap>>>;
     dispose(): void;
 }
 
@@ -2886,7 +2877,7 @@ declare interface LineObjectOptions {
     onCacheMiss?: (options: Partial<LineObjectOptions>) => Partial<LineObjectOptions> | Promise<Partial<LineObjectOptions>>;
 }
 
-declare type Listener_2 = (event?: DispatcherEvent) => void;
+declare type Listener = (event?: DispatcherEvent) => void;
 
 declare class Loader {
     loadingManager: LoadingManager;
@@ -2894,7 +2885,7 @@ declare class Loader {
     loaderConfigs: Map<string, LoaderConfig>;
     loadObj: Asset[];
     delLoadArr: string[];
-    assets: Map<string, Texture | Object3D | any>;
+    assets: Map<string, Texture | Object3D_2 | any>;
     event: EventEmitter;
     options: Options_9;
     scene: Scene_2;
@@ -2910,7 +2901,7 @@ declare class Loader {
     getAsset(src: `${string}.${TypeImage}`): Texture;
     getAsset(src: `${string}.${TypeMedia}`): VideoTexture;
     getAsset(src: `${string}.${TypeGLTF}`): {
-        scene: Object3D;
+        scene: Object3D_2;
     };
     getAsset(src: `${string}.${TypeLottie}`): Texture;
     getAsset(src: `${string}.${TypeJSON}`): any;
@@ -2921,13 +2912,13 @@ declare class Loader {
     private loaderKey;
     getLoader(type: string, options?: AssetOptions): any;
     add(src: string | string[], options?: AssetOptions): void;
-    getSrcByAsset(asset: Texture | Object3D | any, assets?: Map<string, any>): string | undefined;
+    getSrcByAsset(asset: Texture | Object3D_2 | any, assets?: Map<string, any>): string | undefined;
     get textureAssets(): Map<string, Texture<unknown, TextureEventMap>>;
     loadAll(): Promise<Texture<unknown, TextureEventMap>[]>;
     load(src: `${string}.${TypeImage}`, options?: AssetOptions): Promise<Texture>;
     load(src: `${string}.${TypeMedia}`, options?: AssetOptions): Promise<VideoTexture>;
     load(src: `${string}.${TypeGLTF}`, options?: AssetOptions): Promise<{
-        scene: Object3D;
+        scene: Object3D_2;
     }>;
     load(src: `${string}.${TypeLottie}`, options?: AssetOptions): Promise<Texture>;
     load(src: `${string}.${TypeJSON}`, options?: AssetOptions): Promise<any>;
@@ -3009,6 +3000,11 @@ declare class Map_4 extends Base_3 {
     private regionCameraFitReference?;
     private authoredCameraPose?;
     private cameraAngleOverrides?;
+    private bundledMapSwitchKey?;
+    private navigationAssets?;
+    setRuntimeAssets(catalog?: RuntimeAssetCatalog): void;
+    private requireMapAuthorization;
+    protected authorizeSceneOptions(options: Record<string, any>): Promise<void>;
     setOptions(options: MapOptions): void;
     private _getProjectionCenter;
     private _getProjectionRotate;
@@ -3171,7 +3167,7 @@ declare class Map_4 extends Base_3 {
      */
     private applyRegionObjectState;
     /** Internal: 仅由 SceneManager 在隔离页面调用，成功后才对外提交。 */
-    rebuildRegion(targetAdcode: number, switchKey?: string, force?: boolean): Promise<void>;
+    rebuildRegion(targetAdcode: number, force?: boolean): Promise<void>;
     private rebuildRegionGeometry;
     /** 候选区域提交后的相机过渡，不参与场景序列化。 */
     playRegionEnterTransition({ duration, sourceCamera, preparedCamera, onPrepared, }: MapRegionEnterTransitionOptions): Promise<void>;
@@ -3244,16 +3240,19 @@ declare interface MapCityOptions extends MapOptions {
     cacheCity?: boolean;
     nearbyCities?: boolean | 'full';
     showBuilding?: boolean;
-    buildingSideGradient?: boolean;
     showRoad?: boolean;
     showGrassland?: boolean;
     showRiver?: boolean;
-    setWaterMaterial?: boolean;
     showCityOnMapInnerLine?: boolean;
     bloom?: boolean;
     citySSAO?: boolean;
 }
 
+export declare interface MapExportScope {
+    rootAdcode: number;
+    maxLevel: 'province' | 'city' | 'district';
+}
+
 declare interface MapLabelStyle {
     color?: string;
     fontSize?: number;
@@ -3261,6 +3260,14 @@ declare interface MapLabelStyle {
     fontWeight?: string;
 }
 
+export declare type MapNavigation = {
+    mode: 'static';
+} | {
+    mode: 'dynamic';
+    scope: MapExportScope;
+    templates: Partial<Record<MapExportScope['maxLevel'], string>>;
+};
+
 declare interface MapOptions extends BaseOptions {
     adcode: number;
     mapData?: MapBoundaryData;
@@ -3309,7 +3316,7 @@ declare interface MapOptions extends BaseOptions {
 export declare interface MapPlacementOptions {
     mapCRS: string;
     /** Explicit ground meshes only. Exclude the model, roofs, helpers and hidden surfaces. */
-    surfaces: Object3D[];
+    surfaces: Object3D_2[];
     /** Model's physical height; optional if already in map units. Z is model/map up. */
     heightMeters?: number;
     /** Clearance in map units along map Z. */
@@ -3404,6 +3411,8 @@ export declare interface MaterialAsset {
     /** Complete Material.toJSON(); schema 6 exports may pool image/texture payloads. */
     material: Record<string, any>;
     locked?: boolean;
+    /** Keep this definition and its dependencies in exports for later business use. Does not prevent editing or deletion. */
+    alwaysExport?: boolean;
 }
 
 declare type MaterialBindings = Record<string, Record<string, string>>;
@@ -3490,6 +3499,22 @@ declare type MatrixState = {
     matrixAutoUpdate?: boolean;
 };
 
+/** File metadata belongs to the manifest, never to a Three image URL. */
+declare interface MediaAssetInfo {
+    sha256: string;
+    bytes: number;
+    mimeType: string;
+    kind: 'image' | 'hdr' | 'tga' | 'video' | 'pixels';
+    pixels?: {
+        type: string;
+        width: number;
+        height: number;
+        depth?: number;
+    };
+}
+
+declare type MediaAssetManifest = Record<string, MediaAssetInfo>;
+
 /** 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[];
@@ -3969,7 +3994,6 @@ declare interface Options_19 {
     material?: THREE.Material | THREE.Material[];
     meters?: number;
     hasSide?: boolean;
-    sideGradient?: boolean;
     grey?: boolean;
     materialOptions?: Record<string, THREE.Material>;
 }
@@ -4088,11 +4112,6 @@ declare class OrigonPages<T = any> {
     dispose(): void;
 }
 
-/** Pack an export copy only; preserve the editor's independent scene snapshots. */
-export declare function packSceneDocumentResources<T extends VisSceneDocument>(document: T, options?: {
-    encodePixels?: boolean;
-}): T;
-
 /** Page identities are independent of Three's 32 rendering layers. */
 declare class Pages {
     private readonly indices;
@@ -4326,14 +4345,14 @@ declare class Pencil {
     } | undefined;
     setViewPadding(top?: number, right?: number, bottom?: number, left?: number): void;
     /** Optional host filters; these are never serialized into a scene. */
-    renderObjectFilter?: (object: Object3D_2) => boolean;
-    pickObjectFilter?: (object: Object3D_2) => boolean;
+    renderObjectFilter?: (object: Object3D) => boolean;
+    pickObjectFilter?: (object: Object3D) => boolean;
     /** Certify host raycasts that only hit this object and never stop child traversal. */
-    pickRaycastCanBeSkipped?: (object: Object3D_2) => boolean;
-    pick(event: MouseEvent, objects?: Object3D_2[], recursive?: boolean): {
-        object: Object3D_2< Object3DEventMap>;
+    pickRaycastCanBeSkipped?: (object: Object3D) => boolean;
+    pick(event: MouseEvent, objects?: Object3D[], recursive?: boolean): {
+        object: Object3D< Object3DEventMap>;
         index: number | undefined;
-        intersects: Intersection<Object3D_2< Object3DEventMap>>[];
+        intersects: Intersection<Object3D< Object3DEventMap>>[];
     } | undefined;
     render(): void;
     /** Capture only authored content without advancing animation or touching editor tools. */
@@ -4438,7 +4457,7 @@ declare type PickFunctionsItem = {
 };
 
 export declare interface PlanarMap {
-    object3d: Object3D;
+    object3d: Object3D_2;
     options: {
         projection?: ProjectionOptions;
         conic?: boolean;
@@ -4524,7 +4543,7 @@ declare class PlaneShadow extends MeshObject {
 /** Read-only plan. Aligns the model bounds center in XY and lowest vertex to actual ground.
  * Apply the returned local matrix to a detached candidate, serialize, then import/replace once.
  */
-export declare function planPlacement(model: Object3D, map: PlanarMap, anchor: MapAnchor, options: MapPlacementOptions): {
+export declare function planPlacement(model: Object3D_2, map: PlanarMap, anchor: MapAnchor, options: MapPlacementOptions): {
     localMatrix: Matrix4;
     worldMatrix: Matrix4;
     groundPoint: Vector3Tuple;
@@ -4673,6 +4692,7 @@ export declare function remapImportedMaterials(before: VisSceneDocument, incomin
 export declare function remapOwnedSnapshotIdentity(snapshot: any, rootUuid?: string, sharedResourceIds?: ReadonlyMap<string, string>): any;
 
 export declare interface RemappedSceneDocument {
+    runtimeAssets?: RuntimeAssetCatalog;
     entrySceneId: string;
     scenes: SceneViewportDocument[];
     idMap: Map<string, string>;
@@ -4724,6 +4744,7 @@ declare class RendererController {
     private disposed;
     private hasRenderableSize;
     private readonly pointSprites;
+    readonly surfaceEffects: SurfaceEffects;
     options: Options_2;
     private displayScaleObserver?;
     private releaseRenderPipelines?;
@@ -4917,6 +4938,8 @@ declare interface RestoreBaseObjectOptions {
     strictResourceReuse?: boolean;
 }
 
+export declare function restoreRuntimeImageFiles(value: any, sources: MediaAssetManifest | undefined, files: Record<string, RuntimeImageAsset>): void;
+
 /**
  * Live resources whose serialized definitions the caller has already verified.
  * Reuse is explicit: equal UUIDs alone do not establish equal definitions.
@@ -4943,23 +4966,50 @@ 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 {
+/** Static dependencies owned by a project. Source URLs are lookup keys, never fallbacks. */
+export declare interface RuntimeAsset {
+    id: string;
+    path: string;
+    sources: string[];
+    mimeType: string;
+    encoding: 'identity' | 'gzip';
+    bytes: number;
+    sha256: string;
+    /** Owned file bytes; legacy encoded catalogs must be imported by the platform. */
+    data?: ArrayBuffer;
+}
+
+export declare interface RuntimeAssetCatalog {
+    version: 1;
+    entries: RuntimeAsset[];
+    scope?: MapExportScope;
+    /** Explicit delivery contract; omitted only in older packages. */
+    mapNavigation?: MapNavigation;
+    /** Enumerated interaction targets, including regions never opened in the editor. */
+    regions?: Record<string, number[]>;
+    declaredSources?: string[];
+    /** Explicitly deployed shared files; these sources are not stored inside the ZIP. */
+    externalSources?: string[];
+    mapDataMode?: 'bundled' | 'external';
+    /** Signed authorization restricted to the exported map interaction targets. */
+    mapSwitchKey?: string;
+    projectId?: string;
+    /** Runtime-only base for an unpacked deployment. ZIP imports contain data instead. */
+    baseUrl?: string;
+}
+
+export declare interface RuntimeImageAsset {
     data: Uint8Array;
     mimeType: string;
 }
 
 export declare const SCENE_DOCUMENT_FORMAT: "vis-scene";
 
-/** Schema 6 extends the document pool to authored material dependencies. */
-export declare const SCENE_DOCUMENT_RESOURCE_POOL_SCHEMA_VERSION: 6;
-
 export declare const SCENE_DOCUMENT_SCHEMA_VERSION: 6;
 
 export declare const SCENE_MANIFEST_FORMAT: "vis-scene-manifest";
 
-export declare const SCENE_MANIFEST_SCHEMA_VERSION: 3;
+export declare const SCENE_MANIFEST_SCHEMA_VERSION: 5;
 
 export declare interface SceneBackInteraction {
     trigger: 'click' | 'clickOutside';
@@ -4970,6 +5020,8 @@ export declare interface SceneBackInteraction {
     };
 }
 
+export declare type SceneBundleBinary = Blob | ArrayBuffer | Uint8Array;
+
 declare interface SceneCaptureOptions {
     /** Physical output pixels. Defaults to the active content viewport. */
     width?: number;
@@ -4982,6 +5034,7 @@ declare interface SceneCaptureOptions {
 
 /** Scene membership/options delta. Existing authored graphs must use structure patches. */
 export declare interface SceneCollectionTransaction {
+    runtimeAssets?: VisSceneDocument['runtimeAssets'];
     scenes: readonly SceneViewportDocument[];
     entrySceneId: string;
     materialLibrary?: readonly MaterialAsset[];
@@ -5060,7 +5113,6 @@ export declare class SceneManager extends Event_2 {
     private identityTrackedScenes;
     private prefabOperations;
     private transactionCacheDepth;
-    private materialLibraryResources?;
     private invalidatePendingOperations;
     private assertGeneration;
     private debugInteraction;
@@ -5087,6 +5139,8 @@ export declare class SceneManager extends Event_2 {
      */
     prewarmRuntime(): Promise<void>;
     private prepareScene;
+    private resolveMapSwitchKey;
+    private authorizeMapDefinition;
     /** Publish one identity remap without exporting runtimes or copying other pages/resources. */
     remapCommittedIdentity(sceneId: string, previous: string, next: string, objectIdentity: boolean): boolean;
     /**
@@ -5100,7 +5154,7 @@ export declare class SceneManager extends Event_2 {
     private playTransition;
     /** 更新可编辑文档，并释放已经不属于文档的非活动场景实例。 */
     setDocument(document: VisSceneDocument): void;
-    /** Standalone material consumers cannot retain document-level pool references. */
+    /** Standalone material consumers own independent definitions. */
     private resolvedMaterialLibrary;
     /** Keep scene payloads lazy, while independent material APIs own a resolved catalog. */
     private ownDocument;
@@ -5144,12 +5198,12 @@ export declare class SceneManager extends Event_2 {
      * 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;
+    preparedSceneStructureMatches(prepared: PreparedSceneStructure, target: Pick<VisSceneDocument, 'scenes' | 'materialLibrary' | 'prefabLibrary' | 'runtimeAssets'>): 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>, options?: {
+    load(documentOrUrl: SceneSource, hooks?: Record<string, any>, options?: {
         /** Transfer a detached document to the manager; the caller must not mutate it afterwards. */
         consumeInput?: boolean;
         /** Restore a saved active scene without changing the project's entry scene. */
@@ -5164,14 +5218,14 @@ export declare class SceneManager extends Event_2 {
      * 以指定地图模板和行政区直接启动，不先加载文档配置的入口场景。
      * 适用于宿主按路由或业务参数决定初始省、市、区的场景。
      */
-    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>;
+    loadMapRegion(documentOrUrl: SceneSource, sceneId: string, adcode: number, hooks?: Record<string, any>): Promise<Map_4>;
+    loadMapRegion(documentOrUrl: SceneSource, adcode: number, resolveScene: MapRegionSceneResolver, hooks?: Record<string, any>): Promise<Map_4>;
     /**
      * Follow a host's latest region request, loading a new source only when needed.
      * Superseded requests reject with AbortError; only the latest candidate commits.
      * Existing click/back navigation finishes before the requested region starts.
      */
-    requestMapRegion(source: VisSceneDocument | VisSceneManifest | string, adcode: number, resolveScene: MapRegionSceneResolver, options?: MapRegionOptions): Promise<Map_4>;
+    requestMapRegion(source: SceneSource, adcode: number, resolveScene: MapRegionSceneResolver, options?: MapRegionOptions): Promise<Map_4>;
     private loadMapRegionRequest;
     private loadDocument;
     private getSceneMetadata;
@@ -5251,8 +5305,8 @@ export declare interface SceneManagerBehaviorOptions {
 export declare type SceneManagerInitOptions = SceneManagerOptions & SceneManagerBehaviorOptions;
 
 export declare interface SceneManagerOptions extends Pick<BaseOptions, 'container' | 'controlsContainer' | 'css2DContainer' | 'assetsPrefix' | 'pencilConfig' | 'logarithmicDepthBuffer' | 'tier' | 'observeParentScale'> {
-    /** 动态行政区数据访问使用的授权 key。 */
-    mapSwitchKey?: string;
+    /** Editor authoring may add dependencies after opening a bundle. Runtime defaults to strict. */
+    strictBundleAssets?: boolean;
     /** 宿主大屏图表等覆盖区域形成的运行时地图安全区。 */
     safeAreaInsets?: Partial<MapSafeAreaInsets>;
 }
@@ -5321,7 +5375,7 @@ declare class SceneResources_2 {
     private objectLeases;
     private sceneLeases;
     private geometryLeases;
-    readonly emptyGeometryObjects: Set<Object3D< Object3DEventMap>>;
+    readonly emptyGeometryObjects: Set<Object3D_2< Object3DEventMap>>;
     private emptyGeometryOwners;
     private nativeObjectLeases;
     private proxiedObjects;
@@ -5372,7 +5426,7 @@ declare class SceneResources_2 {
     private updateBaseObjectMap;
     rmBaseObjectMap(object: BaseObject, targetMaterial?: Material | Material[]): void;
     private releaseBaseObjectMap;
-    getBaseObjectMap(material: Material): Set<BaseObject<Object3D< Object3DEventMap>>>;
+    getBaseObjectMap(material: Material): Set<BaseObject<Object3D_2< Object3DEventMap>>>;
     setLocked(key: string, locked?: boolean): boolean;
     lock(key: string): boolean;
     unlock(key: string): boolean;
@@ -5397,7 +5451,7 @@ declare class SceneSerializer {
     constructor(lead: Lead_2);
     exportCompressBaseObject(root: BaseObject, options?: ExportBaseObjectOptions): Promise<ArrayBuffer>;
     exportBaseObject(root: BaseObject, options?: ExportBaseObjectOptions): SceneSnapshot;
-    restoreBaseObject(target: BaseObject, data: string | ArrayBuffer | Object3DJSON, registry?: Record<string, new (...args: any[]) => any>, roomEnvMap?: any, createIfNeeded?: boolean, signal?: AbortSignal, options?: RestoreBaseObjectOptions): Promise<BaseObject<Object3D< Object3DEventMap>>>;
+    restoreBaseObject(target: BaseObject, data: string | ArrayBuffer | Object3DJSON, registry?: Record<string, new (...args: any[]) => any>, roomEnvMap?: any, createIfNeeded?: boolean, signal?: AbortSignal, options?: RestoreBaseObjectOptions): Promise<BaseObject<Object3D_2< Object3DEventMap>>>;
     private _graftObject3d;
 }
 
@@ -5405,7 +5459,10 @@ declare type SceneSnapshot = Object3DJSON & {
     materialAliases?: Record<string, SerializedMaterialAlias>;
 };
 
-export declare type SceneStructureGraphKey = 'materialAliases' | 'shapes' | '_sharedOptionsPool' | '_texDataPool';
+/** File transport accepts ZIP bundles; in-memory documents remain available for editor integration. */
+export declare type SceneSource = VisSceneDocument | VisSceneManifest | string | SceneBundleBinary;
+
+export declare type SceneStructureGraphKey = 'materialAliases' | 'shapes' | '_sharedOptionsPool';
 
 /** Metadata is part of an owned structure transaction, never a scalar runtime patch. */
 export declare interface SceneStructureObjectPatch {
@@ -5597,14 +5654,11 @@ declare class SphereShadow extends MeshObject {
     rebuildFromScene(): void;
 }
 
-/**
- * Creates independently fetchable scene JSON values. Manifest 3 owns shared
- * payloads so scene and catalog copies do not multiply the deployed bytes.
- */
+/** Create independently fetchable scenes; manifest 5 owns file metadata while
+ * each native Three image URL points to one deduplicated media file. */
 export declare function splitSceneDocument(document: VisSceneDocument, options?: {
     sceneDirectory?: string;
     extension?: '.json' | '.json.gz';
-    externalizeImages?: boolean;
     omitEditorAssets?: boolean;
 }): SplitSceneDocumentBundle;
 
@@ -5760,6 +5814,38 @@ declare type StructureResourceKind = typeof resourceKinds[number];
 
 export declare type StructureResources = Record<ResourceKind, Record<string, any>[]>;
 
+/** One compositor for surface effects. The authored scene keeps native materials
+ * and JSON parameters; only GPU draws receive gradient → scan → reflection views. */
+declare class SurfaceEffects {
+    private readonly index;
+    private readonly time;
+    private readonly materials;
+    private readonly reflections;
+    private frame;
+    private rendering;
+    private disposed;
+    private readonly clocks;
+    readonly stats: {
+        activePlanes: number;
+        candidates: number;
+        resolution: number;
+        animations: number;
+        gradients: number;
+        waters: number;
+        animationTime: number;
+        surfaces: string[];
+    };
+    getTime(scene: Scene): number;
+    /** Invalidate after changing metadata or material bindings; native graph edits
+     * are observed automatically. No scene traversal is needed on ordinary frames. */
+    invalidate(scene?: Object3D): void;
+    private bypass;
+    private material;
+    render<T>(renderer: WebGPURenderer, scene: Scene, camera: Camera_2, draw: () => T): T;
+    private clear;
+    dispose(): void;
+}
+
 export declare interface SwitchSceneOptions {
     /** 返回历史时不再记录当前场景。 */
     recordHistory?: boolean;
@@ -5797,7 +5883,7 @@ declare class TransformControlsController {
     private viewScene?;
     private viewport?;
     get detach(): () => TransformControls;
-    get attach(): (object: Object3D_2) => TransformControls;
+    get attach(): (object: Object3D) => TransformControls;
     event: EventEmitter;
     constructor(options: Options_7);
     setViewport(viewport: Viewport): void;
@@ -5857,7 +5943,7 @@ declare class UseMaterial extends PointerEvent_2 {
     lead: Lead_2;
     sceneResources: SceneResources_2;
     userData: Record<string, any>;
-    object3d: Object3D;
+    object3d: Object3D_2;
     cloneMaterial(): Material< MaterialEventMap> | Material< MaterialEventMap>[] | undefined;
     useSceneMaterialById(id: string, slot?: number): void;
     useSceneMaterialByName(name: string, slot?: number): void;
@@ -5866,7 +5952,7 @@ declare class UseMaterial extends PointerEvent_2 {
 
 declare type ValuesOf<T extends readonly any[]> = T[number];
 
-export declare const VERSION = "0.33.16";
+export declare const VERSION = "0.33.18";
 
 declare interface Viewport {
     left: number;
@@ -5881,10 +5967,9 @@ declare interface Viewport {
 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 {
+    runtimeAssets?: RuntimeAssetCatalog;
     entrySceneId: string;
     scenes: SceneViewportDocument[];
-    /** Schema 3: scene payloads; schema 6 also shares material-library payloads. */
-    _resourcePool?: any[];
     /** Schema 4: serializable definitions shared by explicit asset identity. */
     materialLibrary?: MaterialAsset[];
     /** Reusable definitions. SDK-enabled assets are retained in deployment exports. */
@@ -5897,14 +5982,14 @@ export declare interface VisSceneDocument extends SceneDocumentMarker {
 
 export declare interface VisSceneManifest {
     format: typeof SCENE_MANIFEST_FORMAT;
-    schemaVersion: 1 | 2 | typeof SCENE_MANIFEST_SCHEMA_VERSION;
+    schemaVersion: typeof SCENE_MANIFEST_SCHEMA_VERSION;
+    /** Manifest 4: complete static dependencies, shared by every scene. */
+    runtimeAssets?: RuntimeAssetCatalog;
     entrySceneId: string;
     scenes: SceneManifestEntry[];
     materialLibrary?: MaterialAsset[];
-    /** Manifest 3: payloads referenced by the material catalog and scene files. */
-    _resourcePool?: any[];
-    /** Externalized image files, relative to the manifest URL. */
-    imageAssets?: string[];
+    /** Manifest 5: media metadata keyed by native image URL. */
+    assets?: MediaAssetManifest;
     /** Reusable definitions. Only assets with sdkKey are available for SDK instantiation. */
     prefabLibrary?: PrefabAsset[];
     c?: Record<string, any>;
@@ -5913,35 +5998,6 @@ export declare interface VisSceneManifest {
     s?: string;
 }
 
-declare class Water extends Mesh_2<BufferGeometry, NodeMaterial & { uniforms: Record<string, IUniform> }> {
-    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_2;
-    flowSpeed?: number;
-    reflectivity?: number;
-    scale?: number;
-    shader?: WaterShader;
-    flowMap?: Texture;
-    normalMap0: Texture;
-    normalMap1: Texture;
-}
-
-declare interface WaterShader {
-    name: string;
-    uniforms: Record<string, IUniform>;
-    colorNode?: Node_2 | ((uniforms: Record<string, IUniform>, defaultColor: Node_2) => Node_2);
-}
-
 declare type WidthCallback = (p: number) => number;
 
 export { }