@kayelaa/canvas 0.2.6 → 0.2.7

package/dist/{kayla-internals-DR1hPIET.d.ts → kayla-internals-Ajxdtt0s.d.ts}

@@ -584,10 +584,12 @@ declare namespace KaylaInternals {
             instance: KaylaContext<any>;
             value: unknown;
         };
+        lastLayer?: KaylaLayerInfo;
         get childrenCount(): number;
         maxSafeChildren: number;
         dynamicChildren: KaylaElement<any>[];
         constructor(globalKayla: GlobalKayla, scene: KaylaScene, element: KaylaElement<Props>);
+        getCorrectMousePos(pos?: Vector2): Vector2;
         getChildrenEntities(): KaylaRectEntity[];
         pointerHook(pos: Vector2, type: KaylaClickType, action: KaylaPointerAction): void;
         resizeHook({ width, height }: {
@@ -634,6 +636,7 @@ declare namespace KaylaInternals {
         setMaxChildren(max: number): void;
         getMaxChildren(): number;
         getFiberChain(): UnsafeKaylaFiber[];
+        getAllChildrenNestedFlattened(): UnsafeKaylaFiber[];
         getContextChain(): KaylaFiber<any, any>["contextInfo"][];
         findContextValueFromInst(inst: KaylaContext<any>): unknown;
         getEntityChain(): KaylaRectEntity[];
@@ -845,6 +848,7 @@ declare namespace KaylaInternals {
     class KaylaScene {
         #private;
         constructor(scene: LeaSceneII);
+        getLayers(): Map<string, KaylaLayerInfo>;
         /**
          * Exposes all the dangerous fibers.
          */
@@ -861,6 +865,15 @@ declare namespace KaylaInternals {
          * Exposes the game object.
          */
         getGame(): KaylaGame;
+        getOrCreateLayer(name: string, defaultZ?: number): KaylaLayerInfo;
+        getSortedLayers(): KaylaLayerInfo[];
+        setLayerVisible(name: string, visible: boolean): void;
+        /**
+         * Draws all entities in z-order (higher z = drawn later).
+         *
+         * @param ctx - The 2D rendering context
+         */
+        protected handleDraw(ctx: CanvasRenderingContext2D): void;
         private drawHandler;
         /**
          * Attaches this scene to a game instance.
@@ -880,6 +893,7 @@ declare namespace KaylaInternals {
          * @param elem - Root Kayla element (usually JSX)
          */
         spawn(elem: KaylaElement<any>): Promise<void>;
+        getRoot(): UnsafeKaylaFiber;
         private createFiber;
         /**
          * Detaches this scene from its game (if attached).
@@ -1094,17 +1108,29 @@ declare const useGlobalClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPoi
  * Useful for global input (pause menu toggle, debug shortcuts, drag anywhere…).
  * Multiple `useGlobalPointer` calls **stack** and run in declaration order.
  *
- * @param callback Global pointer handler — receives world position and click type
+ * **Important – coordinate system depends on context:**
+ * - If this component is inside a `<Layer transform={…}>`, you receive **layer-local coordinates**
+ * - Otherwise you receive **world coordinates** (same as entity positions)
+ *
+ * Multiple handlers stack — they are called in declaration order.
+ *
+ * @param handler Called with:
+ *   - `pos`        pointer position (world or layer-local — see above)
+ *   - `type`       "left" | "right" | "middle"
+ *   - `action`     "down" | "up" | "move" | "cancel"
+ * @param config Optional filter to reduce calls
  *
  * @example
- * useGlobalPointer((pos) => {
- *   isPaused.set(!isPaused.get());
+ * // Global pause on right-click (anywhere)
+ * useGlobalPointer((pos, type) => {
+ *   if (type === "right") isPaused.value = !isPaused.value;
  * }, { type: "right", action: "down" });
- * useGlobalPointer((pos) => {
- *   // set player pos as mouse pos
- *   player.x = pos.x;
- *   player.y = pos.y;
- * }, { action: "move" });
+ *
+ * @example
+ * // Inside a zoomable map layer — pos is already in map-local space
+ * useGlobalPointer((localPos) => {
+ *   console.log("Clicked map at:", localPos);
+ * });
  */
 declare const useGlobalPointer: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
 /**
@@ -1138,17 +1164,35 @@ declare const useClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"]
  * **This hook MUST be called at the top level of a component function — never inside loops, conditions, nested functions, or callbacks.**
  * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
+ * **Coordinate system note (very important since layers):**
+ * - If this component lives inside a `<Layer>` with a `transform` prop (camera, zoom, scroll, rotation…),
+ *   then `pos` is already transformed into the **layer-local coordinate system**.
+ * - The automatic hit-test rectangle check is also performed in **layer-local space**.
+ * - If there is **no transform** on the containing layer → `pos` is in world coordinates.
+ *
  * Uses the rectangle bounds from {@link useRect} / underlying entity.
  * Multiple `usePointer` calls **stack** and run in declaration order.
  *
- * @param callback pointer handler — receives world position and click type ("left" | "right" | "middle")
+ * @param handler Receives:
+ *   - `pos`        pointer position in the coordinate system this entity lives in
+ *   - `type`       button ("left"|"right"|"middle")
+ *   - `action`     "down"|"up"|"move"|"cancel"
+ * @param config Optional filters (button + action)
+ *
+ * @example
+ * // Classic button (no layer transform)
+ * usePointer((worldPos, type, action) => {
+ *   if (action === "down" && type === "left") {
+ *     onClick();
+ *   }
+ * }, { type: "left", action: "down" });
  *
  * @example
- * usePointer((pos) => {
- *   score.add(1);
- *   playSound("collect");
- *   // optional: spawn particle children on click
- * }, { type: "left", action: "up" });
+ * // Inside a zoomed/scrollable UI panel or map
+ * usePointer((localPos) => {
+ *   // localPos is already correct for items inside this zoomed layer
+ *   inventory.selectSlotAt(localPos);
+ * });
  *
  * @see {@link useGlobalPointer} — for pointer events anywhere (not bound to this entity)
  */
@@ -1705,12 +1749,116 @@ declare namespace JSX {
     }
     type ElementType = FC<any>;
 }
+/**
+ * Configuration object for a single named rendering layer.
+ * Created/managed via `<Layer>` components.
+ */
+interface KaylaLayerInfo {
+    /** Unique name of the layer (used as key in scene.#layers Map) */
+    name: string;
+    /** Z-index / sort order of the layer itself (higher = drawn later) */
+    z: number;
+    /** Blend mode applied to the entire layer during rendering */
+    blendMode?: GlobalCompositeOperation;
+    /** Whether this layer should be rendered at all */
+    visible: boolean;
+    /**
+     * Root fiber whose subtree belongs to this layer.
+     * Usually set to the fiber of the `<Layer name="..." />` component that first claimed this name.
+     */
+    rootFiber: UnsafeKaylaFiber | null;
+    /**
+     * 2D transformation matrix applied to rendering **and** pointer coordinate transformation.
+     * When present, pointer events inside this layer are delivered in local coordinates.
+     */
+    transform?: KMatrix2D | null;
+}
+/** Props accepted by the `<Layer>` component */
+interface KaylaLayerProps extends FCProps {
+    /** Required. Unique name identifying this layer */
+    name: string;
+    /** Layer draw order (higher = later / on top) */
+    z?: number;
+    /** Canvas blend mode for the whole layer */
+    blend?: GlobalCompositeOperation;
+    /** Toggle rendering of the entire layer */
+    visible?: boolean;
+    /** Children rendered inside this layer's context */
+    children?: KaylaElement<any>[];
+    /**
+     * Transformation applied to rendering and input coordinates.
+     * Use `KMatrix2D` to build cameras, zoom views, parallax layers, rotated UI panels, etc.
+     */
+    transform?: KMatrix2D;
+}
+/**
+ * Defines a named rendering layer with optional transform, blend mode, visibility, and draw order.
+ *
+ * `<Layer>` is a special component that groups its children into a separate rendering pass.
+ * It allows you to:
+ * - Control draw order between major groups of entities (via `z`)
+ * - Apply coordinate transforms (camera, zoom, scroll, rotation) to an entire subtree
+ * - Change blending behavior for the whole layer
+ * - Toggle visibility of large parts of the scene without unmounting components
+ *
+ * **Coordinate system behavior:**
+ * - If `transform` is provided, **all pointer coordinates** delivered to `usePointer` / `useGlobalPointer`
+ *   inside this layer (and its descendants) are automatically transformed into the **layer-local coordinate system**.
+ * - The automatic hit-test for `usePointer` also happens in layer-local space.
+ * - Without `transform` (identity/default), coordinates remain in **world space**.
+ *
+ * **Important notes:**
+ * - Layers are **not** nested in the traditional sense — each `<Layer>` creates an independent rendering group.
+ * - Multiple `<Layer>` components with the **same `name`** will **share the same layer configuration** (last one wins for most properties).
+ * - The `rootFiber` of the layer is set to the fiber of the **first** `<Layer name="..."` component encountered with that name.
+ * - Children inside `<Layer>` still participate in normal component lifecycle, ticking, painting, pointer handling, etc.
+ *
+ * @example
+ * // Simple UI overlay that draws on top
+ * <Layer name="ui" z={1000} visible={true}>
+ *   <HUD />
+ *   <PauseMenu />
+ * </Layer>
+ *
+ * @example
+ * // Zoomable / scrollable map area
+ * function MapView() {
+ *   const zoom = useSelf(() => ({ scale: 1.8, offset: new LEA.Vector2(120, 80) }));
+ *
+ *   const matrix = new KMatrix2D();
+ *   matrix.translateSelf(zoom.offset.x, zoom.offset.y);
+ *   matrix.scaleSelf(zoom.scale, zoom.scale);
+ *
+ *   return (
+ *     <Layer
+ *       name="world-map"
+ *       z={10}
+ *       transform={matrix}
+ *       blend="source-over"
+ *     >
+ *       <BackgroundTiles />
+ *       <Player />
+ *       <Enemies />
+ *       {// Pointer events inside here receive map-local coordinates }
+ *     </Layer>
+ *   );
+ * }
+ * */
+declare const Layer: FC<KaylaLayerProps>;
+declare class KMatrix2D extends DOMMatrix {
+    #private;
+    constructor();
+    transformV(v: Vector2): Vector2;
+    inverseV(v: Vector2): Vector2;
+}
 
 type Kayla_ExportsOfFC<T extends FC<any, any>> = ExportsOfFC<T>;
 type Kayla_FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExports> = FC<Props, Exports>;
 type Kayla_FCExports = FCExports;
 type Kayla_FCProps = FCProps;
 declare const Kayla_JSX: typeof JSX;
+type Kayla_KMatrix2D = KMatrix2D;
+declare const Kayla_KMatrix2D: typeof KMatrix2D;
 type Kayla_KaylaClickConfig = KaylaClickConfig;
 type Kayla_KaylaClickType = KaylaClickType;
 type Kayla_KaylaContext<Context> = KaylaContext<Context>;
@@ -1724,12 +1872,15 @@ type Kayla_KaylaFiberControl = KaylaFiberControl;
 declare const Kayla_KaylaFragment: typeof KaylaFragment;
 type Kayla_KaylaGame = KaylaGame;
 declare const Kayla_KaylaInternals: typeof KaylaInternals;
+type Kayla_KaylaLayerInfo = KaylaLayerInfo;
+type Kayla_KaylaLayerProps = KaylaLayerProps;
 type Kayla_KaylaPointerAction = KaylaPointerAction;
 declare const Kayla_KaylaRect: typeof KaylaRect;
 type Kayla_KaylaRef<T> = KaylaRef<T>;
 type Kayla_KaylaRenderer = KaylaRenderer;
 type Kayla_KaylaScene = KaylaScene;
 type Kayla_KaylaState<T> = KaylaState<T>;
+declare const Kayla_Layer: typeof Layer;
 type Kayla_PropOfFC<T extends FC<any, any>> = PropOfFC<T>;
 type Kayla_Reassignable<T extends Record<any, any>> = Reassignable<T>;
 type Kayla_UnsafeKaylaFiber = UnsafeKaylaFiber;
@@ -1767,7 +1918,7 @@ declare const Kayla_useState: typeof useState;
 declare const Kayla_useTick: typeof useTick;
 declare const Kayla_useViewportEffect: typeof useViewportEffect;
 declare namespace Kayla {
-  export { type Kayla_ExportsOfFC as ExportsOfFC, type Kayla_FC as FC, type Kayla_FCExports as FCExports, type Kayla_FCProps as FCProps, Kayla_JSX as JSX, type Kayla_KaylaClickConfig as KaylaClickConfig, type Kayla_KaylaClickType as KaylaClickType, Kayla_KaylaContext as KaylaContext, type Kayla_KaylaCustomHookConfig as KaylaCustomHookConfig, type Kayla_KaylaElement as KaylaElement, type Kayla_KaylaElementRef as KaylaElementRef, type Kayla_KaylaExportables as KaylaExportables, type Kayla_KaylaExports as KaylaExports, type Kayla_KaylaFiberControl as KaylaFiberControl, Kayla_KaylaFragment as KaylaFragment, type Kayla_KaylaGame as KaylaGame, Kayla_KaylaInternals as KaylaInternals, type Kayla_KaylaPointerAction as KaylaPointerAction, Kayla_KaylaRect as KaylaRect, type Kayla_KaylaRef as KaylaRef, type Kayla_KaylaRenderer as KaylaRenderer, type Kayla_KaylaScene as KaylaScene, type Kayla_KaylaState as KaylaState, type Kayla_PropOfFC as PropOfFC, type Kayla_Reassignable as Reassignable, type Kayla_UnsafeKaylaFiber as UnsafeKaylaFiber, Kayla_createContext as createContext, Kayla_createElement as createElement, Kayla_createGame as createGame, Kayla_createReassignableObject as createReassignableObject, Kayla_createRenderer as createRenderer, Kayla_createScene as createScene, Kayla_createUseHook as createUseHook, selfSym as self, Kayla_setLogLevel as setLogLevel, Kayla_useClick as useClick, Kayla_useContext as useContext, Kayla_useCurrentGame as useCurrentGame, Kayla_useCurrentRenderer as useCurrentRenderer, Kayla_useCurrentScene as useCurrentScene, Kayla_useCurrentTicker as useCurrentTicker, Kayla_useDisposableRef as useDisposableRef, Kayla_useEffect as useEffect, Kayla_useEntity as useEntity, Kayla_useExports as useExports, Kayla_useFiber as useFiber, Kayla_useFiberControl as useFiberControl, Kayla_useGlobalClick as useGlobalClick, Kayla_useGlobalPointer as useGlobalPointer, Kayla_useInitialization as useInitialization, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, Kayla_usePointer as usePointer, Kayla_useRect as useRect, Kayla_useRef as useRef, Kayla_useSelf as useSelf, Kayla_useShouldRefresh as useShouldRefresh, Kayla_useState as useState, Kayla_useTick as useTick, Kayla_useViewportEffect as useViewportEffect };
+  export { type Kayla_ExportsOfFC as ExportsOfFC, type Kayla_FC as FC, type Kayla_FCExports as FCExports, type Kayla_FCProps as FCProps, Kayla_JSX as JSX, Kayla_KMatrix2D as KMatrix2D, type Kayla_KaylaClickConfig as KaylaClickConfig, type Kayla_KaylaClickType as KaylaClickType, Kayla_KaylaContext as KaylaContext, type Kayla_KaylaCustomHookConfig as KaylaCustomHookConfig, type Kayla_KaylaElement as KaylaElement, type Kayla_KaylaElementRef as KaylaElementRef, type Kayla_KaylaExportables as KaylaExportables, type Kayla_KaylaExports as KaylaExports, type Kayla_KaylaFiberControl as KaylaFiberControl, Kayla_KaylaFragment as KaylaFragment, type Kayla_KaylaGame as KaylaGame, Kayla_KaylaInternals as KaylaInternals, type Kayla_KaylaLayerInfo as KaylaLayerInfo, type Kayla_KaylaLayerProps as KaylaLayerProps, type Kayla_KaylaPointerAction as KaylaPointerAction, Kayla_KaylaRect as KaylaRect, type Kayla_KaylaRef as KaylaRef, type Kayla_KaylaRenderer as KaylaRenderer, type Kayla_KaylaScene as KaylaScene, type Kayla_KaylaState as KaylaState, Kayla_Layer as Layer, type Kayla_PropOfFC as PropOfFC, type Kayla_Reassignable as Reassignable, type Kayla_UnsafeKaylaFiber as UnsafeKaylaFiber, Kayla_createContext as createContext, Kayla_createElement as createElement, Kayla_createGame as createGame, Kayla_createReassignableObject as createReassignableObject, Kayla_createRenderer as createRenderer, Kayla_createScene as createScene, Kayla_createUseHook as createUseHook, selfSym as self, Kayla_setLogLevel as setLogLevel, Kayla_useClick as useClick, Kayla_useContext as useContext, Kayla_useCurrentGame as useCurrentGame, Kayla_useCurrentRenderer as useCurrentRenderer, Kayla_useCurrentScene as useCurrentScene, Kayla_useCurrentTicker as useCurrentTicker, Kayla_useDisposableRef as useDisposableRef, Kayla_useEffect as useEffect, Kayla_useEntity as useEntity, Kayla_useExports as useExports, Kayla_useFiber as useFiber, Kayla_useFiberControl as useFiberControl, Kayla_useGlobalClick as useGlobalClick, Kayla_useGlobalPointer as useGlobalPointer, Kayla_useInitialization as useInitialization, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, Kayla_usePointer as usePointer, Kayla_useRect as useRect, Kayla_useRef as useRef, Kayla_useSelf as useSelf, Kayla_useShouldRefresh as useShouldRefresh, Kayla_useState as useState, Kayla_useTick as useTick, Kayla_useViewportEffect as useViewportEffect };
 }
 
-export { usePointer as $, createUseHook as A, selfSym as B, setLogLevel as C, useClick as D, type ExportsOfFC as E, type FCProps as F, useContext as G, useCurrentGame as H, useCurrentRenderer as I, JSX as J, Kayla as K, useCurrentScene as L, useCurrentTicker as M, useDisposableRef as N, useEffect as O, type PropOfFC as P, useEntity as Q, type Reassignable as R, useExports as S, useFiber as T, type UnsafeKaylaFiber as U, useFiberControl as V, useGlobalClick as W, useGlobalPointer as X, useInitialization as Y, useNextStack as Z, usePaint as _, type FCExports as a, useRect as a0, useRef as a1, useSelf as a2, useShouldRefresh as a3, useState as a4, useTick as a5, useViewportEffect as a6, type FC as b, type KaylaClickConfig as c, type KaylaClickType as d, KaylaContext as e, type KaylaCustomHookConfig as f, type KaylaElement as g, type KaylaElementRef as h, type KaylaExportables as i, type KaylaExports as j, type KaylaFiberControl as k, KaylaFragment as l, KaylaGame as m, KaylaInternals as n, type KaylaPointerAction as o, KaylaRect as p, type KaylaRef as q, KaylaRenderer as r, KaylaScene as s, type KaylaState as t, createContext as u, createElement as v, createGame as w, createReassignableObject as x, createRenderer as y, createScene as z };
+export { useGlobalPointer as $, createReassignableObject as A, createRenderer as B, createScene as C, createUseHook as D, type ExportsOfFC as E, type FCProps as F, selfSym as G, setLogLevel as H, useClick as I, JSX as J, Kayla as K, Layer as L, useContext as M, useCurrentGame as N, useCurrentRenderer as O, type PropOfFC as P, useCurrentScene as Q, type Reassignable as R, useCurrentTicker as S, useDisposableRef as T, type UnsafeKaylaFiber as U, useEffect as V, useEntity as W, useExports as X, useFiber as Y, useFiberControl as Z, useGlobalClick as _, type FCExports as a, useInitialization as a0, useNextStack as a1, usePaint as a2, usePointer as a3, useRect as a4, useRef as a5, useSelf as a6, useShouldRefresh as a7, useState as a8, useTick as a9, useViewportEffect as aa, type FC as b, KMatrix2D as c, type KaylaClickConfig as d, type KaylaClickType as e, KaylaContext as f, type KaylaCustomHookConfig as g, type KaylaElement as h, type KaylaElementRef as i, type KaylaExportables as j, type KaylaExports as k, type KaylaFiberControl as l, KaylaFragment as m, KaylaGame as n, KaylaInternals as o, type KaylaLayerInfo as p, type KaylaLayerProps as q, type KaylaPointerAction as r, KaylaRect as s, type KaylaRef as t, KaylaRenderer as u, KaylaScene as v, type KaylaState as w, createContext as x, createElement as y, createGame as z };

package/dist/{kayla-internals-yPNDC4nT.d.cts → kayla-internals-D4Wr4S0V.d.cts}

@@ -584,10 +584,12 @@ declare namespace KaylaInternals {
             instance: KaylaContext<any>;
             value: unknown;
         };
+        lastLayer?: KaylaLayerInfo;
         get childrenCount(): number;
         maxSafeChildren: number;
         dynamicChildren: KaylaElement<any>[];
         constructor(globalKayla: GlobalKayla, scene: KaylaScene, element: KaylaElement<Props>);
+        getCorrectMousePos(pos?: Vector2): Vector2;
         getChildrenEntities(): KaylaRectEntity[];
         pointerHook(pos: Vector2, type: KaylaClickType, action: KaylaPointerAction): void;
         resizeHook({ width, height }: {
@@ -634,6 +636,7 @@ declare namespace KaylaInternals {
         setMaxChildren(max: number): void;
         getMaxChildren(): number;
         getFiberChain(): UnsafeKaylaFiber[];
+        getAllChildrenNestedFlattened(): UnsafeKaylaFiber[];
         getContextChain(): KaylaFiber<any, any>["contextInfo"][];
         findContextValueFromInst(inst: KaylaContext<any>): unknown;
         getEntityChain(): KaylaRectEntity[];
@@ -845,6 +848,7 @@ declare namespace KaylaInternals {
     class KaylaScene {
         #private;
         constructor(scene: LeaSceneII);
+        getLayers(): Map<string, KaylaLayerInfo>;
         /**
          * Exposes all the dangerous fibers.
          */
@@ -861,6 +865,15 @@ declare namespace KaylaInternals {
          * Exposes the game object.
          */
         getGame(): KaylaGame;
+        getOrCreateLayer(name: string, defaultZ?: number): KaylaLayerInfo;
+        getSortedLayers(): KaylaLayerInfo[];
+        setLayerVisible(name: string, visible: boolean): void;
+        /**
+         * Draws all entities in z-order (higher z = drawn later).
+         *
+         * @param ctx - The 2D rendering context
+         */
+        protected handleDraw(ctx: CanvasRenderingContext2D): void;
         private drawHandler;
         /**
          * Attaches this scene to a game instance.
@@ -880,6 +893,7 @@ declare namespace KaylaInternals {
          * @param elem - Root Kayla element (usually JSX)
          */
         spawn(elem: KaylaElement<any>): Promise<void>;
+        getRoot(): UnsafeKaylaFiber;
         private createFiber;
         /**
          * Detaches this scene from its game (if attached).
@@ -1094,17 +1108,29 @@ declare const useGlobalClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPoi
  * Useful for global input (pause menu toggle, debug shortcuts, drag anywhere…).
  * Multiple `useGlobalPointer` calls **stack** and run in declaration order.
  *
- * @param callback Global pointer handler — receives world position and click type
+ * **Important – coordinate system depends on context:**
+ * - If this component is inside a `<Layer transform={…}>`, you receive **layer-local coordinates**
+ * - Otherwise you receive **world coordinates** (same as entity positions)
+ *
+ * Multiple handlers stack — they are called in declaration order.
+ *
+ * @param handler Called with:
+ *   - `pos`        pointer position (world or layer-local — see above)
+ *   - `type`       "left" | "right" | "middle"
+ *   - `action`     "down" | "up" | "move" | "cancel"
+ * @param config Optional filter to reduce calls
  *
  * @example
- * useGlobalPointer((pos) => {
- *   isPaused.set(!isPaused.get());
+ * // Global pause on right-click (anywhere)
+ * useGlobalPointer((pos, type) => {
+ *   if (type === "right") isPaused.value = !isPaused.value;
  * }, { type: "right", action: "down" });
- * useGlobalPointer((pos) => {
- *   // set player pos as mouse pos
- *   player.x = pos.x;
- *   player.y = pos.y;
- * }, { action: "move" });
+ *
+ * @example
+ * // Inside a zoomable map layer — pos is already in map-local space
+ * useGlobalPointer((localPos) => {
+ *   console.log("Clicked map at:", localPos);
+ * });
  */
 declare const useGlobalPointer: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
 /**
@@ -1138,17 +1164,35 @@ declare const useClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"]
  * **This hook MUST be called at the top level of a component function — never inside loops, conditions, nested functions, or callbacks.**
  * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
+ * **Coordinate system note (very important since layers):**
+ * - If this component lives inside a `<Layer>` with a `transform` prop (camera, zoom, scroll, rotation…),
+ *   then `pos` is already transformed into the **layer-local coordinate system**.
+ * - The automatic hit-test rectangle check is also performed in **layer-local space**.
+ * - If there is **no transform** on the containing layer → `pos` is in world coordinates.
+ *
  * Uses the rectangle bounds from {@link useRect} / underlying entity.
  * Multiple `usePointer` calls **stack** and run in declaration order.
  *
- * @param callback pointer handler — receives world position and click type ("left" | "right" | "middle")
+ * @param handler Receives:
+ *   - `pos`        pointer position in the coordinate system this entity lives in
+ *   - `type`       button ("left"|"right"|"middle")
+ *   - `action`     "down"|"up"|"move"|"cancel"
+ * @param config Optional filters (button + action)
+ *
+ * @example
+ * // Classic button (no layer transform)
+ * usePointer((worldPos, type, action) => {
+ *   if (action === "down" && type === "left") {
+ *     onClick();
+ *   }
+ * }, { type: "left", action: "down" });
  *
  * @example
- * usePointer((pos) => {
- *   score.add(1);
- *   playSound("collect");
- *   // optional: spawn particle children on click
- * }, { type: "left", action: "up" });
+ * // Inside a zoomed/scrollable UI panel or map
+ * usePointer((localPos) => {
+ *   // localPos is already correct for items inside this zoomed layer
+ *   inventory.selectSlotAt(localPos);
+ * });
  *
  * @see {@link useGlobalPointer} — for pointer events anywhere (not bound to this entity)
  */
@@ -1705,12 +1749,116 @@ declare namespace JSX {
     }
     type ElementType = FC<any>;
 }
+/**
+ * Configuration object for a single named rendering layer.
+ * Created/managed via `<Layer>` components.
+ */
+interface KaylaLayerInfo {
+    /** Unique name of the layer (used as key in scene.#layers Map) */
+    name: string;
+    /** Z-index / sort order of the layer itself (higher = drawn later) */
+    z: number;
+    /** Blend mode applied to the entire layer during rendering */
+    blendMode?: GlobalCompositeOperation;
+    /** Whether this layer should be rendered at all */
+    visible: boolean;
+    /**
+     * Root fiber whose subtree belongs to this layer.
+     * Usually set to the fiber of the `<Layer name="..." />` component that first claimed this name.
+     */
+    rootFiber: UnsafeKaylaFiber | null;
+    /**
+     * 2D transformation matrix applied to rendering **and** pointer coordinate transformation.
+     * When present, pointer events inside this layer are delivered in local coordinates.
+     */
+    transform?: KMatrix2D | null;
+}
+/** Props accepted by the `<Layer>` component */
+interface KaylaLayerProps extends FCProps {
+    /** Required. Unique name identifying this layer */
+    name: string;
+    /** Layer draw order (higher = later / on top) */
+    z?: number;
+    /** Canvas blend mode for the whole layer */
+    blend?: GlobalCompositeOperation;
+    /** Toggle rendering of the entire layer */
+    visible?: boolean;
+    /** Children rendered inside this layer's context */
+    children?: KaylaElement<any>[];
+    /**
+     * Transformation applied to rendering and input coordinates.
+     * Use `KMatrix2D` to build cameras, zoom views, parallax layers, rotated UI panels, etc.
+     */
+    transform?: KMatrix2D;
+}
+/**
+ * Defines a named rendering layer with optional transform, blend mode, visibility, and draw order.
+ *
+ * `<Layer>` is a special component that groups its children into a separate rendering pass.
+ * It allows you to:
+ * - Control draw order between major groups of entities (via `z`)
+ * - Apply coordinate transforms (camera, zoom, scroll, rotation) to an entire subtree
+ * - Change blending behavior for the whole layer
+ * - Toggle visibility of large parts of the scene without unmounting components
+ *
+ * **Coordinate system behavior:**
+ * - If `transform` is provided, **all pointer coordinates** delivered to `usePointer` / `useGlobalPointer`
+ *   inside this layer (and its descendants) are automatically transformed into the **layer-local coordinate system**.
+ * - The automatic hit-test for `usePointer` also happens in layer-local space.
+ * - Without `transform` (identity/default), coordinates remain in **world space**.
+ *
+ * **Important notes:**
+ * - Layers are **not** nested in the traditional sense — each `<Layer>` creates an independent rendering group.
+ * - Multiple `<Layer>` components with the **same `name`** will **share the same layer configuration** (last one wins for most properties).
+ * - The `rootFiber` of the layer is set to the fiber of the **first** `<Layer name="..."` component encountered with that name.
+ * - Children inside `<Layer>` still participate in normal component lifecycle, ticking, painting, pointer handling, etc.
+ *
+ * @example
+ * // Simple UI overlay that draws on top
+ * <Layer name="ui" z={1000} visible={true}>
+ *   <HUD />
+ *   <PauseMenu />
+ * </Layer>
+ *
+ * @example
+ * // Zoomable / scrollable map area
+ * function MapView() {
+ *   const zoom = useSelf(() => ({ scale: 1.8, offset: new LEA.Vector2(120, 80) }));
+ *
+ *   const matrix = new KMatrix2D();
+ *   matrix.translateSelf(zoom.offset.x, zoom.offset.y);
+ *   matrix.scaleSelf(zoom.scale, zoom.scale);
+ *
+ *   return (
+ *     <Layer
+ *       name="world-map"
+ *       z={10}
+ *       transform={matrix}
+ *       blend="source-over"
+ *     >
+ *       <BackgroundTiles />
+ *       <Player />
+ *       <Enemies />
+ *       {// Pointer events inside here receive map-local coordinates }
+ *     </Layer>
+ *   );
+ * }
+ * */
+declare const Layer: FC<KaylaLayerProps>;
+declare class KMatrix2D extends DOMMatrix {
+    #private;
+    constructor();
+    transformV(v: Vector2): Vector2;
+    inverseV(v: Vector2): Vector2;
+}
 
 type Kayla_ExportsOfFC<T extends FC<any, any>> = ExportsOfFC<T>;
 type Kayla_FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExports> = FC<Props, Exports>;
 type Kayla_FCExports = FCExports;
 type Kayla_FCProps = FCProps;
 declare const Kayla_JSX: typeof JSX;
+type Kayla_KMatrix2D = KMatrix2D;
+declare const Kayla_KMatrix2D: typeof KMatrix2D;
 type Kayla_KaylaClickConfig = KaylaClickConfig;
 type Kayla_KaylaClickType = KaylaClickType;
 type Kayla_KaylaContext<Context> = KaylaContext<Context>;
@@ -1724,12 +1872,15 @@ type Kayla_KaylaFiberControl = KaylaFiberControl;
 declare const Kayla_KaylaFragment: typeof KaylaFragment;
 type Kayla_KaylaGame = KaylaGame;
 declare const Kayla_KaylaInternals: typeof KaylaInternals;
+type Kayla_KaylaLayerInfo = KaylaLayerInfo;
+type Kayla_KaylaLayerProps = KaylaLayerProps;
 type Kayla_KaylaPointerAction = KaylaPointerAction;
 declare const Kayla_KaylaRect: typeof KaylaRect;
 type Kayla_KaylaRef<T> = KaylaRef<T>;
 type Kayla_KaylaRenderer = KaylaRenderer;
 type Kayla_KaylaScene = KaylaScene;
 type Kayla_KaylaState<T> = KaylaState<T>;
+declare const Kayla_Layer: typeof Layer;
 type Kayla_PropOfFC<T extends FC<any, any>> = PropOfFC<T>;
 type Kayla_Reassignable<T extends Record<any, any>> = Reassignable<T>;
 type Kayla_UnsafeKaylaFiber = UnsafeKaylaFiber;
@@ -1767,7 +1918,7 @@ declare const Kayla_useState: typeof useState;
 declare const Kayla_useTick: typeof useTick;
 declare const Kayla_useViewportEffect: typeof useViewportEffect;
 declare namespace Kayla {
-  export { type Kayla_ExportsOfFC as ExportsOfFC, type Kayla_FC as FC, type Kayla_FCExports as FCExports, type Kayla_FCProps as FCProps, Kayla_JSX as JSX, type Kayla_KaylaClickConfig as KaylaClickConfig, type Kayla_KaylaClickType as KaylaClickType, Kayla_KaylaContext as KaylaContext, type Kayla_KaylaCustomHookConfig as KaylaCustomHookConfig, type Kayla_KaylaElement as KaylaElement, type Kayla_KaylaElementRef as KaylaElementRef, type Kayla_KaylaExportables as KaylaExportables, type Kayla_KaylaExports as KaylaExports, type Kayla_KaylaFiberControl as KaylaFiberControl, Kayla_KaylaFragment as KaylaFragment, type Kayla_KaylaGame as KaylaGame, Kayla_KaylaInternals as KaylaInternals, type Kayla_KaylaPointerAction as KaylaPointerAction, Kayla_KaylaRect as KaylaRect, type Kayla_KaylaRef as KaylaRef, type Kayla_KaylaRenderer as KaylaRenderer, type Kayla_KaylaScene as KaylaScene, type Kayla_KaylaState as KaylaState, type Kayla_PropOfFC as PropOfFC, type Kayla_Reassignable as Reassignable, type Kayla_UnsafeKaylaFiber as UnsafeKaylaFiber, Kayla_createContext as createContext, Kayla_createElement as createElement, Kayla_createGame as createGame, Kayla_createReassignableObject as createReassignableObject, Kayla_createRenderer as createRenderer, Kayla_createScene as createScene, Kayla_createUseHook as createUseHook, selfSym as self, Kayla_setLogLevel as setLogLevel, Kayla_useClick as useClick, Kayla_useContext as useContext, Kayla_useCurrentGame as useCurrentGame, Kayla_useCurrentRenderer as useCurrentRenderer, Kayla_useCurrentScene as useCurrentScene, Kayla_useCurrentTicker as useCurrentTicker, Kayla_useDisposableRef as useDisposableRef, Kayla_useEffect as useEffect, Kayla_useEntity as useEntity, Kayla_useExports as useExports, Kayla_useFiber as useFiber, Kayla_useFiberControl as useFiberControl, Kayla_useGlobalClick as useGlobalClick, Kayla_useGlobalPointer as useGlobalPointer, Kayla_useInitialization as useInitialization, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, Kayla_usePointer as usePointer, Kayla_useRect as useRect, Kayla_useRef as useRef, Kayla_useSelf as useSelf, Kayla_useShouldRefresh as useShouldRefresh, Kayla_useState as useState, Kayla_useTick as useTick, Kayla_useViewportEffect as useViewportEffect };
+  export { type Kayla_ExportsOfFC as ExportsOfFC, type Kayla_FC as FC, type Kayla_FCExports as FCExports, type Kayla_FCProps as FCProps, Kayla_JSX as JSX, Kayla_KMatrix2D as KMatrix2D, type Kayla_KaylaClickConfig as KaylaClickConfig, type Kayla_KaylaClickType as KaylaClickType, Kayla_KaylaContext as KaylaContext, type Kayla_KaylaCustomHookConfig as KaylaCustomHookConfig, type Kayla_KaylaElement as KaylaElement, type Kayla_KaylaElementRef as KaylaElementRef, type Kayla_KaylaExportables as KaylaExportables, type Kayla_KaylaExports as KaylaExports, type Kayla_KaylaFiberControl as KaylaFiberControl, Kayla_KaylaFragment as KaylaFragment, type Kayla_KaylaGame as KaylaGame, Kayla_KaylaInternals as KaylaInternals, type Kayla_KaylaLayerInfo as KaylaLayerInfo, type Kayla_KaylaLayerProps as KaylaLayerProps, type Kayla_KaylaPointerAction as KaylaPointerAction, Kayla_KaylaRect as KaylaRect, type Kayla_KaylaRef as KaylaRef, type Kayla_KaylaRenderer as KaylaRenderer, type Kayla_KaylaScene as KaylaScene, type Kayla_KaylaState as KaylaState, Kayla_Layer as Layer, type Kayla_PropOfFC as PropOfFC, type Kayla_Reassignable as Reassignable, type Kayla_UnsafeKaylaFiber as UnsafeKaylaFiber, Kayla_createContext as createContext, Kayla_createElement as createElement, Kayla_createGame as createGame, Kayla_createReassignableObject as createReassignableObject, Kayla_createRenderer as createRenderer, Kayla_createScene as createScene, Kayla_createUseHook as createUseHook, selfSym as self, Kayla_setLogLevel as setLogLevel, Kayla_useClick as useClick, Kayla_useContext as useContext, Kayla_useCurrentGame as useCurrentGame, Kayla_useCurrentRenderer as useCurrentRenderer, Kayla_useCurrentScene as useCurrentScene, Kayla_useCurrentTicker as useCurrentTicker, Kayla_useDisposableRef as useDisposableRef, Kayla_useEffect as useEffect, Kayla_useEntity as useEntity, Kayla_useExports as useExports, Kayla_useFiber as useFiber, Kayla_useFiberControl as useFiberControl, Kayla_useGlobalClick as useGlobalClick, Kayla_useGlobalPointer as useGlobalPointer, Kayla_useInitialization as useInitialization, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, Kayla_usePointer as usePointer, Kayla_useRect as useRect, Kayla_useRef as useRef, Kayla_useSelf as useSelf, Kayla_useShouldRefresh as useShouldRefresh, Kayla_useState as useState, Kayla_useTick as useTick, Kayla_useViewportEffect as useViewportEffect };
 }
 
-export { usePointer as $, createUseHook as A, selfSym as B, setLogLevel as C, useClick as D, type ExportsOfFC as E, type FCProps as F, useContext as G, useCurrentGame as H, useCurrentRenderer as I, JSX as J, Kayla as K, useCurrentScene as L, useCurrentTicker as M, useDisposableRef as N, useEffect as O, type PropOfFC as P, useEntity as Q, type Reassignable as R, useExports as S, useFiber as T, type UnsafeKaylaFiber as U, useFiberControl as V, useGlobalClick as W, useGlobalPointer as X, useInitialization as Y, useNextStack as Z, usePaint as _, type FCExports as a, useRect as a0, useRef as a1, useSelf as a2, useShouldRefresh as a3, useState as a4, useTick as a5, useViewportEffect as a6, type FC as b, type KaylaClickConfig as c, type KaylaClickType as d, KaylaContext as e, type KaylaCustomHookConfig as f, type KaylaElement as g, type KaylaElementRef as h, type KaylaExportables as i, type KaylaExports as j, type KaylaFiberControl as k, KaylaFragment as l, KaylaGame as m, KaylaInternals as n, type KaylaPointerAction as o, KaylaRect as p, type KaylaRef as q, KaylaRenderer as r, KaylaScene as s, type KaylaState as t, createContext as u, createElement as v, createGame as w, createReassignableObject as x, createRenderer as y, createScene as z };
+export { useGlobalPointer as $, createReassignableObject as A, createRenderer as B, createScene as C, createUseHook as D, type ExportsOfFC as E, type FCProps as F, selfSym as G, setLogLevel as H, useClick as I, JSX as J, Kayla as K, Layer as L, useContext as M, useCurrentGame as N, useCurrentRenderer as O, type PropOfFC as P, useCurrentScene as Q, type Reassignable as R, useCurrentTicker as S, useDisposableRef as T, type UnsafeKaylaFiber as U, useEffect as V, useEntity as W, useExports as X, useFiber as Y, useFiberControl as Z, useGlobalClick as _, type FCExports as a, useInitialization as a0, useNextStack as a1, usePaint as a2, usePointer as a3, useRect as a4, useRef as a5, useSelf as a6, useShouldRefresh as a7, useState as a8, useTick as a9, useViewportEffect as aa, type FC as b, KMatrix2D as c, type KaylaClickConfig as d, type KaylaClickType as e, KaylaContext as f, type KaylaCustomHookConfig as g, type KaylaElement as h, type KaylaElementRef as i, type KaylaExportables as j, type KaylaExports as k, type KaylaFiberControl as l, KaylaFragment as m, KaylaGame as n, KaylaInternals as o, type KaylaLayerInfo as p, type KaylaLayerProps as q, type KaylaPointerAction as r, KaylaRect as s, type KaylaRef as t, KaylaRenderer as u, KaylaScene as v, type KaylaState as w, createContext as x, createElement as y, createGame as z };