@number10/jsx-phaser 5.0.0

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,SAyB/B"}

package/dist/components/index.js

@@ -0,0 +1,33 @@
+import { register } from "../host.js";
+import { graphicsPatcher, graphicsCreator } from "./primitives/graphics.js";
+import { imagePatcher, imageCreator } from "./primitives/image.js";
+import { nineSlicePatcher, nineSliceCreator } from "./primitives/nineslice.js";
+import { particlesPatcher, particlesCreator } from "./primitives/particles.js";
+import { spritePatcher, spriteCreator } from "./primitives/sprite.js";
+import { textPatcher, textCreator } from "./primitives/text.js";
+import { tileSpritePatcher, tileSpriteCreator } from "./primitives/tilesprite.js";
+import { vectorDrawPatcher, vectorDrawCreator } from "./primitives/vectorDraw.js";
+import { viewPatcher, viewCreator } from "./primitives/view.js";
+function registerBuiltins() {
+  register("view", { create: viewCreator, patch: viewPatcher });
+  register("text", { create: textCreator, patch: textPatcher });
+  register("nineslice", { create: nineSliceCreator, patch: nineSlicePatcher });
+  register("particles", { create: particlesCreator, patch: particlesPatcher });
+  register("sprite", { create: spriteCreator, patch: spritePatcher });
+  register("image", { create: imageCreator, patch: imagePatcher });
+  register("graphics", { create: graphicsCreator, patch: graphicsPatcher });
+  register("vectorDraw", { create: vectorDrawCreator, patch: vectorDrawPatcher });
+  register("tilesprite", { create: tileSpriteCreator, patch: tileSpritePatcher });
+  register("View", { create: viewCreator, patch: viewPatcher });
+  register("Text", { create: textCreator, patch: textPatcher });
+  register("NineSlice", { create: nineSliceCreator, patch: nineSlicePatcher });
+  register("Particles", { create: particlesCreator, patch: particlesPatcher });
+  register("Sprite", { create: spriteCreator, patch: spritePatcher });
+  register("Image", { create: imageCreator, patch: imagePatcher });
+  register("Graphics", { create: graphicsCreator, patch: graphicsPatcher });
+  register("TileSprite", { create: tileSpriteCreator, patch: tileSpritePatcher });
+}
+export {
+  registerBuiltins
+};
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/components/index.ts"],"sourcesContent":["/**\n * Built-in component implementations\n * Exports creators, patchers, props and registration function for all components\n */\nimport { register } from '../host'\nimport { graphicsCreator, graphicsPatcher } from './primitives/graphics'\nimport { imageCreator, imagePatcher } from './primitives/image'\nimport { nineSliceCreator, nineSlicePatcher } from './primitives/nineslice'\nimport { particlesCreator, particlesPatcher } from './primitives/particles'\nimport { spriteCreator, spritePatcher } from './primitives/sprite'\nimport { textCreator, textPatcher } from './primitives/text'\nimport { tileSpriteCreator, tileSpritePatcher } from './primitives/tilesprite'\nimport { vectorDrawCreator, vectorDrawPatcher } from './primitives/vectorDraw'\nimport { viewCreator, viewPatcher } from './primitives/view'\n\n/**\n * Component type constants for JSX usage (legacy primitives)\n * Note: All primitive components now have custom wrappers\n * Use lowercase primitives internally or import wrappers from custom\n */\n\n/**\n * Registers all built-in components with the host\n * This should be called during library initialization\n */\nexport function registerBuiltins() {\n  // Register primitives (lowercase) - internal use\n  register('view' as 'View', { create: viewCreator, patch: viewPatcher })\n  register('text' as 'Text', { create: textCreator, patch: textPatcher })\n  register('nineslice' as 'NineSlice', { create: nineSliceCreator, patch: nineSlicePatcher })\n  register('particles' as 'Particles', { create: particlesCreator, patch: particlesPatcher })\n  register('sprite' as 'Sprite', { create: spriteCreator, patch: spritePatcher })\n  register('image' as 'Image', { create: imageCreator, patch: imagePatcher })\n  register('graphics' as 'Graphics', { create: graphicsCreator, patch: graphicsPatcher })\n  register('vectorDraw', { create: vectorDrawCreator, patch: vectorDrawPatcher })\n  register('tilesprite' as 'TileSprite', { create: tileSpriteCreator, patch: tileSpritePatcher })\n\n  // Register uppercase variants for backward compatibility\n  register('View', { create: viewCreator, patch: viewPatcher })\n  register('Text', { create: textCreator, patch: textPatcher })\n  register('NineSlice', { create: nineSliceCreator, patch: nineSlicePatcher })\n  register('Particles', { create: particlesCreator, patch: particlesPatcher })\n  register('Sprite', { create: spriteCreator, patch: spritePatcher })\n  register('Image', { create: imageCreator, patch: imagePatcher })\n  register('Graphics', { create: graphicsCreator, patch: graphicsPatcher })\n  register('TileSprite', { create: tileSpriteCreator, patch: tileSpritePatcher })\n\n  // Register internal SceneWrapper component (for mountJSX auto-sizing)\n  // SceneWrapper is a function component, not a primitive, so it doesn't need creators\n  // It will be handled by the function component path in mount()\n}\n"],"names":[],"mappings":";;;;;;;;;;AAyBO,SAAS,mBAAmB;AAEjC,WAAS,QAAkB,EAAE,QAAQ,aAAa,OAAO,aAAa;AACtE,WAAS,QAAkB,EAAE,QAAQ,aAAa,OAAO,aAAa;AACtE,WAAS,aAA4B,EAAE,QAAQ,kBAAkB,OAAO,kBAAkB;AAC1F,WAAS,aAA4B,EAAE,QAAQ,kBAAkB,OAAO,kBAAkB;AAC1F,WAAS,UAAsB,EAAE,QAAQ,eAAe,OAAO,eAAe;AAC9E,WAAS,SAAoB,EAAE,QAAQ,cAAc,OAAO,cAAc;AAC1E,WAAS,YAA0B,EAAE,QAAQ,iBAAiB,OAAO,iBAAiB;AACtF,WAAS,cAAc,EAAE,QAAQ,mBAAmB,OAAO,mBAAmB;AAC9E,WAAS,cAA8B,EAAE,QAAQ,mBAAmB,OAAO,mBAAmB;AAG9F,WAAS,QAAQ,EAAE,QAAQ,aAAa,OAAO,aAAa;AAC5D,WAAS,QAAQ,EAAE,QAAQ,aAAa,OAAO,aAAa;AAC5D,WAAS,aAAa,EAAE,QAAQ,kBAAkB,OAAO,kBAAkB;AAC3E,WAAS,aAAa,EAAE,QAAQ,kBAAkB,OAAO,kBAAkB;AAC3E,WAAS,UAAU,EAAE,QAAQ,eAAe,OAAO,eAAe;AAClE,WAAS,SAAS,EAAE,QAAQ,cAAc,OAAO,cAAc;AAC/D,WAAS,YAAY,EAAE,QAAQ,iBAAiB,OAAO,iBAAiB;AACxE,WAAS,cAAc,EAAE,QAAQ,mBAAmB,OAAO,mBAAmB;AAKhF;"}

package/dist/components/internal/SceneWrapper.cjs

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const vdom = require("@number10/jsx-core/vdom");
+function SceneWrapper(props) {
+  const { width, height, children } = props;
+  const child = vdom.normalizeVNodeLike(children);
+  return child ? vdom.createElement("View", { width, height }, child) : vdom.createElement("View", { width, height });
+}
+exports.SceneWrapper = SceneWrapper;
+//# sourceMappingURL=SceneWrapper.cjs.map

package/dist/components/internal/SceneWrapper.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneWrapper.cjs","sources":["../../../src/components/internal/SceneWrapper.tsx"],"sourcesContent":["/**\n * SceneWrapper - Internal component that provides scene dimensions\n * Enables percentage-based sizing for mounted components\n * Used automatically by mountJSX unless disableAutoSize is true\n */\nimport type { VNodeLike } from '@number10/jsx-core'\nimport { createElement, normalizeVNodeLike } from '@number10/jsx-core/vdom'\n\n/**\n * Props for SceneWrapper\n */\nexport interface SceneWrapperProps {\n  /** Scene/container width in pixels */\n  width: number\n  /** Scene/container height in pixels */\n  height: number\n  /** Child component to render */\n  children: VNodeLike\n}\n\n/**\n * Internal wrapper that provides scene dimensions to child components\n * This allows child components to use percentage-based widths/heights\n * @param props - SceneWrapper properties\n * @returns View with absolute dimensions\n */\nexport function SceneWrapper(props: SceneWrapperProps) {\n  const { width, height, children } = props\n  const child = normalizeVNodeLike(children)\n\n  return child\n    ? createElement('View', { width, height }, child)\n    : createElement('View', { width, height })\n}\n"],"names":["normalizeVNodeLike","createElement"],"mappings":";;;AA0BO,SAAS,aAAa,OAA0B;AACrD,QAAM,EAAE,OAAO,QAAQ,SAAA,IAAa;AACpC,QAAM,QAAQA,KAAAA,mBAAmB,QAAQ;AAEzC,SAAO,QACHC,KAAAA,cAAc,QAAQ,EAAE,OAAO,OAAA,GAAU,KAAK,IAC9CA,KAAAA,cAAc,QAAQ,EAAE,OAAO,QAAQ;AAC7C;;"}

package/dist/components/internal/SceneWrapper.d.ts

@@ -0,0 +1,20 @@
+import { VNodeLike } from '@number10/jsx-core';
+/**
+ * Props for SceneWrapper
+ */
+export interface SceneWrapperProps {
+    /** Scene/container width in pixels */
+    width: number;
+    /** Scene/container height in pixels */
+    height: number;
+    /** Child component to render */
+    children: VNodeLike;
+}
+/**
+ * Internal wrapper that provides scene dimensions to child components
+ * This allows child components to use percentage-based widths/heights
+ * @param props - SceneWrapper properties
+ * @returns View with absolute dimensions
+ */
+export declare function SceneWrapper(props: SceneWrapperProps): import('@number10/jsx-core').VNode;
+//# sourceMappingURL=SceneWrapper.d.ts.map

package/dist/components/internal/SceneWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneWrapper.d.ts","sourceRoot":"","sources":["../../../src/components/internal/SceneWrapper.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAGnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,sCAOpD"}

package/dist/components/internal/SceneWrapper.js

@@ -0,0 +1,10 @@
+import { normalizeVNodeLike, createElement } from "@number10/jsx-core/vdom";
+function SceneWrapper(props) {
+  const { width, height, children } = props;
+  const child = normalizeVNodeLike(children);
+  return child ? createElement("View", { width, height }, child) : createElement("View", { width, height });
+}
+export {
+  SceneWrapper
+};
+//# sourceMappingURL=SceneWrapper.js.map

package/dist/components/internal/SceneWrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneWrapper.js","sources":["../../../src/components/internal/SceneWrapper.tsx"],"sourcesContent":["/**\n * SceneWrapper - Internal component that provides scene dimensions\n * Enables percentage-based sizing for mounted components\n * Used automatically by mountJSX unless disableAutoSize is true\n */\nimport type { VNodeLike } from '@number10/jsx-core'\nimport { createElement, normalizeVNodeLike } from '@number10/jsx-core/vdom'\n\n/**\n * Props for SceneWrapper\n */\nexport interface SceneWrapperProps {\n  /** Scene/container width in pixels */\n  width: number\n  /** Scene/container height in pixels */\n  height: number\n  /** Child component to render */\n  children: VNodeLike\n}\n\n/**\n * Internal wrapper that provides scene dimensions to child components\n * This allows child components to use percentage-based widths/heights\n * @param props - SceneWrapper properties\n * @returns View with absolute dimensions\n */\nexport function SceneWrapper(props: SceneWrapperProps) {\n  const { width, height, children } = props\n  const child = normalizeVNodeLike(children)\n\n  return child\n    ? createElement('View', { width, height }, child)\n    : createElement('View', { width, height })\n}\n"],"names":[],"mappings":";AA0BO,SAAS,aAAa,OAA0B;AACrD,QAAM,EAAE,OAAO,QAAQ,SAAA,IAAa;AACpC,QAAM,QAAQ,mBAAmB,QAAQ;AAEzC,SAAO,QACH,cAAc,QAAQ,EAAE,OAAO,OAAA,GAAU,KAAK,IAC9C,cAAc,QAAQ,EAAE,OAAO,QAAQ;AAC7C;"}

package/dist/components/primitives/graphics.cjs

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const applyGraphics = require("../appliers/applyGraphics.cjs");
+const applyGraphicsLayout = require("../appliers/applyGraphicsLayout.cjs");
+const applyPhaser = require("../appliers/applyPhaser.cjs");
+const applyTransform = require("../appliers/applyTransform.cjs");
+const createGraphicsLayout = require("../creators/createGraphicsLayout.cjs");
+const createPhaser = require("../creators/createPhaser.cjs");
+const createTransform = require("../creators/createTransform.cjs");
+const graphicsCreator = (scene, props) => {
+  const graphics = scene.add.graphics();
+  graphics.setPosition(createTransform.resolveAnimatableNumber(props.x) ?? 0, createTransform.resolveAnimatableNumber(props.y) ?? 0);
+  createTransform.createTransform(graphics, props);
+  createPhaser.createPhaser(graphics, props);
+  createGraphicsLayout.createGraphicsLayout(graphics, props);
+  if (props.onDraw) {
+    props.onDraw(graphics, props);
+  }
+  return graphics;
+};
+const graphicsPatcher = (node, prev, next) => {
+  applyTransform.applyTransformProps(node, prev, next);
+  applyPhaser.applyPhaserProps(node, prev, next);
+  applyGraphics.applyGraphicsProps(node, prev, next);
+  applyGraphicsLayout.applyGraphicsLayout(node, prev, next);
+};
+exports.graphicsCreator = graphicsCreator;
+exports.graphicsPatcher = graphicsPatcher;
+//# sourceMappingURL=graphics.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphics.cjs","sources":["../../../src/components/primitives/graphics.ts"],"sourcesContent":["/**\n * Graphics component - Phaser Graphics GameObject (custom shapes)\n * Status: IMPLEMENTED ✅\n *\n * Design Decisions & Answers:\n * ===========================\n *\n * 1. Headless Default: TRUE ✅\n *    Rationale: Graphics are typically decorative (custom shapes, effects).\n *    They should NOT affect layout unless explicitly configured.\n *    Use Cases:\n *    - ✅ Headless (default): Debug visualizations, particle trails, decorative effects\n *    - ❌ Layout-aware: Custom UI shapes (via headless=false + explicit width/height)\n *\n * 2. View Background vs. Graphics Component: CLEAR SEPARATION ✅\n *    View Background (internal):\n *    - Special role: Defines container dimensions\n *    - Automatically managed by View component\n *    - Marked with __isBackground flag\n *    - Always excluded from layout calculations\n *    Graphics Component (user-facing):\n *    - Custom shapes for any purpose\n *    - User controls drawing via onDraw callback\n *    - Can be headless OR layout-aware (explicit)\n *    - Independent GameObject, not tied to View\n *\n * 3. Layout Size Provider: EXPLICIT DIMENSIONS REQUIRED ✅\n *    Decision: Option A - Require explicit width/height props for layout participation\n *    Reasoning:\n *    - Graphics have no inherent dimensions until drawn\n *    - Calculating bounds dynamically is expensive (getBounds() forces geometry calc)\n *    - Bounds change with every draw call (unstable for layout)\n *    - Explicit dimensions = predictable layout behavior\n *    Implementation:\n *    - If headless=false: Require width/height props (throw error if missing)\n *    - __getLayoutSize = () => ({ width: props.width!, height: props.height! })\n *\n * 4. Drawing API: IMPERATIVE CALLBACK ✅\n *    Decision: Option A - onDraw callback (imperative)\n *    Reasoning:\n *    - Simplest API, full Phaser Graphics power\n *    - No abstraction overhead\n *    - Familiar to Phaser developers\n *    - Flexible for complex shapes\n *    Interface:\n *      onDraw?: (graphics: Phaser.GameObjects.Graphics, props: GraphicsBaseProps) => void\n *    Example:\n *      <Graphics onDraw={(g) => {\n *        g.fillStyle(0xff0000, 1)\n *        g.fillCircle(50, 50, 50)\n *      }} />\n *    Future: Consider declarative shape components if demand is high\n *\n * 5. Redraw Strategy: DEPENDENCY-BASED ✅\n *    Decision: Redraw when dependencies array changes (React useEffect style)\n *    Behavior:\n *    - autoClear=true (default): Clear graphics before each onDraw call\n *    - dependencies=[...]: Only redraw when dependencies change (shallow compare)\n *    - No dependencies: Redraw on every patch (expensive!)\n *    Implementation:\n *    - Store previous dependencies on graphics object\n *    - Compare with current dependencies in patcher\n *    - Call onDraw only if changed\n *\n * 6. Performance Optimization: GENERATE-TEXTURE PATH 🆕\n *    Strategy for static graphics:\n *    - Static graphics (no redraw) → Consider generateTexture() optimization\n *    - Converts geometry to texture (faster rendering, loses vector quality)\n *    - Trade-off: Memory (texture) vs. CPU (redraw)\n *    Props:\n *    - static?: boolean (if true, generate texture after first draw)\n *    - textureKey?: string (cache key for generated texture)\n *    Recommendation: Advanced feature, implement later if needed\n *\n * 7. Common Use Cases & Alternatives: DOCUMENTED ✅\n *    Use Graphics For:\n *    - ✅ Custom complex shapes (polygons, stars, bezier curves)\n *    - ✅ Dynamic visualizations (graphs, charts)\n *    - ✅ Progress bars with custom shapes\n *    - ✅ Debug overlays (hit boxes, grids)\n *    Use Alternatives For:\n *    - ❌ Simple rectangles → Use View with backgroundColor\n *    - ❌ Borders → Use View with borderColor/borderWidth\n *    - ❌ Static shapes → Consider Image with pre-rendered texture\n *    - ❌ Repeated patterns → Use TileSprite\n *\n * 8. Clear Behavior: CONFIGURABLE ✅\n *    Decision: autoClear=true by default\n *    Reasoning:\n *    - Most use cases: Single shape per Graphics object\n *    - Prevents accumulation of draw calls\n *    - Override with autoClear=false for additive drawing\n *    Edge Case: Multiple draw calls in onDraw → All executed, then cleared on next redraw\n *\n * Implementation Status:\n * ======================\n * [✅] Create graphics with scene.add.graphics()\n * [✅] Apply transform props via applyTransformProps\n * [✅] Setup onDraw callback invocation\n * [✅] Implement dependency-based redraw logic\n * [✅] Handle autoClear flag\n * [✅] Setup layout size provider (explicit width/height)\n * [✅] Validate width/height if headless=false\n * [✅] Example component with interactive demos\n * [❌] generateTexture optimization (future enhancement)\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 { applyGraphicsProps } from '../appliers/applyGraphics'\nimport { applyGraphicsLayout } from '../appliers/applyGraphicsLayout'\nimport { applyPhaserProps } from '../appliers/applyPhaser'\nimport { applyTransformProps } from '../appliers/applyTransform'\nimport { createGraphicsLayout } from '../creators/createGraphicsLayout'\nimport { createPhaser } from '../creators/createPhaser'\nimport { createTransform, resolveAnimatableNumber } from '../creators/createTransform'\n\n/**\n * Base props for Graphics component\n */\nexport interface GraphicsBaseProps extends TransformProps, PhaserProps, LayoutProps {\n  /**\n   * Drawing callback - receives Graphics instance for custom drawing\n   * Called on mount and when dependencies change\n   * @param graphics - Phaser Graphics instance\n   * @param props - Current props (for accessing dynamic values)\n   */\n  onDraw?: (graphics: Phaser.GameObjects.Graphics, props: GraphicsBaseProps) => void\n\n  /**\n   * If true, graphics is cleared before onDraw is called\n   * Default: true (usually what you want)\n   */\n  autoClear?: boolean\n\n  /**\n   * Dependencies array - if any value changes, onDraw is re-executed\n   * Similar to React useEffect dependencies\n   */\n  dependencies?: unknown[]\n}\n\n/**\n * Props for Graphics component\n */\nexport interface GraphicsProps\n  extends GraphicsBaseProps, PropsDefaultExtension<Phaser.GameObjects.Graphics> {}\n\n/**\n * Graphics creator - creates a Phaser Graphics object\n */\nexport const graphicsCreator: HostCreator<'Graphics'> = (scene, props) => {\n  // Create graphics (position set via setPosition below)\n  const graphics = scene.add.graphics()\n\n  // Set initial position explicitly (Graphics doesn't take x/y in constructor like Text does)\n  graphics.setPosition(resolveAnimatableNumber(props.x) ?? 0, resolveAnimatableNumber(props.y) ?? 0)\n\n  // Apply transform props (scale, rotation)\n  createTransform(graphics, props)\n\n  // Apply Phaser display props (alpha, depth, visible)\n  createPhaser(graphics, props)\n\n  // Setup layout system (props and size provider)\n  createGraphicsLayout(graphics, props)\n\n  // Execute initial draw if onDraw callback provided\n  if (props.onDraw) {\n    props.onDraw(graphics, props)\n  }\n  return graphics\n}\n\n/**\n * Graphics patcher - updates Graphics properties\n */\nexport const graphicsPatcher: HostPatcher<'Graphics'> = (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 Graphics-specific props (onDraw, autoClear, dependencies)\n  applyGraphicsProps(node, prev, next)\n\n  // Apply layout props and update size provider if needed\n  applyGraphicsLayout(node, prev, next)\n}\n"],"names":["resolveAnimatableNumber","createTransform","createPhaser","createGraphicsLayout","applyTransformProps","applyPhaserProps","applyGraphicsProps","applyGraphicsLayout"],"mappings":";;;;;;;;;AAwJO,MAAM,kBAA2C,CAAC,OAAO,UAAU;AAExE,QAAM,WAAW,MAAM,IAAI,SAAA;AAG3B,WAAS,YAAYA,wCAAwB,MAAM,CAAC,KAAK,GAAGA,wCAAwB,MAAM,CAAC,KAAK,CAAC;AAGjGC,kBAAAA,gBAAgB,UAAU,KAAK;AAG/BC,eAAAA,aAAa,UAAU,KAAK;AAG5BC,uBAAAA,qBAAqB,UAAU,KAAK;AAGpC,MAAI,MAAM,QAAQ;AAChB,UAAM,OAAO,UAAU,KAAK;AAAA,EAC9B;AACA,SAAO;AACT;AAKO,MAAM,kBAA2C,CAAC,MAAM,MAAM,SAAS;AAE5EC,qCAAoB,MAAM,MAAM,IAAI;AAGpCC,+BAAiB,MAAM,MAAM,IAAI;AAGjCC,mCAAmB,MAAM,MAAM,IAAI;AAGnCC,0CAAoB,MAAM,MAAM,IAAI;AACtC;;;"}

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

@@ -0,0 +1,146 @@
+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: GENERATE-TEXTURE 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 (hit boxes, 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
+ */
+export interface GraphicsBaseProps extends TransformProps, PhaserProps, LayoutProps {
+    /**
+     * Drawing callback - receives Graphics instance for custom drawing
+     * Called on mount and when dependencies change
+     * @param graphics - Phaser Graphics instance
+     * @param props - Current props (for accessing dynamic values)
+     */
+    onDraw?: (graphics: Phaser.GameObjects.Graphics, props: GraphicsBaseProps) => void;
+    /**
+     * If true, graphics is cleared before onDraw is called
+     * Default: true (usually what you want)
+     */
+    autoClear?: boolean;
+    /**
+     * Dependencies array - if any value changes, onDraw is re-executed
+     * Similar to React useEffect dependencies
+     */
+    dependencies?: unknown[];
+}
+/**
+ * Props for Graphics component
+ */
+export interface GraphicsProps extends GraphicsBaseProps, PropsDefaultExtension<Phaser.GameObjects.Graphics> {
+}
+/**
+ * Graphics creator - creates a Phaser Graphics object
+ */
+export declare const graphicsCreator: HostCreator<'Graphics'>;
+/**
+ * Graphics patcher - updates Graphics properties
+ */
+export declare const graphicsPatcher: HostPatcher<'Graphics'>;
+//# sourceMappingURL=graphics.d.ts.map

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

@@ -0,0 +1 @@
+{"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,EAAE,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC;CAAG;AAElF;;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/graphics.js

@@ -0,0 +1,29 @@
+import { applyGraphicsProps } from "../appliers/applyGraphics.js";
+import { applyGraphicsLayout } from "../appliers/applyGraphicsLayout.js";
+import { applyPhaserProps } from "../appliers/applyPhaser.js";
+import { applyTransformProps } from "../appliers/applyTransform.js";
+import { createGraphicsLayout } from "../creators/createGraphicsLayout.js";
+import { createPhaser } from "../creators/createPhaser.js";
+import { resolveAnimatableNumber, createTransform } from "../creators/createTransform.js";
+const graphicsCreator = (scene, props) => {
+  const graphics = scene.add.graphics();
+  graphics.setPosition(resolveAnimatableNumber(props.x) ?? 0, resolveAnimatableNumber(props.y) ?? 0);
+  createTransform(graphics, props);
+  createPhaser(graphics, props);
+  createGraphicsLayout(graphics, props);
+  if (props.onDraw) {
+    props.onDraw(graphics, props);
+  }
+  return graphics;
+};
+const graphicsPatcher = (node, prev, next) => {
+  applyTransformProps(node, prev, next);
+  applyPhaserProps(node, prev, next);
+  applyGraphicsProps(node, prev, next);
+  applyGraphicsLayout(node, prev, next);
+};
+export {
+  graphicsCreator,
+  graphicsPatcher
+};
+//# sourceMappingURL=graphics.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphics.js","sources":["../../../src/components/primitives/graphics.ts"],"sourcesContent":["/**\n * Graphics component - Phaser Graphics GameObject (custom shapes)\n * Status: IMPLEMENTED ✅\n *\n * Design Decisions & Answers:\n * ===========================\n *\n * 1. Headless Default: TRUE ✅\n *    Rationale: Graphics are typically decorative (custom shapes, effects).\n *    They should NOT affect layout unless explicitly configured.\n *    Use Cases:\n *    - ✅ Headless (default): Debug visualizations, particle trails, decorative effects\n *    - ❌ Layout-aware: Custom UI shapes (via headless=false + explicit width/height)\n *\n * 2. View Background vs. Graphics Component: CLEAR SEPARATION ✅\n *    View Background (internal):\n *    - Special role: Defines container dimensions\n *    - Automatically managed by View component\n *    - Marked with __isBackground flag\n *    - Always excluded from layout calculations\n *    Graphics Component (user-facing):\n *    - Custom shapes for any purpose\n *    - User controls drawing via onDraw callback\n *    - Can be headless OR layout-aware (explicit)\n *    - Independent GameObject, not tied to View\n *\n * 3. Layout Size Provider: EXPLICIT DIMENSIONS REQUIRED ✅\n *    Decision: Option A - Require explicit width/height props for layout participation\n *    Reasoning:\n *    - Graphics have no inherent dimensions until drawn\n *    - Calculating bounds dynamically is expensive (getBounds() forces geometry calc)\n *    - Bounds change with every draw call (unstable for layout)\n *    - Explicit dimensions = predictable layout behavior\n *    Implementation:\n *    - If headless=false: Require width/height props (throw error if missing)\n *    - __getLayoutSize = () => ({ width: props.width!, height: props.height! })\n *\n * 4. Drawing API: IMPERATIVE CALLBACK ✅\n *    Decision: Option A - onDraw callback (imperative)\n *    Reasoning:\n *    - Simplest API, full Phaser Graphics power\n *    - No abstraction overhead\n *    - Familiar to Phaser developers\n *    - Flexible for complex shapes\n *    Interface:\n *      onDraw?: (graphics: Phaser.GameObjects.Graphics, props: GraphicsBaseProps) => void\n *    Example:\n *      <Graphics onDraw={(g) => {\n *        g.fillStyle(0xff0000, 1)\n *        g.fillCircle(50, 50, 50)\n *      }} />\n *    Future: Consider declarative shape components if demand is high\n *\n * 5. Redraw Strategy: DEPENDENCY-BASED ✅\n *    Decision: Redraw when dependencies array changes (React useEffect style)\n *    Behavior:\n *    - autoClear=true (default): Clear graphics before each onDraw call\n *    - dependencies=[...]: Only redraw when dependencies change (shallow compare)\n *    - No dependencies: Redraw on every patch (expensive!)\n *    Implementation:\n *    - Store previous dependencies on graphics object\n *    - Compare with current dependencies in patcher\n *    - Call onDraw only if changed\n *\n * 6. Performance Optimization: GENERATE-TEXTURE PATH 🆕\n *    Strategy for static graphics:\n *    - Static graphics (no redraw) → Consider generateTexture() optimization\n *    - Converts geometry to texture (faster rendering, loses vector quality)\n *    - Trade-off: Memory (texture) vs. CPU (redraw)\n *    Props:\n *    - static?: boolean (if true, generate texture after first draw)\n *    - textureKey?: string (cache key for generated texture)\n *    Recommendation: Advanced feature, implement later if needed\n *\n * 7. Common Use Cases & Alternatives: DOCUMENTED ✅\n *    Use Graphics For:\n *    - ✅ Custom complex shapes (polygons, stars, bezier curves)\n *    - ✅ Dynamic visualizations (graphs, charts)\n *    - ✅ Progress bars with custom shapes\n *    - ✅ Debug overlays (hit boxes, grids)\n *    Use Alternatives For:\n *    - ❌ Simple rectangles → Use View with backgroundColor\n *    - ❌ Borders → Use View with borderColor/borderWidth\n *    - ❌ Static shapes → Consider Image with pre-rendered texture\n *    - ❌ Repeated patterns → Use TileSprite\n *\n * 8. Clear Behavior: CONFIGURABLE ✅\n *    Decision: autoClear=true by default\n *    Reasoning:\n *    - Most use cases: Single shape per Graphics object\n *    - Prevents accumulation of draw calls\n *    - Override with autoClear=false for additive drawing\n *    Edge Case: Multiple draw calls in onDraw → All executed, then cleared on next redraw\n *\n * Implementation Status:\n * ======================\n * [✅] Create graphics with scene.add.graphics()\n * [✅] Apply transform props via applyTransformProps\n * [✅] Setup onDraw callback invocation\n * [✅] Implement dependency-based redraw logic\n * [✅] Handle autoClear flag\n * [✅] Setup layout size provider (explicit width/height)\n * [✅] Validate width/height if headless=false\n * [✅] Example component with interactive demos\n * [❌] generateTexture optimization (future enhancement)\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 { applyGraphicsProps } from '../appliers/applyGraphics'\nimport { applyGraphicsLayout } from '../appliers/applyGraphicsLayout'\nimport { applyPhaserProps } from '../appliers/applyPhaser'\nimport { applyTransformProps } from '../appliers/applyTransform'\nimport { createGraphicsLayout } from '../creators/createGraphicsLayout'\nimport { createPhaser } from '../creators/createPhaser'\nimport { createTransform, resolveAnimatableNumber } from '../creators/createTransform'\n\n/**\n * Base props for Graphics component\n */\nexport interface GraphicsBaseProps extends TransformProps, PhaserProps, LayoutProps {\n  /**\n   * Drawing callback - receives Graphics instance for custom drawing\n   * Called on mount and when dependencies change\n   * @param graphics - Phaser Graphics instance\n   * @param props - Current props (for accessing dynamic values)\n   */\n  onDraw?: (graphics: Phaser.GameObjects.Graphics, props: GraphicsBaseProps) => void\n\n  /**\n   * If true, graphics is cleared before onDraw is called\n   * Default: true (usually what you want)\n   */\n  autoClear?: boolean\n\n  /**\n   * Dependencies array - if any value changes, onDraw is re-executed\n   * Similar to React useEffect dependencies\n   */\n  dependencies?: unknown[]\n}\n\n/**\n * Props for Graphics component\n */\nexport interface GraphicsProps\n  extends GraphicsBaseProps, PropsDefaultExtension<Phaser.GameObjects.Graphics> {}\n\n/**\n * Graphics creator - creates a Phaser Graphics object\n */\nexport const graphicsCreator: HostCreator<'Graphics'> = (scene, props) => {\n  // Create graphics (position set via setPosition below)\n  const graphics = scene.add.graphics()\n\n  // Set initial position explicitly (Graphics doesn't take x/y in constructor like Text does)\n  graphics.setPosition(resolveAnimatableNumber(props.x) ?? 0, resolveAnimatableNumber(props.y) ?? 0)\n\n  // Apply transform props (scale, rotation)\n  createTransform(graphics, props)\n\n  // Apply Phaser display props (alpha, depth, visible)\n  createPhaser(graphics, props)\n\n  // Setup layout system (props and size provider)\n  createGraphicsLayout(graphics, props)\n\n  // Execute initial draw if onDraw callback provided\n  if (props.onDraw) {\n    props.onDraw(graphics, props)\n  }\n  return graphics\n}\n\n/**\n * Graphics patcher - updates Graphics properties\n */\nexport const graphicsPatcher: HostPatcher<'Graphics'> = (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 Graphics-specific props (onDraw, autoClear, dependencies)\n  applyGraphicsProps(node, prev, next)\n\n  // Apply layout props and update size provider if needed\n  applyGraphicsLayout(node, prev, next)\n}\n"],"names":[],"mappings":";;;;;;;AAwJO,MAAM,kBAA2C,CAAC,OAAO,UAAU;AAExE,QAAM,WAAW,MAAM,IAAI,SAAA;AAG3B,WAAS,YAAY,wBAAwB,MAAM,CAAC,KAAK,GAAG,wBAAwB,MAAM,CAAC,KAAK,CAAC;AAGjG,kBAAgB,UAAU,KAAK;AAG/B,eAAa,UAAU,KAAK;AAG5B,uBAAqB,UAAU,KAAK;AAGpC,MAAI,MAAM,QAAQ;AAChB,UAAM,OAAO,UAAU,KAAK;AAAA,EAC9B;AACA,SAAO;AACT;AAKO,MAAM,kBAA2C,CAAC,MAAM,MAAM,SAAS;AAE5E,sBAAoB,MAAM,MAAM,IAAI;AAGpC,mBAAiB,MAAM,MAAM,IAAI;AAGjC,qBAAmB,MAAM,MAAM,IAAI;AAGnC,sBAAoB,MAAM,MAAM,IAAI;AACtC;"}

package/dist/components/primitives/image.cjs

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const imageSubtextureRegistry = require("../../utils/image-subtexture-registry.cjs");
+const applyImage = require("../appliers/applyImage.cjs");
+const applyImageLayout = require("../appliers/applyImageLayout.cjs");
+const applyPhaser = require("../appliers/applyPhaser.cjs");
+const applyTransform = require("../appliers/applyTransform.cjs");
+const createImageLayout = require("../creators/createImageLayout.cjs");
+const createPhaser = require("../creators/createPhaser.cjs");
+const createTransform = require("../creators/createTransform.cjs");
+const imageCreator = (scene, props) => {
+  const resolvedSource = imageSubtextureRegistry.retainImageSubTexture(scene, props.texture, props.frame, props.sourceRect);
+  const image = scene.add.image(
+    createTransform.resolveAnimatableNumber(props.x) ?? 0,
+    createTransform.resolveAnimatableNumber(props.y) ?? 0,
+    resolvedSource.texture,
+    resolvedSource.frame
+  );
+  image.__subTextureCacheKey = resolvedSource.cacheKey;
+  if (resolvedSource.cacheKey) {
+    image.once?.("destroy", () => {
+      imageSubtextureRegistry.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.createTransform(image, normalizedProps);
+  createPhaser.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 } = applyImage.calculateImageFitScale(
+        image,
+        props.displayWidth,
+        props.displayHeight,
+        props.fit,
+        props.sourceRect
+      );
+      image.setScale(scaleX, scaleY);
+    } else if (props.displayWidth !== void 0) {
+      const { width } = applyImage.getImageSourceDimensions(image, props.sourceRect);
+      const scale = width > 0 ? props.displayWidth / width : 1;
+      image.setScale(scale);
+    } else if (props.displayHeight !== void 0) {
+      const { height } = applyImage.getImageSourceDimensions(image, props.sourceRect);
+      const scale = height > 0 ? props.displayHeight / height : 1;
+      image.setScale(scale);
+    }
+  }
+  createImageLayout.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;
+    }
+  }
+  applyTransform.applyTransformProps(node, normalizedPrev, normalizedNext);
+  applyPhaser.applyPhaserProps(node, normalizedPrev, normalizedNext);
+  applyImage.applyImageProps(node, normalizedPrev, normalizedNext);
+  applyImageLayout.applyImageLayout(node, normalizedPrev, normalizedNext);
+};
+exports.imageCreator = imageCreator;
+exports.imagePatcher = imagePatcher;
+//# sourceMappingURL=image.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image.cjs","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":["retainImageSubTexture","resolveAnimatableNumber","releaseImageSubTexture","createTransform","createPhaser","calculateImageFitScale","getImageSourceDimensions","createImageLayout","applyTransformProps","applyPhaserProps","applyImageProps","applyImageLayout"],"mappings":";;;;;;;;;;AA6LO,MAAM,eAAqC,CAAC,OAAO,UAAU;AAClE,QAAM,iBAAiBA,8CAAsB,OAAO,MAAM,SAAS,MAAM,OAAO,MAAM,UAAU;AAChG,QAAM,QAAQ,MAAM,IAAI;AAAA,IACtBC,wCAAwB,MAAM,CAAC,KAAK;AAAA,IACpCA,wCAAwB,MAAM,CAAC,KAAK;AAAA,IACpC,eAAe;AAAA,IACf,eAAe;AAAA,EAAA;AAEjB,QAAM,uBAAuB,eAAe;AAC5C,MAAI,eAAe,UAAU;AAC3B,UAAM,OAAO,WAAW,MAAM;AAC5BC,qDAAuB,OAAO,MAAM,oBAAoB;AACxD,YAAM,uBAAuB;AAAA,IAC/B,CAAC;AAAA,EACH;AAKA,MAAI,MAAM,UAAU;AAClB,UAAM,UAAU,KAAK,GAAG;AAAA,EAC1B,OAAO;AACL,UAAM,UAAU,GAAG,CAAC;AAAA,EACtB;AAGA,MAAI,MAAM,YAAY,UAAa,MAAM,YAAY,QAAW;AAC9D,UAAM,UAAU,MAAM,WAAW,MAAM,SAAS,MAAM,WAAW,MAAM,OAAO;AAAA,EAChF;AAIA,QAAM,kBAAkB,EAAE,GAAG,MAAA;AAC7B,MAAI,MAAM,UAAU;AAElB,WAAO,gBAAgB;AACvB,WAAO,gBAAgB;AACvB,WAAO,gBAAgB;AAAA,EACzB,OAAO;AAEL,QAAI,gBAAgB,aAAa,QAAW;AAC1C,aAAO,gBAAgB;AAAA,IACzB;AAAA,EACF;AAGAC,kBAAAA,gBAAgB,OAAO,eAAe;AAGtCC,eAAAA,aAAa,OAAO,eAAe;AAGnC,MAAI,MAAM,SAAS,QAAW;AAC5B,UAAM,QAAQ,MAAM,IAAI;AAAA,EAC1B;AAIA,MAAI,MAAM,iBAAiB,UAAa,MAAM,kBAAkB,QAAW;AACzE,QAAI,MAAM,iBAAiB,UAAa,MAAM,kBAAkB,QAAW;AACzE,YAAM,EAAE,QAAQ,OAAA,IAAWC,WAAAA;AAAAA,QACzB;AAAA,QACA,MAAM;AAAA,QACN,MAAM;AAAA,QACN,MAAM;AAAA,QACN,MAAM;AAAA,MAAA;AAER,YAAM,SAAS,QAAQ,MAAM;AAAA,IAC/B,WAAW,MAAM,iBAAiB,QAAW;AAC3C,YAAM,EAAE,MAAA,IAAUC,WAAAA,yBAAyB,OAAO,MAAM,UAAU;AAClE,YAAM,QAAQ,QAAQ,IAAI,MAAM,eAAe,QAAQ;AACvD,YAAM,SAAS,KAAK;AAAA,IACtB,WAAW,MAAM,kBAAkB,QAAW;AAC5C,YAAM,EAAE,OAAA,IAAWA,WAAAA,yBAAyB,OAAO,MAAM,UAAU;AACnE,YAAM,QAAQ,SAAS,IAAI,MAAM,gBAAgB,SAAS;AAC1D,YAAM,SAAS,KAAK;AAAA,IACtB;AAAA,EACF;AAGAC,oBAAAA,kBAAkB,OAAO,eAAe;AAGxC,MAAI,MAAM,SAAS;AACjB,UAAM,QAAQ,KAAK;AAAA,EACrB;AAEA,SAAO;AACT;AAKO,MAAM,eAAqC,CAAC,MAAM,MAAM,SAAS;AAEtE,MAAI,KAAK,aAAa,KAAK,UAAU;AACnC,QAAI,KAAK,UAAU;AACjB,WAAK,UAAU,KAAK,GAAG;AAAA,IACzB,OAAO;AACL,WAAK,UAAU,GAAG,CAAC;AAAA,IACrB;AAAA,EACF;AAGA,QAAM,iBAAiB,EAAE,GAAG,KAAA;AAC5B,QAAM,iBAAiB,EAAE,GAAG,KAAA;AAE5B,MAAI,KAAK,UAAU;AAEjB,WAAO,eAAe;AACtB,WAAO,eAAe;AACtB,WAAO,eAAe;AAAA,EACxB,OAAO;AAEL,QAAI,eAAe,aAAa,QAAW;AACzC,aAAO,eAAe;AAAA,IACxB;AAAA,EACF;AAEA,MAAI,KAAK,UAAU;AACjB,WAAO,eAAe;AACtB,WAAO,eAAe;AACtB,WAAO,eAAe;AAAA,EACxB,OAAO;AACL,QAAI,eAAe,aAAa,QAAW;AACzC,aAAO,eAAe;AAAA,IACxB;AAAA,EACF;AAGAC,qCAAoB,MAAM,gBAAgB,cAAc;AAGxDC,+BAAiB,MAAM,gBAAgB,cAAc;AAGrDC,6BAAgB,MAAM,gBAAgB,cAAc;AAGpDC,oCAAiB,MAAM,gBAAgB,cAAc;AACvD;;;"}