@kayelaa/canvas 0.2.4 → 0.2.6

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

@@ -368,13 +368,16 @@ declare namespace KaylaInternals {
             alwaysRecall?: boolean;
         }): KaylaState<T>;
         useShouldRefresh(deps: KaylaState<any>[]): void;
+        /**
+         * @deprecated
+         */
         useRef(initialValue: typeof selfSym): KaylaElementRef;
         useRef<T>(initialValue: T | null): KaylaRef<T>;
         useEffect(onEffect: KaylaFiber["onEffect"][number]): void;
         useViewportEffect(onEffect: KaylaFiber["onViewportEffect"][number]): void;
         useExports<T extends FC<any, any>>(_fc: T, onExport: KaylaFiber<PropOfFC<T>, ExportsOfFC<T>>["onExport"]): void;
-        useGlobalClick(onClick: KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig): void;
-        useClick(onClick: KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig): void;
+        useGlobalPointer(onPointer: KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig): void;
+        usePointer(onPointer: KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig): void;
         useContext<T>(context: KaylaContext<T>): T;
         save(): void;
         restore(): void;
@@ -566,6 +569,9 @@ declare namespace KaylaInternals {
          */
         getFiberChain(): UnsafeKaylaFiber[];
     }
+    /**
+     * @private
+     */
     class KaylaFiber<Props extends FCProps = {}, Exports extends FCExports = FCExports> implements KaylaFiberControlIm {
         state: KaylaState<any>[];
         refs: KaylaRef<unknown>[];
@@ -598,7 +604,7 @@ declare namespace KaylaInternals {
         onExport: () => KaylaExports<Exports>;
         onEffect: Array<() => (() => void) | void>;
         onViewportEffect: Array<(renderer: KaylaRenderer, width: number, height: number) => void>;
-        onGlobalClick: Array<{
+        onGlobalPointer: Array<{
             handler: (pos: Vector2, type: KaylaClickType, action: KaylaPointerAction) => void | void;
             config: KaylaClickConfig;
         }>;
@@ -863,6 +869,10 @@ declare namespace KaylaInternals {
          */
         attachTo(game: KaylaGame): void;
         /**
+         * **Dangerous**: Call this function only **ONCE**.
+         *
+         * There is no way to unmount a spawned root.
+         *
          * Mounts a root component tree into the scene.
          *
          * Triggers component execution, entity creation, and hook registration.
@@ -906,7 +916,7 @@ declare class KaylaContext<Context> {
  * @param defaultValue Fallback value used when no `<Provider>` is found in the ancestor chain
  * @returns Context object with a `.Provider` component (and `.defaultValue` for reference)
  *
- * @example Creating and using a simple game settings context
+ * @example
  * // settings.ts
  * export const GameSettingsContext = createContext({
  *   difficulty: "normal",
@@ -936,7 +946,7 @@ type KaylaClickType = "left" | "right" | "middle" | "invalid";
 type KaylaPointerAction = "down" | "up" | "move" | "cancel" | "any";
 interface KaylaClickConfig {
     /**
-     * Default: "left"
+     * Default: "any"
      */
     type?: Exclude<KaylaClickType, "invalid"> | "any";
     /**
@@ -1055,6 +1065,8 @@ declare const useEffect: (onEffect: KaylaInternals.KaylaFiber["onEffect"][number
  */
 declare const useViewportEffect: (onEffect: KaylaInternals.KaylaFiber["onViewportEffect"][number]) => void;
 /**
+ * Alternative: {@link useGlobalPointer}
+ * @deprecated
  * Registers a callback that runs on **every click anywhere** in any attached renderer.
  *
  * **This hook MUST be called at the top level of a component function — never inside loops, conditions, nested functions, or callbacks.**
@@ -1072,8 +1084,32 @@ declare const useViewportEffect: (onEffect: KaylaInternals.KaylaFiber["onViewpor
  *   }
  * });
  */
-declare const useGlobalClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig) => void;
+declare const useGlobalClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
+/**
+ * Registers a callback that runs on **every pointer events anywhere** in any attached renderer.
+ *
+ * **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.
+ *
+ * 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
+ *
+ * @example
+ * useGlobalPointer((pos) => {
+ *   isPaused.set(!isPaused.get());
+ * }, { type: "right", action: "down" });
+ * useGlobalPointer((pos) => {
+ *   // set player pos as mouse pos
+ *   player.x = pos.x;
+ *   player.y = pos.y;
+ * }, { action: "move" });
+ */
+declare const useGlobalPointer: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
 /**
+ * Alternative: {@link usePointer}
+ * @deprecated
  * Registers a callback that runs **whenever the entity is clicked** (inside its bounds).
  *
  * **This hook MUST be called at the top level of a component function — never inside loops, conditions, nested functions, or callbacks.**
@@ -1095,7 +1131,28 @@ declare const useGlobalClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick
  *
  * @see {@link useGlobalClick} — for clicks anywhere (not bound to this entity)
  */
-declare const useClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig) => void;
+declare const useClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
+/**
+ * Registers a callback that runs **whenever the entity has pointer events that's bound to entity/collides** (inside its bounds).
+ *
+ * **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.
+ *
+ * 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")
+ *
+ * @example
+ * usePointer((pos) => {
+ *   score.add(1);
+ *   playSound("collect");
+ *   // optional: spawn particle children on click
+ * }, { type: "left", action: "up" });
+ *
+ * @see {@link useGlobalPointer} — for pointer events anywhere (not bound to this entity)
+ */
+declare const usePointer: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
 /**
  * Runs a one-time initialization function **exactly once** when the entity is first mounted.
  *
@@ -1158,7 +1215,7 @@ declare const useRect: () => KaylaRect;
  *
  * @param callback Update handler — receives delta time (seconds) and cancellable event
  *
- * @example Movement + simple boundary check
+ * @example
  * useTick((dt, event) => {
  *   rect.pos.x += 200 * dt;
  *   if (rect.right > 800) {
@@ -1415,7 +1472,7 @@ declare const useCurrentTicker: () => LeaTickerII;
  * @param context - The context object created via `createContext(defaultValue)`
  * @returns The current context value (type-inferred from context)
  *
- * @example Using a theme context
+ * @example
  * const ThemeContext = createContext({
  *   bg: "#111",
  *   accent: "#ff3366",
@@ -1474,7 +1531,7 @@ declare const selfSym: unique symbol;
  *
  * @param callback Function to run asynchronously in the next microtask
  *
- * @example Accessing child exports right after spawn
+ * @example
  * function Parent() {
  *   const childrenRef = useRef<KaylaExports<any>[]>([]);
  *
@@ -1495,7 +1552,7 @@ declare const selfSym: unique symbol;
  *   );
  * }
  *
- * @example Delaying something until after paint/tick phase
+ * @example
  * useTick(dt => {
  *   // ... movement logic ...
  *   useNextStack(() => {
@@ -1511,7 +1568,7 @@ declare const useNextStack: (callback: () => void) => void;
  *
  * **This is a regular functional component** — use it in JSX/TSX just like any other component.
  *
- * @example Grouping without extra entity overhead
+ * @example
  * function Explosion() {
  *   return (
  *     <KaylaFragment>
@@ -1697,9 +1754,11 @@ declare const Kayla_useExports: typeof useExports;
 declare const Kayla_useFiber: typeof useFiber;
 declare const Kayla_useFiberControl: typeof useFiberControl;
 declare const Kayla_useGlobalClick: typeof useGlobalClick;
+declare const Kayla_useGlobalPointer: typeof useGlobalPointer;
 declare const Kayla_useInitialization: typeof useInitialization;
 declare const Kayla_useNextStack: typeof useNextStack;
 declare const Kayla_usePaint: typeof usePaint;
+declare const Kayla_usePointer: typeof usePointer;
 declare const Kayla_useRect: typeof useRect;
 declare const Kayla_useRef: typeof useRef;
 declare const Kayla_useSelf: typeof useSelf;
@@ -1708,7 +1767,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_useInitialization as useInitialization, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, 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, 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 { useRef 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, useInitialization as X, useNextStack as Y, usePaint as Z, useRect as _, type FCExports as a, useSelf as a0, useShouldRefresh as a1, useState as a2, useTick as a3, useViewportEffect as a4, 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 { 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 };

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

@@ -368,13 +368,16 @@ declare namespace KaylaInternals {
             alwaysRecall?: boolean;
         }): KaylaState<T>;
         useShouldRefresh(deps: KaylaState<any>[]): void;
+        /**
+         * @deprecated
+         */
         useRef(initialValue: typeof selfSym): KaylaElementRef;
         useRef<T>(initialValue: T | null): KaylaRef<T>;
         useEffect(onEffect: KaylaFiber["onEffect"][number]): void;
         useViewportEffect(onEffect: KaylaFiber["onViewportEffect"][number]): void;
         useExports<T extends FC<any, any>>(_fc: T, onExport: KaylaFiber<PropOfFC<T>, ExportsOfFC<T>>["onExport"]): void;
-        useGlobalClick(onClick: KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig): void;
-        useClick(onClick: KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig): void;
+        useGlobalPointer(onPointer: KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig): void;
+        usePointer(onPointer: KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig): void;
         useContext<T>(context: KaylaContext<T>): T;
         save(): void;
         restore(): void;
@@ -566,6 +569,9 @@ declare namespace KaylaInternals {
          */
         getFiberChain(): UnsafeKaylaFiber[];
     }
+    /**
+     * @private
+     */
     class KaylaFiber<Props extends FCProps = {}, Exports extends FCExports = FCExports> implements KaylaFiberControlIm {
         state: KaylaState<any>[];
         refs: KaylaRef<unknown>[];
@@ -598,7 +604,7 @@ declare namespace KaylaInternals {
         onExport: () => KaylaExports<Exports>;
         onEffect: Array<() => (() => void) | void>;
         onViewportEffect: Array<(renderer: KaylaRenderer, width: number, height: number) => void>;
-        onGlobalClick: Array<{
+        onGlobalPointer: Array<{
             handler: (pos: Vector2, type: KaylaClickType, action: KaylaPointerAction) => void | void;
             config: KaylaClickConfig;
         }>;
@@ -863,6 +869,10 @@ declare namespace KaylaInternals {
          */
         attachTo(game: KaylaGame): void;
         /**
+         * **Dangerous**: Call this function only **ONCE**.
+         *
+         * There is no way to unmount a spawned root.
+         *
          * Mounts a root component tree into the scene.
          *
          * Triggers component execution, entity creation, and hook registration.
@@ -906,7 +916,7 @@ declare class KaylaContext<Context> {
  * @param defaultValue Fallback value used when no `<Provider>` is found in the ancestor chain
  * @returns Context object with a `.Provider` component (and `.defaultValue` for reference)
  *
- * @example Creating and using a simple game settings context
+ * @example
  * // settings.ts
  * export const GameSettingsContext = createContext({
  *   difficulty: "normal",
@@ -936,7 +946,7 @@ type KaylaClickType = "left" | "right" | "middle" | "invalid";
 type KaylaPointerAction = "down" | "up" | "move" | "cancel" | "any";
 interface KaylaClickConfig {
     /**
-     * Default: "left"
+     * Default: "any"
      */
     type?: Exclude<KaylaClickType, "invalid"> | "any";
     /**
@@ -1055,6 +1065,8 @@ declare const useEffect: (onEffect: KaylaInternals.KaylaFiber["onEffect"][number
  */
 declare const useViewportEffect: (onEffect: KaylaInternals.KaylaFiber["onViewportEffect"][number]) => void;
 /**
+ * Alternative: {@link useGlobalPointer}
+ * @deprecated
  * Registers a callback that runs on **every click anywhere** in any attached renderer.
  *
  * **This hook MUST be called at the top level of a component function — never inside loops, conditions, nested functions, or callbacks.**
@@ -1072,8 +1084,32 @@ declare const useViewportEffect: (onEffect: KaylaInternals.KaylaFiber["onViewpor
  *   }
  * });
  */
-declare const useGlobalClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig) => void;
+declare const useGlobalClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
+/**
+ * Registers a callback that runs on **every pointer events anywhere** in any attached renderer.
+ *
+ * **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.
+ *
+ * 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
+ *
+ * @example
+ * useGlobalPointer((pos) => {
+ *   isPaused.set(!isPaused.get());
+ * }, { type: "right", action: "down" });
+ * useGlobalPointer((pos) => {
+ *   // set player pos as mouse pos
+ *   player.x = pos.x;
+ *   player.y = pos.y;
+ * }, { action: "move" });
+ */
+declare const useGlobalPointer: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
 /**
+ * Alternative: {@link usePointer}
+ * @deprecated
  * Registers a callback that runs **whenever the entity is clicked** (inside its bounds).
  *
  * **This hook MUST be called at the top level of a component function — never inside loops, conditions, nested functions, or callbacks.**
@@ -1095,7 +1131,28 @@ declare const useGlobalClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick
  *
  * @see {@link useGlobalClick} — for clicks anywhere (not bound to this entity)
  */
-declare const useClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick"][number]["handler"], config?: KaylaClickConfig) => void;
+declare const useClick: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
+/**
+ * Registers a callback that runs **whenever the entity has pointer events that's bound to entity/collides** (inside its bounds).
+ *
+ * **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.
+ *
+ * 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")
+ *
+ * @example
+ * usePointer((pos) => {
+ *   score.add(1);
+ *   playSound("collect");
+ *   // optional: spawn particle children on click
+ * }, { type: "left", action: "up" });
+ *
+ * @see {@link useGlobalPointer} — for pointer events anywhere (not bound to this entity)
+ */
+declare const usePointer: (onPointer: KaylaInternals.KaylaFiber["onGlobalPointer"][number]["handler"], config?: KaylaClickConfig) => void;
 /**
  * Runs a one-time initialization function **exactly once** when the entity is first mounted.
  *
@@ -1158,7 +1215,7 @@ declare const useRect: () => KaylaRect;
  *
  * @param callback Update handler — receives delta time (seconds) and cancellable event
  *
- * @example Movement + simple boundary check
+ * @example
  * useTick((dt, event) => {
  *   rect.pos.x += 200 * dt;
  *   if (rect.right > 800) {
@@ -1415,7 +1472,7 @@ declare const useCurrentTicker: () => LeaTickerII;
  * @param context - The context object created via `createContext(defaultValue)`
  * @returns The current context value (type-inferred from context)
  *
- * @example Using a theme context
+ * @example
  * const ThemeContext = createContext({
  *   bg: "#111",
  *   accent: "#ff3366",
@@ -1474,7 +1531,7 @@ declare const selfSym: unique symbol;
  *
  * @param callback Function to run asynchronously in the next microtask
  *
- * @example Accessing child exports right after spawn
+ * @example
  * function Parent() {
  *   const childrenRef = useRef<KaylaExports<any>[]>([]);
  *
@@ -1495,7 +1552,7 @@ declare const selfSym: unique symbol;
  *   );
  * }
  *
- * @example Delaying something until after paint/tick phase
+ * @example
  * useTick(dt => {
  *   // ... movement logic ...
  *   useNextStack(() => {
@@ -1511,7 +1568,7 @@ declare const useNextStack: (callback: () => void) => void;
  *
  * **This is a regular functional component** — use it in JSX/TSX just like any other component.
  *
- * @example Grouping without extra entity overhead
+ * @example
  * function Explosion() {
  *   return (
  *     <KaylaFragment>
@@ -1697,9 +1754,11 @@ declare const Kayla_useExports: typeof useExports;
 declare const Kayla_useFiber: typeof useFiber;
 declare const Kayla_useFiberControl: typeof useFiberControl;
 declare const Kayla_useGlobalClick: typeof useGlobalClick;
+declare const Kayla_useGlobalPointer: typeof useGlobalPointer;
 declare const Kayla_useInitialization: typeof useInitialization;
 declare const Kayla_useNextStack: typeof useNextStack;
 declare const Kayla_usePaint: typeof usePaint;
+declare const Kayla_usePointer: typeof usePointer;
 declare const Kayla_useRect: typeof useRect;
 declare const Kayla_useRef: typeof useRef;
 declare const Kayla_useSelf: typeof useSelf;
@@ -1708,7 +1767,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_useInitialization as useInitialization, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, 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, 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 { useRef 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, useInitialization as X, useNextStack as Y, usePaint as Z, useRect as _, type FCExports as a, useSelf as a0, useShouldRefresh as a1, useState as a2, useTick as a3, useViewportEffect as a4, 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 { 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 };