@energy8platform/game-engine 0.15.0 → 0.15.2

package/src/react/jsx-runtime.ts

@@ -1,17 +1,26 @@
 /**
- * Ambient JSX IntrinsicElements declarations for the PixiJS React reconciler.
+ * JSX prop types for the PixiJS React reconciler.
  *
- * Consumer apps opt in once (e.g. from an app-level `vite-env.d.ts`):
+ * 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>`.
  *
- *   import '@energy8platform/game-engine/react-jsx';
+ * **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.
  *
- * After that, TypeScript recognises `<flexContainer>`, `<button>`, `<label>` etc.
- * with fully-typed props — no need to hand-maintain a local `pixi-jsx.d.ts`.
+ * If a project imports only from `/ui` or `/core` and never touches `/react`,
+ * add a one-line side-effect import to trigger the augmentation:
  *
- * The JS entry for this subpath is intentionally empty: this module exists
- * solely to carry type declarations that side-effect the global `JSX` namespace.
+ * ```ts
+ * // app/src/pixi-jsx.d.ts
+ * import '@energy8platform/game-engine/react-jsx';
+ * ```
  *
- * Dash-notation is supported for nested config objects:
+ * Dash-notation for nested config objects is supported:
  *   <button colors-default={0xff0000} colors-hover={0x00ff00} />
  */
 
@@ -34,7 +43,7 @@ import type { ToggleConfig } from '../ui/Toggle';
 
 // ─── Event props ─────────────────────────────────────────
 
-interface PixiEventProps {
+export interface PixiEventProps {
   onClick?: (e: any) => void;
   onPointerDown?: (e: any) => void;
   onPointerUp?: (e: any) => void;
@@ -58,7 +67,7 @@ interface PixiEventProps {
 
 // ─── Base container props (shared by all elements) ───────
 
-interface BaseProps extends PixiEventProps {
+export interface BaseProps extends PixiEventProps {
   key?: React.Key;
   ref?: React.Ref<any>;
   children?: React.ReactNode;
@@ -113,13 +122,13 @@ interface BaseProps extends PixiEventProps {
 
 // ─── PixiJS primitive elements ───────────────────────────
 
-interface SpriteProps extends BaseProps {
+export interface SpriteProps extends BaseProps {
   texture?: string | Texture;
   anchor?: number | { x: number; y: number };
   tint?: number;
 }
 
-interface TextProps extends BaseProps {
+export interface TextProps extends BaseProps {
   text?: string;
   style?: Partial<TextStyle>;
   anchor?: number | { x: number; y: number };
@@ -131,7 +140,7 @@ interface TextProps extends BaseProps {
   'style-letterSpacing'?: number;
 }
 
-interface GraphicsProps extends BaseProps {
+export interface GraphicsProps extends BaseProps {
   /** Draw function: receives the Graphics instance, called on mount and updates */
   draw?: (g: any) => void;
   /**
@@ -144,9 +153,29 @@ interface GraphicsProps extends BaseProps {
   height?: number;
 }
 
+export interface AnimatedSpriteProps extends BaseProps {
+  textures?: Texture[];
+  animationSpeed?: number;
+  loop?: boolean;
+  playing?: boolean;
+}
+
+export interface NineSliceSpriteProps extends BaseProps {
+  texture?: string | Texture;
+  leftWidth?: number;
+  topHeight?: number;
+  rightWidth?: number;
+  bottomHeight?: number;
+}
+
+export interface TilingSpriteProps extends BaseProps {
+  texture?: string | Texture;
+  tilePosition?: { x: number; y: number };
+}
+
 // ─── Engine UI component props ───────────────────────────
 
-interface ButtonComponentProps extends BaseProps, Omit<ButtonConfig, 'colors' | 'textStyle'> {
+export interface ButtonComponentProps extends BaseProps, Omit<ButtonConfig, 'colors' | 'textStyle'> {
   // Full object form
   colors?: Partial<Record<ButtonState, number>>;
   textStyle?: Record<string, unknown>;
@@ -170,7 +199,7 @@ interface ButtonComponentProps extends BaseProps, Omit<ButtonConfig, 'colors' |
   onPress?: () => void;
 }
 
-interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
+export interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
   style?: Partial<TextStyle>;
   'style-fontSize'?: number;
   'style-fill'?: number | string;
@@ -179,7 +208,7 @@ interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
   'style-letterSpacing'?: number;
 }
 
-interface LabelValueComponentProps extends Omit<BaseProps, 'width' | 'height' | 'label'>,
+export interface LabelValueComponentProps extends Omit<BaseProps, 'width' | 'height' | 'label'>,
   Omit<LabelValueConfig, 'labelStyle' | 'valueStyle'> {
   labelStyle?: Partial<TextStyle>;
   valueStyle?: Partial<TextStyle>;
@@ -196,11 +225,11 @@ interface LabelValueComponentProps extends Omit<BaseProps, 'width' | 'height' |
   'valueStyle-fontWeight'?: string;
 }
 
-interface PanelComponentProps extends BaseProps, Omit<PanelConfig, 'layout'> {
+export interface PanelComponentProps extends BaseProps, Omit<PanelConfig, 'layout'> {
   layout?: Partial<FlexContainerConfig>;
 }
 
-interface FlexContainerComponentProps extends Omit<BaseProps, 'width' | 'height'>, FlexContainerConfig {
+export interface FlexContainerComponentProps extends Omit<BaseProps, 'width' | 'height'>, FlexContainerConfig {
   padding?: number | [number, number, number, number];
   paddingTop?: number;
   paddingRight?: number;
@@ -211,7 +240,7 @@ interface FlexContainerComponentProps extends Omit<BaseProps, 'width' | 'height'
   height?: number | string;
 }
 
-interface ProgressBarComponentProps extends BaseProps, ProgressBarConfig {
+export interface ProgressBarComponentProps extends BaseProps, ProgressBarConfig {
   progress?: number;
   /** Custom track background (string texture name, Texture, or Container) */
   trackView?: ViewInput;
@@ -219,7 +248,7 @@ interface ProgressBarComponentProps extends BaseProps, ProgressBarConfig {
   fillView?: ViewInput;
 }
 
-interface ScrollContainerComponentProps extends BaseProps, Omit<ScrollContainerConfig, 'width' | 'height'> {
+export interface ScrollContainerComponentProps extends BaseProps, Omit<ScrollContainerConfig, 'width' | 'height'> {
   width: number;
   height: number;
   /** Show scrollbar indicator */
@@ -232,32 +261,32 @@ interface ScrollContainerComponentProps extends BaseProps, Omit<ScrollContainerC
   scrollbarAlpha?: number;
 }
 
-interface ModalComponentProps extends BaseProps, ModalConfig {
+export interface ModalComponentProps extends BaseProps, ModalConfig {
   onClose?: () => void;
 }
 
-interface ToastComponentProps extends BaseProps, ToastConfig {
+export interface ToastComponentProps extends BaseProps, ToastConfig {
   /** Custom background view */
   backgroundView?: ViewInput;
 }
 
-interface BalanceDisplayComponentProps extends BaseProps, BalanceDisplayConfig {
+export interface BalanceDisplayComponentProps extends BaseProps, BalanceDisplayConfig {
   /** Current balance value */
   value?: number;
 }
 
-interface WinDisplayComponentProps extends BaseProps, WinDisplayConfig {}
+export interface WinDisplayComponentProps extends BaseProps, WinDisplayConfig {}
 
-interface LayoutComponentProps extends BaseProps, LayoutConfig {}
+export interface LayoutComponentProps extends BaseProps, LayoutConfig {}
 
-interface SliderComponentProps extends BaseProps, Omit<SliderConfig, 'width' | 'height'> {
+export 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'> {
+export interface ToggleComponentProps extends BaseProps, Omit<ToggleConfig, 'width' | 'height'> {
   width?: number;
   height?: number;
   onView?: ViewInput;
@@ -265,37 +294,53 @@ interface ToggleComponentProps extends BaseProps, Omit<ToggleConfig, 'width' | '
   onChange?: (value: boolean) => void;
 }
 
-// ─── JSX IntrinsicElements ───────────────────────────────
+// ─── IntrinsicElements map ───────────────────────────────
+
+/**
+ * Complete element → prop-type map for all engine-registered JSX elements.
+ * Also consumable directly for typing custom wrappers around engine elements.
+ */
+export interface EngineIntrinsicElements {
+  // PixiJS primitives
+  container: BaseProps;
+  sprite: SpriteProps;
+  text: TextProps;
+  graphics: GraphicsProps;
+  animatedSprite: AnimatedSpriteProps;
+  nineSliceSprite: NineSliceSpriteProps;
+  tilingSprite: TilingSpriteProps;
+
+  // Engine UI components
+  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 global {
+// ─── Auto-augment React's JSX namespace ──────────────────
+//
+// React 19 scopes `JSX.IntrinsicElements` inside `declare module 'react'`,
+// so we augment the same module. `extends EngineIntrinsicElements {}` adds
+// every engine element to the interface the reconciler sees.
+//
+// Interface merging with `@types/react`'s HTML defaults: property names
+// unique to the engine (`flexContainer`, `labelValue`, `button` since it
+// carries our ButtonComponentProps, etc.) merge cleanly. For HTML-colliding
+// names (`button`, `label`), this module-scoped augmentation takes precedence
+// over the legacy global JSX namespace in React-19 apps.
+
+declare module 'react' {
   namespace JSX {
-    interface IntrinsicElements {
-      // PixiJS primitives
-      container: BaseProps;
-      sprite: SpriteProps;
-      text: TextProps;
-      graphics: GraphicsProps;
-      animatedSprite: BaseProps & { textures?: Texture[]; animationSpeed?: number; loop?: boolean; playing?: boolean };
-      nineSliceSprite: BaseProps & { texture?: string | Texture; leftWidth?: number; topHeight?: number; rightWidth?: number; bottomHeight?: number };
-      tilingSprite: BaseProps & { texture?: string | Texture; tilePosition?: { x: number; y: number } };
-
-      // Engine UI components
-      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;
-    }
+    interface IntrinsicElements extends EngineIntrinsicElements {}
   }
 }
-
-export {};

package/src/ui/FlexContainer.ts

@@ -118,26 +118,31 @@ function measureChild(
   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,
+  };
 }
 
 // ─── Layout items within a single line ───────────────────
@@ -699,25 +704,30 @@ export class FlexContainer extends Container {
     }
 
     // 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;
-      else if (cfg.left !== undefined) child.x = cfg.left - ox;
-      else if (cfg.right !== undefined) child.x = cw - w - cfg.right - ox;
+      if (centerX !== undefined) child.x = centerX - bounds.x - bounds.width / 2;
+      else if (cfg.left !== undefined) child.x = cfg.left - bounds.x;
+      else if (cfg.right !== undefined) child.x = cw - cfg.right - bounds.x - bounds.width;
 
       const centerY = resolveDimension(cfg.centerY, pctRefH);
-      if (centerY !== undefined) child.y = centerY - h / 2 - oy;
-      else if (cfg.top !== undefined) child.y = cfg.top - oy;
-      else if (cfg.bottom !== undefined) child.y = ch - h - cfg.bottom - oy;
+      if (centerY !== undefined) child.y = centerY - bounds.y - bounds.height / 2;
+      else if (cfg.top !== undefined) child.y = cfg.top - bounds.y;
+      else if (cfg.bottom !== undefined) child.y = ch - cfg.bottom - bounds.y - bounds.height;
     }
   }