@iwsdk/core 0.1.0

package/dist/ui/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * UI toolkit integration: spatial and screen‑space panels, DOM‑like queries, and behaviors.
+ *
+ * @packageDocumentation
+ * @category UI
+ */
+export { UIKitDocument } from './document.js';
+export { PanelUI, PanelDocument, PanelUISystem } from './ui.js';
+export type { PanelUIProps } from './ui.js';
+export * from './follow.js';
+export * from './screenspace.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}

package/dist/ui/screenspace.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+/**
+ * CSS‑like screen‑space layout for a {@link PanelUI}.
+ *
+ * @remarks
+ * When XR is not presenting, the panel is re‑parented under the active camera and positioned
+ * in pixels using CSS‑like expressions for `top`/`left`/`bottom`/`right`, with `width`/`height`
+ * specified in any CSS units supported by the browser (e.g. `px`, `vw`, `vh`, `%`, `em`).
+ *
+ * On XR session start, the panel is automatically returned to world space.
+ *
+ * All size inputs are ultimately converted to meters using the camera frustum at `zOffset`.
+ *
+ * @example Place a panel at bottom‑right, 40% width, auto height
+ * ```ts
+ * entity.addComponent(PanelUI, { config: '/ui/menu.json' })
+ * entity.addComponent(ScreenSpace, {
+ *   width: '40vw',
+ *   height: 'auto',
+ *   bottom: '24px',
+ *   right: '24px',
+ *   zOffset: 0.25,
+ * })
+ * ```
+ *
+ * @category UI
+ */
+export declare const ScreenSpace: import("elics").Component<{
+    /** CSS size expression for height (e.g., `240px`, `40vh`, `auto`). */
+    height: {
+        type: Types.String;
+        default: string;
+    };
+    /** CSS size expression for width (e.g., `480px`, `40vw`, `auto`). */
+    width: {
+        type: Types.String;
+        default: string;
+    };
+    /** CSS absolute `top` position (pixels/percent/vh) or `auto`. */
+    top: {
+        type: Types.String;
+        default: string;
+    };
+    /** CSS absolute `bottom` position (pixels/percent/vh) or `auto`. */
+    bottom: {
+        type: Types.String;
+        default: string;
+    };
+    /** CSS absolute `left` position (pixels/percent/vw) or `auto`. */
+    left: {
+        type: Types.String;
+        default: string;
+    };
+    /** CSS absolute `right` position (pixels/percent/vw) or `auto`. */
+    right: {
+        type: Types.String;
+        default: string;
+    };
+    /** Distance in meters in front of the camera’s near plane. */
+    zOffset: {
+        type: Types.Float32;
+        default: number;
+    };
+}>;
+declare const ScreenSpaceUISystem_base: import("elics").SystemConstructor<import("elics").SystemSchema, {
+    panels: {
+        required: (import("elics").Component<{
+            config: {
+                type: Types.String;
+                default: string;
+            };
+            maxWidth: {
+                type: Types.Float32;
+                default: number;
+            };
+            maxHeight: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }> | import("elics").Component<{
+            /** CSS size expression for height (e.g., `240px`, `40vh`, `auto`). */
+            height: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS size expression for width (e.g., `480px`, `40vw`, `auto`). */
+            width: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `top` position (pixels/percent/vh) or `auto`. */
+            top: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `bottom` position (pixels/percent/vh) or `auto`. */
+            bottom: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `left` position (pixels/percent/vw) or `auto`. */
+            left: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `right` position (pixels/percent/vw) or `auto`. */
+            right: {
+                type: Types.String;
+                default: string;
+            };
+            /** Distance in meters in front of the camera’s near plane. */
+            zOffset: {
+                type: Types.Float32;
+                default: number;
+            };
+        }>)[];
+    };
+}, import("../ecs/world.js").World, import("../ecs/system.js").System<import("elics").SystemSchema, {
+    panels: {
+        required: (import("elics").Component<{
+            config: {
+                type: Types.String;
+                default: string;
+            };
+            maxWidth: {
+                type: Types.Float32;
+                default: number;
+            };
+            maxHeight: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }> | import("elics").Component<{
+            /** CSS size expression for height (e.g., `240px`, `40vh`, `auto`). */
+            height: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS size expression for width (e.g., `480px`, `40vw`, `auto`). */
+            width: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `top` position (pixels/percent/vh) or `auto`. */
+            top: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `bottom` position (pixels/percent/vh) or `auto`. */
+            bottom: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `left` position (pixels/percent/vw) or `auto`. */
+            left: {
+                type: Types.String;
+                default: string;
+            };
+            /** CSS absolute `right` position (pixels/percent/vw) or `auto`. */
+            right: {
+                type: Types.String;
+                default: string;
+            };
+            /** Distance in meters in front of the camera’s near plane. */
+            zOffset: {
+                type: Types.Float32;
+                default: number;
+            };
+        }>)[];
+    };
+}>>;
+/**
+ * Positions {@link PanelUI} documents relative to the camera with CSS‑like semantics.
+ *
+ * @remarks
+ * - Converts CSS units to pixels using temporary DOM nodes, then maps pixels to meters at
+ *   a camera‑relative plane given by `zOffset`.
+ * - Automatically toggles between screen‑space (under the camera) and world‑space depending on
+ *   `renderer.xr.isPresenting`.
+ * - Sets {@link UIKitDocument.setTargetDimensions} so that the UI scales to the requested size
+ *   without distorting aspect ratio.
+ *
+ * @category UI
+ */
+export declare class ScreenSpaceUISystem extends ScreenSpaceUISystem_base {
+    private layoutHelpers;
+    private resized;
+    /** Prepare hidden DOM helpers and resize listener. */
+    init(): void;
+    /** Move panels between world and screen space and recompute layout on changes. */
+    update(): void;
+    /** Compute pixel size/position and apply camera‑relative transform. */
+    private calculateLayout;
+    /**
+     * Evaluate CSS expressions for width/height using a temporary DOM node.
+     * Returns pixel values from `window.getComputedStyle`.
+     */
+    private getComputedDimensionValues;
+    /** Evaluate CSS absolute positioning and return `top`/`left` in pixels. */
+    private getComputedPositionValues;
+}
+export {};
+//# sourceMappingURL=screenspace.d.ts.map

package/dist/ui/screenspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenspace.d.ts","sourceRoot":"","sources":["../../src/ui/screenspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAyC,MAAM,iBAAiB,CAAC;AAK/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW;IAGpB,sEAAsE;;;;;IAEtE,qEAAqE;;;;;IAErE,iEAAiE;;;;;IAEjE,oEAAoE;;;;;IAEpE,kEAAkE;;;;;IAElE,mEAAmE;;;;;IAEnE,8DAA8D;;;;;EAIjE,CAAC;;;;;;;;;;;;;;;;;;;;;;YAhBE,sEAAsE;;;;;YAEtE,qEAAqE;;;;;YAErE,iEAAiE;;;;;YAEjE,oEAAoE;;;;;YAEpE,kEAAkE;;;;;YAElE,mEAAmE;;;;;YAEnE,8DAA8D;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAZ9D,sEAAsE;;;;;YAEtE,qEAAqE;;;;;YAErE,iEAAiE;;;;;YAEjE,oEAAoE;;;;;YAEpE,kEAAkE;;;;;YAElE,mEAAmE;;;;;YAEnE,8DAA8D;;;;;;;;AAKlE;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,wBAEvC;IACA,OAAO,CAAC,aAAa,CAKnB;IACF,OAAO,CAAC,OAAO,CAAQ;IAEvB,sDAAsD;IACtD,IAAI;IAoBJ,kFAAkF;IAClF,MAAM,IAAI,IAAI;IA8Bd,uEAAuE;IACvE,OAAO,CAAC,eAAe;IAmEvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAgBlC,2EAA2E;IAC3E,OAAO,CAAC,yBAAyB;CAwBlC"}

package/dist/ui/screenspace.js

@@ -0,0 +1,215 @@
+import { createSystem } from '../ecs/system.js';
+import '../ecs/world.js';
+import { createComponent, Types } from 'elics';
+import '../ecs/component-registry.js';
+import '../runtime/three.js';
+import { PanelUI, PanelDocument } from './ui.js';
+import { MathUtils } from 'three';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * CSS‑like screen‑space layout for a {@link PanelUI}.
+ *
+ * @remarks
+ * When XR is not presenting, the panel is re‑parented under the active camera and positioned
+ * in pixels using CSS‑like expressions for `top`/`left`/`bottom`/`right`, with `width`/`height`
+ * specified in any CSS units supported by the browser (e.g. `px`, `vw`, `vh`, `%`, `em`).
+ *
+ * On XR session start, the panel is automatically returned to world space.
+ *
+ * All size inputs are ultimately converted to meters using the camera frustum at `zOffset`.
+ *
+ * @example Place a panel at bottom‑right, 40% width, auto height
+ * ```ts
+ * entity.addComponent(PanelUI, { config: '/ui/menu.json' })
+ * entity.addComponent(ScreenSpace, {
+ *   width: '40vw',
+ *   height: 'auto',
+ *   bottom: '24px',
+ *   right: '24px',
+ *   zOffset: 0.25,
+ * })
+ * ```
+ *
+ * @category UI
+ */
+const ScreenSpace = createComponent('ScreenSpace', {
+    /** CSS size expression for height (e.g., `240px`, `40vh`, `auto`). */
+    height: { type: Types.String, default: 'auto' },
+    /** CSS size expression for width (e.g., `480px`, `40vw`, `auto`). */
+    width: { type: Types.String, default: 'auto' },
+    /** CSS absolute `top` position (pixels/percent/vh) or `auto`. */
+    top: { type: Types.String, default: 'auto' },
+    /** CSS absolute `bottom` position (pixels/percent/vh) or `auto`. */
+    bottom: { type: Types.String, default: 'auto' },
+    /** CSS absolute `left` position (pixels/percent/vw) or `auto`. */
+    left: { type: Types.String, default: 'auto' },
+    /** CSS absolute `right` position (pixels/percent/vw) or `auto`. */
+    right: { type: Types.String, default: 'auto' },
+    /** Distance in meters in front of the camera’s near plane. */
+    zOffset: { type: Types.Float32, default: 0.2 },
+}, 'Component for screen-space UI positioning');
+/**
+ * Positions {@link PanelUI} documents relative to the camera with CSS‑like semantics.
+ *
+ * @remarks
+ * - Converts CSS units to pixels using temporary DOM nodes, then maps pixels to meters at
+ *   a camera‑relative plane given by `zOffset`.
+ * - Automatically toggles between screen‑space (under the camera) and world‑space depending on
+ *   `renderer.xr.isPresenting`.
+ * - Sets {@link UIKitDocument.setTargetDimensions} so that the UI scales to the requested size
+ *   without distorting aspect ratio.
+ *
+ * @category UI
+ */
+class ScreenSpaceUISystem extends createSystem({
+    panels: { required: [PanelUI, PanelDocument, ScreenSpace] },
+}) {
+    constructor() {
+        super(...arguments);
+        this.layoutHelpers = {
+            dimensionContainer: document.createElement('div'),
+            positionContainer: document.createElement('div'),
+            dimensionElement: document.createElement('div'),
+            positionElement: document.createElement('div'),
+        };
+        this.resized = true;
+    }
+    /** Prepare hidden DOM helpers and resize listener. */
+    init() {
+        this.layoutHelpers.dimensionContainer.style.width = '100vw';
+        this.layoutHelpers.dimensionContainer.style.height = '100vh';
+        this.layoutHelpers.dimensionContainer.style.position = 'absolute';
+        this.layoutHelpers.dimensionContainer.style.visibility = 'hidden';
+        this.layoutHelpers.positionContainer.style.width = '100vw';
+        this.layoutHelpers.positionContainer.style.height = '100vh';
+        this.layoutHelpers.positionContainer.style.position = 'relative';
+        this.layoutHelpers.positionContainer.style.visibility = 'hidden';
+        window.addEventListener('resize', () => {
+            this.resized = true;
+        }, false);
+    }
+    /** Move panels between world and screen space and recompute layout on changes. */
+    update() {
+        this.queries.panels.entities.forEach((entity) => {
+            const parent = entity.object3D;
+            const document = PanelDocument.data.document[entity.index];
+            if (!document) {
+                return;
+            } // Skip if UI not loaded yet
+            const panelInScreenSpace = document.parent === this.camera;
+            if (this.renderer.xr.isPresenting && panelInScreenSpace) {
+                // Move back to world space when entering XR
+                parent === null || parent === void 0 ? void 0 : parent.add(document);
+                // Reset position that were set during screen space layout
+                document.position.set(0, 0, 0);
+            }
+            else if (!this.renderer.xr.isPresenting && !panelInScreenSpace) {
+                // Move to screen space when not in XR
+                this.camera.add(document);
+                this.calculateLayout(entity);
+            }
+            else if (panelInScreenSpace && this.resized) {
+                // Recalculate layout on resize
+                this.calculateLayout(entity);
+                this.resized = false;
+            }
+        });
+    }
+    /** Compute pixel size/position and apply camera‑relative transform. */
+    calculateLayout(entity) {
+        const document = PanelDocument.data.document[entity.index];
+        const computedSize = document === null || document === void 0 ? void 0 : document.computedSize;
+        if (document && computedSize) {
+            const widthExp = entity.getValue(ScreenSpace, 'width');
+            const heightExp = entity.getValue(ScreenSpace, 'height');
+            const top = entity.getValue(ScreenSpace, 'top');
+            const bottom = entity.getValue(ScreenSpace, 'bottom');
+            const left = entity.getValue(ScreenSpace, 'left');
+            const right = entity.getValue(ScreenSpace, 'right');
+            const zOffset = entity.getValue(ScreenSpace, 'zOffset');
+            // Get desired dimensions in screen pixels
+            const { height: hPx, width: wPx } = this.getComputedDimensionValues(widthExp, heightExp);
+            // Convert UIKit dimensions to world space units (UIKit uses cm units)
+            const uiWidthInWorldUnits = computedSize.width / 100;
+            const uiHeightInWorldUnits = computedSize.height / 100;
+            // Screen dimensions
+            const W = this.renderer.domElement.clientWidth;
+            const H = this.renderer.domElement.clientHeight;
+            // Calculate world-to-pixel conversion for screen space at zOffset
+            const vFOV = MathUtils.degToRad(this.camera.fov);
+            const worldHeightAtZ = 2 * Math.tan(vFOV / 2) * zOffset;
+            const worldPerPixel = worldHeightAtZ / H;
+            // Calculate desired world space dimensions
+            const targetWorldWidth = wPx * worldPerPixel;
+            const targetWorldHeight = hPx * worldPerPixel;
+            // Set target dimensions on UIKitDocument - this will trigger reactive scaling
+            document.setTargetDimensions(targetWorldWidth, targetWorldHeight);
+            // Get final scaled dimensions for positioning
+            const finalScale = document.scale.x; // UIKitDocument sets uniform scale
+            const usedWpx = (uiWidthInWorldUnits * finalScale) / worldPerPixel;
+            const usedHpx = (uiHeightInWorldUnits * finalScale) / worldPerPixel;
+            // Calculate position based on CSS-like positioning
+            const { top: computedTop, left: computedLeft } = this.getComputedPositionValues(usedWpx, usedHpx, {
+                top,
+                bottom,
+                left,
+                right,
+            });
+            // Convert screen position to camera-relative world position
+            const centerXpx = computedLeft + usedWpx / 2;
+            const centerYpx = H - computedTop - usedHpx / 2;
+            const camX = (centerXpx - W / 2) * worldPerPixel;
+            const camY = (centerYpx - H / 2) * worldPerPixel;
+            const camZ = -zOffset;
+            // Position the UIKitDocument in camera space
+            document.position.set(camX, camY, camZ);
+        }
+    }
+    /**
+     * Evaluate CSS expressions for width/height using a temporary DOM node.
+     * Returns pixel values from `window.getComputedStyle`.
+     */
+    getComputedDimensionValues(widthExp, heightExp) {
+        const { dimensionElement: element, dimensionContainer: container } = this.layoutHelpers;
+        document.body.appendChild(container);
+        element.style.width = widthExp;
+        element.style.height = heightExp;
+        container.appendChild(element);
+        const pixelValues = window.getComputedStyle(element);
+        const result = {
+            width: parseFloat(pixelValues.width),
+            height: parseFloat(pixelValues.height),
+        };
+        document.body.removeChild(container);
+        return result;
+    }
+    /** Evaluate CSS absolute positioning and return `top`/`left` in pixels. */
+    getComputedPositionValues(widthPx, heightPx, { top = 'auto', bottom = 'auto', left = 'auto', right = 'auto' }) {
+        const { positionElement: element, positionContainer: container } = this.layoutHelpers;
+        document.body.appendChild(container);
+        element.style.position = 'absolute';
+        element.style.width = `${widthPx}px`;
+        element.style.height = `${heightPx}px`;
+        element.style.top = top;
+        element.style.bottom = bottom;
+        element.style.left = left;
+        element.style.right = right;
+        container.appendChild(element);
+        const pixelValues = window.getComputedStyle(element);
+        const result = {
+            top: parseFloat(pixelValues.top),
+            left: parseFloat(pixelValues.left),
+        };
+        document.body.removeChild(container);
+        return result;
+    }
+}
+
+export { ScreenSpace, ScreenSpaceUISystem };
+//# sourceMappingURL=screenspace.js.map

package/dist/ui/screenspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenspace.js","sources":["../../src/ui/screenspace.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/ui/ui.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Types } from '../ecs/index.js';
+/**
+ * Props accepted by the {@link PanelUI} component.
+ * @category UI
+ */
+export interface PanelUIProps {
+    /** Path to compiled UIKitML JSON. @example "/ui/settings.json" */
+    config: string;
+    /** Max panel width in meters. @defaultValue 1 */
+    maxWidth?: number;
+    /** Max panel height in meters. @defaultValue 1 */
+    maxHeight?: number;
+}
+/**
+ * Component for 3D panel UI elements with file‑based configuration.
+ *
+ * @remarks
+ * - Compile `.uikitml` → JSON using the UIKitML Vite plugin, then set {@link PanelUIProps.config}.
+ * - When parented to world space (default), {@link PanelUISystem} drives target dimensions from
+ *   {@link PanelUIProps.maxWidth} / {@link PanelUIProps.maxHeight} and accounts for world scale.
+ * - Pointer events are forwarded to the UI when `forwardHtmlEvents` is enabled.
+ * @category UI
+ * @see /getting-started/06-spatial-ui
+ */
+export declare const PanelUI: import("elics").Component<{
+    /** Path to .json file */
+    config: {
+        type: Types.String;
+        default: string;
+    };
+    /** Max width constraint */
+    maxWidth: {
+        type: Types.Float32;
+        default: number;
+    };
+    /** Max height constraint */
+    maxHeight: {
+        type: Types.Float32;
+        default: number;
+    };
+}>;
+/**
+ * Internal component containing the loaded UI document (a UIKitDocument `Group`).
+ * @category UI
+ * @hideineditor
+ */
+export declare const PanelDocument: import("elics").Component<{
+    document: {
+        type: Types.Object;
+        default: undefined;
+    };
+}>;
+declare const PanelUISystem_base: import("elics").SystemConstructor<{
+    /** When true, forwards HTML/DOM pointer events to the 3D UI. */
+    forwardHtmlEvents: {
+        type: Types.Boolean;
+        default: true;
+    };
+    /** Additional pre-built UI component libraries */
+    kits: {
+        type: Types.Object;
+        default: {};
+    };
+}, {
+    unconfiguredPanels: {
+        required: import("elics").Component<{
+            /** Path to .json file */
+            config: {
+                type: Types.String;
+                default: string;
+            };
+            /** Max width constraint */
+            maxWidth: {
+                type: Types.Float32;
+                default: number;
+            };
+            /** Max height constraint */
+            maxHeight: {
+                type: Types.Float32;
+                default: number;
+            };
+        }>[];
+        excluded: import("elics").Component<{
+            document: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }>[];
+    };
+    configuredPanels: {
+        required: (import("elics").Component<{
+            /** Path to .json file */
+            config: {
+                type: Types.String;
+                default: string;
+            };
+            /** Max width constraint */
+            maxWidth: {
+                type: Types.Float32;
+                default: number;
+            };
+            /** Max height constraint */
+            maxHeight: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }>)[];
+    };
+}, import("../ecs/world.js").World, import("../ecs/system.js").System<{
+    /** When true, forwards HTML/DOM pointer events to the 3D UI. */
+    forwardHtmlEvents: {
+        type: Types.Boolean;
+        default: true;
+    };
+    /** Additional pre-built UI component libraries */
+    kits: {
+        type: Types.Object;
+        default: {};
+    };
+}, {
+    unconfiguredPanels: {
+        required: import("elics").Component<{
+            /** Path to .json file */
+            config: {
+                type: Types.String;
+                default: string;
+            };
+            /** Max width constraint */
+            maxWidth: {
+                type: Types.Float32;
+                default: number;
+            };
+            /** Max height constraint */
+            maxHeight: {
+                type: Types.Float32;
+                default: number;
+            };
+        }>[];
+        excluded: import("elics").Component<{
+            document: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }>[];
+    };
+    configuredPanels: {
+        required: (import("elics").Component<{
+            /** Path to .json file */
+            config: {
+                type: Types.String;
+                default: string;
+            };
+            /** Max width constraint */
+            maxWidth: {
+                type: Types.Float32;
+                default: number;
+            };
+            /** Max height constraint */
+            maxHeight: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: Types.Object;
+                default: undefined;
+            };
+        }>)[];
+    };
+}>>;
+/**
+ * Renders and updates spatial UI panels and forwards pointer events.
+ *
+ * @remarks
+ * - Sets Three.js transparent sort to a stable painter order for UI readability.
+ * - When configured to forward HTML events, bridges DOM events into the 3D scene.
+ * - Continuously updates document target dimensions in world space.
+ * @category UI
+ */
+export declare class PanelUISystem extends PanelUISystem_base {
+    private htmlHandler?;
+    private vec3;
+    /** Configure transparent sort, set up DOM event forwarding, and reactive queries. */
+    init(): void;
+    /** Forward HTML events and tick loaded UIKit documents each frame. */
+    update(_delta: number): void;
+    /**
+     * Load and interpret the `PanelUI.config` JSON file, create a {@link UIKitDocument},
+     * attach it to the entity, and tag the entity with {@link PanelDocument}.
+     */
+    private loadPanel;
+    /** Remove, dispose, and detach the loaded {@link UIKitDocument} from the entity. */
+    private cleanupPanel;
+    /** Tear down forwarded event handling. */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=ui.d.ts.map