@number10/jsx-phaser 5.0.0

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

@@ -0,0 +1,170 @@
+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
+ */
+export interface ImageBaseProps extends TransformProps, PhaserProps, LayoutProps {
+    /** Texture key (loaded via Phaser's texture manager) */
+    texture: string;
+    /** Optional frame from texture atlas */
+    frame?: string | number;
+    /** Tint color applied to image (0xRRGGBB) */
+    tint?: number | undefined;
+    /** Display width (scales image to fit) */
+    displayWidth?: number | undefined;
+    /** Display height (scales image to fit) */
+    displayHeight?: number | undefined;
+    /**
+     * How image should fit within bounds (if displayWidth/displayHeight set)
+     * - 'fill': Stretch to fill (default, may distort aspect ratio)
+     * - 'contain': Scale to fit within bounds, preserve aspect ratio
+     * - 'cover': Scale to cover bounds, preserve aspect ratio (may crop)
+     */
+    fit?: 'fill' | 'contain' | 'cover';
+    /** Origin X (0-1, default 0.5) */
+    originX?: number;
+    /** Origin Y (0-1, default 0.5) */
+    originY?: number;
+    /**
+     * Optional explicit source region within the texture/frame.
+     * When set, the image renders only this sub-rectangle as a derived texture.
+     * Coordinates are relative to the frame origin (if frame is specified)
+     * or the texture origin otherwise.
+     */
+    sourceRect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | undefined;
+}
+/**
+ * Props for primitive image component (internal use only)
+ * For public API, use ImageProps from custom/Image.tsx
+ */
+export interface ImagePrimitiveProps extends ImageBaseProps, PropsDefaultExtension<Phaser.GameObjects.Image> {
+}
+/**
+ * Image creator - creates a Phaser Image object
+ */
+export declare const imageCreator: HostCreator<'Image'>;
+/**
+ * Image patcher - updates Image properties
+ */
+export declare const imagePatcher: HostPatcher<'Image'>;
+//# sourceMappingURL=image.d.ts.map

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

@@ -0,0 +1 @@
+{"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;AAiBxD;;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;IAEhB;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CACxE;AAED;;;GAGG;AACH,MAAM,WAAW,mBACf,SAAQ,cAAc,EAAE,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;CAAG;AAM5E;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,OAAO,CAwF7C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,OAAO,CA+C7C,CAAA"}

package/dist/components/primitives/image.js

@@ -0,0 +1,110 @@
+import { retainImageSubTexture, releaseImageSubTexture } from "../../utils/image-subtexture-registry.js";
+import { applyImageProps, calculateImageFitScale, getImageSourceDimensions } from "../appliers/applyImage.js";
+import { applyImageLayout } from "../appliers/applyImageLayout.js";
+import { applyPhaserProps } from "../appliers/applyPhaser.js";
+import { applyTransformProps } from "../appliers/applyTransform.js";
+import { createImageLayout } from "../creators/createImageLayout.js";
+import { createPhaser } from "../creators/createPhaser.js";
+import { resolveAnimatableNumber, createTransform } from "../creators/createTransform.js";
+const imageCreator = (scene, props) => {
+  const resolvedSource = retainImageSubTexture(scene, props.texture, props.frame, props.sourceRect);
+  const image = scene.add.image(
+    resolveAnimatableNumber(props.x) ?? 0,
+    resolveAnimatableNumber(props.y) ?? 0,
+    resolvedSource.texture,
+    resolvedSource.frame
+  );
+  image.__subTextureCacheKey = resolvedSource.cacheKey;
+  if (resolvedSource.cacheKey) {
+    image.once?.("destroy", () => {
+      releaseImageSubTexture(scene, image.__subTextureCacheKey);
+      image.__subTextureCacheKey = void 0;
+    });
+  }
+  if (props.headless) {
+    image.setOrigin(0.5, 0.5);
+  } else {
+    image.setOrigin(0, 0);
+  }
+  if (props.originX !== void 0 || props.originY !== void 0) {
+    image.setOrigin(props.originX ?? image.originX, props.originY ?? image.originY);
+  }
+  const normalizedProps = { ...props };
+  if (props.headless) {
+    delete normalizedProps.padding;
+    delete normalizedProps.margin;
+    delete normalizedProps.gap;
+  } else {
+    if (normalizedProps.rotation !== void 0) {
+      delete normalizedProps.rotation;
+    }
+  }
+  createTransform(image, normalizedProps);
+  createPhaser(image, normalizedProps);
+  if (props.tint !== void 0) {
+    image.setTint(props.tint);
+  }
+  if (props.displayWidth !== void 0 || props.displayHeight !== void 0) {
+    if (props.displayWidth !== void 0 && props.displayHeight !== void 0) {
+      const { scaleX, scaleY } = calculateImageFitScale(
+        image,
+        props.displayWidth,
+        props.displayHeight,
+        props.fit,
+        props.sourceRect
+      );
+      image.setScale(scaleX, scaleY);
+    } else if (props.displayWidth !== void 0) {
+      const { width } = getImageSourceDimensions(image, props.sourceRect);
+      const scale = width > 0 ? props.displayWidth / width : 1;
+      image.setScale(scale);
+    } else if (props.displayHeight !== void 0) {
+      const { height } = getImageSourceDimensions(image, props.sourceRect);
+      const scale = height > 0 ? props.displayHeight / height : 1;
+      image.setScale(scale);
+    }
+  }
+  createImageLayout(image, normalizedProps);
+  if (props.onReady) {
+    props.onReady(image);
+  }
+  return image;
+};
+const imagePatcher = (node, prev, next) => {
+  if (prev.headless !== next.headless) {
+    if (next.headless) {
+      node.setOrigin(0.5, 0.5);
+    } else {
+      node.setOrigin(0, 0);
+    }
+  }
+  const normalizedPrev = { ...prev };
+  const normalizedNext = { ...next };
+  if (next.headless) {
+    delete normalizedNext.padding;
+    delete normalizedNext.margin;
+    delete normalizedNext.gap;
+  } else {
+    if (normalizedNext.rotation !== void 0) {
+      delete normalizedNext.rotation;
+    }
+  }
+  if (prev.headless) {
+    delete normalizedPrev.padding;
+    delete normalizedPrev.margin;
+    delete normalizedPrev.gap;
+  } else {
+    if (normalizedPrev.rotation !== void 0) {
+      delete normalizedPrev.rotation;
+    }
+  }
+  applyTransformProps(node, normalizedPrev, normalizedNext);
+  applyPhaserProps(node, normalizedPrev, normalizedNext);
+  applyImageProps(node, normalizedPrev, normalizedNext);
+  applyImageLayout(node, normalizedPrev, normalizedNext);
+};
+export {
+  imageCreator,
+  imagePatcher
+};
+//# sourceMappingURL=image.js.map

package/dist/components/primitives/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sources":["../../../src/components/primitives/image.ts"],"sourcesContent":["/**\n * Image component - Phaser Image GameObject (static texture)\n * Status: IMPLEMENTED ✅\n *\n * Design Overview:\n * ================\n *\n * 1. Component Role: TEXTURE RENDERING\n *    Purpose: Display static textures in UI layouts (icons, avatars, illustrations)\n *    Phaser Type: Phaser.GameObjects.Image (texture-based rendering)\n *    Characteristics:\n *    - Layout-aware by default (participates in parent layout)\n *    - Auto-sizing based on texture dimensions (like HTML <img>)\n *    - Supports Phaser texture system (atlases, frames)\n *\n * 2. Headless Default: FALSE ✅\n *    Decision: Image participates in layout by default\n *    Reasoning:\n *    - Images are UI elements (icons, avatars, illustrations)\n *    - Should affect parent container dimensions\n *    - Similar to Text component behavior\n *    Use Cases:\n *    - ✅ Layout-aware (default): Icons, avatars, logos, UI illustrations\n *    - ❌ Headless (optional): Decorative backgrounds, overlays, parallax layers\n *    Usage:\n *      <Image texture=\"icon\" />                    // Layout-aware\n *      <Image texture=\"bg\" headless={true} />      // Decorative (no layout impact)\n *\n * 3. Layout Size Provider: DISPLAY DIMENSIONS ✅\n *    Implementation: Uses image.displayWidth and image.displayHeight\n *    Behavior:\n *    - Returns scaled display dimensions\n *    - Rotation is IGNORED for layout-aware images (headless=false)\n *    - Rotation only works with headless=true (no layout impact)\n *    Reasoning:\n *    - Flow layout is incompatible with rotation (causes positioning issues)\n *    - Rotated images would overlap siblings in flow layout\n *    - Matches Text component behavior\n *    Example:\n *      <Image texture=\"icon\" />                          // ✅ Layout size: 64x64\n *      <Image texture=\"icon\" rotation={Math.PI/4} />     // ⚠️ Rotation IGNORED, size: 64x64\n *      <Image texture=\"icon\" rotation={Math.PI/4} headless={true} /> // ✅ Rotated, no layout\n *    Recommendation: Use rotation only with headless=true or absolute positioning\n *\n * 4. Sizing Strategy: HYBRID APPROACH ✅\n *    Auto-Size (default):\n *    - No displayWidth/displayHeight → Use texture dimensions\n *    - Like HTML <img> natural size\n *    Explicit Size:\n *    - displayWidth + displayHeight → Scale to fit\n *    - fit prop controls aspect ratio handling\n *    Example:\n *      <Image texture=\"icon\" />                                  // Auto-size\n *      <Image texture=\"icon\" displayWidth={64} displayHeight={64} fit=\"contain\" />\n *\n * 5. Fit Modes: CSS-LIKE BEHAVIOR ✅\n *    Decision: Implement CSS object-fit equivalent\n *    Modes:\n *    - 'fill' (default): Stretch to fill bounds (may distort aspect ratio)\n *    - 'contain': Scale to fit within bounds, preserve aspect ratio (letterbox)\n *    - 'cover': Scale to cover bounds, preserve aspect ratio (crop)\n *    Implementation: Calculate scale in applier based on fit mode\n *\n * 6. Origin Behavior: HEADLESS-AWARE ✅\n *    Current: Like Text component\n *    - Layout-aware (headless=false): Origin (0, 0) - top-left, UI-friendly\n *    - Headless (headless=true): Origin (0.5, 0.5) - centered, game object semantics\n *    Reasoning:\n *    - UI elements align naturally with top-left origin\n *    - Game objects (headless) work better centered\n *    - Consistent with Text component behavior\n *\n * 7. Rotation Behavior: LIKE TEXT ✅\n *    Decision: Rotation only supported with headless=true\n *    Reasoning:\n *    - Flow layout is incompatible with rotation\n *    - Matches Text component constraints\n *    - Props normalized: rotation removed if headless=false\n *\n * 8. Common Patterns:\n *    Icon:\n *      <View direction=\"row\" gap={10}>\n *        <Image texture=\"icon-user\" />\n *        <Text text=\"Username\" />\n *      </View>\n *    Avatar:\n *      <Image texture=\"avatar\" displayWidth={64} displayHeight={64} fit=\"cover\" />\n *    Background (headless):\n *      <Image texture=\"bg\" headless={true} alpha={0.5} />\n *\n * 9. Performance Considerations:\n *    - Texture atlases recommended (reduce texture switches)\n *    - Static images are efficient (single draw call)\n *    - Texture changes trigger re-render\n *    - Scaling via displayWidth/displayHeight is GPU-accelerated\n *\n * 10. Known Limitations:\n *     - Rotation only supported with headless=true (ignored for layout-aware)\n *     - Missing textures show Phaser default (white square)\n *     - No built-in loading states\n *     - Texture must be preloaded before use\n *\n * Implementation Status:\n * ======================\n * [✅] Phaser Image creation with texture/frame support\n * [✅] Transform props (position, scale, alpha)\n * [✅] Layout system integration (__layoutProps, __getLayoutSize)\n * [✅] Origin handling (headless-aware: 0,0 vs 0.5,0.5)\n * [✅] Display size with fit modes (contain/cover/fill)\n * [✅] Tint support\n * [✅] Texture and frame patching\n * [⚠️] Rotation - Only with headless=true (ignored for layout-aware)\n */\nimport type * as Phaser from 'phaser'\nimport type { LayoutProps, PhaserProps, TransformProps } from '../../core-props'\nimport type { HostCreator, HostPatcher } from '../../host'\nimport type { PropsDefaultExtension } from '../../types'\nimport {\n  releaseImageSubTexture,\n  retainImageSubTexture,\n} from '../../utils/image-subtexture-registry'\nimport {\n  applyImageProps,\n  calculateImageFitScale,\n  getImageSourceDimensions,\n} from '../appliers/applyImage'\nimport { applyImageLayout } from '../appliers/applyImageLayout'\nimport { applyPhaserProps } from '../appliers/applyPhaser'\nimport { applyTransformProps } from '../appliers/applyTransform'\nimport { createImageLayout } from '../creators/createImageLayout'\nimport { createPhaser } from '../creators/createPhaser'\nimport { createTransform, resolveAnimatableNumber } from '../creators/createTransform'\n\n/**\n * Base props for Image component\n */\nexport interface ImageBaseProps extends TransformProps, PhaserProps, LayoutProps {\n  /** Texture key (loaded via Phaser's texture manager) */\n  texture: string\n\n  /** Optional frame from texture atlas */\n  frame?: string | number\n\n  /** Tint color applied to image (0xRRGGBB) */\n  tint?: number | undefined\n\n  /** Display width (scales image to fit) */\n  displayWidth?: number | undefined\n\n  /** Display height (scales image to fit) */\n  displayHeight?: number | undefined\n\n  /**\n   * How image should fit within bounds (if displayWidth/displayHeight set)\n   * - 'fill': Stretch to fill (default, may distort aspect ratio)\n   * - 'contain': Scale to fit within bounds, preserve aspect ratio\n   * - 'cover': Scale to cover bounds, preserve aspect ratio (may crop)\n   */\n  fit?: 'fill' | 'contain' | 'cover'\n\n  /** Origin X (0-1, default 0.5) */\n  originX?: number\n\n  /** Origin Y (0-1, default 0.5) */\n  originY?: number\n\n  /**\n   * Optional explicit source region within the texture/frame.\n   * When set, the image renders only this sub-rectangle as a derived texture.\n   * Coordinates are relative to the frame origin (if frame is specified)\n   * or the texture origin otherwise.\n   */\n  sourceRect?: { x: number; y: number; w: number; h: number } | undefined\n}\n\n/**\n * Props for primitive image component (internal use only)\n * For public API, use ImageProps from custom/Image.tsx\n */\nexport interface ImagePrimitiveProps\n  extends ImageBaseProps, PropsDefaultExtension<Phaser.GameObjects.Image> {}\n\ntype DerivedTextureImage = Phaser.GameObjects.Image & {\n  __subTextureCacheKey?: string | undefined\n}\n\n/**\n * Image creator - creates a Phaser Image object\n */\nexport const imageCreator: HostCreator<'Image'> = (scene, props) => {\n  const resolvedSource = retainImageSubTexture(scene, props.texture, props.frame, props.sourceRect)\n  const image = scene.add.image(\n    resolveAnimatableNumber(props.x) ?? 0,\n    resolveAnimatableNumber(props.y) ?? 0,\n    resolvedSource.texture,\n    resolvedSource.frame\n  ) as DerivedTextureImage\n  image.__subTextureCacheKey = resolvedSource.cacheKey\n  if (resolvedSource.cacheKey) {\n    image.once?.('destroy', () => {\n      releaseImageSubTexture(scene, image.__subTextureCacheKey)\n      image.__subTextureCacheKey = undefined\n    })\n  }\n\n  // Set origin based on headless flag\n  // Headless: (0.5, 0.5) - centered, works naturally with rotation/scale\n  // Layout-aware: (0, 0) - top-left, aligns with layout flow\n  if (props.headless) {\n    image.setOrigin(0.5, 0.5)\n  } else {\n    image.setOrigin(0, 0)\n  }\n\n  // Apply custom origin if specified\n  if (props.originX !== undefined || props.originY !== undefined) {\n    image.setOrigin(props.originX ?? image.originX, props.originY ?? image.originY)\n  }\n\n  // Normalize props for headless objects\n  // Headless objects are positioned as points - no spacing or rotation constraints\n  const normalizedProps = { ...props } as Record<string, unknown>\n  if (props.headless) {\n    // Remove spacing props (headless = positioned as point)\n    delete normalizedProps.padding\n    delete normalizedProps.margin\n    delete normalizedProps.gap\n  } else {\n    // Remove rotation (only supported with headless=true)\n    if (normalizedProps.rotation !== undefined) {\n      delete normalizedProps.rotation\n    }\n  }\n\n  // Apply transform props (scale, rotation if headless)\n  createTransform(image, normalizedProps)\n\n  // Apply Phaser display props (alpha, depth, visible)\n  createPhaser(image, normalizedProps)\n\n  // Apply image-specific props (tint, displaySize, fit)\n  if (props.tint !== undefined) {\n    image.setTint(props.tint)\n  }\n\n  // Apply displayWidth/displayHeight if specified\n  // (now computed from cropped dimensions)\n  if (props.displayWidth !== undefined || props.displayHeight !== undefined) {\n    if (props.displayWidth !== undefined && props.displayHeight !== undefined) {\n      const { scaleX, scaleY } = calculateImageFitScale(\n        image,\n        props.displayWidth,\n        props.displayHeight,\n        props.fit,\n        props.sourceRect\n      )\n      image.setScale(scaleX, scaleY)\n    } else if (props.displayWidth !== undefined) {\n      const { width } = getImageSourceDimensions(image, props.sourceRect)\n      const scale = width > 0 ? props.displayWidth / width : 1\n      image.setScale(scale)\n    } else if (props.displayHeight !== undefined) {\n      const { height } = getImageSourceDimensions(image, props.sourceRect)\n      const scale = height > 0 ? props.displayHeight / height : 1\n      image.setScale(scale)\n    }\n  }\n\n  // Setup layout system (props and size provider)\n  createImageLayout(image, normalizedProps)\n\n  // Call onReady callback if provided\n  if (props.onReady) {\n    props.onReady(image)\n  }\n\n  return image\n}\n\n/**\n * Image patcher - updates Image properties\n */\nexport const imagePatcher: HostPatcher<'Image'> = (node, prev, next) => {\n  // Update origin if headless flag changed\n  if (prev.headless !== next.headless) {\n    if (next.headless) {\n      node.setOrigin(0.5, 0.5) // Headless: centered\n    } else {\n      node.setOrigin(0, 0) // Layout-aware: top-left\n    }\n  }\n\n  // Normalize props for headless objects\n  const normalizedPrev = { ...prev } as Record<string, unknown>\n  const normalizedNext = { ...next } as Record<string, unknown>\n\n  if (next.headless) {\n    // Remove spacing props (headless = positioned as point)\n    delete normalizedNext.padding\n    delete normalizedNext.margin\n    delete normalizedNext.gap\n  } else {\n    // Remove rotation (only supported with headless=true)\n    if (normalizedNext.rotation !== undefined) {\n      delete normalizedNext.rotation\n    }\n  }\n\n  if (prev.headless) {\n    delete normalizedPrev.padding\n    delete normalizedPrev.margin\n    delete normalizedPrev.gap\n  } else {\n    if (normalizedPrev.rotation !== undefined) {\n      delete normalizedPrev.rotation\n    }\n  }\n\n  // Apply transform props (position, rotation only if headless, scale)\n  applyTransformProps(node, normalizedPrev, normalizedNext)\n\n  // Apply Phaser display props (alpha, depth, visible)\n  applyPhaserProps(node, normalizedPrev, normalizedNext)\n\n  // Apply image-specific props (texture, frame, tint, displaySize, fit)\n  applyImageProps(node, normalizedPrev, normalizedNext)\n\n  // Apply layout props and update size provider if needed\n  applyImageLayout(node, normalizedPrev, normalizedNext)\n}\n"],"names":[],"mappings":"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"}

package/dist/components/primitives/nineslice.cjs

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const applyNineSlice = require("../appliers/applyNineSlice.cjs");
+const applyNineSliceLayout = require("../appliers/applyNineSliceLayout.cjs");
+const applyPhaser = require("../appliers/applyPhaser.cjs");
+const applyTransform = require("../appliers/applyTransform.cjs");
+const createNineSliceLayout = require("../creators/createNineSliceLayout.cjs");
+const createPhaser = require("../creators/createPhaser.cjs");
+const createTransform = require("../creators/createTransform.cjs");
+const nineSliceCreator = (scene, props) => {
+  const initialWidth = typeof props.width === "number" ? props.width : 64;
+  const initialHeight = typeof props.height === "number" ? props.height : 64;
+  const nineSlice = scene.add.nineslice(
+    createTransform.resolveAnimatableNumber(props.x) ?? 0,
+    createTransform.resolveAnimatableNumber(props.y) ?? 0,
+    props.texture,
+    props.frame,
+    initialWidth,
+    initialHeight,
+    props.leftWidth,
+    props.rightWidth,
+    props.topHeight,
+    props.bottomHeight
+  );
+  nineSlice.setOrigin(0, 0);
+  if (props.tint !== void 0) {
+    nineSlice.setTint(props.tint);
+  }
+  createTransform.createTransform(nineSlice, props);
+  createPhaser.createPhaser(nineSlice, props);
+  createNineSliceLayout.createNineSliceLayout(nineSlice, props);
+  return nineSlice;
+};
+const nineSlicePatcher = (node, prev, next) => {
+  applyTransform.applyTransformProps(node, prev, next);
+  applyPhaser.applyPhaserProps(node, prev, next);
+  applyNineSlice.applyNineSliceProps(node, prev, next);
+  applyNineSliceLayout.applyNineSliceLayout(node, prev, next);
+};
+exports.nineSliceCreator = nineSliceCreator;
+exports.nineSlicePatcher = nineSlicePatcher;
+//# sourceMappingURL=nineslice.cjs.map

package/dist/components/primitives/nineslice.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"nineslice.cjs","sources":["../../../src/components/primitives/nineslice.ts"],"sourcesContent":["/**\n * NineSlice component - Phaser NineSlice GameObject for scalable UI panels\n * Status: IMPLEMENTED ✅\n *\n * Design Overview:\n * ================\n *\n * 1. Component Role: SCALABLE UI PANELS\n *    Purpose: Create resizable UI elements that preserve border/corner integrity\n *    Phaser Type: Phaser.GameObjects.NineSlice (9-slice scaling)\n *    Use Cases:\n *    - Buttons with fixed corner radius\n *    - Dialog boxes with preserved borders\n *    - Progress bars with capped ends\n *    - Panels that scale without distorting decorative edges\n *\n * 2. Nine-Slice Scaling Concept:\n *    Texture divided into 9 regions:\n *      ┌─────┬─────────┬─────┐\n *      │ TL  │   Top   │ TR  │  (corners + edges)\n *      ├─────┼─────────┼─────┤\n *      │Left │ Center  │Right│  (center scales, edges stretch)\n *      ├─────┼─────────┼─────┤\n *      │ BL  │ Bottom  │ BR  │  (corners stay fixed)\n *      └─────┴─────────┴─────┘\n *    Behavior:\n *    - Corners: Never scale (preserve pixel-perfect)\n *    - Edges: Stretch along one axis (top/bottom: horizontal, left/right: vertical)\n *    - Center: Scales in both directions\n *    Benefit: UI elements scale to any size without visual distortion\n *\n * 3. Three-Slice Mode (Optional):\n *    Feature: Omit topHeight/bottomHeight for horizontal-only slicing\n *    Use Case: Horizontal buttons, progress bars\n *    Layout:\n *      ┌─────┬─────────────────┬─────┐\n *      │Left │     Center      │Right│\n *      └─────┴─────────────────┴─────┘\n *    Props: Only leftWidth + rightWidth required\n *\n * 4. Headless Default: FALSE ✅\n *    Decision: NineSlice participates in layout by default\n *    Reasoning:\n *    - NineSlice is a UI element (buttons, panels, containers)\n *    - Should affect parent container dimensions\n *    - Similar to View component (container semantics)\n *    Use Cases:\n *    - ✅ Layout-aware (default): Buttons, panels, dialogs, cards\n *    - ❌ Headless (optional): Background overlays, decorative frames\n *    Usage:\n *      <NineSlice texture=\"panel\" leftWidth={16} rightWidth={16} width={200} height={100} />\n *      <NineSlice texture=\"frame\" headless={true} />  // Decorative\n *\n * 5. Layout Size Provider:\n *    Implementation: Uses explicit width/height (required props)\n *    Reasoning:\n *    - NineSlice requires explicit dimensions (Phaser constructor param)\n *    - No auto-sizing (unlike Text)\n *    - Dimensions always known and stable\n *    __getLayoutSize:\n *      return { width: nineSlice.width, height: nineSlice.height }\n *    Note: getBounds() not needed (no rotation typically applied)\n *\n * 6. Slice Configuration:\n *    Required Props:\n *    - texture: string (texture key)\n *    - leftWidth: number (pixels)\n *    - rightWidth: number (pixels)\n *    - width: number (total width)\n *    - height: number (total height)\n *    Optional Props:\n *    - topHeight: number (9-slice mode, default: 0 for 3-slice)\n *    - bottomHeight: number (9-slice mode, default: 0 for 3-slice)\n *    - frame: string | number (texture atlas frame)\n *    Validation:\n *    - Width must be >= leftWidth + rightWidth\n *    - Height must be >= topHeight + bottomHeight\n *    - Slice widths/heights define source texture regions\n *\n * 7. Inner Bounds Feature:\n *    Purpose: Calculate content area excluding slices\n *    Use Case: Position children inside panel borders\n *    Calculation:\n *      innerBounds = {\n *        x: leftWidth,\n *        y: topHeight,\n *        width: totalWidth - leftWidth - rightWidth,\n *        height: totalHeight - topHeight - bottomHeight\n *      }\n *    Access:\n *      const ref = useRef<NineSliceRef>(null)\n *      <NineSlice ref={ref} ... />\n *      console.log(ref.current?.innerBounds)  // { x, y, width, height }\n *    Pattern: Useful for padding-aware content positioning\n *\n * 8. Ref Extension:\n *    Feature: NineSliceRef provides slice metadata\n *    Properties:\n *    - node: Phaser.GameObjects.NineSlice (the GameObject)\n *    - leftWidth, rightWidth, topHeight, bottomHeight: Slice dimensions\n *    - innerBounds: Content area calculation\n *    Usage:\n *      const panelRef = useRef<NineSliceRef>(null)\n *      // Access slice info for child positioning\n *      const { innerBounds } = panelRef.current\n *\n * 9. Common Patterns:\n *    Button:\n *      <NineSlice\n *        texture=\"button\"\n *        leftWidth={16} rightWidth={16}\n *        topHeight={16} bottomHeight={16}\n *        width={200} height={60}\n *      >\n *        <Text text=\"Click Me\" />\n *      </NineSlice>\n *    Dialog Box:\n *      <NineSlice\n *        texture=\"panel\"\n *        leftWidth={32} rightWidth={32}\n *        topHeight={32} bottomHeight={32}\n *        width={400} height={300}\n *      >\n *        <View padding={32}>  {/* Padding matches slice sizes * }\n *          <Text text=\"Dialog Content\" />\n *        </View>\n *      </NineSlice>\n *    Progress Bar (3-slice):\n *      <NineSlice\n *        texture=\"progressbar\"\n *        leftWidth={8} rightWidth={8}\n *        width={progress * 200} height={20}\n *      />\n *\n * 10. Performance Considerations:\n *     - Efficient rendering (single draw call per NineSlice)\n *     - Texture atlases recommended (reduce texture switches)\n *     - Scaling performance: No geometry regeneration needed\n *     - Slice configuration: Calculated once on creation\n *     - Dynamic resizing: Efficiently handled by Phaser\n *\n * 11. Known Limitations:\n *     - Requires pre-designed 9-slice texture\n *     - Slice dimensions must match source texture layout exactly\n *     - Rotation not recommended (distorts slice alignment)\n *     - Can't animate slice dimensions (only width/height)\n *     - No rounded corner support (must be in texture)\n *\n * Implementation Status:\n * ======================\n * [✅] Phaser NineSlice creation with slice configuration\n * [✅] Transform props (position, scale, alpha, depth)\n * [✅] Layout system integration (__layoutProps, __getLayoutSize)\n * [✅] Width/height as layout props (explicit sizing)\n * [✅] Three-slice mode support (optional topHeight/bottomHeight)\n * [✅] NineSliceRef with innerBounds calculation\n * [✅] Slice dimension validation\n * [✅] Theme system integration\n * [✅] Dynamic resizing support (width/height patching)\n */\nimport type * as Phaser from 'phaser'\nimport type { LayoutProps, PhaserProps, TransformProps } from '../../core-props'\nimport type { HostCreator, HostPatcher } from '../../host'\nimport type { PropsDefaultExtension } from '../../types'\nimport { applyNineSliceProps } from '../appliers/applyNineSlice'\nimport { applyNineSliceLayout } from '../appliers/applyNineSliceLayout'\nimport { applyPhaserProps } from '../appliers/applyPhaser'\nimport { applyTransformProps } from '../appliers/applyTransform'\nimport { createNineSliceLayout } from '../creators/createNineSliceLayout'\nimport { createPhaser } from '../creators/createPhaser'\nimport { createTransform, resolveAnimatableNumber } from '../creators/createTransform'\n\n/**\n * Inner bounds of a NineSlice - the content area excluding slices\n */\nexport interface NineSliceInnerBounds {\n  /**\n   * X offset from left edge (equals leftWidth)\n   */\n  x: number\n  /**\n   * Y offset from top edge (equals topHeight)\n   */\n  y: number\n  /**\n   * Width of inner content area (totalWidth - leftWidth - rightWidth)\n   */\n  width: number\n  /**\n   * Height of inner content area (totalHeight - topHeight - bottomHeight)\n   */\n  height: number\n}\n\n/**\n * Extended NineSlice reference with slice information and inner bounds\n */\nexport interface NineSliceRef {\n  /**\n   * The underlying Phaser NineSlice GameObject\n   */\n  node: Phaser.GameObjects.NineSlice | null\n  /**\n   * Width of the left slice in pixels\n   */\n  leftWidth: number\n  /**\n   * Width of the right slice in pixels\n   */\n  rightWidth: number\n  /**\n   * Height of the top slice in pixels (0 for 3-slice mode)\n   */\n  topHeight: number\n  /**\n   * Height of the bottom slice in pixels (0 for 3-slice mode)\n   */\n  bottomHeight: number\n  /**\n   * Inner content bounds excluding slices\n   * Useful for positioning content within the NineSlice\n   */\n  innerBounds: NineSliceInnerBounds\n}\n\n/**\n * NineSlice-specific properties for texture and slice configuration\n */\nexport interface NineSliceSpecificProps {\n  /**\n   * Texture key to use for the NineSlice\n   */\n  texture: string\n\n  /**\n   * Optional tint to apply to the NineSlice\n   */\n  tint?: number | undefined\n\n  /**\n   * Optional frame within the texture atlas\n   */\n  frame?: string | number\n\n  /**\n   * Width of the left slice (in pixels of source texture)\n   */\n  leftWidth: number\n\n  /**\n   * Width of the right slice (in pixels of source texture)\n   */\n  rightWidth: number\n\n  /**\n   * Height of the top slice (in pixels of source texture)\n   * Optional - omit for 3-slice mode (horizontal only)\n   */\n  topHeight?: number\n\n  /**\n   * Height of the bottom slice (in pixels of source texture)\n   * Optional - omit for 3-slice mode (horizontal only)\n   */\n  bottomHeight?: number\n}\n\n/**\n * Base props for NineSlice - composing shared prop groups\n * Note: No InteractionProps - interaction should be handled by parent View container\n */\nexport interface NineSliceBaseProps\n  extends TransformProps, PhaserProps, LayoutProps, NineSliceSpecificProps {}\n\n/**\n * Props for NineSlice primitive - extends base props with JSX-specific props\n * Renamed to avoid conflict with custom NineSlice wrapper\n */\nexport interface NineSlicePrimitiveProps\n  extends NineSliceBaseProps, PropsDefaultExtension<Phaser.GameObjects.NineSlice> {}\n\n/**\n * NineSlice creator - creates a Phaser NineSlice object\n */\nexport const nineSliceCreator: HostCreator<'NineSlice'> = (scene, props) => {\n  // For width/height, use a small default that will be overridden by layout system\n  // This prevents the NineSlice from being created with huge dimensions\n  const initialWidth = typeof props.width === 'number' ? props.width : 64\n  const initialHeight = typeof props.height === 'number' ? props.height : 64\n\n  const nineSlice = scene.add.nineslice(\n    resolveAnimatableNumber(props.x) ?? 0,\n    resolveAnimatableNumber(props.y) ?? 0,\n    props.texture,\n    props.frame,\n    initialWidth,\n    initialHeight,\n    props.leftWidth,\n    props.rightWidth,\n    props.topHeight,\n    props.bottomHeight\n  )\n  nineSlice.setOrigin(0, 0) // Top-left origin for easier layout handling as it is in UI\n\n  // Apply tint if provided\n  if (props.tint !== undefined) {\n    nineSlice.setTint(props.tint)\n  }\n\n  // Apply transform props (scale, rotation)\n  createTransform(nineSlice, props)\n\n  // Apply Phaser display props (alpha, depth, visible)\n  createPhaser(nineSlice, props)\n\n  // Setup layout system (props and size provider)\n  createNineSliceLayout(nineSlice, props)\n\n  return nineSlice\n}\n\n/**\n * NineSlice patcher - updates NineSlice properties\n */\nexport const nineSlicePatcher: HostPatcher<'NineSlice'> = (node, prev, next) => {\n  // Apply transform props (position, rotation, scale)\n  applyTransformProps(node, prev, next)\n\n  // Apply Phaser display props (alpha, depth, visible)\n  applyPhaserProps(node, prev, next)\n\n  // Apply NineSlice-specific props (texture, frame, slice dimensions)\n  applyNineSliceProps(node, prev, next)\n\n  // Apply layout props and update size provider if needed\n  applyNineSliceLayout(node, prev, next)\n}\n"],"names":["resolveAnimatableNumber","createTransform","createPhaser","createNineSliceLayout","applyTransformProps","applyPhaserProps","applyNineSliceProps","applyNineSliceLayout"],"mappings":";;;;;;;;;AA4RO,MAAM,mBAA6C,CAAC,OAAO,UAAU;AAG1E,QAAM,eAAe,OAAO,MAAM,UAAU,WAAW,MAAM,QAAQ;AACrE,QAAM,gBAAgB,OAAO,MAAM,WAAW,WAAW,MAAM,SAAS;AAExE,QAAM,YAAY,MAAM,IAAI;AAAA,IAC1BA,wCAAwB,MAAM,CAAC,KAAK;AAAA,IACpCA,wCAAwB,MAAM,CAAC,KAAK;AAAA,IACpC,MAAM;AAAA,IACN,MAAM;AAAA,IACN;AAAA,IACA;AAAA,IACA,MAAM;AAAA,IACN,MAAM;AAAA,IACN,MAAM;AAAA,IACN,MAAM;AAAA,EAAA;AAER,YAAU,UAAU,GAAG,CAAC;AAGxB,MAAI,MAAM,SAAS,QAAW;AAC5B,cAAU,QAAQ,MAAM,IAAI;AAAA,EAC9B;AAGAC,kBAAAA,gBAAgB,WAAW,KAAK;AAGhCC,eAAAA,aAAa,WAAW,KAAK;AAG7BC,wBAAAA,sBAAsB,WAAW,KAAK;AAEtC,SAAO;AACT;AAKO,MAAM,mBAA6C,CAAC,MAAM,MAAM,SAAS;AAE9EC,qCAAoB,MAAM,MAAM,IAAI;AAGpCC,+BAAiB,MAAM,MAAM,IAAI;AAGjCC,qCAAoB,MAAM,MAAM,IAAI;AAGpCC,4CAAqB,MAAM,MAAM,IAAI;AACvC;;;"}

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

@@ -0,0 +1,271 @@
+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
+ */
+export interface NineSliceInnerBounds {
+    /**
+     * X offset from left edge (equals leftWidth)
+     */
+    x: number;
+    /**
+     * Y offset from top edge (equals topHeight)
+     */
+    y: number;
+    /**
+     * Width of inner content area (totalWidth - leftWidth - rightWidth)
+     */
+    width: number;
+    /**
+     * Height of inner content area (totalHeight - topHeight - bottomHeight)
+     */
+    height: number;
+}
+/**
+ * Extended NineSlice reference with slice information and inner bounds
+ */
+export interface NineSliceRef {
+    /**
+     * The underlying Phaser NineSlice GameObject
+     */
+    node: Phaser.GameObjects.NineSlice | null;
+    /**
+     * Width of the left slice in pixels
+     */
+    leftWidth: number;
+    /**
+     * Width of the right slice in pixels
+     */
+    rightWidth: number;
+    /**
+     * Height of the top slice in pixels (0 for 3-slice mode)
+     */
+    topHeight: number;
+    /**
+     * Height of the bottom slice in pixels (0 for 3-slice mode)
+     */
+    bottomHeight: number;
+    /**
+     * Inner content bounds excluding slices
+     * Useful for positioning content within the NineSlice
+     */
+    innerBounds: NineSliceInnerBounds;
+}
+/**
+ * NineSlice-specific properties for texture and slice configuration
+ */
+export interface NineSliceSpecificProps {
+    /**
+     * Texture key to use for the NineSlice
+     */
+    texture: string;
+    /**
+     * Optional tint to apply to the NineSlice
+     */
+    tint?: number | undefined;
+    /**
+     * Optional frame within the texture atlas
+     */
+    frame?: string | number;
+    /**
+     * Width of the left slice (in pixels of source texture)
+     */
+    leftWidth: number;
+    /**
+     * Width of the right slice (in pixels of source texture)
+     */
+    rightWidth: number;
+    /**
+     * Height of the top slice (in pixels of source texture)
+     * Optional - omit for 3-slice mode (horizontal only)
+     */
+    topHeight?: number;
+    /**
+     * Height of the bottom slice (in pixels of source texture)
+     * Optional - omit for 3-slice mode (horizontal only)
+     */
+    bottomHeight?: number;
+}
+/**
+ * Base props for NineSlice - composing shared prop groups
+ * Note: No InteractionProps - interaction should be handled by parent View container
+ */
+export interface NineSliceBaseProps extends TransformProps, PhaserProps, LayoutProps, NineSliceSpecificProps {
+}
+/**
+ * Props for NineSlice primitive - extends base props with JSX-specific props
+ * Renamed to avoid conflict with custom NineSlice wrapper
+ */
+export interface NineSlicePrimitiveProps extends NineSliceBaseProps, PropsDefaultExtension<Phaser.GameObjects.NineSlice> {
+}
+/**
+ * NineSlice creator - creates a Phaser NineSlice object
+ */
+export declare const nineSliceCreator: HostCreator<'NineSlice'>;
+/**
+ * NineSlice patcher - updates NineSlice properties
+ */
+export declare const nineSlicePatcher: HostPatcher<'NineSlice'>;
+//# sourceMappingURL=nineslice.d.ts.map

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

@@ -0,0 +1 @@
+{"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,EAAE,WAAW,EAAE,WAAW,EAAE,sBAAsB;CAAG;AAE7E;;;GAGG;AACH,MAAM,WAAW,uBACf,SAAQ,kBAAkB,EAAE,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC;CAAG;AAEpF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAmCrD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAYrD,CAAA"}