@energy8platform/game-engine 0.15.0 → 0.15.2

package/dist/react.d.ts

@@ -1,8 +1,607 @@
-import { Container, ApplicationOptions, Application } from 'pixi.js';
+import { Texture, Container, TextStyle, ColorSource, ApplicationOptions, Application } from 'pixi.js';
 import * as react from 'react';
 import { ReactElement } from 'react';
 import { CasinoGameSDK, InitData, GameConfigData, SessionData } from '@energy8platform/game-sdk';
 
+/**
+ * Universal view input type for UI component visual slots.
+ *
+ * - `string` — texture name, resolved via `Sprite.from()`
+ * - `Texture` — wrapped in a `Sprite`
+ * - `Container` — used as-is (Sprite, Graphics, NineSliceSprite, AnimatedSprite, custom...)
+ */
+type ViewInput = string | Texture | Container;
+
+type ButtonState = 'default' | 'hover' | 'pressed' | 'disabled';
+interface ButtonConfig {
+    /** Custom view for default state (string texture name, Texture, or Container) */
+    defaultView?: ViewInput;
+    /** Custom view for hover state */
+    hoverView?: ViewInput;
+    /** Custom view for pressed state */
+    pressedView?: ViewInput;
+    /** Custom view for disabled state */
+    disabledView?: ViewInput;
+    /** Width (for Graphics-based button, ignored when custom views provided) */
+    width?: number;
+    /** Height (for Graphics-based button) */
+    height?: number;
+    /** Corner radius (for Graphics-based button) */
+    borderRadius?: number;
+    /** Colors for each state (for Graphics-based button) */
+    colors?: Partial<Record<ButtonState, number>>;
+    /** Scale on press */
+    pressScale?: number;
+    /** Scale animation duration (ms) */
+    animationDuration?: number;
+    /** Start disabled */
+    disabled?: boolean;
+    /** Button text (rendered on top of the view) */
+    text?: string;
+    /** Button text style */
+    textStyle?: Record<string, unknown>;
+    /** Press callback */
+    onPress?: () => void;
+}
+
+interface LabelConfig {
+    text?: string;
+    style?: Partial<TextStyle>;
+    /** Maximum width — text will be scaled down to fit */
+    maxWidth?: number;
+    /** Auto-fit: scale text to fit maxWidth */
+    autoFit?: boolean;
+}
+
+type FlexDirection = 'row' | 'column';
+type JustifyContent = 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+type AlignItems = 'start' | 'center' | 'end' | 'stretch';
+type AlignContent = 'start' | 'center' | 'end' | 'space-between' | 'stretch';
+type AlignSelf = 'auto' | 'start' | 'center' | 'end' | 'stretch';
+interface FlexContainerConfig {
+    /** Layout direction (default: 'row') */
+    direction?: FlexDirection;
+    /** Main-axis distribution (default: 'start') */
+    justifyContent?: JustifyContent;
+    /** Cross-axis alignment (default: 'start') */
+    alignItems?: AlignItems;
+    /** Gap between children in pixels (default: 0) */
+    gap?: number;
+    /** Padding [top, right, bottom, left] or single number (default: 0) */
+    padding?: number | [number, number, number, number];
+    /** Individual padding overrides (take priority over `padding`) */
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /** Enable wrapping to next line (default: false) */
+    flexWrap?: boolean;
+    /** Distribution of lines along the cross axis when wrapping (default: 'start') */
+    alignContent?: AlignContent;
+    /** Maximum width before wrapping (only with flexWrap) */
+    maxWidth?: number;
+    /** Maximum height before wrapping (only with flexWrap + column) */
+    maxHeight?: number;
+    /** Explicit container width — number in pixels, or string percentage (e.g. "50%") resolved against parent */
+    width?: number | string;
+    /** Explicit container height — number in pixels, or string percentage (e.g. "50%") resolved against parent */
+    height?: number | string;
+}
+
+type LabelValueAlign = 'start' | 'center' | 'end';
+interface LabelValueConfig {
+    /** Caption text (top row, typically smaller/muted) */
+    label?: string;
+    /** Value text (bottom row, typically larger/prominent) */
+    value?: string;
+    /** Style for the caption Label */
+    labelStyle?: Partial<TextStyle>;
+    /** Style for the value Label */
+    valueStyle?: Partial<TextStyle>;
+    /** Gap in pixels between caption and value (default: 4) */
+    gap?: number;
+    /** Horizontal alignment of both rows (default: 'center') */
+    align?: LabelValueAlign;
+    /** Maximum width — value will be auto-scaled to fit when exceeded */
+    maxWidth?: number;
+    /** Optional padding (forwarded to the underlying FlexContainer) */
+    padding?: FlexContainerConfig['padding'];
+}
+
+interface PanelConfig {
+    /** Width */
+    width?: number;
+    /** Height */
+    height?: number;
+    /** Background color (for Graphics-based panel) */
+    backgroundColor?: number;
+    /** Background alpha */
+    backgroundAlpha?: number;
+    /** Corner radius */
+    borderRadius?: number;
+    /** Border color */
+    borderColor?: number;
+    /** Border width */
+    borderWidth?: number;
+    /** 9-slice texture (if provided, uses NineSliceSprite instead of Graphics) */
+    nineSliceTexture?: string | Texture;
+    /** 9-slice borders [left, top, right, bottom] */
+    nineSliceBorders?: [number, number, number, number];
+    /** Padding inside the panel */
+    padding?: number;
+    /** Flex layout config for content */
+    layout?: Partial<FlexContainerConfig>;
+}
+
+interface ProgressBarConfig {
+    /** Width of the bar */
+    width?: number;
+    /** Height of the bar */
+    height?: number;
+    /** Corner radius (for Graphics-based bar) */
+    borderRadius?: number;
+    /** Fill color (for Graphics-based bar, ignored when fillView provided) */
+    fillColor?: number;
+    /** Track background color (for Graphics-based bar, ignored when trackView provided) */
+    trackColor?: number;
+    /** Border color */
+    borderColor?: number;
+    /** Border width */
+    borderWidth?: number;
+    /** Animated fill (smoothly interpolate) */
+    animated?: boolean;
+    /** Animation speed (0..1 per frame, default: 0.1) */
+    animationSpeed?: number;
+    /** Custom track background (string texture name, Texture, or Container) */
+    trackView?: ViewInput;
+    /** Custom fill bar (string texture name, Texture, or Container) */
+    fillView?: ViewInput;
+}
+
+type ScrollDirection = 'vertical' | 'horizontal' | 'both';
+interface ScrollContainerConfig {
+    /** Visible viewport width */
+    width: number;
+    /** Visible viewport height */
+    height: number;
+    /** Scroll direction (default: 'vertical') */
+    direction?: ScrollDirection;
+    /** Background color (undefined = transparent) */
+    backgroundColor?: ColorSource;
+    /** Border radius for the mask (default: 0) */
+    borderRadius?: number;
+    /** Gap between items (default: 0) */
+    elementsMargin?: number;
+    /** Padding */
+    padding?: number;
+    /** Disable easing/inertia */
+    disableEasing?: boolean;
+    /** Show scrollbar indicator (default: false) */
+    scrollbar?: boolean;
+    /** Custom scrollbar thumb view (string texture name, Texture, or Container) */
+    thumbView?: ViewInput;
+    /** Scrollbar width in px (default: 6) */
+    scrollbarWidth?: number;
+    /** Scrollbar padding from edge (default: 4) */
+    scrollbarPadding?: number;
+    /** Scrollbar color (when no thumbView, default: 0xaaaaaa) */
+    scrollbarColor?: number;
+    /** Scrollbar alpha (default: 0.5) */
+    scrollbarAlpha?: number;
+}
+
+interface ModalConfig {
+    /** Overlay color */
+    overlayColor?: number;
+    /** Overlay alpha */
+    overlayAlpha?: number;
+    /** Close on overlay tap */
+    closeOnOverlay?: boolean;
+    /** Animation duration */
+    animationDuration?: number;
+}
+
+interface ToastConfig {
+    /** Auto-dismiss after this many ms (0 = manual dismiss only) */
+    duration?: number;
+    /** Toast position from bottom */
+    bottomOffset?: number;
+    /** Custom background view (string texture name, Texture, or Container). Sized to fit text. */
+    backgroundView?: ViewInput;
+}
+
+interface BalanceDisplayConfig {
+    /** Label prefix (e.g., "BALANCE") */
+    prefix?: string;
+    /** Text style overrides */
+    style?: Record<string, unknown>;
+    /** Currency code */
+    currency?: string;
+    /** Locale for number formatting */
+    locale?: string;
+    /** Max width */
+    maxWidth?: number;
+    /** Animate value changes */
+    animated?: boolean;
+    /** Animation duration in ms */
+    animationDuration?: number;
+}
+
+interface WinDisplayConfig {
+    /** Text style overrides */
+    style?: Record<string, unknown>;
+    /** Currency code */
+    currency?: string;
+    /** Locale for number formatting */
+    locale?: string;
+    /** Countup duration in ms */
+    countupDuration?: number;
+    /** Scale pop animation on win */
+    popScale?: number;
+}
+
+type LayoutDirection = 'horizontal' | 'vertical' | 'grid' | 'wrap';
+type LayoutAlignment = 'start' | 'center' | 'end' | 'stretch';
+type LayoutAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+interface LayoutConfig {
+    /** Layout direction (default: 'vertical') */
+    direction?: LayoutDirection;
+    /** Gap between children in pixels (default: 0) */
+    gap?: number;
+    /** Padding inside the layout container [top, right, bottom, left] or a single number */
+    padding?: number | [number, number, number, number];
+    /** Alignment of children on the cross axis (default: 'start') */
+    alignment?: LayoutAlignment;
+    /** Anchor point determining where the layout is positioned relative to its coordinates */
+    anchor?: LayoutAnchor;
+    /** Number of columns (only for 'grid' direction) */
+    columns?: number;
+    /** Maximum width for 'wrap' direction before wrapping to next line */
+    maxWidth?: number;
+    /** Whether to auto-layout when children change (default: true) */
+    autoLayout?: boolean;
+    /** Breakpoints: map of max viewport widths to override configs */
+    breakpoints?: Record<number, Partial<LayoutConfig>>;
+}
+
+interface SliderConfig {
+    /** Minimum value (default: 0) */
+    min?: number;
+    /** Maximum value (default: 1) */
+    max?: number;
+    /** Step increment (0 = continuous, default: 0) */
+    step?: number;
+    /** Initial value (default: min) */
+    value?: number;
+    /** Track width in pixels (default: 200) */
+    width?: number;
+    /** Track height in pixels (default: 8) */
+    height?: number;
+    /** Corner radius for Graphics-based track/fill (default: 4) */
+    borderRadius?: number;
+    /** Track background color (ignored when trackView provided) */
+    trackColor?: number;
+    /** Fill bar color (ignored when fillView provided) */
+    fillColor?: number;
+    /** Handle radius (for Graphics-based handle, default: 12) */
+    handleRadius?: number;
+    /** Handle color (for Graphics-based handle, ignored when handleView provided) */
+    handleColor?: number;
+    /** Custom track background view */
+    trackView?: ViewInput;
+    /** Custom fill bar view */
+    fillView?: ViewInput;
+    /** Custom handle view */
+    handleView?: ViewInput;
+    /** Called when value changes during drag */
+    onUpdate?: (value: number) => void;
+    /** Called when drag ends */
+    onChange?: (value: number) => void;
+}
+
+interface ToggleConfig {
+    /** Initial state (default: false) */
+    value?: boolean;
+    /** Custom view for the ON state */
+    onView?: ViewInput;
+    /** Custom view for the OFF state */
+    offView?: ViewInput;
+    /** Width (for Graphics-based toggle, default: 52) */
+    width?: number;
+    /** Height (for Graphics-based toggle, default: 28) */
+    height?: number;
+    /** Track color when ON (ignored when custom views provided) */
+    onColor?: number;
+    /** Track color when OFF (ignored when custom views provided) */
+    offColor?: number;
+    /** Handle color (for Graphics-based toggle) */
+    handleColor?: number;
+    /** Handle radius (for Graphics-based toggle, default: auto) */
+    handleRadius?: number;
+    /** Animation duration in ms (default: 200) */
+    animationDuration?: number;
+    /** Called when value changes */
+    onChange?: (value: boolean) => void;
+}
+
+/**
+ * JSX prop types for the PixiJS React reconciler.
+ *
+ * The engine auto-augments `react`'s module-scoped `JSX.IntrinsicElements`
+ * with every registered element (`<flexContainer>`, `<button>`, `<label>`,
+ * `<labelValue>`, etc). Because the augmentation is scoped to the `react`
+ * module (not the legacy global `JSX` namespace), it reliably wins over
+ * `@types/react`'s HTML defaults for colliding names like `<button>` / `<label>`.
+ *
+ * **Consumers don't need any shim.** Any import from `@energy8platform/game-engine/react`
+ * (e.g. `createPixiRoot`, `extendUIElements`, `ReactScene` — you're already
+ * importing these to boot the reconciler) pulls this module in and the JSX
+ * types activate automatically.
+ *
+ * If a project imports only from `/ui` or `/core` and never touches `/react`,
+ * add a one-line side-effect import to trigger the augmentation:
+ *
+ * ```ts
+ * // app/src/pixi-jsx.d.ts
+ * import '@energy8platform/game-engine/react-jsx';
+ * ```
+ *
+ * Dash-notation for nested config objects is supported:
+ *   <button colors-default={0xff0000} colors-hover={0x00ff00} />
+ */
+
+interface PixiEventProps {
+    onClick?: (e: any) => void;
+    onPointerDown?: (e: any) => void;
+    onPointerUp?: (e: any) => void;
+    onPointerMove?: (e: any) => void;
+    onPointerOver?: (e: any) => void;
+    onPointerOut?: (e: any) => void;
+    onPointerEnter?: (e: any) => void;
+    onPointerLeave?: (e: any) => void;
+    onPointerCancel?: (e: any) => void;
+    onPointerTap?: (e: any) => void;
+    onPointerUpOutside?: (e: any) => void;
+    onMouseDown?: (e: any) => void;
+    onMouseUp?: (e: any) => void;
+    onMouseMove?: (e: any) => void;
+    onMouseOver?: (e: any) => void;
+    onMouseOut?: (e: any) => void;
+    onWheel?: (e: any) => void;
+    onTap?: (e: any) => void;
+    onRightClick?: (e: any) => void;
+}
+interface BaseProps extends PixiEventProps {
+    key?: React.Key;
+    ref?: React.Ref<any>;
+    children?: React.ReactNode;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    alpha?: number;
+    visible?: boolean;
+    rotation?: number;
+    angle?: number;
+    zIndex?: number;
+    label?: string;
+    cursor?: string;
+    eventMode?: 'auto' | 'none' | 'passive' | 'static' | 'dynamic';
+    'scale-x'?: number;
+    'scale-y'?: number;
+    'pivot-x'?: number;
+    'pivot-y'?: number;
+    'position-x'?: number;
+    'position-y'?: number;
+    'anchor-x'?: number;
+    'anchor-y'?: number;
+    scale?: number | {
+        x: number;
+        y: number;
+    };
+    flexGrow?: number;
+    flexShrink?: number;
+    layoutWidth?: number | string;
+    layoutHeight?: number | string;
+    alignSelf?: AlignSelf;
+    flexExclude?: boolean;
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    /** X coordinate of the visual center within parent (px or `'50%'`). Overrides left/right. */
+    centerX?: number | string;
+    /** Y coordinate of the visual center within parent (px or `'50%'`). Overrides top/bottom. */
+    centerY?: number | string;
+}
+interface SpriteProps extends BaseProps {
+    texture?: string | Texture;
+    anchor?: number | {
+        x: number;
+        y: number;
+    };
+    tint?: number;
+}
+interface TextProps extends BaseProps {
+    text?: string;
+    style?: Partial<TextStyle>;
+    anchor?: number | {
+        x: number;
+        y: number;
+    };
+    'style-fontSize'?: number;
+    'style-fill'?: number | string;
+    'style-fontFamily'?: string;
+    'style-fontWeight'?: string;
+    'style-letterSpacing'?: number;
+}
+interface GraphicsProps extends BaseProps {
+    /** Draw function: receives the Graphics instance, called on mount and updates */
+    draw?: (g: any) => void;
+    /**
+     * Layout size hint (pixels). For Graphics, `width`/`height` do NOT apply a scale
+     * transform (unlike Container.width). They're forwarded to the parent
+     * FlexContainer as `layoutWidth`/`layoutHeight` so layout measures the element
+     * at the requested size while the actual geometry stays in the `draw` callback.
+     */
+    width?: number;
+    height?: number;
+}
+interface AnimatedSpriteProps extends BaseProps {
+    textures?: Texture[];
+    animationSpeed?: number;
+    loop?: boolean;
+    playing?: boolean;
+}
+interface NineSliceSpriteProps extends BaseProps {
+    texture?: string | Texture;
+    leftWidth?: number;
+    topHeight?: number;
+    rightWidth?: number;
+    bottomHeight?: number;
+}
+interface TilingSpriteProps extends BaseProps {
+    texture?: string | Texture;
+    tilePosition?: {
+        x: number;
+        y: number;
+    };
+}
+interface ButtonComponentProps extends BaseProps, Omit<ButtonConfig, 'colors' | 'textStyle'> {
+    colors?: Partial<Record<ButtonState, number>>;
+    textStyle?: Record<string, unknown>;
+    defaultView?: ViewInput;
+    hoverView?: ViewInput;
+    pressedView?: ViewInput;
+    disabledView?: ViewInput;
+    'colors-default'?: number;
+    'colors-hover'?: number;
+    'colors-pressed'?: number;
+    'colors-disabled'?: number;
+    'textStyle-fontSize'?: number;
+    'textStyle-fill'?: number | string;
+    'textStyle-fontFamily'?: string;
+    'textStyle-fontWeight'?: string;
+    'textStyle-fontStyle'?: string;
+    'textStyle-letterSpacing'?: number;
+    onPress?: () => void;
+}
+interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
+    style?: Partial<TextStyle>;
+    'style-fontSize'?: number;
+    'style-fill'?: number | string;
+    'style-fontFamily'?: string;
+    'style-fontWeight'?: string;
+    'style-letterSpacing'?: number;
+}
+interface LabelValueComponentProps extends Omit<BaseProps, 'width' | 'height' | 'label'>, Omit<LabelValueConfig, 'labelStyle' | 'valueStyle'> {
+    labelStyle?: Partial<TextStyle>;
+    valueStyle?: Partial<TextStyle>;
+    width?: number | string;
+    height?: number | string;
+    'labelStyle-fontSize'?: number;
+    'labelStyle-fill'?: number | string;
+    'labelStyle-fontFamily'?: string;
+    'labelStyle-fontWeight'?: string;
+    'valueStyle-fontSize'?: number;
+    'valueStyle-fill'?: number | string;
+    'valueStyle-fontFamily'?: string;
+    'valueStyle-fontWeight'?: string;
+}
+interface PanelComponentProps extends BaseProps, Omit<PanelConfig, 'layout'> {
+    layout?: Partial<FlexContainerConfig>;
+}
+interface FlexContainerComponentProps extends Omit<BaseProps, 'width' | 'height'>, FlexContainerConfig {
+    padding?: number | [number, number, number, number];
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    alignContent?: AlignContent;
+    width?: number | string;
+    height?: number | string;
+}
+interface ProgressBarComponentProps extends BaseProps, ProgressBarConfig {
+    progress?: number;
+    /** Custom track background (string texture name, Texture, or Container) */
+    trackView?: ViewInput;
+    /** Custom fill bar */
+    fillView?: ViewInput;
+}
+interface ScrollContainerComponentProps extends BaseProps, Omit<ScrollContainerConfig, 'width' | 'height'> {
+    width: number;
+    height: number;
+    /** Show scrollbar indicator */
+    scrollbar?: boolean;
+    /** Custom scrollbar thumb view */
+    thumbView?: ViewInput;
+    scrollbarWidth?: number;
+    scrollbarPadding?: number;
+    scrollbarColor?: number;
+    scrollbarAlpha?: number;
+}
+interface ModalComponentProps extends BaseProps, ModalConfig {
+    onClose?: () => void;
+}
+interface ToastComponentProps extends BaseProps, ToastConfig {
+    /** Custom background view */
+    backgroundView?: ViewInput;
+}
+interface BalanceDisplayComponentProps extends BaseProps, BalanceDisplayConfig {
+    /** Current balance value */
+    value?: number;
+}
+interface WinDisplayComponentProps extends BaseProps, WinDisplayConfig {
+}
+interface LayoutComponentProps extends BaseProps, LayoutConfig {
+}
+interface SliderComponentProps extends BaseProps, Omit<SliderConfig, 'width' | 'height'> {
+    width?: number;
+    height?: number;
+    onUpdate?: (value: number) => void;
+    onChange?: (value: number) => void;
+}
+interface ToggleComponentProps extends BaseProps, Omit<ToggleConfig, 'width' | 'height'> {
+    width?: number;
+    height?: number;
+    onView?: ViewInput;
+    offView?: ViewInput;
+    onChange?: (value: boolean) => void;
+}
+/**
+ * Complete element → prop-type map for all engine-registered JSX elements.
+ * Also consumable directly for typing custom wrappers around engine elements.
+ */
+interface EngineIntrinsicElements {
+    container: BaseProps;
+    sprite: SpriteProps;
+    text: TextProps;
+    graphics: GraphicsProps;
+    animatedSprite: AnimatedSpriteProps;
+    nineSliceSprite: NineSliceSpriteProps;
+    tilingSprite: TilingSpriteProps;
+    button: ButtonComponentProps;
+    label: LabelComponentProps;
+    labelValue: LabelValueComponentProps;
+    panel: PanelComponentProps;
+    flexContainer: FlexContainerComponentProps;
+    progressBar: ProgressBarComponentProps;
+    scrollContainer: ScrollContainerComponentProps;
+    modal: ModalComponentProps;
+    toast: ToastComponentProps;
+    balanceDisplay: BalanceDisplayComponentProps;
+    winDisplay: WinDisplayComponentProps;
+    layout: LayoutComponentProps;
+    slider: SliderComponentProps;
+    toggle: ToggleComponentProps;
+}
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements extends EngineIntrinsicElements {
+        }
+    }
+}
+
 interface PixiRoot {
     render(element: ReactElement): void;
     unmount(): void;

package/dist/react.esm.js

@@ -312,24 +312,29 @@ function measureChild(child, parentContentW = 0, parentContentH = 0) {
     const cfg = child._flexConfig;
     const resolvedLW = resolveDimension(cfg?.layoutWidth, parentContentW);
     const resolvedLH = resolveDimension(cfg?.layoutHeight, parentContentH);
-    if (resolvedLW !== undefined && resolvedLH !== undefined) {
-        return { w: resolvedLW, h: resolvedLH, ox: 0, oy: 0 };
-    }
-    // For FlexContainers, use their explicit or computed size
+    // FlexContainer children are top-left origin by construction, so `ox/oy = 0`
+    // is correct and we can skip the `getLocalBounds()` call entirely.
     if (child instanceof FlexContainer) {
         const fc = child;
         const w = fc._explicitWidth > 0 ? fc._explicitWidth : (fc._computedWidth > 0 ? fc._computedWidth : undefined);
         const h = fc._explicitHeight > 0 ? fc._explicitHeight : (fc._computedHeight > 0 ? fc._computedHeight : undefined);
         if (w !== undefined && h !== undefined) {
-            return { w, h, ox: 0, oy: 0 };
+            return { w: resolvedLW ?? w, h: resolvedLH ?? h, 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).
+    // Use localBounds to get the true visual origin offset.
+    // We take `ox/oy` from bounds unconditionally — a user-supplied `layoutWidth/Height`
+    // overrides the SIZE used by flex (protection against pre-paint bounds of 0), but
+    // it must NOT erase the center-anchor compensation: Button/Label views are drawn at
+    // `(-w/2..w/2)` and their bounds.x = -w/2 is what lets `layoutLine` place the
+    // visible rectangle where the layout intends.
     const bounds = child.getLocalBounds();
-    const w = resolvedLW ?? bounds.width;
-    const h = resolvedLH ?? bounds.height;
-    return { w, h, ox: bounds.x, oy: bounds.y };
+    return {
+        w: resolvedLW ?? bounds.width,
+        h: resolvedLH ?? bounds.height,
+        ox: bounds.x,
+        oy: bounds.y,
+    };
 }
 /**
  * Set a child's main or cross dimension.
@@ -818,30 +823,35 @@ class FlexContainer extends Container {
             this._computedHeight = this._explicitHeight > 0 ? this._explicitHeight : (pt + naturalMainSize + pb);
         }
         // Position flexExclude children (absolute positioning).
-        // All position props describe the visual (bounds) rectangle, so we subtract
-        // `ox/oy` to compensate for children with a centered origin (Button, Label).
+        // All position props describe the visual (bounds) rectangle. We derive the
+        // visual rectangle directly from `getLocalBounds()` rather than the
+        // layout-config `w`/`h` returned by measureChild — those may differ from
+        // actual bounds when the user pins `layoutWidth`/`layoutHeight` to a value
+        // that doesn't match the child's real visual extent (e.g. a Button whose
+        // text overflows its configured `width`). Mixing layout size with real
+        // bounds-origin would shift the visual center off the requested point.
         // `centerX/centerY` take precedence over `left/right` / `top/bottom` on each axis.
         for (const child of this._layoutChildren) {
             if (!child._flexConfig?.flexExclude)
                 continue;
             const cfg = child._flexConfig;
-            const { w, h, ox, oy } = measureChild(child, pctRefW, pctRefH);
+            const bounds = child.getLocalBounds();
             const cw = this._computedWidth;
             const ch = this._computedHeight;
             const centerX = resolveDimension(cfg.centerX, pctRefW);
             if (centerX !== undefined)
-                child.x = centerX - w / 2 - ox;
+                child.x = centerX - bounds.x - bounds.width / 2;
             else if (cfg.left !== undefined)
-                child.x = cfg.left - ox;
+                child.x = cfg.left - bounds.x;
             else if (cfg.right !== undefined)
-                child.x = cw - w - cfg.right - ox;
+                child.x = cw - cfg.right - bounds.x - bounds.width;
             const centerY = resolveDimension(cfg.centerY, pctRefH);
             if (centerY !== undefined)
-                child.y = centerY - h / 2 - oy;
+                child.y = centerY - bounds.y - bounds.height / 2;
             else if (cfg.top !== undefined)
-                child.y = cfg.top - oy;
+                child.y = cfg.top - bounds.y;
             else if (cfg.bottom !== undefined)
-                child.y = ch - h - cfg.bottom - oy;
+                child.y = ch - cfg.bottom - bounds.y - bounds.height;
         }
     }
     /** Computed content size (after layout) */