@babylonjs/core 9.12.1 → 9.14.0

package/Materials/Textures/HTML/htmlRaycastInteractionManager.js

@@ -0,0 +1,246 @@
+import { PointerEventTypes } from "../../../Events/pointerEvents.js";
+// Attribution: the raycast/UV event-routing technique used here is prior art from
+// `three-html-render` (Palash Bansal, MIT) and Jake Archibald's `curved-markup` demo.
+// The implementation below is a clean-room rewrite against Babylon.js' own picking APIs.
+/**
+ * Maps a UV coordinate sampled from an {@link HtmlTexture} to a pixel position inside the source element.
+ *
+ * When `invertY` is true (the default, matching {@link HtmlTexture}'s default upload orientation) the V
+ * axis is flipped so that `v = 1` maps to the top of the element, matching the top-left origin used by
+ * DOM layout.
+ * @param u horizontal texture coordinate, normally in [0, 1]
+ * @param v vertical texture coordinate, normally in [0, 1]
+ * @param width element width in pixels
+ * @param height element height in pixels
+ * @param invertY whether the texture content is stored Y-inverted (default true)
+ * @returns the pixel position `{ x, y }` within the element
+ */
+export function GetElementPixelFromUv(u, v, width, height, invertY = true) {
+    return { x: u * width, y: (invertY ? 1 - v : v) * height };
+}
+/**
+ * Routes Babylon pointer events to a live HTML element rendered through an {@link HtmlTexture}.
+ *
+ * On every pointer event the scene is picked; when the configured mesh is hit, the picked UV is mapped to
+ * a pixel inside the source element and an equivalent DOM pointer (and mouse) event is dispatched there.
+ * This works for arbitrary meshes (planes, boxes, curved surfaces) because it relies on UV coordinates
+ * rather than a flat CSS overlay. For a perspective-correct overlay on planar surfaces, see
+ * {@link HtmlInteractionManager}.
+ */
+export class HtmlRaycastInteractionManager {
+    /**
+     * Creates a raycast interaction manager.
+     * @param scene the scene to listen to for pointer events
+     * @param texture the HTML texture whose element should receive the forwarded events
+     * @param mesh the mesh displaying the texture; only hits on this mesh are forwarded
+     * @param options optional configuration
+     */
+    constructor(scene, texture, mesh, options = {}) {
+        this._rectCache = new Map();
+        this._rectCacheValid = false;
+        this._resizeObserver = null;
+        this._mutationObserver = null;
+        this._scene = scene;
+        this._mesh = mesh;
+        this._element = options.targetElement ?? texture.element;
+        this._backFaceCulling = options.backFaceCulling ?? true;
+        this._invertY = options.invertY ?? true;
+        // The hosted element is a child of the engine's rendering canvas, where Babylon's own input
+        // listeners live. The synthetic events we dispatch bubble, so without this they would reach the
+        // canvas and be re-interpreted as real input - moving the camera and re-entering this manager in a
+        // feedback loop. Stopping propagation at the host element keeps them inside the HTML subtree (so
+        // event delegation still works) while never leaking back to the engine.
+        this._containHandler = (evt) => evt.stopPropagation();
+        for (const type of _ContainedEventTypes) {
+            this._element.addEventListener(type, this._containHandler);
+        }
+        // Resolving the target reads layout (getBoundingClientRect) for the element and its descendants on
+        // every pointer event. Cache those rects and only re-read them when layout can actually change - on
+        // size changes, DOM mutations, or viewport scroll/resize - so high-frequency pointermove events stay
+        // pure arithmetic instead of forcing a synchronous reflow each time.
+        this._invalidateRectCache = () => {
+            this._rectCacheValid = false;
+        };
+        if (typeof ResizeObserver !== "undefined") {
+            this._resizeObserver = new ResizeObserver(this._invalidateRectCache);
+            this._resizeObserver.observe(this._element);
+        }
+        if (typeof MutationObserver !== "undefined") {
+            this._mutationObserver = new MutationObserver(this._invalidateRectCache);
+            this._mutationObserver.observe(this._element, { attributes: true, childList: true, characterData: true, subtree: true });
+        }
+        if (typeof window !== "undefined") {
+            window.addEventListener("resize", this._invalidateRectCache);
+            window.addEventListener("scroll", this._invalidateRectCache, true);
+        }
+        this._observer = scene.onPointerObservable.add((pointerInfo) => this._onPointer(pointerInfo));
+    }
+    _onPointer(pointerInfo) {
+        const domName = _PointerTypeToDomEvent(pointerInfo.type);
+        if (!domName) {
+            return;
+        }
+        const pickInfo = pointerInfo.pickInfo;
+        if (!pickInfo || !pickInfo.hit || pickInfo.pickedMesh !== this._mesh) {
+            return;
+        }
+        if (this._backFaceCulling && this._isBackFace(pointerInfo)) {
+            return;
+        }
+        const uv = pickInfo.getTextureCoordinates();
+        if (!uv) {
+            return;
+        }
+        const rect = this._getRect(this._element);
+        const { x, y } = GetElementPixelFromUv(uv.x, uv.y, rect.width || this._element.offsetWidth, rect.height || this._element.offsetHeight, this._invertY);
+        this._dispatch(domName, rect.left + x, rect.top + y, pointerInfo);
+    }
+    _isBackFace(pointerInfo) {
+        const pickInfo = pointerInfo.pickInfo;
+        const normal = pickInfo.getNormal(true, true);
+        if (!normal || !pickInfo.pickedPoint) {
+            return false;
+        }
+        const camera = this._scene.activeCamera;
+        if (!camera) {
+            return false;
+        }
+        // The face is back-facing when its world normal points away from the camera-to-surface direction.
+        const toSurface = pickInfo.pickedPoint.subtract(camera.globalPosition);
+        return normal.dot(toSurface) > 0;
+    }
+    _dispatch(domName, clientX, clientY, pointerInfo) {
+        if (typeof PointerEvent === "undefined") {
+            return;
+        }
+        const sourceEvent = pointerInfo.event;
+        // document.elementFromPoint is unreliable here: the element is hosted inside the engine's rendering
+        // canvas (whose painted WebGL/WebGPU content covers the DOM children) and is marked `inert`, so the
+        // browser's own hit testing skips it. Resolve the deepest descendant under the mapped point manually
+        // from the laid-out subtree instead; synthetic dispatch still triggers listeners on inert elements.
+        const target = this._resolveTarget(clientX, clientY);
+        const init = {
+            bubbles: true,
+            cancelable: true,
+            clientX,
+            clientY,
+            button: sourceEvent.button ?? 0,
+            buttons: sourceEvent.buttons ?? 0,
+            pointerId: sourceEvent.pointerId ?? 1,
+            pointerType: sourceEvent.pointerType ?? "mouse",
+        };
+        target.dispatchEvent(new PointerEvent(domName, init));
+        const mouseName = _PointerToMouseEvent(domName);
+        if (mouseName) {
+            target.dispatchEvent(new MouseEvent(mouseName, init));
+        }
+        // The browser synthesizes a "click" from a native down/up pair, but synthetic mouse events do not,
+        // so we emit it ourselves: on pointerdown remember the target, then on pointerup dispatch a click
+        // when the release lands on the same element (matching native click semantics closely enough).
+        // Native browsers only synthesize "click" for the primary button, so gate on button 0.
+        if (domName === "pointerdown") {
+            this._downTarget = target;
+        }
+        else if (domName === "pointerup") {
+            if (this._downTarget === target && init.button === 0) {
+                target.dispatchEvent(new MouseEvent("click", init));
+            }
+            this._downTarget = null;
+        }
+    }
+    /**
+     * Resolves the deepest descendant of the hosted element whose layout box contains the given client point.
+     * @param clientX horizontal client coordinate
+     * @param clientY vertical client coordinate
+     * @returns the deepest matching element, or the hosted element itself when no descendant matches
+     */
+    _resolveTarget(clientX, clientY) {
+        let target = this._element;
+        let advanced = true;
+        while (advanced) {
+            advanced = false;
+            const children = target.children;
+            for (let i = children.length - 1; i >= 0; i--) {
+                const child = children[i];
+                const rect = this._getRect(child);
+                if (clientX >= rect.left && clientX <= rect.right && clientY >= rect.top && clientY <= rect.bottom) {
+                    target = child;
+                    advanced = true;
+                    break;
+                }
+            }
+        }
+        return target;
+    }
+    /**
+     * Returns the client rect of an element, served from a cache that is rebuilt only when layout may have
+     * changed (see the constructor). This keeps pointer routing free of per-event layout reads.
+     * @param element the element whose bounding rect is needed
+     * @returns the element's cached {@link DOMRect}
+     */
+    _getRect(element) {
+        if (!this._rectCacheValid) {
+            this._rectCache.clear();
+            this._rectCacheValid = true;
+        }
+        let rect = this._rectCache.get(element);
+        if (!rect) {
+            rect = element.getBoundingClientRect();
+            this._rectCache.set(element, rect);
+        }
+        return rect;
+    }
+    /**
+     * Detaches the manager and stops forwarding pointer events.
+     */
+    dispose() {
+        for (const type of _ContainedEventTypes) {
+            this._element.removeEventListener(type, this._containHandler);
+        }
+        if (this._resizeObserver) {
+            this._resizeObserver.disconnect();
+            this._resizeObserver = null;
+        }
+        if (this._mutationObserver) {
+            this._mutationObserver.disconnect();
+            this._mutationObserver = null;
+        }
+        if (typeof window !== "undefined") {
+            window.removeEventListener("resize", this._invalidateRectCache);
+            window.removeEventListener("scroll", this._invalidateRectCache, true);
+        }
+        this._rectCache.clear();
+        if (this._observer) {
+            this._scene.onPointerObservable.remove(this._observer);
+            this._observer = null;
+        }
+    }
+}
+function _PointerTypeToDomEvent(type) {
+    switch (type) {
+        case PointerEventTypes.POINTERDOWN:
+            return "pointerdown";
+        case PointerEventTypes.POINTERUP:
+            return "pointerup";
+        case PointerEventTypes.POINTERMOVE:
+            return "pointermove";
+        default:
+            return null;
+    }
+}
+function _PointerToMouseEvent(domName) {
+    switch (domName) {
+        case "pointerdown":
+            return "mousedown";
+        case "pointerup":
+            return "mouseup";
+        case "pointermove":
+            return "mousemove";
+        default:
+            return null;
+    }
+}
+// Synthetic event types we dispatch into the hosted element; they are contained at the host so they do
+// not bubble back into the engine's rendering canvas (see the constructor for the rationale).
+const _ContainedEventTypes = ["pointerdown", "pointerup", "pointermove", "mousedown", "mouseup", "mousemove", "click"];
+//# sourceMappingURL=htmlRaycastInteractionManager.js.map

package/Materials/Textures/HTML/htmlRaycastInteractionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlRaycastInteractionManager.js","sourceRoot":"","sources":["../../../../../../dev/core/src/Materials/Textures/HTML/htmlRaycastInteractionManager.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Scene } from \"../../../scene.pure\";\nimport { type AbstractMesh } from \"../../../Meshes/abstractMesh.pure\";\nimport { type HtmlTexture } from \"./htmlTexture\";\nimport { type Observer } from \"../../../Misc/observable.pure\";\nimport { type PointerInfo, PointerEventTypes } from \"../../../Events/pointerEvents\";\nimport { type Nullable } from \"../../../types\";\n\n// Attribution: the raycast/UV event-routing technique used here is prior art from\n// `three-html-render` (Palash Bansal, MIT) and Jake Archibald's `curved-markup` demo.\n// The implementation below is a clean-room rewrite against Babylon.js' own picking APIs.\n\n/**\n * Maps a UV coordinate sampled from an {@link HtmlTexture} to a pixel position inside the source element.\n *\n * When `invertY` is true (the default, matching {@link HtmlTexture}'s default upload orientation) the V\n * axis is flipped so that `v = 1` maps to the top of the element, matching the top-left origin used by\n * DOM layout.\n * @param u horizontal texture coordinate, normally in [0, 1]\n * @param v vertical texture coordinate, normally in [0, 1]\n * @param width element width in pixels\n * @param height element height in pixels\n * @param invertY whether the texture content is stored Y-inverted (default true)\n * @returns the pixel position `{ x, y }` within the element\n */\nexport function GetElementPixelFromUv(u: number, v: number, width: number, height: number, invertY: boolean = true): { x: number; y: number } {\n    return { x: u * width, y: (invertY ? 1 - v : v) * height };\n}\n\n/**\n * Options for {@link HtmlRaycastInteractionManager}.\n */\nexport interface IHtmlRaycastInteractionManagerOptions {\n    /** The DOM element that receives the forwarded pointer events (defaults to the texture's element). */\n    targetElement?: HTMLElement;\n    /** Whether hits on back-facing geometry are ignored (default true). */\n    backFaceCulling?: boolean;\n    /** Whether the texture content is stored Y-inverted, used when mapping UVs to element pixels (default true). */\n    invertY?: boolean;\n}\n\n/**\n * Routes Babylon pointer events to a live HTML element rendered through an {@link HtmlTexture}.\n *\n * On every pointer event the scene is picked; when the configured mesh is hit, the picked UV is mapped to\n * a pixel inside the source element and an equivalent DOM pointer (and mouse) event is dispatched there.\n * This works for arbitrary meshes (planes, boxes, curved surfaces) because it relies on UV coordinates\n * rather than a flat CSS overlay. For a perspective-correct overlay on planar surfaces, see\n * {@link HtmlInteractionManager}.\n */\nexport class HtmlRaycastInteractionManager {\n    private readonly _scene: Scene;\n    private readonly _mesh: AbstractMesh;\n    private readonly _element: HTMLElement;\n    private readonly _backFaceCulling: boolean;\n    private readonly _invertY: boolean;\n    private _observer: Nullable<Observer<PointerInfo>>;\n    private _downTarget: Nullable<EventTarget>;\n    private readonly _containHandler: (evt: Event) => void;\n    private readonly _rectCache = new Map<HTMLElement, DOMRect>();\n    private _rectCacheValid = false;\n    private readonly _invalidateRectCache: () => void;\n    private _resizeObserver: Nullable<ResizeObserver> = null;\n    private _mutationObserver: Nullable<MutationObserver> = null;\n\n    /**\n     * Creates a raycast interaction manager.\n     * @param scene the scene to listen to for pointer events\n     * @param texture the HTML texture whose element should receive the forwarded events\n     * @param mesh the mesh displaying the texture; only hits on this mesh are forwarded\n     * @param options optional configuration\n     */\n    constructor(scene: Scene, texture: HtmlTexture, mesh: AbstractMesh, options: IHtmlRaycastInteractionManagerOptions = {}) {\n        this._scene = scene;\n        this._mesh = mesh;\n        this._element = options.targetElement ?? texture.element;\n        this._backFaceCulling = options.backFaceCulling ?? true;\n        this._invertY = options.invertY ?? true;\n\n        // The hosted element is a child of the engine's rendering canvas, where Babylon's own input\n        // listeners live. The synthetic events we dispatch bubble, so without this they would reach the\n        // canvas and be re-interpreted as real input - moving the camera and re-entering this manager in a\n        // feedback loop. Stopping propagation at the host element keeps them inside the HTML subtree (so\n        // event delegation still works) while never leaking back to the engine.\n        this._containHandler = (evt: Event) => evt.stopPropagation();\n        for (const type of _ContainedEventTypes) {\n            this._element.addEventListener(type, this._containHandler);\n        }\n\n        // Resolving the target reads layout (getBoundingClientRect) for the element and its descendants on\n        // every pointer event. Cache those rects and only re-read them when layout can actually change - on\n        // size changes, DOM mutations, or viewport scroll/resize - so high-frequency pointermove events stay\n        // pure arithmetic instead of forcing a synchronous reflow each time.\n        this._invalidateRectCache = () => {\n            this._rectCacheValid = false;\n        };\n        if (typeof ResizeObserver !== \"undefined\") {\n            this._resizeObserver = new ResizeObserver(this._invalidateRectCache);\n            this._resizeObserver.observe(this._element);\n        }\n        if (typeof MutationObserver !== \"undefined\") {\n            this._mutationObserver = new MutationObserver(this._invalidateRectCache);\n            this._mutationObserver.observe(this._element, { attributes: true, childList: true, characterData: true, subtree: true });\n        }\n        if (typeof window !== \"undefined\") {\n            window.addEventListener(\"resize\", this._invalidateRectCache);\n            window.addEventListener(\"scroll\", this._invalidateRectCache, true);\n        }\n\n        this._observer = scene.onPointerObservable.add((pointerInfo) => this._onPointer(pointerInfo));\n    }\n\n    private _onPointer(pointerInfo: PointerInfo): void {\n        const domName = _PointerTypeToDomEvent(pointerInfo.type);\n        if (!domName) {\n            return;\n        }\n\n        const pickInfo = pointerInfo.pickInfo;\n        if (!pickInfo || !pickInfo.hit || pickInfo.pickedMesh !== this._mesh) {\n            return;\n        }\n\n        if (this._backFaceCulling && this._isBackFace(pointerInfo)) {\n            return;\n        }\n\n        const uv = pickInfo.getTextureCoordinates();\n        if (!uv) {\n            return;\n        }\n\n        const rect = this._getRect(this._element);\n        const { x, y } = GetElementPixelFromUv(uv.x, uv.y, rect.width || this._element.offsetWidth, rect.height || this._element.offsetHeight, this._invertY);\n\n        this._dispatch(domName, rect.left + x, rect.top + y, pointerInfo);\n    }\n\n    private _isBackFace(pointerInfo: PointerInfo): boolean {\n        const pickInfo = pointerInfo.pickInfo!;\n        const normal = pickInfo.getNormal(true, true);\n        if (!normal || !pickInfo.pickedPoint) {\n            return false;\n        }\n        const camera = this._scene.activeCamera;\n        if (!camera) {\n            return false;\n        }\n        // The face is back-facing when its world normal points away from the camera-to-surface direction.\n        const toSurface = pickInfo.pickedPoint.subtract(camera.globalPosition);\n        return normal.dot(toSurface) > 0;\n    }\n\n    private _dispatch(domName: string, clientX: number, clientY: number, pointerInfo: PointerInfo): void {\n        if (typeof PointerEvent === \"undefined\") {\n            return;\n        }\n\n        const sourceEvent = pointerInfo.event as Partial<PointerEvent>;\n        // document.elementFromPoint is unreliable here: the element is hosted inside the engine's rendering\n        // canvas (whose painted WebGL/WebGPU content covers the DOM children) and is marked `inert`, so the\n        // browser's own hit testing skips it. Resolve the deepest descendant under the mapped point manually\n        // from the laid-out subtree instead; synthetic dispatch still triggers listeners on inert elements.\n        const target = this._resolveTarget(clientX, clientY);\n\n        const init: PointerEventInit = {\n            bubbles: true,\n            cancelable: true,\n            clientX,\n            clientY,\n            button: sourceEvent.button ?? 0,\n            buttons: sourceEvent.buttons ?? 0,\n            pointerId: sourceEvent.pointerId ?? 1,\n            pointerType: sourceEvent.pointerType ?? \"mouse\",\n        };\n\n        target.dispatchEvent(new PointerEvent(domName, init));\n\n        const mouseName = _PointerToMouseEvent(domName);\n        if (mouseName) {\n            target.dispatchEvent(new MouseEvent(mouseName, init));\n        }\n\n        // The browser synthesizes a \"click\" from a native down/up pair, but synthetic mouse events do not,\n        // so we emit it ourselves: on pointerdown remember the target, then on pointerup dispatch a click\n        // when the release lands on the same element (matching native click semantics closely enough).\n        // Native browsers only synthesize \"click\" for the primary button, so gate on button 0.\n        if (domName === \"pointerdown\") {\n            this._downTarget = target;\n        } else if (domName === \"pointerup\") {\n            if (this._downTarget === target && init.button === 0) {\n                target.dispatchEvent(new MouseEvent(\"click\", init));\n            }\n            this._downTarget = null;\n        }\n    }\n\n    /**\n     * Resolves the deepest descendant of the hosted element whose layout box contains the given client point.\n     * @param clientX horizontal client coordinate\n     * @param clientY vertical client coordinate\n     * @returns the deepest matching element, or the hosted element itself when no descendant matches\n     */\n    private _resolveTarget(clientX: number, clientY: number): HTMLElement {\n        let target: HTMLElement = this._element;\n        let advanced = true;\n        while (advanced) {\n            advanced = false;\n            const children = target.children;\n            for (let i = children.length - 1; i >= 0; i--) {\n                const child = children[i] as HTMLElement;\n                const rect = this._getRect(child);\n                if (clientX >= rect.left && clientX <= rect.right && clientY >= rect.top && clientY <= rect.bottom) {\n                    target = child;\n                    advanced = true;\n                    break;\n                }\n            }\n        }\n        return target;\n    }\n\n    /**\n     * Returns the client rect of an element, served from a cache that is rebuilt only when layout may have\n     * changed (see the constructor). This keeps pointer routing free of per-event layout reads.\n     * @param element the element whose bounding rect is needed\n     * @returns the element's cached {@link DOMRect}\n     */\n    private _getRect(element: HTMLElement): DOMRect {\n        if (!this._rectCacheValid) {\n            this._rectCache.clear();\n            this._rectCacheValid = true;\n        }\n        let rect = this._rectCache.get(element);\n        if (!rect) {\n            rect = element.getBoundingClientRect();\n            this._rectCache.set(element, rect);\n        }\n        return rect;\n    }\n\n    /**\n     * Detaches the manager and stops forwarding pointer events.\n     */\n    public dispose(): void {\n        for (const type of _ContainedEventTypes) {\n            this._element.removeEventListener(type, this._containHandler);\n        }\n        if (this._resizeObserver) {\n            this._resizeObserver.disconnect();\n            this._resizeObserver = null;\n        }\n        if (this._mutationObserver) {\n            this._mutationObserver.disconnect();\n            this._mutationObserver = null;\n        }\n        if (typeof window !== \"undefined\") {\n            window.removeEventListener(\"resize\", this._invalidateRectCache);\n            window.removeEventListener(\"scroll\", this._invalidateRectCache, true);\n        }\n        this._rectCache.clear();\n        if (this._observer) {\n            this._scene.onPointerObservable.remove(this._observer);\n            this._observer = null;\n        }\n    }\n}\n\nfunction _PointerTypeToDomEvent(type: number): Nullable<string> {\n    switch (type) {\n        case PointerEventTypes.POINTERDOWN:\n            return \"pointerdown\";\n        case PointerEventTypes.POINTERUP:\n            return \"pointerup\";\n        case PointerEventTypes.POINTERMOVE:\n            return \"pointermove\";\n        default:\n            return null;\n    }\n}\n\nfunction _PointerToMouseEvent(domName: string): Nullable<string> {\n    switch (domName) {\n        case \"pointerdown\":\n            return \"mousedown\";\n        case \"pointerup\":\n            return \"mouseup\";\n        case \"pointermove\":\n            return \"mousemove\";\n        default:\n            return null;\n    }\n}\n\n// Synthetic event types we dispatch into the hosted element; they are contained at the host so they do\n// not bubble back into the engine's rendering canvas (see the constructor for the rationale).\nconst _ContainedEventTypes = [\"pointerdown\", \"pointerup\", \"pointermove\", \"mousedown\", \"mouseup\", \"mousemove\", \"click\"] as const;\n"]}

package/Materials/Textures/HTML/htmlTexture.d.ts

@@ -0,0 +1,148 @@
+/** This module has no top-level side effects: the engine extension it depends on is registered lazily from the constructor */
+import { type Nullable } from "../../../types.js";
+import { BaseTexture } from "../baseTexture.pure.js";
+import { Matrix } from "../../../Maths/math.vector.pure.js";
+import { Observable } from "../../../Misc/observable.pure.js";
+import { type AbstractEngine } from "../../../Engines/abstractEngine.pure.js";
+import { type InternalTexture } from "../internalTexture.js";
+import { type Scene } from "../../../scene.pure.js";
+/**
+ * Detects whether the engine can upload an HTML element through the native (or polyfilled) WICG
+ * HTML-in-Canvas API, without emitting any warning. Used to decide whether the SVG fallback is needed.
+ * @param engine defines the engine to test
+ * @returns true when the WICG upload API is available for this engine
+ */
+export declare function IsHtmlInCanvasUploadSupported(engine: AbstractEngine): boolean;
+/**
+ * Uploads a live HTML element (or a captured ElementImage) into an existing 2D texture using the WICG
+ * HTML-in-Canvas API (https://github.com/WICG/html-in-canvas).
+ *
+ * This is a side-effect-free helper - it is only reachable when {@link HtmlTexture} (or a direct caller)
+ * is imported, so it adds nothing to bundles that do not use it. It relies on
+ * `WebGLRenderingContext.texElementImage2D` (WebGL) or `GPUQueue.copyElementImageToTexture` (WebGPU),
+ * available either natively (behind chrome://flags/#canvas-draw-element) or through the
+ * three-html-render polyfill.
+ * @param engine defines the engine that owns the texture
+ * @param texture defines the internal texture to update
+ * @param element defines the source HTML element (or captured ElementImage) to upload
+ * @param invertY defines if data must be stored with Y axis inverted (true by default)
+ * @param config defines an optional source rectangle and sizing configuration
+ * @returns true if the upload succeeded, false otherwise (e.g. the API is unavailable)
+ */
+export declare function UploadHtmlElementToTexture(engine: AbstractEngine, texture: Nullable<InternalTexture>, element: Element | ElementImage, invertY?: boolean, config?: WebGLCopyElementImageConfig): boolean;
+/**
+ * Defines the options used to create an {@link HtmlTexture}.
+ */
+export interface IHtmlTextureOptions {
+    /** Defines the width of the texture in pixels (defaults to the element's offset width, then 256). */
+    width?: number;
+    /** Defines the height of the texture in pixels (defaults to the element's offset height, then 256). */
+    height?: number;
+    /** Defines whether mip maps should be created or not (default: false). */
+    generateMipMaps?: boolean;
+    /** Defines the sampling mode of the texture (default: TEXTURE_BILINEAR_SAMPLINGMODE). */
+    samplingMode?: number;
+    /** Defines the associated texture format (default: TEXTUREFORMAT_RGBA). */
+    format?: number;
+    /** Defines whether the texture is automatically updated when the host canvas emits a paint event (default: true). */
+    autoUpdate?: boolean;
+    /**
+     * Defines whether to fall back to an SVG `<foreignObject>` rasterization when the native WICG
+     * HTML-in-Canvas API is unavailable (default: true). The fallback works in any browser but only
+     * captures same-origin, inline-styled content as a static snapshot (see the documentation for caveats).
+     */
+    useSvgFallback?: boolean;
+    /** Defines the engine instance to use the texture with. Not mandatory if a scene is provided. */
+    engine?: Nullable<AbstractEngine>;
+    /** Defines the scene the texture belongs to. Not mandatory if an engine is provided. */
+    scene?: Nullable<Scene>;
+}
+/**
+ * A texture whose content is rendered from a live HTML element using the WICG HTML-in-Canvas API
+ * (https://github.com/WICG/html-in-canvas).
+ *
+ * The element is hosted as a child of the engine's rendering canvas (which is marked `layoutsubtree`) so
+ * the browser can lay it out and snapshot it; the WICG API requires the source element to be a direct
+ * child of the canvas whose context performs the upload. Content is uploaded through
+ * `WebGLRenderingContext.texElementImage2D` (WebGL) or `GPUQueue.copyElementImageToTexture` (WebGPU),
+ * available either natively (behind chrome://flags/#canvas-draw-element) or via the three-html-render
+ * polyfill (https://github.com/repalash/three-html-render). When neither is present, a built-in SVG
+ * `<foreignObject>` fallback is used instead (see `useSvgFallback`).
+ *
+ * As with {@link HtmlElementTexture}, updates are not automatic unless `autoUpdate` is enabled; in
+ * that case the texture refreshes whenever the host canvas reports a paint change.
+ */
+export declare class HtmlTexture extends BaseTexture {
+    /**
+     * The HTML element rendered into the texture.
+     */
+    readonly element: HTMLElement;
+    /**
+     * The element that hosts {@link element} in the document. This is the engine's rendering canvas when one
+     * is available (required by the WICG API, which can only capture the element from that canvas), or a
+     * hidden helper `<div>` otherwise - in which case only the SVG fallback can render.
+     */
+    readonly host: Nullable<HTMLElement>;
+    /**
+     * Observable triggered once the texture has been rendered for the first time.
+     */
+    onLoadObservable: Observable<HtmlTexture>;
+    private static readonly _DefaultOptions;
+    private readonly _format;
+    private readonly _generateMipMaps;
+    private readonly _samplingMode;
+    private readonly _useSvgFallback;
+    private readonly _textureMatrix;
+    private _paintHandler;
+    private _ownsHost;
+    private _originalParent;
+    private _originalNextSibling;
+    private _addedInert;
+    private _width;
+    private _height;
+    /**
+     * Instantiates an HtmlTexture from an HTML element.
+     * @param name Defines the name of the texture
+     * @param element Defines the HTML element to render into the texture
+     * @param options Defines the texture creation options
+     */
+    constructor(name: string, element: HTMLElement, options: IHtmlTextureOptions);
+    private _createHost;
+    private _createInternalTexture;
+    /**
+     * @returns the texture matrix used in most of the material.
+     */
+    getTextureMatrix(): Matrix;
+    /**
+     * Requests the host canvas to emit a paint event on the next rendering update. When auto-update is
+     * enabled, this triggers a texture refresh in sync with the DOM. Falls back to an immediate update
+     * when the WICG API is not available.
+     */
+    requestUpdate(): void;
+    /**
+     * Updates the content of the texture from the current state of the HTML element.
+     * @param invertY Defines whether the texture should be inverted on Y (true by default)
+     */
+    update(invertY?: boolean): void;
+    /**
+     * Renders the element through an SVG `<foreignObject>` snapshot and uploads it to the texture. This
+     * fallback works in any browser but only captures same-origin, inline-styled content as a static image.
+     * @param engine defines the engine that owns the texture
+     * @param invertY defines whether the texture should be inverted on Y
+     */
+    private _updateFromSvgFallback;
+    /**
+     * Serializes the element into an SVG `<foreignObject>` data URL sized to the texture.
+     * @returns a data URL, or null if serialization failed
+     */
+    private _buildSvgDataUrl;
+    /**
+     * Gets the current class name of the texture useful for serialization or dynamic coding.
+     * @returns "HtmlTexture"
+     */
+    getClassName(): string;
+    /**
+     * Dispose the texture and release its associated resources.
+     */
+    dispose(): void;
+}