@energy8platform/game-engine 0.10.11 → 0.12.0

package/dist/react.cjs.js

@@ -23,6 +23,84 @@ function extend(components) {
 }
 
 const RESERVED = new Set(['children', 'key', 'ref']);
+/** Props handled by the reconciler as flex item config, not forwarded to components */
+const FLEX_ITEM_PROPS$1 = new Set(['flexGrow', 'flexShrink', 'layoutWidth', 'layoutHeight', 'alignSelf', 'flexExclude']);
+// ─── UI Component helpers ────────────────────────────────
+/**
+ * Extract a config object from React props.
+ * - Strips reserved keys (children, key, ref) and event props
+ * - Unfolds dash-notation into nested objects: `colors-default` → `{ colors: { default: ... } }`
+ */
+function extractConfig(props) {
+    const config = {};
+    for (const key in props) {
+        if (RESERVED.has(key) || FLEX_ITEM_PROPS$1.has(key) || isEventProp(key))
+            continue;
+        if (key.includes('-')) {
+            const parts = key.split('-');
+            const root = parts[0];
+            const nested = parts.slice(1).join('-');
+            if (!config[root] || typeof config[root] !== 'object') {
+                config[root] = {};
+            }
+            config[root][nested] = props[key];
+        }
+        else {
+            config[key] = props[key];
+        }
+    }
+    return config;
+}
+/**
+ * Diff two prop sets and return a config object with only changed values.
+ * Uses extractConfig format (dash-notation unfolded).
+ */
+function diffConfig(newProps, oldProps) {
+    const changed = {};
+    // New or changed props
+    for (const key in newProps) {
+        if (RESERVED.has(key) || FLEX_ITEM_PROPS$1.has(key) || isEventProp(key))
+            continue;
+        if (newProps[key] !== oldProps[key]) {
+            if (key.includes('-')) {
+                const parts = key.split('-');
+                const root = parts[0];
+                const nested = parts.slice(1).join('-');
+                if (!changed[root] || typeof changed[root] !== 'object') {
+                    changed[root] = {};
+                }
+                changed[root][nested] = newProps[key];
+            }
+            else {
+                changed[key] = newProps[key];
+            }
+        }
+    }
+    return changed;
+}
+/**
+ * Apply only event props from React props to a PixiJS instance.
+ */
+function applyEventProps(instance, newProps, oldProps = {}) {
+    // Remove old event handlers
+    for (const key in oldProps) {
+        if (!isEventProp(key) || key in newProps)
+            continue;
+        instance[REACT_TO_PIXI_EVENTS[key]] = null;
+    }
+    // Apply new/changed event handlers + onPress (component-level callback)
+    for (const key in newProps) {
+        if (key === 'onPress') {
+            instance.onPress = newProps[key];
+            continue;
+        }
+        if (!isEventProp(key))
+            continue;
+        if (newProps[key] !== oldProps[key]) {
+            instance[REACT_TO_PIXI_EVENTS[key]] = newProps[key];
+        }
+    }
+}
 const REACT_TO_PIXI_EVENTS = {
     onClick: 'onclick',
     onPointerDown: 'onpointerdown',
@@ -80,7 +158,7 @@ function setNestedValue(target, path, value) {
 function applyProps(instance, newProps, oldProps = {}) {
     // Remove old props not in newProps
     for (const key in oldProps) {
-        if (RESERVED.has(key) || key in newProps)
+        if (RESERVED.has(key) || FLEX_ITEM_PROPS$1.has(key) || key in newProps)
             continue;
         const pixiEvent = REACT_TO_PIXI_EVENTS[key];
         if (pixiEvent) {
@@ -99,7 +177,7 @@ function applyProps(instance, newProps, oldProps = {}) {
     }
     // Apply new props
     for (const key in newProps) {
-        if (RESERVED.has(key))
+        if (RESERVED.has(key) || FLEX_ITEM_PROPS$1.has(key))
             continue;
         const value = newProps[key];
         const pixiEvent = REACT_TO_PIXI_EVENTS[key];
@@ -125,6 +203,452 @@ function applyProps(instance, newProps, oldProps = {}) {
     }
 }
 
+// ─── Helpers ─────────────────────────────────────────────
+function normalizePadding(p) {
+    return typeof p === 'number' ? [p, p, p, p] : p;
+}
+/** Measure a child's size and bounds offset for layout purposes */
+function measureChild(child) {
+    const cfg = child._flexConfig;
+    if (cfg?.layoutWidth !== undefined && cfg?.layoutHeight !== undefined) {
+        return { w: cfg.layoutWidth, h: cfg.layoutHeight, ox: 0, oy: 0 };
+    }
+    // For FlexContainers, use their explicit size if set
+    if (child instanceof FlexContainer) {
+        const fc = child;
+        if (fc._explicitWidth > 0 && fc._explicitHeight > 0) {
+            return { w: fc._explicitWidth, h: fc._explicitHeight, ox: 0, oy: 0 };
+        }
+    }
+    // Use localBounds to get the true visual extent and origin offset.
+    // This handles children with non-zero anchors (e.g. Button, Label with centered text).
+    const bounds = child.getLocalBounds();
+    const w = cfg?.layoutWidth ?? bounds.width;
+    const h = cfg?.layoutHeight ?? bounds.height;
+    return { w, h, ox: bounds.x, oy: bounds.y };
+}
+function layoutLine(items, isRow, mainSize, justify, align, gap, crossOffset, crossSize) {
+    if (items.length === 0)
+        return;
+    // Compute total fixed main size and flex grow total
+    let totalFixed = 0;
+    let totalGrow = 0;
+    for (const item of items) {
+        const grow = item.child._flexConfig?.flexGrow ?? 0;
+        if (grow > 0) {
+            totalGrow += grow;
+        }
+        else {
+            totalFixed += isRow ? item.w : item.h;
+        }
+    }
+    const totalGap = gap * (items.length - 1);
+    const availableForFlex = Math.max(0, mainSize - totalFixed - totalGap);
+    // Resolve flex sizes
+    if (totalGrow > 0) {
+        for (const item of items) {
+            const grow = item.child._flexConfig?.flexGrow ?? 0;
+            if (grow > 0) {
+                const flexSize = (grow / totalGrow) * availableForFlex;
+                if (isRow) {
+                    item.w = flexSize;
+                    item.child.width = flexSize;
+                }
+                else {
+                    item.h = flexSize;
+                    item.child.height = flexSize;
+                }
+            }
+        }
+    }
+    // Shrink: if content overflows and mainSize is finite, shrink eligible items
+    if (totalGrow === 0 && mainSize > 0) {
+        const overflow = totalFixed + totalGap - mainSize;
+        if (overflow > 0) {
+            let totalShrinkable = 0;
+            for (const item of items) {
+                const shrink = item.child._flexConfig?.flexShrink ?? 1;
+                if (shrink > 0) {
+                    totalShrinkable += isRow ? item.w : item.h;
+                }
+            }
+            if (totalShrinkable > 0) {
+                for (const item of items) {
+                    const shrink = item.child._flexConfig?.flexShrink ?? 1;
+                    if (shrink > 0) {
+                        const itemMain = isRow ? item.w : item.h;
+                        const reduction = overflow * (itemMain / totalShrinkable);
+                        const newSize = Math.max(0, itemMain - reduction);
+                        if (isRow) {
+                            item.w = newSize;
+                            item.child.width = newSize;
+                        }
+                        else {
+                            item.h = newSize;
+                            item.child.height = newSize;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Calculate total main size after flex
+    let totalMain = totalGap;
+    for (const item of items) {
+        totalMain += isRow ? item.w : item.h;
+    }
+    // Justify: compute starting offset and extra spacing
+    let mainOffset = 0;
+    let extraGap = 0;
+    switch (justify) {
+        case 'start':
+            break;
+        case 'center':
+            mainOffset = Math.max(0, (mainSize - totalMain) / 2);
+            break;
+        case 'end':
+            mainOffset = Math.max(0, mainSize - totalMain);
+            break;
+        case 'space-between':
+            if (items.length > 1) {
+                extraGap = Math.max(0, (mainSize - totalMain + totalGap) / (items.length - 1)) - gap;
+            }
+            break;
+        case 'space-around':
+            if (items.length > 0) {
+                const totalSpace = Math.max(0, mainSize - totalMain + totalGap);
+                const segment = totalSpace / items.length;
+                mainOffset = segment / 2;
+                extraGap = segment - gap;
+            }
+            break;
+    }
+    // Position each item
+    let pos = mainOffset;
+    for (const item of items) {
+        const mainDim = isRow ? item.w : item.h;
+        const crossDim = isRow ? item.h : item.w;
+        // Cross-axis alignment (alignSelf overrides align)
+        const effectiveAlign = (item.child._flexConfig?.alignSelf && item.child._flexConfig.alignSelf !== 'auto')
+            ? item.child._flexConfig.alignSelf
+            : align;
+        let crossPos = crossOffset;
+        switch (effectiveAlign) {
+            case 'start':
+                break;
+            case 'center':
+                crossPos += (crossSize - crossDim) / 2;
+                break;
+            case 'end':
+                crossPos += crossSize - crossDim;
+                break;
+            case 'stretch':
+                if (isRow) {
+                    item.child.height = crossSize;
+                }
+                else {
+                    item.child.width = crossSize;
+                }
+                break;
+        }
+        // Compensate for local bounds offset (e.g. centered anchors)
+        if (isRow) {
+            item.child.x = pos - item.ox;
+            item.child.y = crossPos - item.oy;
+        }
+        else {
+            item.child.x = crossPos - item.ox;
+            item.child.y = pos - item.oy;
+        }
+        pos += mainDim + gap + extraGap;
+    }
+}
+// ─── FlexContainer ───────────────────────────────────────
+/**
+ * Lightweight flexbox-like layout container for PixiJS.
+ *
+ * Supports row/column direction, justify/align, gap, padding, wrapping,
+ * and flex-grow distribution. Zero external dependencies.
+ *
+ * @example
+ * ```ts
+ * const toolbar = new FlexContainer({
+ *   direction: 'row',
+ *   justifyContent: 'space-between',
+ *   alignItems: 'center',
+ *   gap: 16,
+ *   padding: 12,
+ * });
+ *
+ * toolbar.addFlexChild(button1);
+ * toolbar.addFlexChild(button2);
+ * toolbar.resize(800, 60);
+ * ```
+ */
+class FlexContainer extends pixi_js.Container {
+    __uiComponent = true;
+    _config;
+    _padding;
+    _maxWidth;
+    _maxHeight;
+    /** @internal */ _explicitWidth;
+    /** @internal */ _explicitHeight;
+    _layoutChildren = [];
+    _layoutDirty = true;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            direction: config.direction ?? 'row',
+            justifyContent: config.justifyContent ?? 'start',
+            alignItems: config.alignItems ?? 'start',
+            gap: config.gap ?? 0,
+            flexWrap: config.flexWrap ?? false,
+        };
+        this._padding = normalizePadding(config.padding ?? 0);
+        this._maxWidth = config.maxWidth ?? Infinity;
+        this._maxHeight = config.maxHeight ?? Infinity;
+        this._explicitWidth = config.width ?? 0;
+        this._explicitHeight = config.height ?? 0;
+    }
+    // ─── Public API ──────────────────────────────────────
+    /** Add a child with optional flex config. Also registers in flex layout. */
+    addFlexChild(child, flexConfig) {
+        if (flexConfig)
+            child._flexConfig = flexConfig;
+        if (!this._layoutChildren.includes(child)) {
+            this._layoutChildren.push(child);
+            this._layoutDirty = true;
+        }
+        super.addChild(child);
+        return this;
+    }
+    /** Remove a child from flex layout and display list */
+    removeFlexChild(child) {
+        const idx = this._layoutChildren.indexOf(child);
+        if (idx !== -1) {
+            this._layoutChildren.splice(idx, 1);
+            this._layoutDirty = true;
+        }
+        super.removeChild(child);
+        return this;
+    }
+    /** Remove all flex children */
+    clearFlexChildren() {
+        for (const child of this._layoutChildren) {
+            super.removeChild(child);
+        }
+        this._layoutChildren.length = 0;
+        this._layoutDirty = true;
+        return this;
+    }
+    /**
+     * Override addChild so children automatically participate in flex layout.
+     * This enables declarative usage from React JSX.
+     */
+    addChild(...children) {
+        for (const child of children) {
+            if (!this._layoutChildren.includes(child)) {
+                this._layoutChildren.push(child);
+                this._layoutDirty = true;
+            }
+        }
+        const result = super.addChild(...children);
+        if (this._layoutDirty)
+            this.updateLayout();
+        return result;
+    }
+    removeChild(...children) {
+        for (const child of children) {
+            const idx = this._layoutChildren.indexOf(child);
+            if (idx !== -1) {
+                this._layoutChildren.splice(idx, 1);
+                this._layoutDirty = true;
+            }
+        }
+        return super.removeChild(...children);
+    }
+    /** Get all flex layout children (read-only) */
+    get flexChildren() {
+        return this._layoutChildren;
+    }
+    /** Update the container size and recalculate layout */
+    resize(width, height) {
+        this._explicitWidth = width;
+        this._explicitHeight = height;
+        this._layoutDirty = true;
+        this.updateLayout();
+    }
+    /** Update layout direction */
+    setDirection(direction) {
+        this._config.direction = direction;
+        this._layoutDirty = true;
+    }
+    /** Update justifyContent */
+    setJustifyContent(justify) {
+        this._config.justifyContent = justify;
+        this._layoutDirty = true;
+    }
+    /** Update alignItems */
+    setAlignItems(align) {
+        this._config.alignItems = align;
+        this._layoutDirty = true;
+    }
+    /** Update gap */
+    setGap(gap) {
+        this._config.gap = gap;
+        this._layoutDirty = true;
+    }
+    /** Update padding */
+    setPadding(padding) {
+        this._padding = normalizePadding(padding);
+        this._layoutDirty = true;
+    }
+    /**
+     * Recalculate and apply layout positions for all children.
+     * Called automatically by `resize()`. Call manually after
+     * adding/removing children without resize.
+     */
+    updateLayout() {
+        this._layoutDirty = false;
+        const { direction, justifyContent, alignItems, gap, flexWrap } = this._config;
+        const [pt, pr, pb, pl] = this._padding;
+        const isRow = direction === 'row';
+        const contentW = this._explicitWidth > 0 ? this._explicitWidth - pl - pr : Infinity;
+        const contentH = this._explicitHeight > 0 ? this._explicitHeight - pt - pb : Infinity;
+        const mainLimit = isRow ? contentW : contentH;
+        const crossLimit = isRow ? contentH : contentW;
+        // Measure children (skip flexExclude — they position themselves)
+        const measured = [];
+        for (const child of this._layoutChildren) {
+            if (child._flexConfig?.flexExclude)
+                continue;
+            const { w, h, ox, oy } = measureChild(child);
+            measured.push({ child, w, h, ox, oy });
+        }
+        // Split into lines (if wrapping)
+        const lines = [];
+        if (flexWrap && mainLimit < Infinity) {
+            let currentLine = [];
+            let lineMain = 0;
+            for (const item of measured) {
+                const itemMain = isRow ? item.w : item.h;
+                const wouldBe = lineMain + (currentLine.length > 0 ? gap : 0) + itemMain;
+                if (currentLine.length > 0 && wouldBe > mainLimit) {
+                    lines.push(currentLine);
+                    currentLine = [item];
+                    lineMain = itemMain;
+                }
+                else {
+                    currentLine.push(item);
+                    lineMain = wouldBe;
+                }
+            }
+            if (currentLine.length > 0)
+                lines.push(currentLine);
+        }
+        else {
+            lines.push(measured);
+        }
+        // Compute cross size per line
+        const lineCrossSizes = lines.map((line) => {
+            let maxCross = 0;
+            for (const item of line) {
+                const cross = isRow ? item.h : item.w;
+                if (cross > maxCross)
+                    maxCross = cross;
+            }
+            return maxCross;
+        });
+        // Layout each line
+        let crossOffset = isRow ? pt : pl;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineCross = lineCrossSizes[i];
+            const mainStart = isRow ? pl : pt;
+            // Offset items by padding
+            const tempItems = line.map((item) => ({ ...item }));
+            // For single-line layouts, use the full available cross space for alignment;
+            // for multi-line (wrapping), each line gets its own measured cross size.
+            const effectiveCross = lines.length === 1 && crossLimit < Infinity
+                ? crossLimit
+                : (crossLimit < Infinity ? Math.min(lineCross, crossLimit) : lineCross);
+            layoutLine(tempItems, isRow, mainLimit < Infinity ? mainLimit : 0, mainLimit < Infinity ? justifyContent : 'start', alignItems, gap, crossOffset, effectiveCross);
+            // Apply main-axis padding offset
+            for (const item of tempItems) {
+                const origChild = line.find((l) => l.child === item.child);
+                origChild.child.x = item.child.x + (isRow ? mainStart : 0);
+                origChild.child.y = item.child.y + (isRow ? 0 : mainStart);
+            }
+            crossOffset += lineCross + gap;
+        }
+    }
+    /** Computed content size (after layout) */
+    getContentSize() {
+        if (this._layoutDirty)
+            this.updateLayout();
+        let maxX = 0;
+        let maxY = 0;
+        for (const child of this._layoutChildren) {
+            const { w, h } = measureChild(child);
+            maxX = Math.max(maxX, child.x + w);
+            maxY = Math.max(maxY, child.y + h);
+        }
+        const [, pr, pb] = this._padding;
+        return { width: maxX + pr, height: maxY + pb };
+    }
+    /** React reconciler update hook — applies changed config props */
+    updateConfig(changed) {
+        if ('direction' in changed)
+            this.setDirection(changed.direction);
+        if ('justifyContent' in changed)
+            this.setJustifyContent(changed.justifyContent);
+        if ('alignItems' in changed)
+            this.setAlignItems(changed.alignItems);
+        if ('gap' in changed)
+            this.setGap(changed.gap);
+        if ('padding' in changed)
+            this.setPadding(changed.padding);
+        if ('flexWrap' in changed) {
+            this._config.flexWrap = changed.flexWrap;
+            this._layoutDirty = true;
+        }
+        if ('width' in changed || 'height' in changed) {
+            this.resize(changed.width ?? this._explicitWidth, changed.height ?? this._explicitHeight);
+            return; // resize calls updateLayout
+        }
+        if (this._layoutDirty)
+            this.updateLayout();
+    }
+    destroy(options) {
+        this._layoutChildren.length = 0;
+        super.destroy(options);
+    }
+}
+
+/** Flex item prop names that should be forwarded to _flexConfig on the child */
+const FLEX_ITEM_PROPS = ['flexGrow', 'flexShrink', 'layoutWidth', 'layoutHeight', 'alignSelf', 'flexExclude'];
+/** Extract FlexItemConfig from props if any flex item props are present */
+function extractFlexItemConfig(props) {
+    let config;
+    for (const key of FLEX_ITEM_PROPS) {
+        if (key in props) {
+            if (!config)
+                config = {};
+            config[key] = props[key];
+        }
+    }
+    return config;
+}
+/** Apply flex item config to a child being added to a FlexContainer */
+function addChildToFlex(parent, child) {
+    const flexConfig = child._flexConfig;
+    if (flexConfig && Object.keys(flexConfig).length > 0) {
+        parent.addFlexChild(child, flexConfig);
+    }
+    else {
+        parent.addChild(child);
+    }
+}
 function toPascalCase(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
@@ -140,24 +664,50 @@ const hostConfig = {
             throw new Error(`[PixiReconciler] Unknown element "<${type}>". ` +
                 `Call extend({ ${name} }) before rendering.`);
         }
-        const instance = new Ctor();
-        applyProps(instance, props);
-        // Enable interactivity if any event prop is present
+        let instance;
+        if (Ctor.prototype.__uiComponent) {
+            // Config-based UI component: pass props as constructor config
+            const config = extractConfig(props);
+            instance = new Ctor(config);
+            applyEventProps(instance, props);
+        }
+        else {
+            // Standard PixiJS element
+            instance = new Ctor();
+            applyProps(instance, props);
+        }
         if (hasEventProps(props) && instance.eventMode === 'auto') {
             instance.eventMode = 'static';
         }
+        // Store flex item config for when this child is added to a FlexContainer parent
+        const flexItemConfig = extractFlexItemConfig(props);
+        if (flexItemConfig) {
+            instance._flexConfig = { ...instance._flexConfig, ...flexItemConfig };
+        }
         return instance;
     },
     createTextInstance() {
         throw new Error('[PixiReconciler] Text strings are not supported. Use a <text> element.');
     },
     appendInitialChild(parent, child) {
-        if (child instanceof pixi_js.Container)
-            parent.addChild(child);
+        if (child instanceof pixi_js.Container) {
+            if (parent instanceof FlexContainer) {
+                addChildToFlex(parent, child);
+            }
+            else {
+                parent.addChild(child);
+            }
+        }
     },
     appendChild(parent, child) {
-        if (child instanceof pixi_js.Container)
-            parent.addChild(child);
+        if (child instanceof pixi_js.Container) {
+            if (parent instanceof FlexContainer) {
+                addChildToFlex(parent, child);
+            }
+            else {
+                parent.addChild(child);
+            }
+        }
     },
     appendChildToContainer(container, child) {
         if (child instanceof pixi_js.Container)
@@ -192,7 +742,26 @@ const hostConfig = {
         }
     },
     commitUpdate(instance, _updatePayload, _type, oldProps, newProps) {
-        applyProps(instance, newProps, oldProps);
+        if (instance.__uiComponent && typeof instance.updateConfig === 'function') {
+            const changed = diffConfig(newProps, oldProps);
+            if (Object.keys(changed).length > 0) {
+                instance.updateConfig(changed);
+            }
+            applyEventProps(instance, newProps, oldProps);
+        }
+        else {
+            applyProps(instance, newProps, oldProps);
+        }
+        // Update flex item config if parent is FlexContainer
+        const newFlexConfig = extractFlexItemConfig(newProps);
+        const oldFlexConfig = extractFlexItemConfig(oldProps);
+        if (newFlexConfig || oldFlexConfig) {
+            instance._flexConfig = { ...instance._flexConfig, ...newFlexConfig };
+            // Trigger parent relayout
+            if (instance.parent instanceof FlexContainer) {
+                instance.parent.updateLayout();
+            }
+        }
         if (hasEventProps(newProps) && instance.eventMode === 'auto') {
             instance.eventMode = 'static';
         }
@@ -263,37 +832,2280 @@ function createPixiRoot(container) {
 }
 
 /**
- * Register all standard PixiJS display objects for JSX use.
- * Call once at app startup before rendering any React scenes.
+ * Resolve a ViewInput to a Container instance.
+ *
+ * @example
+ * ```ts
+ * resolveView('btn-idle')          // → Sprite.from('btn-idle')
+ * resolveView(someTexture)         // → new Sprite(someTexture)
+ * resolveView(myCustomContainer)   // → myCustomContainer (as-is)
+ * resolveView(undefined)           // → null
+ * ```
  */
-function extendPixiElements() {
-    extend({
-        Container: pixi_js.Container,
-        Sprite: pixi_js.Sprite,
-        Graphics: pixi_js.Graphics,
-        Text: pixi_js.Text,
-        AnimatedSprite: pixi_js.AnimatedSprite,
-        NineSliceSprite: pixi_js.NineSliceSprite,
-        TilingSprite: pixi_js.TilingSprite,
-        Mesh: pixi_js.Mesh,
-        MeshPlane: pixi_js.MeshPlane,
-        MeshRope: pixi_js.MeshRope,
-        MeshSimple: pixi_js.MeshSimple,
-        BitmapText: pixi_js.BitmapText,
-        HTMLText: pixi_js.HTMLText,
-    });
+function resolveView(input) {
+    if (input == null)
+        return null;
+    if (typeof input === 'string')
+        return pixi_js.Sprite.from(input);
+    if (input instanceof pixi_js.Texture)
+        return new pixi_js.Sprite(input);
+    return input;
+}
+
+/**
+ * Collection of easing functions for use with Tween and Timeline.
+ *
+ * All functions take a progress value t (0..1) and return the eased value.
+ */
+const Easing = {
+    easeOutQuad: (t) => t * (2 - t),
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => --t * t * t + 1,
+    easeOutBack: (t) => {
+        const c1 = 1.70158;
+        const c3 = c1 + 1;
+        return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+    }};
+
+/**
+ * Lightweight tween system integrated with PixiJS Ticker.
+ * Zero external dependencies — no GSAP required.
+ *
+ * All tweens return a Promise that resolves on completion.
+ *
+ * @example
+ * ```ts
+ * // Fade in a sprite
+ * await Tween.to(sprite, { alpha: 1, y: 100 }, 500, Easing.easeOutBack);
+ *
+ * // Move and wait
+ * await Tween.to(sprite, { x: 500 }, 300);
+ *
+ * // From a starting value
+ * await Tween.from(sprite, { scale: 0, alpha: 0 }, 400);
+ * ```
+ */
+class Tween {
+    static _tweens = [];
+    static _tickerAdded = false;
+    /**
+     * Animate properties from current values to target values.
+     *
+     * @param target - Object to animate (Sprite, Container, etc.)
+     * @param props - Target property values
+     * @param duration - Duration in milliseconds
+     * @param easing - Easing function (default: easeOutQuad)
+     * @param onUpdate - Progress callback (0..1)
+     */
+    static to(target, props, duration, easing, onUpdate) {
+        return new Promise((resolve) => {
+            // Capture starting values
+            const from = {};
+            for (const key of Object.keys(props)) {
+                from[key] = Tween.getProperty(target, key);
+            }
+            const tween = {
+                target,
+                from,
+                to: { ...props },
+                duration: Math.max(1, duration),
+                easing: easing ?? Easing.easeOutQuad,
+                elapsed: 0,
+                delay: 0,
+                resolve,
+                onUpdate,
+            };
+            Tween._tweens.push(tween);
+            Tween.ensureTicker();
+        });
+    }
+    /**
+     * Animate properties from given values to current values.
+     */
+    static from(target, props, duration, easing, onUpdate) {
+        // Capture current values as "to"
+        const to = {};
+        for (const key of Object.keys(props)) {
+            to[key] = Tween.getProperty(target, key);
+            Tween.setProperty(target, key, props[key]);
+        }
+        return Tween.to(target, to, duration, easing, onUpdate);
+    }
+    /**
+     * Animate from one set of values to another.
+     */
+    static fromTo(target, fromProps, toProps, duration, easing, onUpdate) {
+        // Set starting values
+        for (const key of Object.keys(fromProps)) {
+            Tween.setProperty(target, key, fromProps[key]);
+        }
+        return Tween.to(target, toProps, duration, easing, onUpdate);
+    }
+    /**
+     * Wait for a given duration (useful in timelines).
+     * Uses PixiJS Ticker for consistent timing with other tweens.
+     */
+    static delay(ms) {
+        return new Promise((resolve) => {
+            let elapsed = 0;
+            const onTick = (ticker) => {
+                elapsed += ticker.deltaMS;
+                if (elapsed >= ms) {
+                    pixi_js.Ticker.shared.remove(onTick);
+                    resolve();
+                }
+            };
+            pixi_js.Ticker.shared.add(onTick);
+        });
+    }
+    /**
+     * Kill all tweens on a target.
+     */
+    static killTweensOf(target) {
+        Tween._tweens = Tween._tweens.filter((tw) => {
+            if (tw.target === target) {
+                tw.resolve();
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Kill all active tweens.
+     */
+    static killAll() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+    }
+    /** Number of active tweens */
+    static get activeTweens() {
+        return Tween._tweens.length;
+    }
+    /**
+     * Reset the tween system — kill all tweens and remove the ticker.
+     * Useful for cleanup between game instances, tests, or hot-reload.
+     */
+    static reset() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+        if (Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    }
+    // ─── Internal ──────────────────────────────────────────
+    static ensureTicker() {
+        if (Tween._tickerAdded)
+            return;
+        Tween._tickerAdded = true;
+        pixi_js.Ticker.shared.add(Tween.tick);
+    }
+    static tick = (ticker) => {
+        const dt = ticker.deltaMS;
+        const completed = [];
+        for (const tw of Tween._tweens) {
+            tw.elapsed += dt;
+            if (tw.elapsed < tw.delay)
+                continue;
+            const raw = Math.min((tw.elapsed - tw.delay) / tw.duration, 1);
+            const t = tw.easing(raw);
+            // Interpolate each property
+            for (const key of Object.keys(tw.to)) {
+                const start = tw.from[key];
+                const end = tw.to[key];
+                const value = start + (end - start) * t;
+                Tween.setProperty(tw.target, key, value);
+            }
+            tw.onUpdate?.(raw);
+            if (raw >= 1) {
+                completed.push(tw);
+            }
+        }
+        // Remove completed tweens
+        for (const tw of completed) {
+            const idx = Tween._tweens.indexOf(tw);
+            if (idx !== -1)
+                Tween._tweens.splice(idx, 1);
+            tw.resolve();
+        }
+        // Remove ticker when no active tweens
+        if (Tween._tweens.length === 0 && Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    };
+    /**
+     * Get a potentially nested property (supports 'scale.x', 'position.y', etc.)
+     */
+    static getProperty(target, key) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj[parts[i]];
+        }
+        return obj[parts[parts.length - 1]] ?? 0;
+    }
+    /**
+     * Set a potentially nested property.
+     */
+    static setProperty(target, key, value) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj[parts[i]];
+        }
+        obj[parts[parts.length - 1]] = value;
+    }
+}
+
+const DEFAULT_COLORS = {
+    default: 0xffd700,
+    hover: 0xffe44d,
+    pressed: 0xccac00,
+    disabled: 0x666666,
+};
+function makeGraphicsView(w, h, radius, color) {
+    const g = new pixi_js.Graphics();
+    g.roundRect(-w / 2, -h / 2, w, h, radius).fill(color);
+    return g;
+}
+/**
+ * Interactive button with per-state custom views and animations.
+ *
+ * Each visual state accepts a `ViewInput`: texture name, Texture, or any Container
+ * (Sprite, NineSliceSprite, AnimatedSprite, custom artwork, etc).
+ * Falls back to colored Graphics when no custom view is provided.
+ *
+ * @example
+ * ```ts
+ * // Graphics-based (quick prototyping)
+ * const btn = new Button({
+ *   width: 200, height: 60, borderRadius: 12,
+ *   colors: { default: 0x22aa22, hover: 0x33cc33 },
+ *   text: 'SPIN',
+ *   onPress: () => spin(),
+ * });
+ *
+ * // Asset-based (production art)
+ * const btn = new Button({
+ *   defaultView: 'btn-idle',
+ *   hoverView: 'btn-hover',
+ *   pressedView: 'btn-pressed',
+ *   disabledView: 'btn-disabled',
+ *   text: 'SPIN',
+ *   onPress: () => spin(),
+ * });
+ *
+ * // Custom Container view
+ * const btn = new Button({
+ *   defaultView: myAnimatedSprite,
+ *   text: 'SPIN',
+ * });
+ * ```
+ */
+class Button extends pixi_js.Container {
+    __uiComponent = true;
+    _views = new Map();
+    _state = 'default';
+    _enabled = true;
+    _config;
+    _textObj = null;
+    /** Press callback */
+    onPress;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            width: config.width ?? 200,
+            height: config.height ?? 60,
+            borderRadius: config.borderRadius ?? 8,
+            pressScale: config.pressScale ?? 0.95,
+            animationDuration: config.animationDuration ?? 100,
+            ...config,
+        };
+        this.onPress = config.onPress;
+        this._buildViews(config);
+        // Text
+        if (config.text) {
+            this._textObj = new pixi_js.Text({
+                text: config.text,
+                style: {
+                    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+                    fontSize: 20,
+                    fill: 0xffffff,
+                    fontWeight: 'bold',
+                    ...config.textStyle,
+                },
+            });
+            this._textObj.anchor.set(0.5);
+            this.addChild(this._textObj);
+        }
+        // Interaction
+        this.eventMode = 'static';
+        this.cursor = 'pointer';
+        this.on('pointerover', this._onPointerOver, this);
+        this.on('pointerout', this._onPointerOut, this);
+        this.on('pointerdown', this._onPointerDown, this);
+        this.on('pointerup', this._onPointerUp, this);
+        this.on('pointerupoutside', this._onPointerUpOutside, this);
+        if (config.disabled) {
+            this.enabled = false;
+        }
+    }
+    /** Current button state */
+    get state() {
+        return this._state;
+    }
+    /** Enable the button */
+    enable() {
+        this.enabled = true;
+    }
+    /** Disable the button */
+    disable() {
+        this.enabled = false;
+    }
+    /** Whether the button is enabled */
+    get enabled() {
+        return this._enabled;
+    }
+    set enabled(value) {
+        this._enabled = value;
+        this.cursor = value ? 'pointer' : 'default';
+        this.eventMode = value ? 'static' : 'none';
+        this._setState(value ? 'default' : 'disabled');
+    }
+    /** Whether the button is disabled */
+    get disabled() {
+        return !this._enabled;
+    }
+    /** Update button text */
+    set text(value) {
+        if (this._textObj) {
+            this._textObj.text = value;
+        }
+    }
+    // ─── View building ──────────────────────────────────
+    _buildViews(config) {
+        const colorMap = { ...DEFAULT_COLORS, ...config.colors };
+        const { width, height, borderRadius } = this._config;
+        const stateViews = {
+            default: config.defaultView,
+            hover: config.hoverView,
+            pressed: config.pressedView,
+            disabled: config.disabledView,
+        };
+        const states = ['default', 'hover', 'pressed', 'disabled'];
+        for (const state of states) {
+            const customView = resolveView(stateViews[state]);
+            const view = customView ?? makeGraphicsView(width, height, borderRadius, colorMap[state]);
+            view.visible = state === 'default';
+            this._views.set(state, view);
+            this.addChild(view);
+        }
+    }
+    _rebuildViews() {
+        for (const [, view] of this._views) {
+            this.removeChild(view);
+            view.destroy();
+        }
+        this._views.clear();
+        this._buildViews(this._config);
+        // Re-insert views before text
+        if (this._textObj && this._textObj.parent === this) {
+            this.setChildIndex(this._textObj, this.children.length - 1);
+        }
+    }
+    // ─── State management ───────────────────────────────
+    _setState(state) {
+        if (this._state === state)
+            return;
+        this._state = state;
+        for (const [s, view] of this._views) {
+            view.visible = s === state;
+        }
+    }
+    _onPointerOver() {
+        if (!this._enabled)
+            return;
+        this._setState('hover');
+        Tween.killTweensOf(this);
+        Tween.to(this, { 'scale.x': 1.03, 'scale.y': 1.03 }, this._config.animationDuration, Easing.easeOutQuad);
+    }
+    _onPointerOut() {
+        if (!this._enabled)
+            return;
+        this._setState('default');
+        Tween.killTweensOf(this);
+        Tween.to(this, { 'scale.x': 1, 'scale.y': 1 }, this._config.animationDuration, Easing.easeOutQuad);
+    }
+    _onPointerDown() {
+        if (!this._enabled)
+            return;
+        this._setState('pressed');
+        Tween.killTweensOf(this);
+        const s = this._config.pressScale;
+        Tween.to(this, { 'scale.x': s, 'scale.y': s }, this._config.animationDuration, Easing.easeOutQuad);
+    }
+    _onPointerUp() {
+        if (!this._enabled)
+            return;
+        this._setState('hover');
+        Tween.killTweensOf(this);
+        Tween.to(this, { 'scale.x': 1.03, 'scale.y': 1.03 }, this._config.animationDuration, Easing.easeOutQuad);
+        this.onPress?.();
+    }
+    _onPointerUpOutside() {
+        if (!this._enabled)
+            return;
+        this._setState('default');
+        Tween.killTweensOf(this);
+        Tween.to(this, { 'scale.x': 1, 'scale.y': 1 }, this._config.animationDuration, Easing.easeOutQuad);
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('text' in changed && this._textObj)
+            this._textObj.text = changed.text;
+        if ('disabled' in changed)
+            this.enabled = !changed.disabled;
+        if ('onPress' in changed)
+            this.onPress = changed.onPress;
+        const structural = [
+            'colors', 'width', 'height', 'borderRadius', 'textStyle',
+            'defaultView', 'hoverView', 'pressedView', 'disabledView',
+        ];
+        const needsRebuild = structural.some((k) => k in changed);
+        if (needsRebuild) {
+            Object.assign(this._config, changed);
+            this._rebuildViews();
+        }
+    }
+    destroy(options) {
+        Tween.killTweensOf(this);
+        this.off('pointerover', this._onPointerOver, this);
+        this.off('pointerout', this._onPointerOut, this);
+        this.off('pointerdown', this._onPointerDown, this);
+        this.off('pointerup', this._onPointerUp, this);
+        this.off('pointerupoutside', this._onPointerUpOutside, this);
+        this._views.clear();
+        this._textObj = null;
+        super.destroy(options);
+    }
 }
+
 /**
- * Register @pixi/layout components for JSX use.
- * Pass the dynamically imported module:
+ * Horizontal progress bar with optional custom track/fill views.
  *
+ * Supports asset-based skinning: provide `trackView` and/or `fillView`
+ * as texture names, Textures, or any Container (NineSliceSprite, custom artwork, etc).
+ * Falls back to colored Graphics when no custom views are provided.
+ *
+ * @example
  * ```ts
- * const layout = await import('@pixi/layout/components');
- * extendLayoutElements(layout);
+ * // Graphics-based (quick prototyping)
+ * const bar = new ProgressBar({ width: 300, height: 20, fillColor: 0x22cc22 });
+ * bar.progress = 0.5;
+ *
+ * // Asset-based (production art)
+ * const bar = new ProgressBar({
+ *   width: 300, height: 20,
+ *   trackView: 'bar-track',
+ *   fillView: new NineSliceSprite({ texture: 'bar-fill', ... }),
+ * });
+ * bar.progress = 0.75;
  * ```
  */
-function extendLayoutElements(layoutModule) {
-    extend(layoutModule);
+class ProgressBar extends pixi_js.Container {
+    __uiComponent = true;
+    _track;
+    _fill;
+    _fillMask;
+    _borderGfx;
+    _config;
+    _progress = 0;
+    _displayedProgress = 0;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            width: config.width ?? 300,
+            height: config.height ?? 16,
+            borderRadius: config.borderRadius ?? 8,
+            fillColor: config.fillColor ?? 0xffd700,
+            trackColor: config.trackColor ?? 0x333333,
+            borderColor: config.borderColor ?? 0x555555,
+            borderWidth: config.borderWidth ?? 1,
+            animated: config.animated ?? true,
+            animationSpeed: config.animationSpeed ?? 0.1,
+        };
+        const { width, height, borderRadius, fillColor, trackColor, borderColor, borderWidth } = this._config;
+        // Track background — custom view or Graphics
+        const customTrack = resolveView(config.trackView);
+        if (customTrack) {
+            customTrack.width = width;
+            customTrack.height = height;
+            this._track = customTrack;
+        }
+        else {
+            const g = new pixi_js.Graphics();
+            g.roundRect(0, 0, width, height, borderRadius).fill(trackColor);
+            this._track = g;
+        }
+        this.addChild(this._track);
+        // Fill bar — custom view or Graphics
+        const customFill = resolveView(config.fillView);
+        if (customFill) {
+            customFill.x = borderWidth;
+            customFill.y = borderWidth;
+            customFill.width = width - borderWidth * 2;
+            customFill.height = height - borderWidth * 2;
+            this._fill = customFill;
+        }
+        else {
+            const g = new pixi_js.Graphics();
+            g.roundRect(borderWidth, borderWidth, width - borderWidth * 2, height - borderWidth * 2, Math.max(0, borderRadius - 1)).fill(fillColor);
+            this._fill = g;
+        }
+        this.addChild(this._fill);
+        // Mask for the fill (controls visible width)
+        this._fillMask = new pixi_js.Graphics();
+        this._fillMask.rect(0, 0, 0, height).fill(0xffffff);
+        this.addChild(this._fillMask);
+        this._fill.mask = this._fillMask;
+        // Border overlay
+        this._borderGfx = new pixi_js.Graphics();
+        if (borderColor !== undefined && borderWidth > 0) {
+            this._borderGfx
+                .roundRect(0, 0, width, height, borderRadius)
+                .stroke({ color: borderColor, width: borderWidth });
+        }
+        this.addChild(this._borderGfx);
+    }
+    /** Get/set progress (0..1) */
+    get progress() {
+        return this._progress;
+    }
+    set progress(value) {
+        this._progress = Math.max(0, Math.min(1, value));
+        if (!this._config.animated) {
+            this._displayedProgress = this._progress;
+            this.updateMask();
+        }
+    }
+    /**
+     * Call each frame if animated is true.
+     */
+    update(_dt) {
+        if (!this._config.animated)
+            return;
+        if (Math.abs(this._displayedProgress - this._progress) < 0.001) {
+            this._displayedProgress = this._progress;
+            this.updateMask();
+            return;
+        }
+        this._displayedProgress +=
+            (this._progress - this._displayedProgress) * this._config.animationSpeed;
+        this.updateMask();
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('progress' in changed)
+            this.progress = changed.progress;
+        if ('animated' in changed)
+            this._config.animated = changed.animated;
+        if ('animationSpeed' in changed)
+            this._config.animationSpeed = changed.animationSpeed;
+    }
+    updateMask() {
+        const w = this._config.width * this._displayedProgress;
+        this._fillMask.clear();
+        this._fillMask.rect(0, 0, w, this._config.height).fill(0xffffff);
+    }
+}
+
+/**
+ * Enhanced text label with auto-fit scaling and currency formatting.
+ *
+ * @example
+ * ```ts
+ * const label = new Label({
+ *   text: 'BALANCE',
+ *   style: { fontSize: 24, fill: 0xffd700 },
+ *   maxWidth: 200,
+ *   autoFit: true,
+ * });
+ * ```
+ */
+class Label extends pixi_js.Container {
+    __uiComponent = true;
+    _text;
+    _maxWidth;
+    _autoFit;
+    constructor(config = {}) {
+        super();
+        this._maxWidth = config.maxWidth ?? Infinity;
+        this._autoFit = config.autoFit ?? false;
+        this._text = new pixi_js.Text({
+            text: config.text ?? '',
+            style: {
+                fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+                fontSize: 24,
+                fill: 0xffffff,
+                ...config.style,
+            },
+        });
+        this._text.anchor.set(0.5);
+        this.addChild(this._text);
+        this.fitText();
+    }
+    /** Get/set the displayed text */
+    get text() {
+        return this._text.text;
+    }
+    set text(value) {
+        this._text.text = value;
+        this.fitText();
+    }
+    /** Get/set the text style */
+    get style() {
+        return this._text.style;
+    }
+    /** Set max width constraint */
+    set maxWidth(value) {
+        this._maxWidth = value;
+        this.fitText();
+    }
+    /**
+     * Format and display a number as currency.
+     *
+     * @param amount - The numeric amount
+     * @param currency - Currency code (e.g., 'USD', 'EUR')
+     * @param locale - Locale string (default: 'en-US')
+     */
+    setCurrency(amount, currency, locale = 'en-US') {
+        try {
+            this.text = new Intl.NumberFormat(locale, {
+                style: 'currency',
+                currency,
+                minimumFractionDigits: 2,
+                maximumFractionDigits: 2,
+            }).format(amount);
+        }
+        catch {
+            this.text = `${amount.toFixed(2)} ${currency}`;
+        }
+    }
+    /**
+     * Format a number with thousands separators.
+     */
+    setNumber(value, decimals = 0, locale = 'en-US') {
+        this.text = new Intl.NumberFormat(locale, {
+            minimumFractionDigits: decimals,
+            maximumFractionDigits: decimals,
+        }).format(value);
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('text' in changed)
+            this.text = changed.text;
+        if ('maxWidth' in changed)
+            this.maxWidth = changed.maxWidth;
+        if ('autoFit' in changed) {
+            this._autoFit = changed.autoFit;
+            this.fitText();
+        }
+        if ('style' in changed && typeof changed.style === 'object') {
+            Object.assign(this._text.style, changed.style);
+            this.fitText();
+        }
+    }
+    fitText() {
+        if (!this._autoFit || this._maxWidth === Infinity)
+            return;
+        this._text.scale.set(1);
+        if (this._text.width > this._maxWidth) {
+            const scale = this._maxWidth / this._text.width;
+            this._text.scale.set(scale);
+        }
+    }
+}
+
+/**
+ * Background panel with optional flexbox content layout.
+ *
+ * Supports both Graphics-based (color + border) and 9-slice sprite backgrounds.
+ * Children added via `addContent()` participate in flex layout automatically.
+ *
+ * @example
+ * ```ts
+ * // Simple colored panel
+ * const panel = new Panel({ width: 400, height: 300, backgroundColor: 0x222222, borderRadius: 12 });
+ *
+ * // 9-slice panel (texture-based)
+ * const panel = new Panel({
+ *   nineSliceTexture: 'panel-bg',
+ *   nineSliceBorders: [20, 20, 20, 20],
+ *   width: 400, height: 300,
+ * });
+ * ```
+ */
+class Panel extends pixi_js.Container {
+    __uiComponent = true;
+    _bg;
+    _content;
+    _internalSetup = true;
+    _panelConfig;
+    constructor(config = {}) {
+        super();
+        const resolvedConfig = {
+            width: config.width ?? 400,
+            height: config.height ?? 300,
+            padding: config.padding ?? 16,
+            backgroundAlpha: config.backgroundAlpha ?? 1,
+            ...config,
+        };
+        this._panelConfig = resolvedConfig;
+        // Create background
+        if (config.nineSliceTexture) {
+            const texture = typeof config.nineSliceTexture === 'string'
+                ? pixi_js.Texture.from(config.nineSliceTexture)
+                : config.nineSliceTexture;
+            const [left, top, right, bottom] = config.nineSliceBorders ?? [10, 10, 10, 10];
+            const nineSlice = new pixi_js.NineSliceSprite({
+                texture,
+                leftWidth: left,
+                topHeight: top,
+                rightWidth: right,
+                bottomHeight: bottom,
+            });
+            nineSlice.width = resolvedConfig.width;
+            nineSlice.height = resolvedConfig.height;
+            nineSlice.alpha = resolvedConfig.backgroundAlpha;
+            this._bg = nineSlice;
+        }
+        else {
+            const g = new pixi_js.Graphics();
+            const bgColor = config.backgroundColor ?? 0x1a1a2e;
+            const radius = config.borderRadius ?? 0;
+            g.roundRect(0, 0, resolvedConfig.width, resolvedConfig.height, radius).fill(bgColor);
+            if (config.borderColor !== undefined && config.borderWidth) {
+                g.roundRect(0, 0, resolvedConfig.width, resolvedConfig.height, radius)
+                    .stroke({ color: config.borderColor, width: config.borderWidth });
+            }
+            g.alpha = resolvedConfig.backgroundAlpha;
+            this._bg = g;
+        }
+        this.addChild(this._bg);
+        // Create content flex container
+        this._content = new FlexContainer({
+            ...config.layout,
+            direction: config.layout?.direction ?? 'column',
+            justifyContent: config.layout?.justifyContent ?? 'start',
+            alignItems: config.layout?.alignItems ?? 'start',
+            gap: config.layout?.gap ?? 0,
+            padding: resolvedConfig.padding,
+            width: resolvedConfig.width,
+            height: resolvedConfig.height,
+        });
+        this.addChild(this._content);
+        this._internalSetup = false;
+    }
+    /** Access the content flex container — add children here for layout */
+    get content() {
+        return this._content;
+    }
+    /** Convenience: add a child to the content layout */
+    addContent(child) {
+        this._content.addFlexChild(child);
+        this._content.updateLayout();
+        return this;
+    }
+    /** Resize the panel */
+    setSize(width, height) {
+        this._panelConfig.width = width;
+        this._panelConfig.height = height;
+        // Resize background
+        if (this._bg instanceof pixi_js.NineSliceSprite) {
+            this._bg.width = width;
+            this._bg.height = height;
+        }
+        else if (this._bg instanceof pixi_js.Graphics) {
+            const radius = this._panelConfig.borderRadius ?? 0;
+            const bgColor = this._panelConfig.backgroundColor ?? 0x1a1a2e;
+            this._bg.clear();
+            this._bg.roundRect(0, 0, width, height, radius).fill(bgColor);
+            if (this._panelConfig.borderColor !== undefined && this._panelConfig.borderWidth) {
+                this._bg.roundRect(0, 0, width, height, radius)
+                    .stroke({ color: this._panelConfig.borderColor, width: this._panelConfig.borderWidth });
+            }
+            this._bg.alpha = this._panelConfig.backgroundAlpha;
+        }
+        this._content.resize(width, height);
+    }
+    /**
+     * Override addChild so external children are routed to content FlexContainer.
+     * Enables `<panel><label /><button /></panel>` in React JSX.
+     */
+    addChild(...children) {
+        if (this._internalSetup) {
+            return super.addChild(...children);
+        }
+        for (const child of children) {
+            this._content.addFlexChild(child);
+        }
+        this._content.updateLayout();
+        return children[0];
+    }
+    removeChild(...children) {
+        if (this._internalSetup) {
+            return super.removeChild(...children);
+        }
+        for (const child of children) {
+            this._content.removeFlexChild(child);
+        }
+        return children[0];
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('width' in changed || 'height' in changed) {
+            this.setSize(changed.width ?? this._panelConfig.width, changed.height ?? this._panelConfig.height);
+        }
+        if ('backgroundAlpha' in changed) {
+            this._panelConfig.backgroundAlpha = changed.backgroundAlpha;
+            this._bg.alpha = changed.backgroundAlpha;
+        }
+    }
+    destroy(options) {
+        super.destroy(options);
+    }
+}
+
+/**
+ * Reactive balance display component.
+ *
+ * Automatically formats currency and can animate value changes
+ * with a smooth countup/countdown effect using engine Tween.
+ *
+ * @example
+ * ```ts
+ * const balance = new BalanceDisplay({ currency: 'USD', animated: true });
+ * balance.setValue(1000);
+ *
+ * // Wire to SDK
+ * sdk.on('balanceUpdate', ({ balance: val }) => balance.setValue(val));
+ * ```
+ */
+class BalanceDisplay extends pixi_js.Container {
+    __uiComponent = true;
+    _prefixLabel = null;
+    _valueLabel;
+    _config;
+    _currentValue = 0;
+    _displayedValue = 0;
+    /** Internal target for Tween animation */
+    _tweenTarget = { value: 0 };
+    constructor(config = {}) {
+        super();
+        this._config = {
+            currency: config.currency ?? 'USD',
+            locale: config.locale ?? 'en-US',
+            animated: config.animated ?? true,
+            animationDuration: config.animationDuration ?? 500,
+        };
+        // Prefix label
+        if (config.prefix) {
+            this._prefixLabel = new Label({
+                text: config.prefix,
+                style: {
+                    fontSize: 16,
+                    fill: 0xaaaaaa,
+                    ...config.style,
+                },
+            });
+            this.addChild(this._prefixLabel);
+        }
+        // Value label
+        this._valueLabel = new Label({
+            text: '0.00',
+            style: {
+                fontSize: 28,
+                fontWeight: 'bold',
+                fill: 0xffffff,
+                ...config.style,
+            },
+            maxWidth: config.maxWidth,
+            autoFit: !!config.maxWidth,
+        });
+        this.addChild(this._valueLabel);
+        this.layoutLabels();
+    }
+    /** Current displayed value */
+    get value() {
+        return this._currentValue;
+    }
+    /**
+     * Set the balance value. If animated, smoothly counts to the new value.
+     */
+    setValue(value) {
+        const oldValue = this._currentValue;
+        this._currentValue = value;
+        if (this._config.animated && oldValue !== value) {
+            this.animateValue(oldValue, value);
+        }
+        else {
+            this._displayedValue = value;
+            this.updateDisplay();
+        }
+    }
+    /**
+     * Set the currency code.
+     */
+    setCurrency(currency) {
+        this._config.currency = currency;
+        this.updateDisplay();
+    }
+    animateValue(from, to) {
+        // Cancel any running animation
+        Tween.killTweensOf(this._tweenTarget);
+        this._tweenTarget.value = from;
+        Tween.to(this._tweenTarget, { value: to }, this._config.animationDuration, Easing.easeOutCubic, () => {
+            this._displayedValue = this._tweenTarget.value;
+            this.updateDisplay();
+        });
+    }
+    updateDisplay() {
+        this._valueLabel.setCurrency(this._displayedValue, this._config.currency, this._config.locale);
+    }
+    layoutLabels() {
+        if (this._prefixLabel) {
+            this._prefixLabel.y = -14;
+            this._valueLabel.y = 14;
+        }
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('value' in changed)
+            this.setValue(changed.value);
+        if ('currency' in changed)
+            this.setCurrency(changed.currency);
+    }
+    destroy(options) {
+        Tween.killTweensOf(this._tweenTarget);
+        super.destroy(options);
+    }
+}
+
+/**
+ * Win amount display with countup animation.
+ *
+ * Shows a dramatic countup from 0 to the win amount, with optional
+ * scale pop effect — typical of slot games. Uses engine Tween system.
+ *
+ * @example
+ * ```ts
+ * const winDisplay = new WinDisplay({ currency: 'USD' });
+ * scene.container.addChild(winDisplay);
+ * await winDisplay.showWin(150.50); // countup animation
+ * winDisplay.hide();
+ * ```
+ */
+class WinDisplay extends pixi_js.Container {
+    __uiComponent = true;
+    _label;
+    _config;
+    /** Internal target for Tween countup */
+    _tweenTarget = { value: 0 };
+    constructor(config = {}) {
+        super();
+        this._config = {
+            currency: config.currency ?? 'USD',
+            locale: config.locale ?? 'en-US',
+            countupDuration: config.countupDuration ?? 1500,
+            popScale: config.popScale ?? 1.2,
+        };
+        this._label = new Label({
+            text: '',
+            style: {
+                fontSize: 48,
+                fontWeight: 'bold',
+                fill: 0xffd700,
+                stroke: { color: 0x000000, width: 3 },
+                ...config.style,
+            },
+        });
+        this.addChild(this._label);
+        this.visible = false;
+    }
+    /**
+     * Show a win with countup animation.
+     *
+     * @param amount - Win amount
+     * @returns Promise that resolves when the animation completes
+     */
+    async showWin(amount) {
+        this.visible = true;
+        this.alpha = 1;
+        // Cancel any running animation
+        Tween.killTweensOf(this._tweenTarget);
+        Tween.killTweensOf(this);
+        // Setup countup
+        this._tweenTarget.value = 0;
+        this.scale.set(0.5);
+        // Scale pop animation
+        const scalePromise = Tween.to(this, { 'scale.x': 1, 'scale.y': 1 }, 300, Easing.easeOutBack);
+        // Countup animation
+        const countupPromise = Tween.to(this._tweenTarget, { value: amount }, this._config.countupDuration, Easing.easeOutCubic, () => {
+            this.displayAmount(this._tweenTarget.value);
+        });
+        await Promise.all([scalePromise, countupPromise]);
+        // Ensure final value is exact
+        this.displayAmount(amount);
+        this.scale.set(1);
+    }
+    /**
+     * Skip the countup animation and show the final amount immediately.
+     */
+    skipCountup(amount) {
+        Tween.killTweensOf(this._tweenTarget);
+        Tween.killTweensOf(this);
+        this.displayAmount(amount);
+        this.scale.set(1);
+    }
+    /**
+     * Hide the win display.
+     */
+    hide() {
+        Tween.killTweensOf(this._tweenTarget);
+        Tween.killTweensOf(this);
+        this.visible = false;
+        this._label.text = '';
+    }
+    displayAmount(amount) {
+        this._label.setCurrency(amount, this._config.currency, this._config.locale);
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('currency' in changed)
+            this._config.currency = changed.currency;
+        if ('locale' in changed)
+            this._config.locale = changed.locale;
+    }
+    destroy(options) {
+        Tween.killTweensOf(this._tweenTarget);
+        Tween.killTweensOf(this);
+        super.destroy(options);
+    }
+}
+
+/**
+ * Modal overlay component.
+ * Shows content on top of a dark overlay with enter/exit animations.
+ *
+ * Content is automatically centered via position calculations.
+ *
+ * @example
+ * ```ts
+ * const modal = new Modal({ closeOnOverlay: true });
+ * modal.content.addChild(settingsPanel);
+ * modal.onClose = () => console.log('Closed');
+ * await modal.show(1920, 1080);
+ * ```
+ */
+class Modal extends pixi_js.Container {
+    __uiComponent = true;
+    _overlay;
+    _contentContainer;
+    _config;
+    _showing = false;
+    /** Called when the modal is closed */
+    onClose;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            overlayColor: config.overlayColor ?? 0x000000,
+            overlayAlpha: config.overlayAlpha ?? 0.7,
+            closeOnOverlay: config.closeOnOverlay ?? true,
+            animationDuration: config.animationDuration ?? 300,
+        };
+        // Overlay
+        this._overlay = new pixi_js.Graphics();
+        this._overlay.eventMode = 'static';
+        this.addChild(this._overlay);
+        if (this._config.closeOnOverlay) {
+            this._overlay.on('pointertap', () => this.hide());
+        }
+        // Content container
+        this._contentContainer = new pixi_js.Container();
+        this.addChild(this._contentContainer);
+        this.visible = false;
+    }
+    /** Content container — add your UI here */
+    get content() {
+        return this._contentContainer;
+    }
+    /** Whether the modal is currently showing */
+    get isShowing() {
+        return this._showing;
+    }
+    /**
+     * Show the modal with animation.
+     */
+    async show(viewWidth, viewHeight) {
+        this._showing = true;
+        this.visible = true;
+        // Draw overlay to cover full screen
+        this._overlay.clear();
+        this._overlay.rect(0, 0, viewWidth, viewHeight).fill(this._config.overlayColor);
+        this._overlay.alpha = 0;
+        // Center content
+        this._contentContainer.x = viewWidth / 2;
+        this._contentContainer.y = viewHeight / 2;
+        this._contentContainer.alpha = 0;
+        this._contentContainer.scale.set(0.8);
+        // Animate in
+        await Promise.all([
+            Tween.to(this._overlay, { alpha: this._config.overlayAlpha }, this._config.animationDuration, Easing.easeOutCubic),
+            Tween.to(this._contentContainer, { alpha: 1, 'scale.x': 1, 'scale.y': 1 }, this._config.animationDuration, Easing.easeOutBack),
+        ]);
+    }
+    /**
+     * Hide the modal with animation.
+     */
+    async hide() {
+        if (!this._showing)
+            return;
+        await Promise.all([
+            Tween.to(this._overlay, { alpha: 0 }, this._config.animationDuration * 0.7, Easing.easeInCubic),
+            Tween.to(this._contentContainer, { alpha: 0, 'scale.x': 0.8, 'scale.y': 0.8 }, this._config.animationDuration * 0.7, Easing.easeInCubic),
+        ]);
+        this.visible = false;
+        this._showing = false;
+        this.onClose?.();
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('overlayAlpha' in changed)
+            this._config.overlayAlpha = changed.overlayAlpha;
+        if ('closeOnOverlay' in changed)
+            this._config.closeOnOverlay = changed.closeOnOverlay;
+        if ('animationDuration' in changed)
+            this._config.animationDuration = changed.animationDuration;
+        if ('onClose' in changed)
+            this.onClose = changed.onClose;
+    }
+}
+
+const TOAST_COLORS = {
+    info: 0x3498db,
+    success: 0x27ae60,
+    warning: 0xf39c12,
+    error: 0xe74c3c,
+};
+/**
+ * Toast notification component for displaying transient messages.
+ *
+ * @example
+ * ```ts
+ * const toast = new Toast();
+ * scene.container.addChild(toast);
+ * await toast.show('Connection lost', 'error', 1920, 1080);
+ * ```
+ */
+class Toast extends pixi_js.Container {
+    __uiComponent = true;
+    _bg;
+    _customBg;
+    _text;
+    _config;
+    _dismissPending = false;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            duration: config.duration ?? 3000,
+            bottomOffset: config.bottomOffset ?? 60,
+        };
+        const customBg = resolveView(config.backgroundView);
+        this._customBg = !!customBg;
+        this._bg = customBg ?? new pixi_js.Graphics();
+        this.addChild(this._bg);
+        this._text = new pixi_js.Text({
+            text: '',
+            style: {
+                fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+                fontSize: 16,
+                fill: 0xffffff,
+            },
+        });
+        this._text.anchor.set(0.5);
+        this.addChild(this._text);
+        this.visible = false;
+    }
+    /**
+     * Show a toast message.
+     */
+    async show(message, type = 'info', viewWidth, viewHeight) {
+        // Cancel any pending dismiss
+        Tween.killTweensOf(this);
+        this._dismissPending = false;
+        this._text.text = message;
+        const padding = 20;
+        const width = Math.max(200, this._text.width + padding * 2);
+        const height = 44;
+        const radius = 8;
+        // Draw the background
+        if (this._customBg) {
+            this._bg.width = width;
+            this._bg.height = height;
+            this._bg.x = -width / 2;
+            this._bg.y = -height / 2;
+        }
+        else {
+            const g = this._bg;
+            g.clear();
+            g.roundRect(-width / 2, -height / 2, width, height, radius);
+            g.fill(TOAST_COLORS[type]);
+        }
+        // Position
+        if (viewWidth && viewHeight) {
+            this.x = viewWidth / 2;
+            this.y = viewHeight - this._config.bottomOffset;
+        }
+        this.visible = true;
+        this.alpha = 0;
+        this.y += 20;
+        await Tween.to(this, { alpha: 1, y: this.y - 20 }, 300, Easing.easeOutCubic);
+        if (this._config.duration > 0) {
+            this._dismissPending = true;
+            await Tween.delay(this._config.duration);
+            if (this._dismissPending) {
+                this._dismissPending = false;
+                await this.dismiss();
+            }
+        }
+    }
+    /**
+     * Dismiss the toast.
+     */
+    async dismiss() {
+        if (!this.visible)
+            return;
+        this._dismissPending = false;
+        Tween.killTweensOf(this);
+        await Tween.to(this, { alpha: 0, y: this.y + 20 }, 200, Easing.easeInCubic);
+        this.visible = false;
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('duration' in changed)
+            this._config.duration = changed.duration;
+        if ('bottomOffset' in changed)
+            this._config.bottomOffset = changed.bottomOffset;
+    }
+    destroy(options) {
+        this._dismissPending = false;
+        Tween.killTweensOf(this);
+        super.destroy(options);
+    }
+}
+
+// ─── Helpers ─────────────────────────────────────────────
+function directionToFlex(direction) {
+    switch (direction) {
+        case 'horizontal': return { direction: 'row', wrap: false };
+        case 'vertical': return { direction: 'column', wrap: false };
+        case 'grid': return { direction: 'row', wrap: true };
+        case 'wrap': return { direction: 'row', wrap: true };
+    }
+}
+/**
+ * Responsive layout container powered by a lightweight built-in flex layout solver.
+ *
+ * Supports horizontal, vertical, grid, and wrap layout modes with
+ * alignment, padding, gap, and viewport-anchor positioning.
+ * Breakpoints allow different layouts for different screen sizes.
+ *
+ * @example
+ * ```ts
+ * const toolbar = new Layout({
+ *   direction: 'horizontal',
+ *   gap: 20,
+ *   alignment: 'center',
+ *   anchor: 'bottom-center',
+ *   padding: 16,
+ *   breakpoints: {
+ *     768: { direction: 'vertical', gap: 10 },
+ *   },
+ * });
+ *
+ * toolbar.addItem(spinButton);
+ * toolbar.addItem(betLabel);
+ * scene.container.addChild(toolbar);
+ *
+ * toolbar.updateViewport(width, height);
+ * ```
+ */
+class Layout extends pixi_js.Container {
+    __uiComponent = true;
+    _layoutConfig;
+    _padding;
+    _anchor;
+    _maxWidth;
+    _breakpoints;
+    _items = [];
+    _viewportWidth = 0;
+    _viewportHeight = 0;
+    _flex;
+    constructor(config = {}) {
+        super();
+        this._layoutConfig = {
+            direction: config.direction ?? 'vertical',
+            gap: config.gap ?? 0,
+            alignment: config.alignment ?? 'start',
+            autoLayout: config.autoLayout ?? true,
+            columns: config.columns ?? 2,
+        };
+        this._padding = config.padding ?? 0;
+        this._anchor = config.anchor ?? 'top-left';
+        this._maxWidth = config.maxWidth ?? Infinity;
+        this._breakpoints = config.breakpoints
+            ? Object.entries(config.breakpoints)
+                .map(([w, cfg]) => [Number(w), cfg])
+                .sort((a, b) => a[0] - b[0])
+            : [];
+        // Create internal FlexContainer
+        this._flex = new FlexContainer();
+        super.addChild(this._flex);
+        this.applyLayoutStyles();
+    }
+    /** Add an item to the layout */
+    addItem(child) {
+        this._items.push(child);
+        const flexConfig = this.buildFlexItemConfig(child);
+        this._flex.addFlexChild(child, flexConfig);
+        if (this._layoutConfig.autoLayout) {
+            this.applyLayoutStyles();
+        }
+        return this;
+    }
+    /** Remove an item from the layout */
+    removeItem(child) {
+        const idx = this._items.indexOf(child);
+        if (idx !== -1) {
+            this._items.splice(idx, 1);
+            this._flex.removeFlexChild(child);
+        }
+        return this;
+    }
+    /** Remove all items */
+    clearItems() {
+        this._flex.clearFlexChildren();
+        this._items.length = 0;
+        return this;
+    }
+    /** Get all layout items */
+    get items() {
+        return this._items;
+    }
+    /**
+     * Update the viewport size and recalculate layout.
+     * Should be called from `Scene.onResize()`.
+     */
+    updateViewport(width, height) {
+        this._viewportWidth = width;
+        this._viewportHeight = height;
+        this.applyLayoutStyles();
+        this.applyAnchor();
+    }
+    applyLayoutStyles() {
+        const effective = this.resolveConfig();
+        const direction = effective.direction ?? this._layoutConfig.direction;
+        const gap = effective.gap ?? this._layoutConfig.gap;
+        const alignment = effective.alignment ?? this._layoutConfig.alignment;
+        const padding = effective.padding ?? this._padding;
+        const maxWidth = effective.maxWidth ?? this._maxWidth;
+        const { direction: flexDir, wrap } = directionToFlex(direction);
+        this._flex.setDirection(flexDir);
+        this._flex.setJustifyContent('start');
+        this._flex.setAlignItems(alignment);
+        this._flex.setGap(gap);
+        this._flex.setPadding(padding);
+        // Wrap and maxWidth
+        if (wrap) {
+            this._flex._config.flexWrap = true;
+            if (direction === 'grid' && maxWidth < Infinity) {
+                this._flex._maxWidth = maxWidth;
+            }
+            if (maxWidth < Infinity) {
+                this._flex._maxWidth = maxWidth;
+            }
+        }
+        else {
+            this._flex._config.flexWrap = false;
+        }
+        // Update grid child widths
+        if (direction === 'grid') {
+            for (const item of this._items) {
+                const flexConfig = this.buildFlexItemConfig(item);
+                item._flexConfig = flexConfig;
+            }
+        }
+        // Set explicit size if we have viewport dimensions
+        if (this._viewportWidth > 0 && this._viewportHeight > 0) {
+            this._flex.resize(this._viewportWidth, this._viewportHeight);
+        }
+        else {
+            this._flex.updateLayout();
+        }
+    }
+    buildFlexItemConfig(_child) {
+        const effective = this.resolveConfig();
+        const direction = effective.direction ?? this._layoutConfig.direction;
+        const columns = effective.columns ?? this._layoutConfig.columns;
+        if (direction === 'grid' && columns > 0) {
+            // For grid, give each item a proportional width
+            // The actual pixel width will be computed during layout
+            return { flexGrow: 1 };
+        }
+        return undefined;
+    }
+    applyAnchor() {
+        const anchor = this.resolveConfig().anchor ?? this._anchor;
+        if (this._viewportWidth === 0 || this._viewportHeight === 0)
+            return;
+        const { width: contentW, height: contentH } = this._flex.getContentSize();
+        const vw = this._viewportWidth;
+        const vh = this._viewportHeight;
+        let anchorX = 0;
+        let anchorY = 0;
+        if (anchor.includes('left')) {
+            anchorX = 0;
+        }
+        else if (anchor.includes('right')) {
+            anchorX = vw - contentW;
+        }
+        else {
+            anchorX = (vw - contentW) / 2;
+        }
+        if (anchor.startsWith('top')) {
+            anchorY = 0;
+        }
+        else if (anchor.startsWith('bottom')) {
+            anchorY = vh - contentH;
+        }
+        else {
+            anchorY = (vh - contentH) / 2;
+        }
+        this.x = anchorX;
+        this.y = anchorY;
+    }
+    resolveConfig() {
+        if (this._breakpoints.length === 0 || this._viewportWidth === 0) {
+            return {};
+        }
+        for (const [maxWidth, overrides] of this._breakpoints) {
+            if (this._viewportWidth <= maxWidth) {
+                return overrides;
+            }
+        }
+        return {};
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('direction' in changed)
+            this._layoutConfig.direction = changed.direction;
+        if ('gap' in changed)
+            this._layoutConfig.gap = changed.gap;
+        if ('alignment' in changed)
+            this._layoutConfig.alignment = changed.alignment;
+        if ('anchor' in changed)
+            this._anchor = changed.anchor;
+        if ('padding' in changed)
+            this._padding = changed.padding;
+        if ('columns' in changed)
+            this._layoutConfig.columns = changed.columns;
+        this.applyLayoutStyles();
+        if (this._viewportWidth > 0)
+            this.applyAnchor();
+    }
+    destroy(options) {
+        this._items.length = 0;
+        super.destroy(options);
+    }
+}
+
+const DECELERATION = 0.95;
+const MIN_VELOCITY = 0.5;
+/**
+ * Scrollable container with touch/drag, mouse wheel, and inertia.
+ *
+ * @example
+ * ```ts
+ * const scroll = new ScrollContainer({
+ *   width: 600,
+ *   height: 400,
+ *   direction: 'vertical',
+ *   elementsMargin: 8,
+ * });
+ *
+ * for (let i = 0; i < 50; i++) {
+ *   scroll.addItem(createRow(i));
+ * }
+ *
+ * scene.container.addChild(scroll);
+ * ```
+ */
+class ScrollContainer extends pixi_js.Container {
+    __uiComponent = true;
+    _viewport;
+    _internalSetup = true;
+    _content;
+    _maskGfx;
+    _bg = null;
+    _scrollConfig;
+    _items = [];
+    // Scrollbar
+    _scrollbar = null;
+    _scrollbarConfig;
+    // Drag state
+    _dragging = false;
+    _dragStart = { x: 0, y: 0 };
+    _contentStart = { x: 0, y: 0 };
+    _velocity = { x: 0, y: 0 };
+    _lastDragPos = { x: 0, y: 0 };
+    _lastDragTime = 0;
+    _inertiaActive = false;
+    // Bound handlers for cleanup
+    _onTickBound = null;
+    _onWheelBound = null;
+    constructor(config) {
+        super();
+        this._viewport = { width: config.width, height: config.height };
+        this._scrollConfig = {
+            direction: config.direction ?? 'vertical',
+            elementsMargin: config.elementsMargin ?? 0,
+            padding: config.padding ?? 0,
+            borderRadius: config.borderRadius ?? 0,
+            disableEasing: config.disableEasing ?? false,
+        };
+        // Background
+        if (config.backgroundColor !== undefined) {
+            this._bg = new pixi_js.Graphics();
+            this._bg.roundRect(0, 0, config.width, config.height, this._scrollConfig.borderRadius)
+                .fill(config.backgroundColor);
+            this.addChild(this._bg);
+        }
+        // Mask
+        this._maskGfx = new pixi_js.Graphics();
+        this._maskGfx.roundRect(0, 0, config.width, config.height, this._scrollConfig.borderRadius)
+            .fill(0xffffff);
+        this.addChild(this._maskGfx);
+        // Content container
+        this._content = new pixi_js.Container();
+        this._content.mask = this._maskGfx;
+        this.addChild(this._content);
+        // Interaction
+        this.eventMode = 'static';
+        this.hitArea = { contains: (x, y) => x >= 0 && x <= config.width && y >= 0 && y <= config.height };
+        this.on('pointerdown', this._onPointerDown, this);
+        this.on('pointermove', this._onPointerMove, this);
+        this.on('pointerup', this._onPointerUp, this);
+        this.on('pointerupoutside', this._onPointerUp, this);
+        // Mouse wheel
+        this._onWheelBound = this._onWheel.bind(this);
+        // Scrollbar
+        const sbWidth = config.scrollbarWidth ?? 6;
+        const sbPadding = config.scrollbarPadding ?? 4;
+        this._scrollbarConfig = { width: sbWidth, padding: sbPadding };
+        if (config.scrollbar) {
+            const customThumb = resolveView(config.thumbView);
+            if (customThumb) {
+                this._scrollbar = customThumb;
+            }
+            else {
+                const g = new pixi_js.Graphics();
+                g.roundRect(0, 0, sbWidth, 40, sbWidth / 2).fill(config.scrollbarColor ?? 0xaaaaaa);
+                g.alpha = config.scrollbarAlpha ?? 0.5;
+                this._scrollbar = g;
+            }
+            this._scrollbar.visible = false;
+            super.addChild(this._scrollbar);
+        }
+        this._internalSetup = false;
+    }
+    /**
+     * Override addChild so external children are routed to scroll content.
+     * Enables `<scrollContainer><label /><panel /></scrollContainer>` in React JSX.
+     */
+    addChild(...children) {
+        if (this._internalSetup) {
+            return super.addChild(...children);
+        }
+        for (const child of children) {
+            this.addItem(child);
+        }
+        return children[0];
+    }
+    removeChild(...children) {
+        if (this._internalSetup) {
+            return super.removeChild(...children);
+        }
+        for (const child of children) {
+            const idx = this._items.indexOf(child);
+            if (idx !== -1) {
+                this._items.splice(idx, 1);
+                this._content.removeChild(child);
+            }
+        }
+        this.layoutItems();
+        return children[0];
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('width' in changed || 'height' in changed) {
+            this.setViewportSize(changed.width ?? this._viewport.width, changed.height ?? this._viewport.height);
+        }
+    }
+    /** Enable mouse wheel scrolling (call after adding to stage) */
+    enableWheel(canvas) {
+        if (this._onWheelBound) {
+            canvas.addEventListener('wheel', this._onWheelBound, { passive: false });
+        }
+    }
+    /** Set scrollable content. Replaces any existing items. */
+    setContent(content) {
+        this.clearItems();
+        const children = [...content.children];
+        for (const child of children) {
+            this.addItem(child);
+        }
+    }
+    /** Add a single item */
+    addItem(child) {
+        this._items.push(child);
+        this._content.addChild(child);
+        this.layoutItems();
+        return this;
+    }
+    /** Remove all items */
+    clearItems() {
+        for (const item of this._items) {
+            this._content.removeChild(item);
+        }
+        this._items.length = 0;
+    }
+    /** Get items */
+    get items() {
+        return this._items;
+    }
+    /** Scroll to make a specific item index visible */
+    scrollToItem(index) {
+        if (index < 0 || index >= this._items.length)
+            return;
+        const item = this._items[index];
+        const isVert = this._scrollConfig.direction !== 'horizontal';
+        if (isVert) {
+            this._content.y = -item.y + this._scrollConfig.padding;
+        }
+        else {
+            this._content.x = -item.x + this._scrollConfig.padding;
+        }
+        this.clampScroll();
+    }
+    /** Current scroll position */
+    get scrollPosition() {
+        return { x: this._content.x, y: this._content.y };
+    }
+    /** Resize the scroll viewport */
+    setViewportSize(width, height) {
+        this._viewport.width = width;
+        this._viewport.height = height;
+        this._maskGfx.clear();
+        this._maskGfx.roundRect(0, 0, width, height, this._scrollConfig.borderRadius).fill(0xffffff);
+        if (this._bg) {
+            this._bg.clear();
+            this._bg.roundRect(0, 0, width, height, this._scrollConfig.borderRadius)
+                .fill(0xffffff); // color will be overridden if needed
+        }
+        this.clampScroll();
+    }
+    // ─── Layout ──────────────────────────────────────────
+    layoutItems() {
+        const { direction, elementsMargin, padding } = this._scrollConfig;
+        const isVert = direction !== 'horizontal';
+        let pos = padding;
+        for (const item of this._items) {
+            if (isVert) {
+                item.x = padding;
+                item.y = pos;
+                pos += item.height + elementsMargin;
+            }
+            else {
+                item.x = pos;
+                item.y = padding;
+                pos += item.width + elementsMargin;
+            }
+        }
+    }
+    // ─── Drag handling ───────────────────────────────────
+    _onPointerDown(e) {
+        this._dragging = true;
+        this._inertiaActive = false;
+        this._dragStart.x = e.globalX;
+        this._dragStart.y = e.globalY;
+        this._contentStart.x = this._content.x;
+        this._contentStart.y = this._content.y;
+        this._lastDragPos.x = e.globalX;
+        this._lastDragPos.y = e.globalY;
+        this._lastDragTime = Date.now();
+        this._velocity.x = 0;
+        this._velocity.y = 0;
+        this.stopInertia();
+    }
+    _onPointerMove(e) {
+        if (!this._dragging)
+            return;
+        const dx = e.globalX - this._dragStart.x;
+        const dy = e.globalY - this._dragStart.y;
+        const { direction } = this._scrollConfig;
+        if (direction !== 'horizontal') {
+            this._content.y = this._contentStart.y + dy;
+        }
+        if (direction !== 'vertical') {
+            this._content.x = this._contentStart.x + dx;
+        }
+        // Track velocity
+        const now = Date.now();
+        const dt = now - this._lastDragTime;
+        if (dt > 0) {
+            this._velocity.x = (e.globalX - this._lastDragPos.x) / dt * 16;
+            this._velocity.y = (e.globalY - this._lastDragPos.y) / dt * 16;
+        }
+        this._lastDragPos.x = e.globalX;
+        this._lastDragPos.y = e.globalY;
+        this._lastDragTime = now;
+        this.clampScroll();
+    }
+    _onPointerUp() {
+        if (!this._dragging)
+            return;
+        this._dragging = false;
+        if (!this._scrollConfig.disableEasing &&
+            (Math.abs(this._velocity.x) > MIN_VELOCITY || Math.abs(this._velocity.y) > MIN_VELOCITY)) {
+            this.startInertia();
+        }
+    }
+    // ─── Inertia ─────────────────────────────────────────
+    startInertia() {
+        this._inertiaActive = true;
+        this._onTickBound = this._inertiaTick.bind(this);
+        pixi_js.Ticker.shared.add(this._onTickBound);
+    }
+    stopInertia() {
+        if (this._onTickBound && this._inertiaActive) {
+            pixi_js.Ticker.shared.remove(this._onTickBound);
+            this._inertiaActive = false;
+        }
+    }
+    _inertiaTick() {
+        const { direction } = this._scrollConfig;
+        if (direction !== 'horizontal') {
+            this._content.y += this._velocity.y;
+            this._velocity.y *= DECELERATION;
+        }
+        if (direction !== 'vertical') {
+            this._content.x += this._velocity.x;
+            this._velocity.x *= DECELERATION;
+        }
+        this.clampScroll();
+        if (Math.abs(this._velocity.x) < MIN_VELOCITY && Math.abs(this._velocity.y) < MIN_VELOCITY) {
+            this.stopInertia();
+        }
+    }
+    // ─── Mouse wheel ─────────────────────────────────────
+    _onWheel(e) {
+        const { direction } = this._scrollConfig;
+        e.preventDefault();
+        if (direction !== 'horizontal') {
+            this._content.y -= e.deltaY;
+        }
+        if (direction !== 'vertical') {
+            this._content.x -= e.deltaX;
+        }
+        this.clampScroll();
+    }
+    // ─── Scroll bounds ───────────────────────────────────
+    clampScroll() {
+        const { direction } = this._scrollConfig;
+        const bounds = this._content.getLocalBounds();
+        if (direction !== 'horizontal') {
+            const contentHeight = bounds.height + bounds.y;
+            const maxScroll = Math.min(0, this._viewport.height - contentHeight);
+            this._content.y = Math.max(maxScroll, Math.min(0, this._content.y));
+        }
+        if (direction !== 'vertical') {
+            const contentWidth = bounds.width + bounds.x;
+            const maxScroll = Math.min(0, this._viewport.width - contentWidth);
+            this._content.x = Math.max(maxScroll, Math.min(0, this._content.x));
+        }
+        this.updateScrollbar();
+    }
+    updateScrollbar() {
+        if (!this._scrollbar)
+            return;
+        const { direction } = this._scrollConfig;
+        const { width: sbW, padding: sbPad } = this._scrollbarConfig;
+        const bounds = this._content.getLocalBounds();
+        const isVert = direction !== 'horizontal';
+        if (isVert) {
+            const contentH = bounds.height + bounds.y;
+            if (contentH <= this._viewport.height) {
+                this._scrollbar.visible = false;
+                return;
+            }
+            this._scrollbar.visible = true;
+            const ratio = this._viewport.height / contentH;
+            const thumbH = Math.max(20, this._viewport.height * ratio);
+            const scrollRange = this._viewport.height - thumbH;
+            const scrollProgress = -this._content.y / (contentH - this._viewport.height);
+            this._scrollbar.x = this._viewport.width - sbW - sbPad;
+            this._scrollbar.y = scrollProgress * scrollRange;
+            this._scrollbar.height = thumbH;
+            this._scrollbar.width = sbW;
+        }
+        else {
+            const contentW = bounds.width + bounds.x;
+            if (contentW <= this._viewport.width) {
+                this._scrollbar.visible = false;
+                return;
+            }
+            this._scrollbar.visible = true;
+            const ratio = this._viewport.width / contentW;
+            const thumbW = Math.max(20, this._viewport.width * ratio);
+            const scrollRange = this._viewport.width - thumbW;
+            const scrollProgress = -this._content.x / (contentW - this._viewport.width);
+            this._scrollbar.y = this._viewport.height - sbW - sbPad;
+            this._scrollbar.x = scrollProgress * scrollRange;
+            this._scrollbar.width = thumbW;
+            this._scrollbar.height = sbW;
+        }
+    }
+    destroy(options) {
+        this.stopInertia();
+        this.off('pointerdown', this._onPointerDown, this);
+        this.off('pointermove', this._onPointerMove, this);
+        this.off('pointerup', this._onPointerUp, this);
+        this.off('pointerupoutside', this._onPointerUp, this);
+        this._items.length = 0;
+        super.destroy(options);
+    }
+}
+
+/**
+ * Draggable slider with customizable track, fill, and handle views.
+ *
+ * @example
+ * ```ts
+ * const volume = new Slider({
+ *   min: 0, max: 1, value: 0.5,
+ *   width: 200, height: 8,
+ *   fillColor: 0xffd700,
+ *   onUpdate: (v) => console.log('Volume:', v),
+ * });
+ * ```
+ */
+class Slider extends pixi_js.Container {
+    __uiComponent = true;
+    _track;
+    _fill;
+    _fillMask;
+    _handle;
+    _config;
+    _value;
+    _dragging = false;
+    onUpdate = null;
+    onChange = null;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            min: config.min ?? 0,
+            max: config.max ?? 1,
+            step: config.step ?? 0,
+            width: config.width ?? 200,
+            height: config.height ?? 8,
+            borderRadius: config.borderRadius ?? 4,
+            trackColor: config.trackColor ?? 0x333333,
+            fillColor: config.fillColor ?? 0xffd700,
+            handleRadius: config.handleRadius ?? 12,
+            handleColor: config.handleColor ?? 0xffffff,
+        };
+        this._value = config.value ?? this._config.min;
+        this.onUpdate = config.onUpdate ?? null;
+        this.onChange = config.onChange ?? null;
+        const { width, height, borderRadius, trackColor, fillColor, handleRadius, handleColor } = this._config;
+        // Track
+        const customTrack = resolveView(config.trackView);
+        if (customTrack) {
+            customTrack.width = width;
+            customTrack.height = height;
+            this._track = customTrack;
+        }
+        else {
+            const g = new pixi_js.Graphics();
+            g.roundRect(0, 0, width, height, borderRadius).fill(trackColor);
+            this._track = g;
+        }
+        this.addChild(this._track);
+        // Fill
+        const customFill = resolveView(config.fillView);
+        if (customFill) {
+            customFill.width = width;
+            customFill.height = height;
+            this._fill = customFill;
+        }
+        else {
+            const g = new pixi_js.Graphics();
+            g.roundRect(0, 0, width, height, borderRadius).fill(fillColor);
+            this._fill = g;
+        }
+        this.addChild(this._fill);
+        // Fill mask
+        this._fillMask = new pixi_js.Graphics();
+        this.addChild(this._fillMask);
+        this._fill.mask = this._fillMask;
+        // Handle
+        const customHandle = resolveView(config.handleView);
+        if (customHandle) {
+            this._handle = customHandle;
+        }
+        else {
+            const g = new pixi_js.Graphics();
+            g.circle(0, 0, handleRadius).fill(handleColor);
+            this._handle = g;
+        }
+        this._handle.y = height / 2;
+        this.addChild(this._handle);
+        // Interaction
+        this.eventMode = 'static';
+        this.cursor = 'pointer';
+        // Hit area covers track + handle overflow
+        const hitPad = Math.max(handleRadius - height / 2, 0);
+        this.hitArea = { contains: (x, y) => x >= -hitPad && x <= width + hitPad && y >= -hitPad && y <= height + hitPad };
+        this.on('pointerdown', this._onPointerDown, this);
+        this.on('globalpointermove', this._onPointerMove, this);
+        this.on('pointerup', this._onPointerUp, this);
+        this.on('pointerupoutside', this._onPointerUp, this);
+        this._updateVisuals();
+    }
+    /** Current value */
+    get value() {
+        return this._value;
+    }
+    set value(v) {
+        const clamped = this._applyStep(Math.max(this._config.min, Math.min(this._config.max, v)));
+        if (clamped === this._value)
+            return;
+        this._value = clamped;
+        this._updateVisuals();
+    }
+    get min() { return this._config.min; }
+    get max() { return this._config.max; }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('value' in changed)
+            this.value = changed.value;
+        if ('min' in changed) {
+            this._config.min = changed.min;
+            this._updateVisuals();
+        }
+        if ('max' in changed) {
+            this._config.max = changed.max;
+            this._updateVisuals();
+        }
+        if ('step' in changed)
+            this._config.step = changed.step;
+        if ('onUpdate' in changed)
+            this.onUpdate = changed.onUpdate;
+        if ('onChange' in changed)
+            this.onChange = changed.onChange;
+    }
+    _fraction() {
+        const { min, max } = this._config;
+        return max === min ? 0 : (this._value - min) / (max - min);
+    }
+    _applyStep(v) {
+        const { step, min } = this._config;
+        if (step <= 0)
+            return v;
+        return min + Math.round((v - min) / step) * step;
+    }
+    _updateVisuals() {
+        const frac = this._fraction();
+        const w = this._config.width;
+        const h = this._config.height;
+        // Update fill mask
+        this._fillMask.clear();
+        this._fillMask.rect(0, 0, w * frac, h).fill(0xffffff);
+        // Update handle position
+        this._handle.x = w * frac;
+    }
+    _valueFromPointer(e) {
+        const local = this.toLocal(e.global);
+        const frac = Math.max(0, Math.min(1, local.x / this._config.width));
+        const { min, max } = this._config;
+        return this._applyStep(min + frac * (max - min));
+    }
+    _onPointerDown(e) {
+        this._dragging = true;
+        const newValue = this._valueFromPointer(e);
+        if (newValue !== this._value) {
+            this._value = newValue;
+            this._updateVisuals();
+            this.onUpdate?.(this._value);
+        }
+    }
+    _onPointerMove(e) {
+        if (!this._dragging)
+            return;
+        const newValue = this._valueFromPointer(e);
+        if (newValue !== this._value) {
+            this._value = newValue;
+            this._updateVisuals();
+            this.onUpdate?.(this._value);
+        }
+    }
+    _onPointerUp(_e) {
+        if (!this._dragging)
+            return;
+        this._dragging = false;
+        this.onChange?.(this._value);
+    }
+    destroy(options) {
+        this.off('pointerdown', this._onPointerDown, this);
+        this.off('globalpointermove', this._onPointerMove, this);
+        this.off('pointerup', this._onPointerUp, this);
+        this.off('pointerupoutside', this._onPointerUp, this);
+        this.onUpdate = null;
+        this.onChange = null;
+        super.destroy(options);
+    }
+}
+
+/**
+ * Toggle switch with two states.
+ *
+ * Supports custom ON/OFF views or auto-generated Graphics-based toggle.
+ * Click to toggle, or use `forceSwitch(value)` programmatically.
+ *
+ * @example
+ * ```ts
+ * const mute = new Toggle({
+ *   value: false,
+ *   onColor: 0x22cc22,
+ *   onChange: (on) => audioManager.mute(!on),
+ * });
+ * ```
+ */
+class Toggle extends pixi_js.Container {
+    __uiComponent = true;
+    _value;
+    _onView = null;
+    _offView = null;
+    _handle = null;
+    _trackGfx = null;
+    _config;
+    _useCustomViews;
+    onChange = null;
+    constructor(config = {}) {
+        super();
+        this._config = {
+            width: config.width ?? 52,
+            height: config.height ?? 28,
+            onColor: config.onColor ?? 0x22cc22,
+            offColor: config.offColor ?? 0x666666,
+            handleColor: config.handleColor ?? 0xffffff,
+            handleRadius: config.handleRadius ?? 0, // 0 = auto
+            animationDuration: config.animationDuration ?? 200,
+        };
+        this._value = config.value ?? false;
+        this.onChange = config.onChange ?? null;
+        const customOn = resolveView(config.onView);
+        const customOff = resolveView(config.offView);
+        this._useCustomViews = !!(customOn || customOff);
+        if (this._useCustomViews) {
+            // Custom view mode: show/hide ON and OFF views
+            if (customOn) {
+                this._onView = customOn;
+                this._onView.visible = this._value;
+                this.addChild(this._onView);
+            }
+            if (customOff) {
+                this._offView = customOff;
+                this._offView.visible = !this._value;
+                this.addChild(this._offView);
+            }
+        }
+        else {
+            // Graphics mode: track + sliding handle
+            const { width, height, handleColor } = this._config;
+            const handleRadius = this._config.handleRadius || (height / 2 - 3);
+            this._config.handleRadius = handleRadius;
+            this._trackGfx = new pixi_js.Graphics();
+            this.addChild(this._trackGfx);
+            this._drawTrack();
+            const handle = new pixi_js.Graphics();
+            handle.circle(0, 0, handleRadius).fill(handleColor);
+            handle.y = height / 2;
+            handle.x = this._value ? width - handleRadius - 3 : handleRadius + 3;
+            this._handle = handle;
+            this.addChild(handle);
+        }
+        // Interaction
+        this.eventMode = 'static';
+        this.cursor = 'pointer';
+        this.on('pointertap', this._onTap, this);
+    }
+    /** Current toggle state */
+    get value() {
+        return this._value;
+    }
+    set value(v) {
+        if (v === this._value)
+            return;
+        this.forceSwitch(v);
+    }
+    /** Programmatically switch to a specific state with animation */
+    forceSwitch(value) {
+        this._value = value;
+        this._animateToState();
+    }
+    /** React reconciler update hook */
+    updateConfig(changed) {
+        if ('value' in changed)
+            this.value = changed.value;
+        if ('onChange' in changed)
+            this.onChange = changed.onChange;
+        if ('animationDuration' in changed)
+            this._config.animationDuration = changed.animationDuration;
+    }
+    _onTap() {
+        this._value = !this._value;
+        this._animateToState();
+        this.onChange?.(this._value);
+    }
+    _animateToState() {
+        const duration = this._config.animationDuration;
+        if (this._useCustomViews) {
+            // Custom views: crossfade
+            if (this._onView) {
+                Tween.killTweensOf(this._onView);
+                if (this._value) {
+                    this._onView.visible = true;
+                    Tween.to(this._onView, { alpha: 1 }, duration);
+                }
+                else {
+                    Tween.to(this._onView, { alpha: 0 }, duration).then(() => {
+                        if (this._onView)
+                            this._onView.visible = false;
+                    });
+                }
+            }
+            if (this._offView) {
+                Tween.killTweensOf(this._offView);
+                if (!this._value) {
+                    this._offView.visible = true;
+                    Tween.to(this._offView, { alpha: 1 }, duration);
+                }
+                else {
+                    Tween.to(this._offView, { alpha: 0 }, duration).then(() => {
+                        if (this._offView)
+                            this._offView.visible = false;
+                    });
+                }
+            }
+        }
+        else {
+            // Graphics mode: slide handle + recolor track
+            this._drawTrack();
+            if (this._handle) {
+                const { width } = this._config;
+                const handleRadius = this._config.handleRadius;
+                const targetX = this._value ? width - handleRadius - 3 : handleRadius + 3;
+                Tween.killTweensOf(this._handle);
+                Tween.to(this._handle, { x: targetX }, duration);
+            }
+        }
+    }
+    _drawTrack() {
+        if (!this._trackGfx)
+            return;
+        const { width, height, onColor, offColor } = this._config;
+        const radius = height / 2;
+        this._trackGfx.clear();
+        this._trackGfx.roundRect(0, 0, width, height, radius).fill(this._value ? onColor : offColor);
+    }
+    destroy(options) {
+        this.off('pointertap', this._onTap, this);
+        if (this._handle)
+            Tween.killTweensOf(this._handle);
+        if (this._onView)
+            Tween.killTweensOf(this._onView);
+        if (this._offView)
+            Tween.killTweensOf(this._offView);
+        this.onChange = null;
+        super.destroy(options);
+    }
+}
+
+/**
+ * Register all standard PixiJS display objects for JSX use.
+ * Call once at app startup before rendering any React scenes.
+ */
+function extendPixiElements() {
+    extend({
+        Container: pixi_js.Container,
+        Sprite: pixi_js.Sprite,
+        Graphics: pixi_js.Graphics,
+        Text: pixi_js.Text,
+        AnimatedSprite: pixi_js.AnimatedSprite,
+        NineSliceSprite: pixi_js.NineSliceSprite,
+        TilingSprite: pixi_js.TilingSprite,
+        Mesh: pixi_js.Mesh,
+        MeshPlane: pixi_js.MeshPlane,
+        MeshRope: pixi_js.MeshRope,
+        MeshSimple: pixi_js.MeshSimple,
+        BitmapText: pixi_js.BitmapText,
+        HTMLText: pixi_js.HTMLText,
+    });
+}
+/**
+ * Register all engine UI components for JSX use.
+ * Call once at app startup before rendering React scenes that use UI components.
+ *
+ * @example
+ * ```ts
+ * extendPixiElements();
+ * extendUIElements();
+ *
+ * // Now you can use:
+ * // <button text="SPIN" onPress={handler} />
+ * // <flexContainer direction="row" gap={16}>...</flexContainer>
+ * // <label text="Hello" style-fontSize={24} />
+ * ```
+ */
+function extendUIElements() {
+    extend({
+        Button, Label, Panel, FlexContainer, ProgressBar,
+        ScrollContainer, Modal, Toast, BalanceDisplay, WinDisplay, Layout,
+        Slider, Toggle,
+    });
+}
+/**
+ * Register additional custom components for JSX use.
+ * Pass an object mapping component names to their constructors.
+ */
+function extendCustomElements(components) {
+    extend(components);
 }
 
 /**
@@ -457,8 +3269,9 @@ exports.EngineContext = EngineContext;
 exports.ReactScene = ReactScene;
 exports.createPixiRoot = createPixiRoot;
 exports.extend = extend;
-exports.extendLayoutElements = extendLayoutElements;
+exports.extendCustomElements = extendCustomElements;
 exports.extendPixiElements = extendPixiElements;
+exports.extendUIElements = extendUIElements;
 exports.useAudio = useAudio;
 exports.useBalance = useBalance;
 exports.useEngine = useEngine;