vis-core 0.33.15 → 0.33.17

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';
@@ -50,8 +46,8 @@ import { Raycaster } from 'three/webgpu';
 import { RectAreaLight as RectAreaLight_2 } from 'three';
 import { RenderPipeline } from 'three/webgpu';
 import { RenderTarget } from 'three/webgpu';
-import { Scene } from 'three';
-import { Scene as Scene_2 } from 'three/webgpu';
+import { Scene } from 'three/webgpu';
+import { Scene as Scene_2 } from 'three';
 import { ShaderMaterial } from 'three';
 import { ShaderMaterialJSON } from 'three';
 import { SpotLight as SpotLight_2 } from 'three';
@@ -343,11 +339,14 @@ declare type Base_2 = Base_3;
 
 declare class Base_3 extends Camera {
     static VisName: string;
+    /** Internal: Share final renderer configuration with SceneManager prewarming. */
+    static prewarmRenderer(options: BaseOptions): ReturnType<typeof Pencil.prewarmRenderer>;
     runtimePolicy: {
         observeParentScale: boolean;
         applyDisabledMouseButtons: boolean;
         cacheCityGeometry: boolean;
         includePrefabPreviews: boolean;
+        strictBundleAssets: boolean;
     };
     leftTruck: boolean;
     options: BaseOptions;
@@ -358,8 +357,8 @@ declare class Base_3 extends Camera {
     roomEnvMap?: _THREE.Texture;
     private roomEnvLease?;
     visName: string;
-    private detectRes?;
     private ownsPencil;
+    private rendererWarmup?;
     private renderingSuspensions;
     /** Internal: 在运行时创建前也可暂停，保证整个初始化过程不提交中间帧。 */
     suspendRendering(): () => void;
@@ -382,10 +381,16 @@ declare class Base_3 extends Camera {
     private getQueryOverrides;
     private getEffectiveLogarithmicDepthBuffer;
     private getEffectiveTier;
-    private isExtClipControlAvailable;
     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?;
@@ -474,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);
@@ -501,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）
@@ -611,6 +616,8 @@ declare interface BaseOptions {
     css2DContainer?: HTMLElement;
     controlsContainer?: HTMLElement;
     pencil?: any;
+    /** Internal: Owned by SceneManager until the first Pencil adopts it. */
+    rendererWarmup?: ReturnType<typeof Pencil.prewarmRenderer>;
     pencilConfig?: Record<string, any>;
     disableInitShow?: boolean;
     logarithmicDepthBuffer?: boolean;
@@ -657,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 {
@@ -1741,7 +1744,7 @@ declare class CameraPages extends OrigonPages<PerspectiveCamera_2> {
     private _cachedMatrixWorldInverse;
     private externallySyncedCameras;
     private ownedCameras;
-    constructor(options: Options_3);
+    constructor(options: Options_4);
     addPerspectiveCamera(cameraParams?: {
         fov: number;
         aspect?: number;
@@ -1808,7 +1811,6 @@ declare class City {
         jsonUrl?: string;
         meters?: number;
         grey?: boolean;
-        sideGradient?: boolean;
         hasSide?: boolean;
     }): Promise<Building | undefined>;
     drawArea(options?: {
@@ -1835,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;
@@ -1854,11 +1854,8 @@ 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;
 }
 
 /** Duplicate scene-owned definitions, while retaining references to project assets. */
@@ -1992,11 +1989,11 @@ declare const ColorSpace: {
 /** WebGPU render pipeline. Compatibility controls retain the saved scene schema. */
 declare class Composer {
     renderer: WebGPURenderer;
-    scene: Scene_2;
+    scene: Scene;
     camera: Camera_2;
     finalComposer: RenderPipeline;
     renderPass: {
-        scene: Scene_2;
+        scene: Scene;
         camera: Camera_2;
     };
     bloomComposer?: RenderTarget;
@@ -2024,10 +2021,10 @@ declare class Composer {
             };
         };
     };
-    bloomSelection: Set<BaseObject< Object3D<Object3DEventMap>>>;
+    bloomSelection: Set<BaseObject< Object3D_2<Object3DEventMap>>>;
     bloomLayer: Layers;
     active: boolean;
-    options: Options_2;
+    options: Options_3;
     private readonly target;
     private overlayTarget?;
     private outputPipeline?;
@@ -2049,13 +2046,15 @@ declare class Composer {
     private readonly gtaoViews;
     private readonly onCameraChange;
     private readonly onSceneChange;
-    constructor(options: Options_2);
+    constructor(options: Options_3);
     private createDepthTexture;
+    /** Reconcile async backend selection before the first draw; preserve target identities. */
+    synchronizeRendererCapabilities(multisampling?: number): void;
     private resizeTargets;
     private rebuild;
     private activateView;
     changeCamera(camera: Camera_2): void;
-    changeScene(scene: Scene_2): void;
+    changeScene(scene: Scene): void;
     addOutputPass(): void;
     setPremultiplieAlpha(value: boolean): void;
     addSSAOPass(params: SSAOParams): void;
@@ -2173,6 +2172,7 @@ export declare interface CreateMaterialAssetOptions {
     material: Record<string, any>;
     scope?: MaterialScope;
     locked?: boolean;
+    alwaysExport?: boolean;
 }
 
 /**
@@ -2217,7 +2217,7 @@ declare class CSSRendererController {
     setSize(width: number, height: number): void;
     setViewport(viewport: CSSRendererViewport): void;
     private applyViewport;
-    render(scene: Scene, camera: PerspectiveCamera_2): void;
+    render(scene: Scene_2, camera: PerspectiveCamera_2): void;
     dispose(): void;
 }
 
@@ -2460,8 +2460,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;
@@ -2476,21 +2476,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
@@ -2733,18 +2733,18 @@ 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>>;
     constructor(pencil: Pencil, ops: {
-        scene: Scene;
+        scene: Scene_2;
         sceneResources: SceneResources_2;
     });
     /**
@@ -2752,7 +2752,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;
     /**
@@ -2775,7 +2775,7 @@ declare class Lead_2 extends Pick_2 {
      * 将原生 Object3D 包装为 BaseObject (Wrapper Pattern)
      * 如果已存在包装器，则返回现有实例
      */
-    wrap(object3d: Object3D): BaseObject;
+    wrap(object3d: Object3D_2): BaseObject;
     private wrapObject;
     /**
      * 统一的添加入口
@@ -2799,7 +2799,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;
 }
 
@@ -2807,7 +2807,7 @@ declare class LeadPages extends OrigonPages<Lead_2> {
     options: Options_11;
     get lead(): Lead_2;
     constructor(options: Options_11);
-    addLead(scene: Scene, sceneResources: SceneResources_2, index?: number): Lead_2;
+    addLead(scene: Scene_2, sceneResources: SceneResources_2, index?: number): Lead_2;
     removePage(index: number): void;
     setPageActive(index: number): void;
     setSize(width: number, height: number): void;
@@ -2881,7 +2881,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;
@@ -2889,10 +2889,10 @@ 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;
+    scene: Scene_2;
     private disposed;
     readonly resources: ResourceRegistry;
     private assetLeases;
@@ -2905,7 +2905,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;
@@ -2916,13 +2916,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>;
@@ -2948,7 +2948,7 @@ declare class LoaderPages extends OrigonPages<Loader> {
     options: Options_10;
     get loader(): Loader;
     constructor(options: Options_10);
-    addLoader(scene: Scene, index?: number): Loader;
+    addLoader(scene: Scene_2, index?: number): Loader;
     removePage(index: number): void;
 }
 
@@ -3004,6 +3004,10 @@ declare class Map_4 extends Base_3 {
     private regionCameraFitReference?;
     private authoredCameraPose?;
     private cameraAngleOverrides?;
+    private bundledMapSwitchKey?;
+    setRuntimeAssets(catalog?: RuntimeAssetCatalog): void;
+    private requireMapAuthorization;
+    protected authorizeSceneOptions(options: Record<string, any>): Promise<void>;
     setOptions(options: MapOptions): void;
     private _getProjectionCenter;
     private _getProjectionRotate;
@@ -3166,7 +3170,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>;
@@ -3239,16 +3243,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;
@@ -3304,7 +3311,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. */
@@ -3399,6 +3406,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>>;
@@ -3841,6 +3850,8 @@ declare class OptionMaterialDependencies {
 
 declare interface Options {
     container: HTMLElement;
+    /** Optional single-use renderer prepared by Pencil.prewarmRenderer(). */
+    rendererWarmup?: RendererWarmup;
     helper?: boolean;
     controls?: Partial<ControlsParams>;
     renderer?: Partial<RendererParams>;
@@ -3962,17 +3973,14 @@ declare interface Options_19 {
     material?: THREE.Material | THREE.Material[];
     meters?: number;
     hasSide?: boolean;
-    sideGradient?: boolean;
     grey?: boolean;
     materialOptions?: Record<string, THREE.Material>;
 }
 
 declare interface Options_2 {
-    sceneController: ScenePages;
-    cameraController: CameraPages;
-    rendererController: RendererController;
-    composerParams: ComposerParams;
-    resources?: ResourceRegistry;
+    width: number;
+    height: number;
+    rendererParams: RendererParams;
 }
 
 declare interface Options_20 {
@@ -4022,14 +4030,16 @@ declare interface Options_23 {
 }
 
 declare interface Options_3 {
-    width: number;
-    height: number;
+    sceneController: ScenePages;
+    cameraController: CameraPages;
+    rendererController: RendererController;
+    composerParams: ComposerParams;
+    resources?: ResourceRegistry;
 }
 
 declare interface Options_4 {
     width: number;
     height: number;
-    rendererParams: RendererParams;
 }
 
 declare interface Options_5 {
@@ -4045,16 +4055,16 @@ declare interface Options_6 {
 
 declare interface Options_7 {
     renderer: WebGPURenderer;
-    scene: Scene_2;
+    scene: Scene;
     /** Authored page identity when scene is a shared overlay. */
-    viewScene?: Scene_2;
+    viewScene?: Scene;
     camera: Camera_2;
 }
 
 declare interface Options_8 {
     sceneController: ScenePages;
     /** Editor overlays live outside the authored scene and its render passes. */
-    helperScene?: Scene_2;
+    helperScene?: Scene;
     cameraController: CameraPages;
     container: HTMLElement;
     resources?: ResourceRegistry;
@@ -4064,7 +4074,7 @@ declare interface Options_9 {
     prefix?: string;
     simpleTexture4deleted?: boolean;
     anisotropy: number;
-    scene: Scene | null;
+    scene: Scene_2 | null;
     resources?: ResourceRegistry;
 }
 
@@ -4082,7 +4092,9 @@ declare class OrigonPages<T = any> {
 }
 
 /** 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 packSceneDocumentResources<T extends VisSceneDocument>(document: T, options?: {
+    encodePixels?: boolean;
+}): T;
 
 /** Page identities are independent of Three's 32 rendering layers. */
 declare class Pages {
@@ -4147,7 +4159,7 @@ export declare function patchSceneViewportDocument(document: VisSceneDocument, s
 declare class Pencil {
     readonly resources: ResourceRegistry;
     readonly ready: Promise<void>;
-    options: Omit<DeepRequiredOptions, 'controls' | 'loader' | 'css2DRendererParams' | 'css3DRendererParams'> & Pick<Options, 'controls' | 'loader'> & {
+    options: Omit<DeepRequiredOptions, 'controls' | 'loader' | 'css2DRendererParams' | 'css3DRendererParams' | 'rendererWarmup'> & Pick<Options, 'controls' | 'loader'> & {
         css2DRendererParams: CSSRendererParams;
         css3DRendererParams: CSSRendererParams;
     };
@@ -4161,7 +4173,7 @@ declare class Pencil {
     helperController?: HelperController;
     private _helperScene?;
     /** Drawn only in the editor, after the authored scene's postprocessing. */
-    get helperScene(): Scene_2< Object3DEventMap>;
+    get helperScene(): Scene< Object3DEventMap>;
     private sceneCapture?;
     loaderController: LoaderPages;
     leadController: LeadPages;
@@ -4182,7 +4194,7 @@ declare class Pencil {
     get cameraPositon(): Vector3_2;
     get cameraTarget(): Vector3_2;
     get camera(): PerspectiveCamera;
-    get scene(): Scene_2< Object3DEventMap>;
+    get scene(): Scene< Object3DEventMap>;
     get loader(): Loader;
     get lead(): Lead_2;
     get sceneResources(): SceneResources_2;
@@ -4195,6 +4207,7 @@ declare class Pencil {
         controls: boolean;
         renderer: {
             forceWebGL: boolean;
+            autoDepthBuffer: boolean;
             antialias: boolean;
             devicePixelRatio: number;
             powerPreference: string;
@@ -4262,6 +4275,9 @@ declare class Pencil {
         attributesWorkerMaxWorkers: number;
     };
     private TweenRaf;
+    private rendererWarmup?;
+    /** Start only the GPU environment; the eventual Pencil takes ownership. */
+    static prewarmRenderer(renderer?: Partial<RendererParams>): RendererWarmup;
     private tweenUpdateRaf;
     private cancelTweenRaf;
     constructor(options: Options);
@@ -4313,14 +4329,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. */
@@ -4425,7 +4441,7 @@ declare type PickFunctionsItem = {
 };
 
 export declare interface PlanarMap {
-    object3d: Object3D;
+    object3d: Object3D_2;
     options: {
         projection?: ProjectionOptions;
         conic?: boolean;
@@ -4511,7 +4527,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;
@@ -4660,6 +4676,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>;
@@ -4711,13 +4728,15 @@ declare class RendererController {
     private disposed;
     private hasRenderableSize;
     private readonly pointSprites;
-    options: Options_4;
+    readonly surfaceEffects: SurfaceEffects;
+    options: Options_2;
     private displayScaleObserver?;
-    constructor(options: Options_4);
+    private releaseRenderPipelines?;
+    constructor(options: Options_2);
     observeDisplayScale(container: HTMLElement): void;
     setSize(width: number, height: number): void;
     setPixelRatio(ratio: number): void;
-    render(scene: Scene_2, camera: Camera_2): void;
+    render(scene: Scene, camera: Camera_2): void;
     setViewport(op: {
         x: number;
         y: number;
@@ -4741,10 +4760,26 @@ declare interface RendererParams {
     stencil: boolean;
     depth: boolean;
     reversedDepthBuffer: boolean;
+    /** Prefer reversed depth on the selected backend; retain logarithmic depth on GL without EXT_clip_control. */
+    autoDepthBuffer?: boolean;
     /** Use the WebGL 2 backend of WebGPURenderer, primarily for compatibility testing. */
     forceWebGL?: boolean;
 }
 
+/** A single-use, privately owned renderer. No scene, loader, DOM attachment or render loop. */
+declare class RendererWarmup {
+    readonly ready: Promise<void>;
+    private controller?;
+    private readonly parameters;
+    private cancelled;
+    private detachDeviceListener?;
+    get available(): boolean;
+    constructor(parameters: RendererParams);
+    /** Transfer ownership only when the final scene's renderer configuration matches. */
+    take(parameters: RendererParams, width: number, height: number): RendererController | undefined;
+    dispose(): void;
+}
+
 export declare function replaceMaterialAssetDocument(document: VisSceneDocument, asset: MaterialAsset): VisSceneDocument;
 
 export declare const RESOURCE_SOURCE = "_resourceSource";
@@ -4913,6 +4948,36 @@ declare class Road extends GroupObject {
     dispose(): void;
 }
 
+/** 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;
+    /** Compressed/original file bytes, base64 encoded for project persistence. */
+    data?: string;
+}
+
+export declare interface RuntimeAssetCatalog {
+    version: 1;
+    entries: RuntimeAsset[];
+    scope?: MapExportScope;
+    /** 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;
+}
+
 /** Only ordinary encoded images are externalized. Typed pixel data, videos and
  * custom payloads keep their original serialization contract. */
 declare interface RuntimeImageAsset {
@@ -4929,7 +4994,7 @@ 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: 4;
 
 export declare interface SceneBackInteraction {
     trigger: 'click' | 'clickOutside';
@@ -4940,6 +5005,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;
@@ -4952,6 +5019,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[];
@@ -5016,6 +5084,8 @@ export declare class SceneManager extends Event_2 {
     private isSwitching;
     private isRegionSwitching;
     private pencil?;
+    private rendererWarmup?;
+    private disposed;
     private safeAreaInsets?;
     private generation;
     private mapRequests;
@@ -5047,7 +5117,16 @@ export declare class SceneManager extends Event_2 {
     setSceneCachePolicy(cacheScenes: boolean, maxCachedScenes?: number | undefined): void;
     private reportSceneRetirementErrors;
     constructor(options: SceneManagerInitOptions);
+    /**
+     * Initialize the eventual renderer without downloading/expanding a scene or drawing.
+     * Call after starting template I/O to overlap network work with GPU startup.
+     * Repeated calls share one promise. A scene with different renderer options
+     * uses its own compatible renderer; failed warmups may be retried.
+     */
+    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;
     /**
@@ -5105,12 +5184,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. */
@@ -5125,14 +5204,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;
@@ -5212,8 +5291,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>;
 }
@@ -5251,14 +5330,14 @@ export declare interface SceneObjectPropertyPatch {
     unset?: readonly string[];
 }
 
-declare class ScenePages extends OrigonPages<Scene> {
-    get scene(): Scene< Object3DEventMap>;
-    addScene(sceneParams?: SceneParams, index?: number): Scene< Object3DEventMap>;
+declare class ScenePages extends OrigonPages<Scene_2> {
+    get scene(): Scene_2< Object3DEventMap>;
+    addScene(sceneParams?: SceneParams, index?: number): Scene_2< Object3DEventMap>;
     setPageActive(index: number): void;
 }
 
 declare interface SceneParams {
-    background: Scene['background'];
+    background: Scene_2['background'];
 }
 
 declare type ScenePropertyField = typeof scenePropertyFields[number];
@@ -5282,7 +5361,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;
@@ -5333,7 +5412,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;
@@ -5358,7 +5437,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;
 }
 
@@ -5366,6 +5445,9 @@ declare type SceneSnapshot = Object3DJSON & {
     materialAliases?: Record<string, SerializedMaterialAlias>;
 };
 
+/** 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' | '_texDataPool';
 
 /** Metadata is part of an owned structure transaction, never a scalar runtime patch. */
@@ -5721,6 +5803,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;
@@ -5758,11 +5872,11 @@ 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;
-    bindActiveView(camera: Camera_2 | undefined, scene: Scene_2 | undefined, viewScene?: Scene_2< Object3DEventMap> | undefined): void;
+    bindActiveView(camera: Camera_2 | undefined, scene: Scene | undefined, viewScene?: Scene< Object3DEventMap> | undefined): void;
     private releaseRaycastCamera;
     private getBoundingClientRect;
     addEvent(): void;
@@ -5818,7 +5932,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;
@@ -5827,7 +5941,7 @@ declare class UseMaterial extends PointerEvent_2 {
 
 declare type ValuesOf<T extends readonly any[]> = T[number];
 
-export declare const VERSION = "0.33.15";
+export declare const VERSION = "0.33.17";
 
 declare interface Viewport {
     left: number;
@@ -5842,6 +5956,7 @@ 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. */
@@ -5858,7 +5973,9 @@ export declare interface VisSceneDocument extends SceneDocumentMarker {
 
 export declare interface VisSceneManifest {
     format: typeof SCENE_MANIFEST_FORMAT;
-    schemaVersion: 1 | 2 | typeof SCENE_MANIFEST_SCHEMA_VERSION;
+    schemaVersion: 1 | 2 | 3 | typeof SCENE_MANIFEST_SCHEMA_VERSION;
+    /** Manifest 4: complete static dependencies, shared by every scene. */
+    runtimeAssets?: RuntimeAssetCatalog;
     entrySceneId: string;
     scenes: SceneManifestEntry[];
     materialLibrary?: MaterialAsset[];
@@ -5874,35 +5991,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 { }