@number10/phaserjsx 0.4.0 → 0.4.2

package/dist/components/primitives/graphics.d.ts

@@ -1,7 +1,113 @@
-import { default as Phaser } from 'phaser';
 import { LayoutProps, PhaserProps, TransformProps } from '../../core-props';
 import { HostCreator, HostPatcher } from '../../host';
 import { PropsDefaultExtension } from '../../types';
+/**
+ * Graphics component - Phaser Graphics GameObject (custom shapes)
+ * Status: IMPLEMENTED ✅
+ *
+ * Design Decisions & Answers:
+ * ===========================
+ *
+ * 1. Headless Default: TRUE ✅
+ *    Rationale: Graphics are typically decorative (custom shapes, effects).
+ *    They should NOT affect layout unless explicitly configured.
+ *    Use Cases:
+ *    - ✅ Headless (default): Debug visualizations, particle trails, decorative effects
+ *    - ❌ Layout-aware: Custom UI shapes (via headless=false + explicit width/height)
+ *
+ * 2. View Background vs. Graphics Component: CLEAR SEPARATION ✅
+ *    View Background (internal):
+ *    - Special role: Defines container dimensions
+ *    - Automatically managed by View component
+ *    - Marked with __isBackground flag
+ *    - Always excluded from layout calculations
+ *    Graphics Component (user-facing):
+ *    - Custom shapes for any purpose
+ *    - User controls drawing via onDraw callback
+ *    - Can be headless OR layout-aware (explicit)
+ *    - Independent GameObject, not tied to View
+ *
+ * 3. Layout Size Provider: EXPLICIT DIMENSIONS REQUIRED ✅
+ *    Decision: Option A - Require explicit width/height props for layout participation
+ *    Reasoning:
+ *    - Graphics have no inherent dimensions until drawn
+ *    - Calculating bounds dynamically is expensive (getBounds() forces geometry calc)
+ *    - Bounds change with every draw call (unstable for layout)
+ *    - Explicit dimensions = predictable layout behavior
+ *    Implementation:
+ *    - If headless=false: Require width/height props (throw error if missing)
+ *    - __getLayoutSize = () => ({ width: props.width!, height: props.height! })
+ *
+ * 4. Drawing API: IMPERATIVE CALLBACK ✅
+ *    Decision: Option A - onDraw callback (imperative)
+ *    Reasoning:
+ *    - Simplest API, full Phaser Graphics power
+ *    - No abstraction overhead
+ *    - Familiar to Phaser developers
+ *    - Flexible for complex shapes
+ *    Interface:
+ *      onDraw?: (graphics: Phaser.GameObjects.Graphics, props: GraphicsBaseProps) => void
+ *    Example:
+ *      <Graphics onDraw={(g) => {
+ *        g.fillStyle(0xff0000, 1)
+ *        g.fillCircle(50, 50, 50)
+ *      }} />
+ *    Future: Consider declarative shape components if demand is high
+ *
+ * 5. Redraw Strategy: DEPENDENCY-BASED ✅
+ *    Decision: Redraw when dependencies array changes (React useEffect style)
+ *    Behavior:
+ *    - autoClear=true (default): Clear graphics before each onDraw call
+ *    - dependencies=[...]: Only redraw when dependencies change (shallow compare)
+ *    - No dependencies: Redraw on every patch (expensive!)
+ *    Implementation:
+ *    - Store previous dependencies on graphics object
+ *    - Compare with current dependencies in patcher
+ *    - Call onDraw only if changed
+ *
+ * 6. Performance Optimization: GENERATETEXTURE PATH 🆕
+ *    Strategy for static graphics:
+ *    - Static graphics (no redraw) → Consider generateTexture() optimization
+ *    - Converts geometry to texture (faster rendering, loses vector quality)
+ *    - Trade-off: Memory (texture) vs. CPU (redraw)
+ *    Props:
+ *    - static?: boolean (if true, generate texture after first draw)
+ *    - textureKey?: string (cache key for generated texture)
+ *    Recommendation: Advanced feature, implement later if needed
+ *
+ * 7. Common Use Cases & Alternatives: DOCUMENTED ✅
+ *    Use Graphics For:
+ *    - ✅ Custom complex shapes (polygons, stars, bezier curves)
+ *    - ✅ Dynamic visualizations (graphs, charts)
+ *    - ✅ Progress bars with custom shapes
+ *    - ✅ Debug overlays (hitboxes, grids)
+ *    Use Alternatives For:
+ *    - ❌ Simple rectangles → Use View with backgroundColor
+ *    - ❌ Borders → Use View with borderColor/borderWidth
+ *    - ❌ Static shapes → Consider Image with pre-rendered texture
+ *    - ❌ Repeated patterns → Use TileSprite
+ *
+ * 8. Clear Behavior: CONFIGURABLE ✅
+ *    Decision: autoClear=true by default
+ *    Reasoning:
+ *    - Most use cases: Single shape per Graphics object
+ *    - Prevents accumulation of draw calls
+ *    - Override with autoClear=false for additive drawing
+ *    Edge Case: Multiple draw calls in onDraw → All executed, then cleared on next redraw
+ *
+ * Implementation Status:
+ * ======================
+ * [✅] Create graphics with scene.add.graphics()
+ * [✅] Apply transform props via applyTransformProps
+ * [✅] Setup onDraw callback invocation
+ * [✅] Implement dependency-based redraw logic
+ * [✅] Handle autoClear flag
+ * [✅] Setup layout size provider (explicit width/height)
+ * [✅] Validate width/height if headless=false
+ * [✅] Example component with interactive demos
+ * [❌] generateTexture optimization (future enhancement)
+ */
+import type * as Phaser from 'phaser';
 /**
  * Base props for Graphics component
  */

package/dist/components/primitives/graphics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphics.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/graphics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc,EAAE,WAAW,EAAE,WAAW;IACjF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAElF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aACf,SAAQ,iBAAiB,EACvB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC;CAAG;AAEzD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,UAAU,CAqBnD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,UAAU,CAYnD,CAAA"}
+{"version":3,"file":"graphics.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/graphics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc,EAAE,WAAW,EAAE,WAAW;IACjF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAElF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aACf,SAAQ,iBAAiB,EACvB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC;CAAG;AAEzD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,UAAU,CAqBnD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,UAAU,CAYnD,CAAA"}

package/dist/components/primitives/image.d.ts

@@ -1,7 +1,120 @@
-import { default as Phaser } from 'phaser';
 import { LayoutProps, PhaserProps, TransformProps } from '../../core-props';
 import { HostCreator, HostPatcher } from '../../host';
 import { PropsDefaultExtension } from '../../types';
+/**
+ * Image component - Phaser Image GameObject (static texture)
+ * Status: IMPLEMENTED ✅
+ *
+ * Design Overview:
+ * ================
+ *
+ * 1. Component Role: TEXTURE RENDERING
+ *    Purpose: Display static textures in UI layouts (icons, avatars, illustrations)
+ *    Phaser Type: Phaser.GameObjects.Image (texture-based rendering)
+ *    Characteristics:
+ *    - Layout-aware by default (participates in parent layout)
+ *    - Auto-sizing based on texture dimensions (like HTML <img>)
+ *    - Supports Phaser texture system (atlases, frames)
+ *
+ * 2. Headless Default: FALSE ✅
+ *    Decision: Image participates in layout by default
+ *    Reasoning:
+ *    - Images are UI elements (icons, avatars, illustrations)
+ *    - Should affect parent container dimensions
+ *    - Similar to Text component behavior
+ *    Use Cases:
+ *    - ✅ Layout-aware (default): Icons, avatars, logos, UI illustrations
+ *    - ❌ Headless (optional): Decorative backgrounds, overlays, parallax layers
+ *    Usage:
+ *      <Image texture="icon" />                    // Layout-aware
+ *      <Image texture="bg" headless={true} />      // Decorative (no layout impact)
+ *
+ * 3. Layout Size Provider: DISPLAY DIMENSIONS ✅
+ *    Implementation: Uses image.displayWidth and image.displayHeight
+ *    Behavior:
+ *    - Returns scaled display dimensions
+ *    - Rotation is IGNORED for layout-aware images (headless=false)
+ *    - Rotation only works with headless=true (no layout impact)
+ *    Reasoning:
+ *    - Flow layout is incompatible with rotation (causes positioning issues)
+ *    - Rotated images would overlap siblings in flow layout
+ *    - Matches Text component behavior
+ *    Example:
+ *      <Image texture="icon" />                          // ✅ Layout size: 64x64
+ *      <Image texture="icon" rotation={Math.PI/4} />     // ⚠️ Rotation IGNORED, size: 64x64
+ *      <Image texture="icon" rotation={Math.PI/4} headless={true} /> // ✅ Rotated, no layout
+ *    Recommendation: Use rotation only with headless=true or absolute positioning
+ *
+ * 4. Sizing Strategy: HYBRID APPROACH ✅
+ *    Auto-Size (default):
+ *    - No displayWidth/displayHeight → Use texture dimensions
+ *    - Like HTML <img> natural size
+ *    Explicit Size:
+ *    - displayWidth + displayHeight → Scale to fit
+ *    - fit prop controls aspect ratio handling
+ *    Example:
+ *      <Image texture="icon" />                                  // Auto-size
+ *      <Image texture="icon" displayWidth={64} displayHeight={64} fit="contain" />
+ *
+ * 5. Fit Modes: CSS-LIKE BEHAVIOR ✅
+ *    Decision: Implement CSS object-fit equivalent
+ *    Modes:
+ *    - 'fill' (default): Stretch to fill bounds (may distort aspect ratio)
+ *    - 'contain': Scale to fit within bounds, preserve aspect ratio (letterbox)
+ *    - 'cover': Scale to cover bounds, preserve aspect ratio (crop)
+ *    Implementation: Calculate scale in applier based on fit mode
+ *
+ * 6. Origin Behavior: HEADLESS-AWARE ✅
+ *    Current: Like Text component
+ *    - Layout-aware (headless=false): Origin (0, 0) - top-left, UI-friendly
+ *    - Headless (headless=true): Origin (0.5, 0.5) - centered, game object semantics
+ *    Reasoning:
+ *    - UI elements align naturally with top-left origin
+ *    - Game objects (headless) work better centered
+ *    - Consistent with Text component behavior
+ *
+ * 7. Rotation Behavior: LIKE TEXT ✅
+ *    Decision: Rotation only supported with headless=true
+ *    Reasoning:
+ *    - Flow layout is incompatible with rotation
+ *    - Matches Text component constraints
+ *    - Props normalized: rotation removed if headless=false
+ *
+ * 8. Common Patterns:
+ *    Icon:
+ *      <View direction="row" gap={10}>
+ *        <Image texture="icon-user" />
+ *        <Text text="Username" />
+ *      </View>
+ *    Avatar:
+ *      <Image texture="avatar" displayWidth={64} displayHeight={64} fit="cover" />
+ *    Background (headless):
+ *      <Image texture="bg" headless={true} alpha={0.5} />
+ *
+ * 9. Performance Considerations:
+ *    - Texture atlases recommended (reduce texture switches)
+ *    - Static images are efficient (single draw call)
+ *    - Texture changes trigger re-render
+ *    - Scaling via displayWidth/displayHeight is GPU-accelerated
+ *
+ * 10. Known Limitations:
+ *     - Rotation only supported with headless=true (ignored for layout-aware)
+ *     - Missing textures show Phaser default (white square)
+ *     - No built-in loading states
+ *     - Texture must be preloaded before use
+ *
+ * Implementation Status:
+ * ======================
+ * [✅] Phaser Image creation with texture/frame support
+ * [✅] Transform props (position, scale, alpha)
+ * [✅] Layout system integration (__layoutProps, __getLayoutSize)
+ * [✅] Origin handling (headless-aware: 0,0 vs 0.5,0.5)
+ * [✅] Display size with fit modes (contain/cover/fill)
+ * [✅] Tint support
+ * [✅] Texture and frame patching
+ * [⚠️] Rotation - Only with headless=true (ignored for layout-aware)
+ */
+import type * as Phaser from 'phaser';
 /**
  * Base props for Image component
  */

package/dist/components/primitives/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,cAAc,EAAE,WAAW,EAAE,WAAW;IAC9E,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IAEf,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAEvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAEzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAEjC,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAElC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;IAElC,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,mBACf,SAAQ,cAAc,EACpB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;CAAG;AAEtD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,OAAO,CA4F7C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,OAAO,CA+C7C,CAAA"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,cAAc,EAAE,WAAW,EAAE,WAAW;IAC9E,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IAEf,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAEvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAEzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAEjC,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAElC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;IAElC,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,mBACf,SAAQ,cAAc,EACpB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;CAAG;AAEtD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,OAAO,CA4F7C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,OAAO,CA+C7C,CAAA"}

package/dist/components/primitives/nineslice.d.ts

@@ -1,7 +1,167 @@
-import { default as Phaser } from 'phaser';
 import { LayoutProps, PhaserProps, TransformProps } from '../../core-props';
 import { HostCreator, HostPatcher } from '../../host';
 import { PropsDefaultExtension } from '../../types';
+/**
+ * NineSlice component - Phaser NineSlice GameObject for scalable UI panels
+ * Status: IMPLEMENTED ✅
+ *
+ * Design Overview:
+ * ================
+ *
+ * 1. Component Role: SCALABLE UI PANELS
+ *    Purpose: Create resizable UI elements that preserve border/corner integrity
+ *    Phaser Type: Phaser.GameObjects.NineSlice (9-slice scaling)
+ *    Use Cases:
+ *    - Buttons with fixed corner radius
+ *    - Dialog boxes with preserved borders
+ *    - Progress bars with capped ends
+ *    - Panels that scale without distorting decorative edges
+ *
+ * 2. Nine-Slice Scaling Concept:
+ *    Texture divided into 9 regions:
+ *      ┌─────┬─────────┬─────┐
+ *      │ TL  │   Top   │ TR  │  (corners + edges)
+ *      ├─────┼─────────┼─────┤
+ *      │Left │ Center  │Right│  (center scales, edges stretch)
+ *      ├─────┼─────────┼─────┤
+ *      │ BL  │ Bottom  │ BR  │  (corners stay fixed)
+ *      └─────┴─────────┴─────┘
+ *    Behavior:
+ *    - Corners: Never scale (preserve pixel-perfect)
+ *    - Edges: Stretch along one axis (top/bottom: horizontal, left/right: vertical)
+ *    - Center: Scales in both directions
+ *    Benefit: UI elements scale to any size without visual distortion
+ *
+ * 3. Three-Slice Mode (Optional):
+ *    Feature: Omit topHeight/bottomHeight for horizontal-only slicing
+ *    Use Case: Horizontal buttons, progress bars
+ *    Layout:
+ *      ┌─────┬─────────────────┬─────┐
+ *      │Left │     Center      │Right│
+ *      └─────┴─────────────────┴─────┘
+ *    Props: Only leftWidth + rightWidth required
+ *
+ * 4. Headless Default: FALSE ✅
+ *    Decision: NineSlice participates in layout by default
+ *    Reasoning:
+ *    - NineSlice is a UI element (buttons, panels, containers)
+ *    - Should affect parent container dimensions
+ *    - Similar to View component (container semantics)
+ *    Use Cases:
+ *    - ✅ Layout-aware (default): Buttons, panels, dialogs, cards
+ *    - ❌ Headless (optional): Background overlays, decorative frames
+ *    Usage:
+ *      <NineSlice texture="panel" leftWidth={16} rightWidth={16} width={200} height={100} />
+ *      <NineSlice texture="frame" headless={true} />  // Decorative
+ *
+ * 5. Layout Size Provider:
+ *    Implementation: Uses explicit width/height (required props)
+ *    Reasoning:
+ *    - NineSlice requires explicit dimensions (Phaser constructor param)
+ *    - No auto-sizing (unlike Text)
+ *    - Dimensions always known and stable
+ *    __getLayoutSize:
+ *      return { width: nineSlice.width, height: nineSlice.height }
+ *    Note: getBounds() not needed (no rotation typically applied)
+ *
+ * 6. Slice Configuration:
+ *    Required Props:
+ *    - texture: string (texture key)
+ *    - leftWidth: number (pixels)
+ *    - rightWidth: number (pixels)
+ *    - width: number (total width)
+ *    - height: number (total height)
+ *    Optional Props:
+ *    - topHeight: number (9-slice mode, default: 0 for 3-slice)
+ *    - bottomHeight: number (9-slice mode, default: 0 for 3-slice)
+ *    - frame: string | number (texture atlas frame)
+ *    Validation:
+ *    - Width must be >= leftWidth + rightWidth
+ *    - Height must be >= topHeight + bottomHeight
+ *    - Slice widths/heights define source texture regions
+ *
+ * 7. Inner Bounds Feature:
+ *    Purpose: Calculate content area excluding slices
+ *    Use Case: Position children inside panel borders
+ *    Calculation:
+ *      innerBounds = {
+ *        x: leftWidth,
+ *        y: topHeight,
+ *        width: totalWidth - leftWidth - rightWidth,
+ *        height: totalHeight - topHeight - bottomHeight
+ *      }
+ *    Access:
+ *      const ref = useRef<NineSliceRef>(null)
+ *      <NineSlice ref={ref} ... />
+ *      console.log(ref.current?.innerBounds)  // { x, y, width, height }
+ *    Pattern: Useful for padding-aware content positioning
+ *
+ * 8. Ref Extension:
+ *    Feature: NineSliceRef provides slice metadata
+ *    Properties:
+ *    - node: Phaser.GameObjects.NineSlice (the GameObject)
+ *    - leftWidth, rightWidth, topHeight, bottomHeight: Slice dimensions
+ *    - innerBounds: Content area calculation
+ *    Usage:
+ *      const panelRef = useRef<NineSliceRef>(null)
+ *      // Access slice info for child positioning
+ *      const { innerBounds } = panelRef.current
+ *
+ * 9. Common Patterns:
+ *    Button:
+ *      <NineSlice
+ *        texture="button"
+ *        leftWidth={16} rightWidth={16}
+ *        topHeight={16} bottomHeight={16}
+ *        width={200} height={60}
+ *      >
+ *        <Text text="Click Me" />
+ *      </NineSlice>
+ *    Dialog Box:
+ *      <NineSlice
+ *        texture="panel"
+ *        leftWidth={32} rightWidth={32}
+ *        topHeight={32} bottomHeight={32}
+ *        width={400} height={300}
+ *      >
+ *        <View padding={32}>  {/* Padding matches slice sizes * }
+ *          <Text text="Dialog Content" />
+ *        </View>
+ *      </NineSlice>
+ *    Progress Bar (3-slice):
+ *      <NineSlice
+ *        texture="progressbar"
+ *        leftWidth={8} rightWidth={8}
+ *        width={progress * 200} height={20}
+ *      />
+ *
+ * 10. Performance Considerations:
+ *     - Efficient rendering (single draw call per NineSlice)
+ *     - Texture atlases recommended (reduce texture switches)
+ *     - Scaling performance: No geometry regeneration needed
+ *     - Slice configuration: Calculated once on creation
+ *     - Dynamic resizing: Efficiently handled by Phaser
+ *
+ * 11. Known Limitations:
+ *     - Requires pre-designed 9-slice texture
+ *     - Slice dimensions must match source texture layout exactly
+ *     - Rotation not recommended (distorts slice alignment)
+ *     - Can't animate slice dimensions (only width/height)
+ *     - No rounded corner support (must be in texture)
+ *
+ * Implementation Status:
+ * ======================
+ * [✅] Phaser NineSlice creation with slice configuration
+ * [✅] Transform props (position, scale, alpha, depth)
+ * [✅] Layout system integration (__layoutProps, __getLayoutSize)
+ * [✅] Width/height as layout props (explicit sizing)
+ * [✅] Three-slice mode support (optional topHeight/bottomHeight)
+ * [✅] NineSliceRef with innerBounds calculation
+ * [✅] Slice dimension validation
+ * [✅] Theme system integration
+ * [✅] Dynamic resizing support (width/height patching)
+ */
+import type * as Phaser from 'phaser';
 /**
  * Inner bounds of a NineSlice - the content area excluding slices
  */

package/dist/components/primitives/nineslice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nineslice.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/nineslice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+JG;AACH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,CAAC,EAAE,MAAM,CAAA;IACT;;OAEG;IACH,CAAC,EAAE,MAAM,CAAA;IACT;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,SAAS,GAAG,IAAI,CAAA;IACzC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,WAAW,EAAE,oBAAoB,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAEzB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,kBACf,SAAQ,cAAc,EACpB,WAAW,EACX,WAAW,EACX,sBAAsB;CAAG;AAE7B;;;GAGG;AACH,MAAM,WAAW,uBACf,SAAQ,kBAAkB,EACxB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC;CAAG;AAE1D;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAmCrD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAYrD,CAAA"}
+{"version":3,"file":"nineslice.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/nineslice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+JG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,CAAC,EAAE,MAAM,CAAA;IACT;;OAEG;IACH,CAAC,EAAE,MAAM,CAAA;IACT;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,SAAS,GAAG,IAAI,CAAA;IACzC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,WAAW,EAAE,oBAAoB,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAEzB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,kBACf,SAAQ,cAAc,EACpB,WAAW,EACX,WAAW,EACX,sBAAsB;CAAG;AAE7B;;;GAGG;AACH,MAAM,WAAW,uBACf,SAAQ,kBAAkB,EACxB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC;CAAG;AAE1D;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAmCrD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAYrD,CAAA"}

package/dist/components/primitives/sprite.d.ts

@@ -1,7 +1,96 @@
-import { default as Phaser } from 'phaser';
 import { LayoutProps, PhaserProps, TransformProps } from '../../core-props';
 import { HostCreator, HostPatcher } from '../../host';
 import { PropsDefaultExtension } from '../../types';
+/**
+ * Sprite component - Phaser Sprite GameObject (animated texture)
+ * Status: IMPLEMENTED ✅
+ *
+ * Design Overview:
+ * ================
+ *
+ * 1. Component Role: ANIMATED GAME OBJECTS
+ *    Purpose: Display animated sprites in game scenes (characters, effects, particles)
+ *    Phaser Type: Phaser.GameObjects.Sprite (animation-capable texture rendering)
+ *    Characteristics:
+ *    - Always headless (does not affect parent layout)
+ *    - Supports Phaser Animation system
+ *    - Free positioning with rotation/scale
+ *
+ * 2. Headless Behavior: MANDATORY ✅
+ *    Decision: Sprites are ALWAYS headless (not configurable)
+ *    Reasoning:
+ *    - Sprites are game objects, not UI elements
+ *    - Should NOT affect parent layout dimensions
+ *    - Free positioning with full transform support (rotation, scale)
+ *    Layout Impact: Returns minimal size (0.01x0.01) - participates in alignment only
+ *    Use Cases:
+ *    - ✅ Game characters, particles, effects, free-floating objects
+ *    - ✅ Animated decorations, background elements
+ *    - ❌ NOT for layout-based UIs (use Image component instead)
+ *
+ * 3. Layout Size Provider: MINIMAL SIZE ✅
+ *    Implementation: Always returns { width: 0.01, height: 0.01 }
+ *    Reasoning:
+ *    - Sprites don't affect layout spacing
+ *    - Minimal size allows alignment but no spacing impact
+ *    - Simpler than getBounds() with same result
+ *
+ * 4. Animation System: PHASER ANIMATIONS ✅
+ *    Features:
+ *    - animationKey: Play pre-registered animation
+ *    - loop: Repeat animation indefinitely
+ *    - repeatDelay: Delay between animation repeats (ms)
+ *    Callbacks:
+ *    - onAnimationStart: Triggered when animation begins
+ *    - onAnimationComplete: Triggered when animation ends
+ *    - onAnimationRepeat: Triggered on each repeat
+ *    - onAnimationUpdate: Triggered on each frame update
+ *    Note: Animations must be pre-registered in Phaser AnimationManager
+ *
+ * 5. Texture & Sizing: LIKE IMAGE ✅
+ *    Props:
+ *    - texture: Texture key (required)
+ *    - frame: Frame from atlas/spritesheet
+ *    - tint: Color tint (0xRRGGBB)
+ *    - displayWidth/displayHeight: Scale sprite to fit
+ *    - fit: 'fill' | 'contain' | 'cover' (aspect ratio handling)
+ *    Error Handling: Missing texture → Phaser default (white square)
+ *
+ * 6. Origin Behavior: CENTERED (0.5, 0.5) ✅
+ *    Decision: Default origin (0.5, 0.5) - centered
+ *    Reasoning:
+ *    - Phaser sprite default
+ *    - Natural for rotation/scale pivot
+ *    - Game object semantics
+ *    Override: Use originX/originY props for custom origin
+ *
+ * 7. Performance: SPRITE BATCHING ✅
+ *    Strategy:
+ *    - Leverages Phaser's sprite batching (WebGL)
+ *    - Props that preserve batching: tint, alpha, scale, position
+ *    - Props that break batching: custom shaders, blend modes (use sparingly)
+ *    - Texture atlases strongly recommended for multiple sprites
+ *
+ * 8. Common Patterns:
+ *    Character:
+ *      <Sprite texture="player" animationKey="walk" loop={true} />
+ *    Particle Effect:
+ *      <Sprite texture="explosion" animationKey="explode" onAnimationComplete={destroy} />
+ *    Scaled Sprite:
+ *      <Sprite texture="coin" displayWidth={32} displayHeight={32} fit="contain" />
+ *
+ * Implementation Status:
+ * ======================
+ * [✅] Phaser Sprite creation with texture/frame support
+ * [✅] Transform props (position, rotation, scale, alpha)
+ * [✅] Layout system integration (always headless)
+ * [✅] Origin handling (0.5, 0.5 default)
+ * [✅] Display size with fit modes (contain/cover/fill)
+ * [✅] Tint support
+ * [✅] Animation system (play, loop, callbacks)
+ * [✅] Texture and frame patching
+ */
+import type * as Phaser from 'phaser';
 /**
  * Base props for Sprite component
  */

package/dist/components/primitives/sprite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sprite.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/sprite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc,EAAE,WAAW,EAAE,WAAW;IAC/E,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IAEf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAEvB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;IAElC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,sCAAsC;IACtC,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAExC,wCAAwC;IACxC,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAE3C,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAEzC,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,cAAc,KAAK,IAAI,CAAA;IAElF,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WACf,SAAQ,eAAe,EACrB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;CAAG;AAEvD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,QAAQ,CAiH/C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,QAAQ,CAY/C,CAAA"}
+{"version":3,"file":"sprite.d.ts","sourceRoot":"","sources":["../../../src/components/primitives/sprite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AASxD;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc,EAAE,WAAW,EAAE,WAAW;IAC/E,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IAEf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAEvB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;IAElC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,sCAAsC;IACtC,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAExC,wCAAwC;IACxC,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAE3C,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAEzC,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,cAAc,KAAK,IAAI,CAAA;IAElF,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WACf,SAAQ,eAAe,EACrB,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;CAAG;AAEvD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,QAAQ,CAiH/C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,QAAQ,CAY/C,CAAA"}

package/dist/components/primitives/text.d.ts

@@ -1,7 +1,136 @@
-import { default as Phaser } from 'phaser';
 import { EdgeInsets, LayoutProps, PhaserProps, TextSpecificProps, TransformProps } from '../../core-props';
 import { HostCreator, HostPatcher } from '../../host';
 import { PropsDefaultExtension } from '../../types';
+/**
+ * Text component - Phaser Text GameObject for rendering text
+ * Status: IMPLEMENTED ✅
+ *
+ * Design Overview:
+ * ================
+ *
+ * 1. Component Role: TEXT RENDERING
+ *    Purpose: Display styled text in UI layouts
+ *    Phaser Type: Phaser.GameObjects.Text (bitmap-based text rendering)
+ *    Characteristics:
+ *    - Layout-aware by default (participates in parent layout)
+ *    - Auto-sizing based on text content + font metrics
+ *    - Supports Phaser text styling (color, font, alignment, etc.)
+ *
+ * 2. Headless Default: FALSE ✅
+ *    Decision: Text participates in layout by default
+ *    Reasoning:
+ *    - Text is a UI element (labels, paragraphs, buttons)
+ *    - Should affect parent container dimensions
+ *    - Similar to HTML text nodes
+ *    Use Cases:
+ *    - ✅ Layout-aware (default): Labels, buttons, paragraphs, UI text
+ *    - ❌ Headless (optional): Floating damage numbers, debug text, tooltips
+ *    Usage:
+ *      <Text text="Label" />                    // Layout-aware
+ *      <Text text="+100" headless={true} />    // Floating (no layout impact)
+ *
+ * 3. Layout Size Provider: UN-ROTATED DIMENSIONS ✅
+ *    Implementation: Uses text.width and text.height (un-rotated)
+ *    Behavior:
+ *    - Returns un-rotated text dimensions
+ *    - Rotation is IGNORED for layout-aware text (headless=false)
+ *    - Rotation only works with headless=true (no layout impact)
+ *    Reasoning:
+ *    - Flow layout is incompatible with rotation (causes positioning issues)
+ *    - Rotated text would overlap siblings in flow layout
+ *    - getBounds() position compensation is complex and error-prone
+ *    Example:
+ *      <Text text="Hello" />                        // ✅ Layout size: 100x20
+ *      <Text text="World" rotation={Math.PI/4} />   // ⚠️ Rotation IGNORED, size: 100x20
+ *      <Text text="World" rotation={Math.PI/4} headless={true} /> // ✅ Rotated, no layout
+ *    Recommendation: Use rotation only with headless=true or absolute positioning
+ *
+ * 4. Text Content & Styling:
+ *    Props:
+ *    - text: string (required, the text to display)
+ *    - style: Phaser.Types.GameObjects.Text.TextStyle (font, color, etc.)
+ *    - fontStyle, align, maxWidth: Convenience props (legacy)
+ *    Styling Priority:
+ *    1. Inline style prop (highest)
+ *    2. Individual props (fontStyle, align)
+ *    3. Theme defaults (lowest)
+ *    Example:
+ *      <Text
+ *        text="Hello"
+ *        style={{ fontSize: '24px', color: '#ffffff', fontFamily: 'Arial' }}
+ *      />
+ *
+ * 5. Margin Support:
+ *    Feature: Text supports margin prop (unique among primitives)
+ *    Reasoning:
+ *    - Text often needs spacing from siblings (inline elements)
+ *    - Margin affects layout calculations (added to text dimensions)
+ *    - Similar to CSS inline element margin
+ *    Usage:
+ *      <Text text="Label" margin={{ left: 10, right: 10 }} />
+ *      <Text text="Spaced" margin={8} />  // All sides
+ *
+ * 6. Layout Behavior:
+ *    Sizing:
+ *    - Auto-size: Text dimensions = rendered text bounds (default)
+ *    - No explicit width/height props (text size determined by content)
+ *    - maxWidth prop wraps text (Phaser feature)
+ *    Positioning:
+ *    - Positioned by parent layout engine (flexbox-style)
+ *    - x/y props override layout position (absolute positioning)
+ *
+ * 7. Origin Behavior:
+ *    Current: Phaser default origin (0, 0) - top-left
+ *    Reasoning:
+ *    - Text aligns naturally with layout flow
+ *    - Top-left origin simplifies position calculations
+ *    - Consistent with HTML text rendering
+ *    Note: Origin affects rotation pivot (if rotation applied)
+ *
+ * 8. Common Patterns:
+ *    Label:
+ *      <View direction="row" gap={10}>
+ *        <Text text="Name:" />
+ *        <Text text={userName} />
+ *      </View>
+ *    Styled Text:
+ *      <Text
+ *        text="Title"
+ *        style={{ fontSize: '32px', fontWeight: 'bold', color: '#ff0000' }}
+ *      />
+ *    Wrapped Text:
+ *      <Text text={longParagraph} maxWidth={300} />
+ *    Floating Damage:
+ *      <Text text="-50 HP" headless={true} alpha={0.8} />
+ *
+ * 9. Performance Considerations:
+ *    - Text rendering is relatively expensive (canvas-based)
+ *    - Frequent text changes trigger re-render
+ *    - Long text with maxWidth: word-wrap calculation cost
+ *    - Consider BitmapText for better performance (future component)
+ *    - Text batching: Multiple Text objects don't batch (separate draw calls)
+ *
+ * 10. Known Limitations:
+ *     - Rotation only supported with headless=true (ignored for layout-aware text)
+ *       → Flow layout is incompatible with rotation
+ *     - No rich text support (HTML tags, colors within text)
+ *     - Limited text effects (no shadows, outlines in base component)
+ *     - WordWrap with maxWidth: Can't specify ellipsis truncation
+ *     - Changing text frequently: Performance impact
+ *
+ * Implementation Status:
+ * ======================
+ * [✅] Phaser Text creation with style support
+ * [✅] Transform props (position, scale, alpha)
+ * [✅] Layout system integration (__layoutProps, __getLayoutSize)
+ * [✅] Margin support (unique feature)
+ * [✅] Text content and style patching
+ * [✅] Theme system integration
+ * [⚠️] Rotation - Only with headless=true (ignored for layout-aware text)
+ * [❌] Rich text support - Future feature
+ * [❌] Text effects (shadow, outline) - Future feature
+ */
+import type * as Phaser from 'phaser';
 /**
  * Base props for Text - composing shared prop groups
  * Includes optional margin for layout engine use