soonspacejs 3.0.0-alpha.12 → 3.0.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soonspacejs",
-  "version": "3.0.0-alpha.12",
+  "version": "3.0.0-alpha.14",
   "homepage": "https://www.xwbuilders.com/soonspacejs/",
   "description": "SoonSpace.js 3.0 alpha",
   "module": "./dist/index.esm.js",

package/types/Cache/ModelValidationScheduler.d.ts

@@ -0,0 +1,9 @@
+/** Shared per-origin validation admission. Work must own its complete HTTP body. */
+export declare class ModelValidationScheduler {
+    private readonly concurrency;
+    private pools;
+    private sequence;
+    constructor(concurrency?: number);
+    schedule<T>(origin: string, bytes: number, signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T>;
+    private drain;
+}

package/types/Entity/ModelResources.d.ts

@@ -2,6 +2,7 @@ import { BufferGeometry, Material, Matrix4, Texture } from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { ModelBufferCache } from '../Cache/ModelBufferCache';
 import { ParsedModelCacheOptions } from '../Cache/ParsedModelCache';
+import { ParametricOpeningModelDescription, ParametricOpeningLoadOptions } from '../Geometry/ParametricOpenings/opening-model';
 export interface ModelPart {
     /** Omitted for triangle meshes. Basic line segments share the Entity lifecycle. */
     kind?: 'mesh' | 'line-segments';
@@ -67,6 +68,9 @@ export declare class ModelResources {
     private urls;
     private gltfLoader;
     private bufferCache;
+    private openingTextures;
+    private openingMaterials;
+    private openingMaterialKeys;
     private parsedCacheOptions;
     private parsedCache;
     /** Borrow a host-configured loader; its decoder workers remain host-owned. */
@@ -84,6 +88,10 @@ export declare class ModelResources {
         ownership: 'transfer';
     }): ModelLease;
     load(url: string, options?: ModelLoadOptions): Promise<ModelLease>;
+    /** Procedural geometry and materials with the same Entity lease/ownership contract as load(). */
+    loadOpening(description: ParametricOpeningModelDescription, options?: ParametricOpeningLoadOptions): Promise<ModelLease>;
+    private resolveOpening;
+    private acquireOpeningMaterial;
     private resolveLoad;
     private create;
     lease<T>(record: ResourceRecord<T>): ResourceLease<T>;

package/types/Geometry/ParametricOpenings/constants.d.ts

@@ -0,0 +1,55 @@
+import { ParametricWindowType, ParametricOpeningKind, ParametricOpeningMaterialLayout } from './types';
+/** Builder generator defaults. Lengths are metres; angles are radians. */
+export declare const OPENING_GENERATOR_CONSTANTS: Readonly<{
+    door: Readonly<{
+        frameThick: 0.05;
+        glassThick: 0.01;
+        leftThick: 0.03;
+        rightThick: 0.03;
+        glassFrameThick: 0.1;
+        openAngle: number;
+        doubleDoorRatio: 0.5;
+        asymmetricDoorRatio: readonly [0.7, 0.3];
+    }>;
+    window: Readonly<{
+        frameThick: 0.05;
+        glassThick: 0.01;
+        openAngle: number;
+        byType: readonly [Readonly<{
+            type: ParametricWindowType.Sliding;
+            layerCount: 2;
+            windowThick: 0.05;
+        }>, Readonly<{
+            type: ParametricWindowType.FixedTopSlidingBottom;
+            layerCount: 2;
+            windowThick: 0.05;
+        }>, Readonly<{
+            type: ParametricWindowType.Fixed;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>, Readonly<{
+            type: ParametricWindowType.Hinged;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>, Readonly<{
+            type: ParametricWindowType.Circular;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>, Readonly<{
+            type: ParametricWindowType.Vent;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>];
+        topWindowRate: number;
+        roundSegments: 40;
+    }>;
+    elevatorDoor: Readonly<{
+        gap: 0.01;
+        leafWidthExtra: 0.05;
+        /** Caller applies this offset when placing a floor's door. */
+        floorHeightOffset: 0.01;
+        uvTileLength: 1;
+    }>;
+}>;
+/** Original Builder slots, including reserved defaults and unused materials. */
+export declare function getOpeningMaterialLayout(kind: ParametricOpeningKind, type?: number): ParametricOpeningMaterialLayout;

package/types/Geometry/ParametricOpenings/door.d.ts

@@ -0,0 +1,6 @@
+import { ParametricDoorGeometryOptions, ParametricOpeningGeometryPart } from './types';
+/**
+ * Ordinary Builder door geometry, in metres. No scene, materials or animation
+ * objects are created. Every call returns new caller-owned geometry and poses.
+ */
+export declare function createDoorGeometryParts(options: ParametricDoorGeometryOptions): ParametricOpeningGeometryPart[];

package/types/Geometry/ParametricOpenings/elevator.d.ts

@@ -0,0 +1,3 @@
+import { ParametricElevatorDoorGeometryOptions, ParametricOpeningGeometryPart } from './types';
+/** Two closed floor leaves in local coordinates; caller owns floor placement. */
+export declare function createElevatorDoorGeometryParts(options: ParametricElevatorDoorGeometryOptions): ParametricOpeningGeometryPart[];

package/types/Geometry/ParametricOpenings/index.d.ts

@@ -0,0 +1,8 @@
+export { createDoorGeometryParts, } from './door';
+export { createWindowGeometryParts, } from './window';
+export { createElevatorDoorGeometryParts, } from './elevator';
+export { OPENING_GENERATOR_CONSTANTS, getOpeningMaterialLayout, } from './constants';
+export * from './types';
+export { DEFAULT_OPENING_MATERIALS, resolveOpeningMaterialDescription, applyOpeningTextureTransform, createOpeningMaterial, } from './materials';
+export type { OpeningMaterialDescription, } from './materials';
+export type { ParametricOpeningModelDescription, ParametricOpeningLoadOptions, } from './opening-model';

package/types/Geometry/ParametricOpenings/materials.d.ts

@@ -0,0 +1,33 @@
+import { MeshPhongMaterial, MeshStandardMaterial, Texture } from 'three';
+/** Builder material values. Rotation is in degrees; SCALE is inverse UV scale. */
+export interface OpeningMaterialDescription {
+    textureFile?: string | null;
+    ambient?: readonly number[];
+    diffuse?: readonly number[];
+    opacity?: number;
+    scale?: readonly number[];
+    scroll?: readonly number[];
+    rotation?: number;
+    full?: number | boolean;
+    cullingMode?: number;
+    alphaBlendMode?: number;
+    depthBias?: readonly number[];
+    metalness?: number;
+    roughness?: number;
+    emissive?: readonly number[];
+    /** Explicit Builder specular lighting selects Phong, including custom material names. */
+    shininess?: number;
+    specular?: readonly number[];
+}
+type NormalizedOpeningMaterialDescription = Required<Omit<OpeningMaterialDescription, 'shininess' | 'specular'>> & Pick<OpeningMaterialDescription, 'shininess' | 'specular'> & {
+    full: boolean;
+};
+/** Opening entries from Builder's DefaultMaterial.ini, plus its fixed elevator material. */
+export declare const DEFAULT_OPENING_MATERIALS: Readonly<Record<string, Readonly<NormalizedOpeningMaterialDescription>>>;
+/** Returns copied RGB tuples and explicit opacity; omitted fields retain their preset. */
+export declare function resolveOpeningMaterialDescription(name: string, input?: OpeningMaterialDescription): NormalizedOpeningMaterialDescription;
+/** Configures only the supplied, caller-owned sampler; this helper never fetches images. */
+export declare function applyOpeningTextureTransform(texture: Texture, description: OpeningMaterialDescription): void;
+/** Creates an independent material. The caller provides and owns any fresh texture sampler. */
+export declare function createOpeningMaterial(name: string, description?: OpeningMaterialDescription, texture?: Texture, textureAlpha?: 'opaque' | 'cutout' | 'blend'): MeshStandardMaterial | MeshPhongMaterial;
+export {};

package/types/Geometry/ParametricOpenings/mesh.d.ts

@@ -0,0 +1,42 @@
+import { Matrix4 } from 'three';
+import { ParametricOpeningGeometryOptions, ParametricOpeningGeometryPart, ParametricOpeningPartRole } from './types';
+export type Point = readonly [number, number, number];
+export interface Rect {
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+}
+export interface Solid extends Rect {
+    front: number;
+    back: number;
+}
+export declare const FRAME: 0.05;
+export declare const GLASS: 0.01;
+/** Semantic face writer: every emitted face owns its normals and UV seam. */
+export declare class OpeningMesh {
+    readonly name: string;
+    readonly materialSlot: number;
+    readonly role: ParametricOpeningPartRole;
+    readonly matrix: Matrix4;
+    private positions;
+    private normals;
+    private uvs;
+    private indices;
+    constructor(name: string, materialSlot: number, role: ParametricOpeningPartRole, matrix?: Matrix4);
+    quad(points: readonly Point[], normal: Point, uvs?: readonly number[]): void;
+    triangle(points: readonly Point[], normal: Point, uv: readonly number[]): void;
+    compile(): ParametricOpeningGeometryPart | null;
+}
+export declare function compileParts(writers: OpeningMesh[]): ParametricOpeningGeometryPart[];
+export declare function validateOptions(options: ParametricOpeningGeometryOptions, maximumType: number): void;
+export declare function assertRect(rect: Rect): void;
+/** UVs follow the reference's top-left origin; back faces mirror U. */
+export declare function faceXY(writer: OpeningMesh, rect: Rect, z: number, front: boolean, uvRect?: Rect, mirrorU?: boolean): void;
+export declare function boxSides(writer: OpeningMesh, box: Solid): void;
+/** One continuous extruded frame with vertically stacked real apertures. */
+export declare function shell(writer: OpeningMesh, outer: Solid, holes: Rect[]): void;
+export declare function glass(writer: OpeningMesh, rect: Rect, back?: number, front?: number): void;
+export declare function pose(x: number, y: number, z: number, angle?: number): Matrix4;
+export declare function sash(writers: OpeningMesh[], name: string, outer: Solid, matrix: Matrix4): void;
+export declare function slidingLeaves(writers: OpeningMesh[], inner: Solid, open: boolean): void;

package/types/Geometry/ParametricOpenings/opening-model.d.ts

@@ -0,0 +1,50 @@
+import { resolveOpeningMaterialDescription, OpeningMaterialDescription } from './materials';
+import { MaterialLease, ModelPart } from '../../Entity/ModelResources';
+import { ParametricDoorGeometryOptions, ParametricWindowGeometryOptions, ParametricElevatorDoorGeometryOptions, ParametricOpeningGeometryPart } from './types';
+interface MaterialBindings {
+    partMaterials?: readonly {
+        slot: number;
+        material: string;
+    }[];
+    /** Partial material overrides. Explicit null/empty textureFile means no texture. */
+    materials?: Readonly<Record<string, OpeningMaterialDescription>>;
+}
+export type ParametricOpeningModelDescription = MaterialBindings & ({
+    kind: 'door';
+    parameters: ParametricDoorGeometryOptions;
+} | {
+    kind: 'window';
+    parameters: ParametricWindowGeometryOptions;
+} | {
+    kind: 'elevator-door';
+    parameters: ParametricElevatorDoorGeometryOptions;
+});
+export interface ParametricOpeningLoadOptions {
+    signal?: AbortSignal;
+    /** Resolve metadata references/default image names into a URL. No filesystem assumptions. */
+    resolveTexture?: (reference: string, materialName: string) => string | null | undefined;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+}
+export interface OpeningMaterialBinding {
+    name: string;
+    description: ReturnType<typeof resolveOpeningMaterialDescription>;
+    url?: string;
+    headers: Headers;
+}
+export interface PreparedOpening {
+    key: string;
+    geometry: () => ParametricOpeningGeometryPart[];
+    bindings: Map<number, OpeningMaterialBinding>;
+    credentials: RequestCredentials;
+}
+/** Snapshot caller data and resolved/authenticated image identities before awaiting. */
+export declare function prepareOpening(input: ParametricOpeningModelDescription, options: ParametricOpeningLoadOptions, managerResolve?: (url: string) => string): PreparedOpening;
+/** Candidate is either transferred atomically to ModelResources or disposed once. */
+export declare function openingMaterialKey(binding: OpeningMaterialBinding, credentials: RequestCredentials): string;
+export declare function buildOpening(prepared: PreparedOpening, acquire: (binding: OpeningMaterialBinding, credentials: RequestCredentials, signal: AbortSignal) => Promise<MaterialLease>, signal: AbortSignal): Promise<{
+    parts: ModelPart[];
+    releaseMaterials: () => void;
+    dispose: () => void;
+}>;
+export {};

package/types/Geometry/ParametricOpenings/opening-textures.d.ts

@@ -0,0 +1,22 @@
+import { Texture } from 'three';
+import { ModelBufferCache } from '../../Cache/ModelBufferCache';
+export type OpeningTextureAlpha = 'opaque' | 'cutout' | 'blend';
+export declare const openingAbort: () => DOMException;
+export declare function openingHeaderPairs(headers: Headers): [string, string][];
+/** Image classification is cached with the live decoded pixels, never scanned per frame. */
+export declare function classifyOpeningAlpha(rgba: Uint8ClampedArray, name?: string): OpeningTextureAlpha;
+/** Registry-owned image pool. Texture objects/sources stay independent per material. */
+export declare class OpeningTexturePool {
+    private cache;
+    private pixels;
+    private pending;
+    private disposed;
+    constructor(cache: () => ModelBufferCache);
+    private sampler;
+    acquire(url: string, headers: Headers, credentials: RequestCredentials, signal: AbortSignal): Promise<{
+        texture: Texture;
+        alpha: OpeningTextureAlpha;
+    }>;
+    private read;
+    dispose(): void;
+}

package/types/Geometry/ParametricOpenings/types.d.ts

@@ -0,0 +1,73 @@
+import { BufferGeometry, Matrix4 } from 'three';
+/** Builder's door type IDs. These IDs are not shared with window types. */
+export declare enum ParametricDoorType {
+    SingleHinged = 0,
+    SingleHingedGlass = 1,
+    DoubleSwing = 2,
+    AsymmetricDoubleHinged = 3,
+    DoubleSwingGlass = 4,
+    DoubleSwingTwoGlass = 5,
+    DoubleHinged = 6,
+    Opening = 7,
+    Sliding = 8,
+    RollUp = 9
+}
+export declare enum ParametricWindowType {
+    Sliding = 0,
+    FixedTopSlidingBottom = 1,
+    Fixed = 2,
+    Hinged = 3,
+    Opening = 4,
+    Circular = 5,
+    Vent = 6
+}
+export type ParametricOpeningKind = 'door' | 'window' | 'elevator-door';
+export interface ParametricOpeningMaterialSlot {
+    readonly materialSlot: number;
+    readonly defaultMaterialTitle: string;
+    readonly userAssignable: boolean;
+}
+export interface ParametricOpeningMaterialLayout {
+    readonly frameSlotIndex: number;
+    readonly faceSlotIndex: number;
+    readonly slots: readonly ParametricOpeningMaterialSlot[];
+}
+export interface ParametricOpeningGeometryOptions {
+    /** Metres. Local X is width, Y is up; the opening bottom is Y=0. */
+    width: number;
+    height: number;
+    /** 0: pivot at local -X; 1: pivot at +X. Default 0. */
+    hingePosition?: 0 | 1;
+    /** Static pose, default false. No animation or frame listener is installed. */
+    open?: boolean;
+}
+export interface ParametricDoorGeometryOptions extends ParametricOpeningGeometryOptions {
+    type: ParametricDoorType;
+    /** Actual additional height in metres, default 0. Not the legacy 0/1 flag. */
+    topWindowHeight?: number;
+}
+export interface ParametricWindowGeometryOptions extends ParametricOpeningGeometryOptions {
+    type: ParametricWindowType;
+}
+/** One floor's closed outer elevator leaves. Dimensions are metres. */
+export interface ParametricElevatorDoorGeometryOptions {
+    doorWidth: number;
+    /** Combined two-layer door depth, greater than the generator's depth gap. */
+    doorDepth: number;
+    /** Exterior elevator depth; zero is allowed. */
+    outDepth: number;
+    outHeight: number;
+    /** Shaft wall thickness; zero is allowed. */
+    wallThick: number;
+}
+export type ParametricOpeningPartRole = 'frame' | 'panel' | 'glass' | 'transom-glass' | 'vent';
+/** Caller owns the geometry. Transfer it to ModelResources or dispose it once. */
+export interface ParametricOpeningGeometryPart {
+    name: string;
+    geometry: BufferGeometry;
+    /** Local part pose, independent from the scene node's transform. */
+    matrix: Matrix4;
+    /** Builder slot: door 0/1/2, window 1/2/3, elevator 0. -1 is untagged transom glass. */
+    materialSlot: number;
+    role: ParametricOpeningPartRole;
+}

package/types/Geometry/ParametricOpenings/window.d.ts

@@ -0,0 +1,3 @@
+import { ParametricWindowGeometryOptions, ParametricOpeningGeometryPart } from './types';
+/** Builder window geometry (types 0–6), with metre dimensions and local poses. */
+export declare function createWindowGeometryParts(options: ParametricWindowGeometryOptions): ParametricOpeningGeometryPart[];

package/types/index.d.ts

@@ -880,6 +880,9 @@ export declare interface AnimationOptions {
  */
 declare type AnimationPath = IVector3[] | Curve<Vector3> | Topology;
 
+/** Configures only the supplied, caller-owned sampler; this helper never fetches images. */
+export declare function applyOpeningTextureTransform(texture: Texture, description: OpeningMaterialDescription): void;
+
 declare function approxEquals(a: number, b: number, error?: number): boolean;
 
 declare function approxZero(number: number, error?: number): boolean;
@@ -1706,6 +1709,15 @@ export declare interface CreateCurveAnimationClipReturn {
     lengths: number[] | undefined;
 }
 
+/**
+ * Ordinary Builder door geometry, in metres. No scene, materials or animation
+ * objects are created. Every call returns new caller-owned geometry and poses.
+ */
+export declare function createDoorGeometryParts(options: ParametricDoorGeometryOptions): ParametricOpeningGeometryPart[];
+
+/** Two closed floor leaves in local coordinates; caller owns floor placement. */
+export declare function createElevatorDoorGeometryParts(options: ParametricElevatorDoorGeometryOptions): ParametricOpeningGeometryPart[];
+
 /**
  * 创建等分链式骨骼
  * @param boneOpts - 等分链式骨骼的选项
@@ -1835,6 +1847,9 @@ export declare function createKeyframeTracksOfCurveAnimationByPolyline(options:
     curveLength: number;
 };
 
+/** Creates an independent material. The caller provides and owns any fresh texture sampler. */
+export declare function createOpeningMaterial(name: string, description?: OpeningMaterialDescription, texture?: Texture, textureAlpha?: 'opaque' | 'cutout' | 'blend'): MeshStandardMaterial | MeshPhongMaterial;
+
 declare type CreatePathAnimationActionForCameraOptions = CreatePathAnimationActionForCameraOptions_Base & CreatePathAnimationOptions;
 
 declare interface CreatePathAnimationActionForCameraOptions_Base {
@@ -1865,6 +1880,9 @@ declare function createTextureLoader(manager?: LoadingManager): TextureLoader;
  */
 export declare function createUVMatrix(box: Box2): Matrix3;
 
+/** Builder window geometry (types 0–6), with metre dimensions and local poses. */
+export declare function createWindowGeometryParts(options: ParametricWindowGeometryOptions): ParametricOpeningGeometryPart[];
+
 declare class CSS2DRenderer {
     readonly viewport: Viewport;
     domElement: HTMLElement;
@@ -1980,6 +1998,9 @@ export declare enum DecalUVMapType {
     	Original = 5
 }
 
+/** Opening entries from Builder's DefaultMaterial.ini, plus its fixed elevator material. */
+export declare const DEFAULT_OPENING_MATERIALS: Readonly<Record<string, Readonly<NormalizedOpeningMaterialDescription>>>;
+
 declare class DefaultManage {
     readonly type: string;
     readonly viewport: Viewport;
@@ -2695,6 +2716,9 @@ export declare interface GetKeyframeTransformDatasOptionsByCurve_Base extends Ge
     us?: number[];
 }
 
+/** Original Builder slots, including reserved defaults and unused materials. */
+export declare function getOpeningMaterialLayout(kind: ParametricOpeningKind, type?: number): ParametricOpeningMaterialLayout;
+
 export declare function getPolygonGeometryInfo(points: Vector3[]): {
     geometry: ShapeGeometry;
     polygonBox: Box2;
@@ -3455,6 +3479,15 @@ declare interface ManagerStore {
     pluginObjectManager: PluginManage;
 }
 
+declare interface MaterialBindings {
+    partMaterials?: readonly {
+        slot: number;
+        material: string;
+    }[];
+    /** Partial material overrides. Explicit null/empty textureFile means no texture. */
+    materials?: Readonly<Record<string, OpeningMaterialDescription>>;
+}
+
 export declare interface MaterialEffectOptionItem {
     type: keyof MaterialEffectOptions;
     option: MaterialEffectOptions[keyof MaterialEffectOptions] | null;
@@ -3734,6 +3767,9 @@ export declare class ModelResources {
     private urls;
     private gltfLoader;
     private bufferCache;
+    private openingTextures;
+    private openingMaterials;
+    private openingMaterialKeys;
     private parsedCacheOptions;
     private parsedCache;
     /** Borrow a host-configured loader; its decoder workers remain host-owned. */
@@ -3751,6 +3787,10 @@ export declare class ModelResources {
         ownership: 'transfer';
     }): ModelLease;
     load(url: string, options?: ModelLoadOptions): Promise<ModelLease>;
+    /** Procedural geometry and materials with the same Entity lease/ownership contract as load(). */
+    loadOpening(description: ParametricOpeningModelDescription, options?: ParametricOpeningLoadOptions): Promise<ModelLease>;
+    private resolveOpening;
+    private acquireOpeningMaterial;
     private resolveLoad;
     private create;
     lease<T>(record: ResourceRecord<T>): ResourceLease<T>;
@@ -3797,6 +3837,10 @@ export declare interface NodeInfo extends PointInfo {
     graphs: TopologyNodeGraph[];
 }
 
+declare type NormalizedOpeningMaterialDescription = Required<Omit<OpeningMaterialDescription, 'shininess' | 'specular'>> & Pick<OpeningMaterialDescription, 'shininess' | 'specular'> & {
+    full: boolean;
+};
+
 /**
  * 通用对象事件参数
  */
@@ -3854,6 +3898,80 @@ export declare interface OffsetPoint {
 
 export declare type OpacitySelectOptions = BaseSelectOptions;
 
+/** Builder generator defaults. Lengths are metres; angles are radians. */
+export declare const OPENING_GENERATOR_CONSTANTS: Readonly<{
+    door: Readonly<{
+        frameThick: 0.05;
+        glassThick: 0.01;
+        leftThick: 0.03;
+        rightThick: 0.03;
+        glassFrameThick: 0.1;
+        openAngle: number;
+        doubleDoorRatio: 0.5;
+        asymmetricDoorRatio: readonly [0.7, 0.3];
+    }>;
+    window: Readonly<{
+        frameThick: 0.05;
+        glassThick: 0.01;
+        openAngle: number;
+        byType: readonly [Readonly<{
+            type: ParametricWindowType.Sliding;
+            layerCount: 2;
+            windowThick: 0.05;
+        }>, Readonly<{
+            type: ParametricWindowType.FixedTopSlidingBottom;
+            layerCount: 2;
+            windowThick: 0.05;
+        }>, Readonly<{
+            type: ParametricWindowType.Fixed;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>, Readonly<{
+            type: ParametricWindowType.Hinged;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>, Readonly<{
+            type: ParametricWindowType.Circular;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>, Readonly<{
+            type: ParametricWindowType.Vent;
+            layerCount: 1;
+            windowThick: 0.06;
+        }>];
+        topWindowRate: number;
+        roundSegments: 40;
+    }>;
+    elevatorDoor: Readonly<{
+        gap: 0.01;
+        leafWidthExtra: 0.05;
+        /** Caller applies this offset when placing a floor's door. */
+        floorHeightOffset: 0.01;
+        uvTileLength: 1;
+    }>;
+}>;
+
+/** Builder material values. Rotation is in degrees; SCALE is inverse UV scale. */
+export declare interface OpeningMaterialDescription {
+    textureFile?: string | null;
+    ambient?: readonly number[];
+    diffuse?: readonly number[];
+    opacity?: number;
+    scale?: readonly number[];
+    scroll?: readonly number[];
+    rotation?: number;
+    full?: number | boolean;
+    cullingMode?: number;
+    alphaBlendMode?: number;
+    depthBias?: readonly number[];
+    metalness?: number;
+    roughness?: number;
+    emissive?: readonly number[];
+    /** Explicit Builder specular lighting selects Phong, including custom material names. */
+    shininess?: number;
+    specular?: readonly number[];
+}
+
 export declare interface OrbitControlsOptions {
     type: OrbitControlsType;
     enableAutoRotate?: boolean;
@@ -3883,6 +4001,108 @@ export declare type OrbitControlsProperties = Required<Omit<OrbitControlsOptions
 
 export declare type OrbitControlsType = 'orbit';
 
+export declare interface ParametricDoorGeometryOptions extends ParametricOpeningGeometryOptions {
+    type: ParametricDoorType;
+    /** Actual additional height in metres, default 0. Not the legacy 0/1 flag. */
+    topWindowHeight?: number;
+}
+
+/** Builder's door type IDs. These IDs are not shared with window types. */
+export declare enum ParametricDoorType {
+    SingleHinged = 0,
+    SingleHingedGlass = 1,
+    DoubleSwing = 2,
+    AsymmetricDoubleHinged = 3,
+    DoubleSwingGlass = 4,
+    DoubleSwingTwoGlass = 5,
+    DoubleHinged = 6,
+    Opening = 7,
+    Sliding = 8,
+    RollUp = 9
+}
+
+/** One floor's closed outer elevator leaves. Dimensions are metres. */
+export declare interface ParametricElevatorDoorGeometryOptions {
+    doorWidth: number;
+    /** Combined two-layer door depth, greater than the generator's depth gap. */
+    doorDepth: number;
+    /** Exterior elevator depth; zero is allowed. */
+    outDepth: number;
+    outHeight: number;
+    /** Shaft wall thickness; zero is allowed. */
+    wallThick: number;
+}
+
+export declare interface ParametricOpeningGeometryOptions {
+    /** Metres. Local X is width, Y is up; the opening bottom is Y=0. */
+    width: number;
+    height: number;
+    /** 0: pivot at local -X; 1: pivot at +X. Default 0. */
+    hingePosition?: 0 | 1;
+    /** Static pose, default false. No animation or frame listener is installed. */
+    open?: boolean;
+}
+
+/** Caller owns the geometry. Transfer it to ModelResources or dispose it once. */
+export declare interface ParametricOpeningGeometryPart {
+    name: string;
+    geometry: BufferGeometry;
+    /** Local part pose, independent from the scene node's transform. */
+    matrix: Matrix4;
+    /** Builder slot: door 0/1/2, window 1/2/3, elevator 0. -1 is untagged transom glass. */
+    materialSlot: number;
+    role: ParametricOpeningPartRole;
+}
+
+export declare type ParametricOpeningKind = 'door' | 'window' | 'elevator-door';
+
+export declare interface ParametricOpeningLoadOptions {
+    signal?: AbortSignal;
+    /** Resolve metadata references/default image names into a URL. No filesystem assumptions. */
+    resolveTexture?: (reference: string, materialName: string) => string | null | undefined;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+}
+
+export declare interface ParametricOpeningMaterialLayout {
+    readonly frameSlotIndex: number;
+    readonly faceSlotIndex: number;
+    readonly slots: readonly ParametricOpeningMaterialSlot[];
+}
+
+export declare interface ParametricOpeningMaterialSlot {
+    readonly materialSlot: number;
+    readonly defaultMaterialTitle: string;
+    readonly userAssignable: boolean;
+}
+
+export declare type ParametricOpeningModelDescription = MaterialBindings & ({
+    kind: 'door';
+    parameters: ParametricDoorGeometryOptions;
+} | {
+    kind: 'window';
+    parameters: ParametricWindowGeometryOptions;
+} | {
+    kind: 'elevator-door';
+    parameters: ParametricElevatorDoorGeometryOptions;
+});
+
+export declare type ParametricOpeningPartRole = 'frame' | 'panel' | 'glass' | 'transom-glass' | 'vent';
+
+export declare interface ParametricWindowGeometryOptions extends ParametricOpeningGeometryOptions {
+    type: ParametricWindowType;
+}
+
+export declare enum ParametricWindowType {
+    Sliding = 0,
+    FixedTopSlidingBottom = 1,
+    Fixed = 2,
+    Hinged = 3,
+    Opening = 4,
+    Circular = 5,
+    Vent = 6
+}
+
 /** Parsed-cache evidence is bounded and contains no URLs, headers or exception text. */
 export declare interface ParsedModelCacheDiagnostic {
     key: string;
@@ -4327,6 +4547,9 @@ declare type RequestInit_2 = {
     redirect?: RequestRedirect;
 };
 
+/** Returns copied RGB tuples and explicit opacity; omitted fields retain their preset. */
+export declare function resolveOpeningMaterialDescription(name: string, input?: OpeningMaterialDescription): NormalizedOpeningMaterialDescription;
+
 export declare class ResourceLease<T> {
     readonly registry: ModelResources;
     private record;