@kayelaa/canvas 0.1.14 → 0.2.0

package/dist/{kayla-internals-DVENIMGb.d.cts → kayla-internals-CudoMM3W.d.cts}

@@ -1,13 +1,16 @@
-import { a as LeaGameII, b as LeaRendererII, V as Vector2, R as RectLeaEntity, c as LeaSceneII } from './lea-DvxsutSf.cjs';
+import { a as LeaGameII, b as LeaTimeout, c as LeaRendererII, d as LeaEventEmitter, V as Vector2, e as LeaTickerII, R as RectLeaEntity, f as LeaSceneII } from './lea-k7IGP_-W.cjs';
 
 /**
- * Base props interface that every Kayla component can receive.
+ * Base props that every Kayla functional component can receive.
  *
- * Extend this when defining custom component props:
+ * @remarks
+ * Extend this interface when defining custom component props.
  *
+ * @example
  * ```ts
- * interface MyProps extends FCProps {
- *   speed: number;
+ * interface PlayerProps extends FCProps {
+ *   initialSpeed?: number;
+ *   color: string;
  * }
  * ```
  */
@@ -17,7 +20,23 @@ type FCProps = {
     ref?: KaylaRef<KaylaInternals.KaylaRectEntity>;
     exportsRef?: KaylaRef<KaylaExports<any>>;
 } & Record<string, unknown>;
+/**
+ * Shape of the object that a component can expose to its parent via `exportsRef`.
+ *
+ * @remarks
+ * Usually contains methods, state handles, refs, or getters.
+ */
 type FCExports = {} & Record<string, KaylaExportables>;
+/**
+ * Functional component type used across Kayla.
+ *
+ * @typeParam Props - Props the component accepts
+ * @typeParam Exports - Public API the component exposes (optional)
+ *
+ * @remarks
+ * Components must return zero, one, or many `KaylaElement`s.
+ * Returning `void` is allowed but produces no entities.
+ */
 interface FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExports> {
     (props: Props & {
         ref?: KaylaElementRef;
@@ -93,22 +112,32 @@ declare function createRenderer(canvas: HTMLCanvasElement): KaylaRenderer;
  * scene.spawn(elem);
  */
 declare function createElement<Props extends FCProps>(fc: FC<Props>, props: Props): KaylaElement<Props>;
+/**
+ * Virtual element descriptor — the JSX representation of a component instance.
+ *
+ * @typeParam Props - Props type of the target component
+ *
+ * @see {@link createElement}
+ * @see {@link FC}
+ */
 interface KaylaElement<Props extends FCProps> {
     type: FC<Props>;
     props: Props;
 }
 /**
- * Read-only view of a state value created via `useState`.
+ * Read-only view of a piece of state managed by `useState`.
  *
- * Returned by `useState`. Changes via `.set()` / `.add()` / `.multiply()` may trigger
- * a component refresh (re-execution of the component function), which can be expensive
- * in performance-critical loops.
+ * @typeParam T - Type of the stored value
  *
- * **Performance warning:** Avoid frequent `.set()` calls in `useTick` / `usePaint` loops.
- * Prefer `useSelf` or `useRef` for hot data (position, velocity, timers, counters).
- * Use `useState` only for infrequent structural changes (e.g. `isDead`, `currentLevel`).
+ * @remarks
+ * **Performance critical warning**
+ * Frequent `.set()` calls inside `useTick` / `usePaint` loops will cause expensive
+ * component re-execution (refresh).
+ * → Use `useSelf` or `useRef` for position, velocity, timers, counters, etc.
+ * → Reserve `useState` for infrequent **structural** changes (health → 0, level up, isDead, etc.).
  *
- * @template T - Type of the stored value
+ * @see {@link useState}
+ * @see {@link useSelf} – recommended for most game loop data
  */
 interface KaylaState<T> extends KaylaInternals.KaylaInternalState<T> {
 }
@@ -170,7 +199,25 @@ interface KaylaRenderer extends KaylaInternals.KaylaRenderer {
  * rect.y += 5;
  * ```
  */
-interface KaylaRect extends KaylaInternals.KaylaRect {
+interface KaylaRect extends KaylaInternals.KaylaInternalRect {
+}
+declare namespace KaylaRect {
+    function rawCollision(a: RawKaylaRect, b: RawKaylaRect): boolean;
+    function getCurrToBound(curr: Vector2, angleTo: number, bounds: RawKaylaRect): Vector2;
+    function createRawRect(hint: Partial<RawKaylaRect> & {
+        x?: number;
+        y?: number;
+    }): RawKaylaRect;
+    interface RawKaylaRect {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }
 }
 /**
  * Internal APIs, do not use outside.
@@ -184,6 +231,12 @@ declare namespace KaylaInternals {
     class KaylaGame extends LeaGameII {
         #private;
         constructor(width: number, height: number, hz: typeof Infinity | number);
+        /**
+         * Thenable tick-based timeout system
+         * @param ms milliseconds to wait, zero can be provided for next tick.
+         * @returns a thenable.
+         */
+        delay(ms: number): LeaTimeout;
         /**
          * Whether the game has been started.
          */
@@ -204,6 +257,16 @@ declare namespace KaylaInternals {
          * @param renderer - The renderer to attach
          */
         addRenderer(renderer: KaylaRenderer): void;
+        /**
+         * Always resolves the first ever renderer registered.
+         */
+        get mainRenderer(): KaylaRenderer;
+        /**
+         * Resolves all valid renderers.
+         *
+         * @returns - Shallow copy of renderers.
+         */
+        getRenderers(): KaylaRenderer[];
         /**
          * Detaches a renderer from the game.
          *
@@ -219,7 +282,6 @@ declare namespace KaylaInternals {
      * @extends LeaRendererII
      */
     class KaylaRenderer extends LeaRendererII {
-        #private;
         /**
          * The attached game instance (set via `attachTo`).
          */
@@ -232,7 +294,16 @@ declare namespace KaylaInternals {
          * Current canvas-space pointer Y coordinate.
          */
         pointerY: number;
+        /**
+         * Pointer related event-emitter
+         */
+        protected pointerEvents: LeaEventEmitter<{
+            down: [Vector2, KaylaClickType];
+        }>;
         constructor(canvas: HTMLCanvasElement);
+        protected pointerPosUpdater(e: PointerEvent): void;
+        protected onPointerDown(e: PointerEvent): void;
+        static getClickType(e: PointerEvent): KaylaClickType;
         listenPointerUpdates(): void;
         unlistenPointerUpdates(): void;
         /**
@@ -285,6 +356,10 @@ declare namespace KaylaInternals {
         useRect(): KaylaRect;
         useFiber(): UnsafeKaylaFiber;
         useFiberControl(): KaylaFiberControl;
+        useCurrentTicker(): LeaTickerII;
+        useCurrentRenderer(): KaylaRenderer;
+        useCurrentGame(): KaylaGame;
+        useCurrentScene(): KaylaScene;
         useState<T>(initialValue?: T, { alwaysRecall }?: {
             alwaysRecall?: boolean;
         }): KaylaState<T>;
@@ -293,6 +368,9 @@ declare namespace KaylaInternals {
         useRef<T>(initialValue: T | null): KaylaRef<T>;
         useEffect(onEffect: KaylaFiber["onEffect"][number]): void;
         useExports<T extends FC<any, any>>(_fc: T, onExport: KaylaFiber<PropOfFC<T>, ExportsOfFC<T>>["onExport"]): void;
+        useGlobalClick(onClick: KaylaFiber["onGlobalClick"][number]): void;
+        useClick(onClick: KaylaFiber["onGlobalClick"][number]): void;
+        useContext<T>(context: KaylaContext<T>): T;
         save(): void;
         restore(): void;
         logLevel: "silent" | "warn" | "info" | "debug";
@@ -310,17 +388,19 @@ declare namespace KaylaInternals {
         isPrevented(): boolean;
     }
     /**
-     * Read-only view of a state value created via `useState`.
+     * Read-only view of a piece of state managed by `useState`.
      *
-     * Returned by `useState`. Changes via `.set()` / `.add()` / `.multiply()` may trigger
-     * a component refresh (re-execution of the component function), which can be expensive
-     * in performance-critical loops.
+     * @typeParam T - Type of the stored value
      *
-     * **Performance warning:** Avoid frequent `.set()` calls in `useTick` / `usePaint` loops.
-     * Prefer `useSelf` or `useRef` for hot data (position, velocity, timers, counters).
-     * Use `useState` only for infrequent structural changes (e.g. `isDead`, `currentLevel`).
+     * @remarks
+     * **Performance critical warning**
+     * Frequent `.set()` calls inside `useTick` / `usePaint` loops will cause expensive
+     * component re-execution (refresh).
+     * → Use `useSelf` or `useRef` for position, velocity, timers, counters, etc.
+     * → Reserve `useState` for infrequent **structural** changes (health → 0, level up, isDead, etc.).
      *
-     * @template T - Type of the stored value
+     * @see {@link useState}
+     * @see {@link useSelf} – recommended for most game loop data
      */
     class KaylaInternalState<T> {
         #private;
@@ -328,6 +408,7 @@ declare namespace KaylaInternals {
         constructor(current: KaylaFiber<any>, initialValue?: T, { alwaysRecall }?: {
             alwaysRecall?: boolean;
         });
+        /** Get the current value */
         get(this: KaylaState<T>): T;
         [Symbol.iterator](): Iterator<never>;
         refreshBased(): readonly [(s: T, args_1?: {
@@ -424,7 +505,7 @@ declare namespace KaylaInternals {
         set current(s: T);
     }
     function createReassignableRef<T>(initial: T): KaylaRef<T>;
-    interface KaylaFiberControl {
+    interface KaylaFiberControlIm {
         /**
          * Current number of direct child fibers (readonly).
          * Reflects the length of `lastChildren` after the last reconciliation.
@@ -459,17 +540,46 @@ declare namespace KaylaInternals {
          * @returns {number} The limit (Infinity if no limit set)
          */
         getMaxChildren(): number;
+        /**
+         * Returns the key of the fiber.
+         */
+        get key(): string;
+        /**
+         * Returns an array of direct child entities.
+         * @returns Child entities
+         * @note Data may be stale; call fresh to ensure up-to-date results
+         */
+        getChildrenEntities(): KaylaRectEntity[];
+        /**
+         * Returns an array of ancestor entities, from closest to root.
+         * @returns Ancestor entities
+         */
+        getEntityChain(): KaylaRectEntity[];
+        /**
+         * Returns an array of ancestor fibers, from closest to root.
+         * @returns Ancestor fibers
+         */
+        getFiberChain(): UnsafeKaylaFiber[];
     }
-    class KaylaFiber<Props extends FCProps = {}, Exports extends FCExports = FCExports> implements KaylaFiberControl {
+    class KaylaFiber<Props extends FCProps = {}, Exports extends FCExports = FCExports> implements KaylaFiberControlIm {
         state: KaylaState<any>[];
         refs: KaylaRef<unknown>[];
         global: GlobalKayla;
         callProps: Props;
         scene: KaylaScene;
         exports: KaylaExports<Exports>;
+        detectedParent?: KaylaFiber<any, any>;
+        contextInfo?: {
+            instance: KaylaContext<any>;
+            value: unknown;
+        };
         get childrenCount(): number;
         maxSafeChildren: number;
         constructor(globalKayla: GlobalKayla, scene: KaylaScene, element: KaylaElement<Props>);
+        getChildrenEntities(): KaylaRectEntity[];
+        pointerHook(pos: Vector2, type: KaylaClickType): void;
+        bindEvents(): void;
+        unbindEvents(): void;
         get key(): string;
         set key(s: string);
         get children(): KaylaElement<any>[];
@@ -477,6 +587,7 @@ declare namespace KaylaInternals {
         entity?: KaylaRectEntity;
         onExport: () => KaylaExports<Exports>;
         onEffect: Array<() => (() => void) | void>;
+        onGlobalClick: Array<(pos: Vector2, type: KaylaClickType) => void | void>;
         onInit: () => (() => void) | void;
         onUnInit: () => (() => void) | void;
         onUnEffect: Array<() => void>;
@@ -486,6 +597,7 @@ declare namespace KaylaInternals {
         fc?: FC<any>;
         useStateCallIndex: number;
         useEffectCallIndex: number;
+        useGlobalClickCallIndex: number;
         useDrawCallIndex: number;
         useStepCallIndex: number;
         useRefCallIndex: number;
@@ -495,8 +607,14 @@ declare namespace KaylaInternals {
         }>;
         watchedDeps?: KaylaState<any>[];
         lastDepStamps: number[];
+        getAttachedRenderer(): KaylaRenderer;
+        getAttachedGame(): KaylaGame;
         setMaxChildren(max: number): void;
         getMaxChildren(): number;
+        getFiberChain(): UnsafeKaylaFiber[];
+        getContextChain(): KaylaFiber<any, any>["contextInfo"][];
+        findContextValueFromInst(inst: KaylaContext<any>): unknown;
+        getEntityChain(): KaylaRectEntity[];
         shouldFullRefresh(): boolean;
         captureDepStamps(): void;
         refresh(): void;
@@ -511,7 +629,7 @@ declare namespace KaylaInternals {
      * Wraps a {@link LEA.RectLeaEntity} and delegates `update()` and `draw()` to the
      * component's `useTick` / `usePaint` hooks.
      *
-     * Users should almost never interact with this class directly — use {@link KaylaRect}
+     * Users should almost never interact with this class directly — use {@link KaylaInternalRect}
      * or {@link useEntity()} / {@link useRef(self)} instead.
      *
      * @extends LEA.RectLeaEntity
@@ -519,9 +637,16 @@ declare namespace KaylaInternals {
      */
     class KaylaRectEntity extends RectLeaEntity {
         #private;
+        flags: Map<string, unknown>;
+        getRawRect(): KaylaRect.RawKaylaRect;
+        getFiber(): KaylaFiber<{}, Record<string, KaylaExportables>>;
         constructor(component: KaylaFiber, name: string);
+        setFlag(key: string, value: unknown): Map<string, unknown>;
+        getFlag(key: string): unknown;
+        removeFlag(key: string): boolean;
         update(_delta: number): void;
         draw(ctx: CanvasRenderingContext2D): void;
+        getRect(): KaylaInternalRect;
     }
     /**
      * A convenient facade for the rectangle entity associated with the current Kayla component.
@@ -550,9 +675,10 @@ declare namespace KaylaInternals {
      * rect.y += 5;
      * ```
      */
-    class KaylaRect {
+    class KaylaInternalRect {
         #private;
         constructor(fiber: KaylaFiber<any, any>);
+        getRaw(): KaylaRect.RawKaylaRect;
         private get entity();
         /**
          * Checks whether this rectangle is currently colliding (overlapping or touching) with another rectangle.
@@ -565,10 +691,10 @@ declare namespace KaylaInternals {
          * - Touching edges **are** considered colliding (inclusive bounds check).
          * - Returns `false` if either entity is missing or not yet mounted.
          *
-         * @param other - The other {@link KaylaRect} to test collision against
+         * @param other - The other {@link KaylaInternalRect} to test collision against
          * @returns `true` if the rectangles overlap or touch, `false` otherwise
          *
-         * @example Basic enemy-player collision in useTick
+         * @example
          * ```ts
          * const playerRect = useRect();
          * const enemyRect = otherEnemy.exportsRef.current?.rect; // assuming exported via useExports
@@ -585,7 +711,11 @@ declare namespace KaylaInternals {
          *
          * @see {@link LEA.RectLeaEntity.isCollidingWith} — the underlying LEA implementation
          */
-        isCollidingWith(rect: KaylaRect): boolean;
+        isCollidingWith(rect: KaylaInternalRect): boolean;
+        get setFlag(): (key: string, value: unknown) => Map<string, unknown>;
+        get getFlag(): (key: string) => unknown;
+        get removeFlag(): (key: string) => boolean;
+        isHovered(): boolean;
         /**
          * The position of the rectangle's top-left corner (or center, depending on LEA's origin convention).
          *
@@ -637,21 +767,79 @@ declare namespace KaylaInternals {
          */
         get z(): number;
         set z(s: number);
+        /**
+         * Left edge of the rectangle from `pos.x` and `width`.
+         * Writing to this property immediately updates the used properties.
+         *
+         * @type {number}
+         */
+        get left(): number;
+        set left(s: number);
+        /**
+         * Right edge of the rectangle from `pos.x` and `width`.
+         * Writing to this property immediately updates the used properties.
+         *
+         * @type {number}
+         */
+        get right(): number;
+        set right(s: number);
+        /**
+         * Top edge (flipped Y) of the rectangle from `pos.y` and `height`.
+         * Writing to this property immediately updates the used properties.
+         *
+         * @type {number}
+         */
+        get top(): number;
+        set top(s: number);
+        /**
+         * Top edge (flipped Y) of the rectangle from `pos.y` and `height`.
+         * Writing to this property immediately updates the used properties.
+         *
+         * @type {number}
+         */
+        get bottom(): number;
+        set bottom(s: number);
+        /**
+         * Converts a world position to local space relative to this entity.
+         *
+         * @param worldVec - World position
+         * @returns Local position
+         */
+        get toLocal(): (worldVec: Vector2) => Vector2;
+        /**
+         * Converts a local position to world space.
+         *
+         * @param localVec - Local position
+         * @returns World position
+         */
+        get toWorld(): (localVec: Vector2) => Vector2;
     }
     class KaylaScene {
         #private;
         constructor(scene: LeaSceneII);
+        /**
+         * Exposes all the dangerous fibers.
+         */
+        getFibers(): KaylaFiber<{}, Record<string, KaylaExportables>>[];
+        /**
+         * Exposes all the entities dangerously.
+         */
+        getEntities(): KaylaRectEntity[];
         /**
          * Returns the underlying LEA scene instance.
          */
         getScene(): LeaSceneII;
+        /**
+         * Exposes the game object.
+         */
+        getGame(): KaylaGame;
         private drawHandler;
         /**
          * Attaches this scene to a game instance.
          *
          * @param game - The game to attach to
          */
-        attachTo(game: LeaGameII): void;
+        attachTo(game: KaylaGame): void;
         /**
          * Mounts a root component tree into the scene.
          *
@@ -659,7 +847,8 @@ declare namespace KaylaInternals {
          *
          * @param elem - Root Kayla element (usually JSX)
          */
-        spawn(elem: KaylaElement<any>): void;
+        spawn(elem: KaylaElement<any>): Promise<void>;
+        private createFiber;
         /**
          * Detaches this scene from its game (if attached).
          */
@@ -668,83 +857,131 @@ declare namespace KaylaInternals {
     }
     const singleGlobalInstance: GlobalKayla;
 }
+declare namespace KaylaContext {
+    interface ProviderProps<Context> extends FCProps {
+        value?: Context;
+    }
+    interface ProviderExports<Context> extends FCExports {
+        value: Context;
+    }
+}
+declare class KaylaContext<Context> {
+    #private;
+    constructor(defaultValue: Context);
+    get defaultValue(): Context;
+    Provider: FC<KaylaContext.ProviderProps<Context>, KaylaContext.ProviderExports<Context>>;
+    Consumer: never;
+}
+/**
+ * Creates a context object for sharing values across the component tree without manual prop drilling.
+ *
+ * **Unlike React, the Provider is a regular functional component** — use it like any other Kayla component.
+ * The context value is provided via the `value` prop on `<Provider>`.
+ *
+ * **This is not a hook** — call it at the top level of your module (outside components).
+ *
+ * @template T Type of the context value
+ * @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
+ * // settings.ts
+ * export const GameSettingsContext = createContext({
+ *   difficulty: "normal",
+ *   soundVolume: 0.7,
+ *   showParticles: true
+ * });
+ *
+ * // Root or layout component
+ * <GameSettingsContext.Provider value={{ difficulty: currentMode, soundVolume: 0.5, showParticles: false }}>
+ *   <HUD />
+ *   <GameWorld />
+ * </GameSettingsContext.Provider>
+ *
+ * // Deep child component
+ * const settings = useContext(GameSettingsContext);
+ *
+ * usePaint(ctx => {
+ *   if (settings.showParticles) {
+ *     // draw fancy effects
+ *   }
+ * });
+ *
+ * @see {@link useContext} — to consume the context value in any descendant
+ */
+declare function createContext<T>(defaultValue: T | null): KaylaContext<T>;
+type KaylaClickType = "left" | "right" | "middle" | "invalid";
 /**
- * Returns a stateful value and a setter to update it.
+ * Returns a stateful value wrapper with `.get()`, `.set()`, `.add()` (for numbers), etc.
  *
  * **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.
  *
- * Calling the setter **may** schedule an entity refresh (re-execution of the component function),
- * which re-binds all hooks to the same entity instance and potentially re-spawns children.
- *
  * **Critical performance warning:**
- * **Do NOT** use `useState` for frequently-updated game data (position, velocity, rotation, timers, health deltas, etc.).
- * Those **must** live in `useSelf` or plain `useRef`.
- * `useState` is **only** for infrequent structural changes that should trigger refresh
- * (e.g. `isDead` → spawn particles, `currentLevel` → reload map, `variant` → change sprite sheet).
- *
- * @template T The type of the state value
- * @param initialValue Optional initial value
- * @param options Configuration object
- * @param options.alwaysRecall If `true`, **every** `.set()` call triggers a refresh (default: `false`)
- * @returns A state wrapper with `.get()`, `.set()`, `.add()`, `.multiply()`, and `.lastChanged`
- *
- * @example Correct structural use
- * const isDead = useState(false);
- * if (health <= 0) isDead.set(true); // → refresh spawns death animation children
- *
- * @example Incorrect hot-data use (do NOT do this)
- * const pos = useState({ x: 400, y: 300 }); // BAD — thrashing + GC pressure
+ * Frequent `.set()` calls (especially inside `useTick`/`usePaint`) cause full component refresh → expensive re-execution,
+ * hook re-binding, child reconciliation. **Do NOT** use `useState` for position, velocity, timers, counters, health deltas, etc.
+ * → Use `useSelf` or `useRef` for hot loop data.
+ * → Reserve `useState` for infrequent **structural** changes (isDead, levelUp, gameOver, variant change → spawn different children).
+ *
+ * @template T Type of the stored value
+ * @param initialValue Optional starting value
+ * @param options Configuration
+ * @param options.alwaysRecall If `true`, **every** `.set()` triggers refresh (default: `false`)
+ * @returns Read-only state handle with `.get()`, `.set(newValue, {recall?})`, `.add(delta, {recall?})`, `.lastChanged`
+ *
+ * @example
+ * const isGameOver = useState(false);
+ * if (player.health <= 0) isGameOver.set(true); // → refresh → show game over screen children
+ *
+ * @example
+ * const x = useState(400);           // BAD — massive overhead
+ * x.set(x.get() + speed * dt);      // thrashing + GC pressure
  */
 declare const useState: <T>(initialValue?: T, { alwaysRecall }?: {
     alwaysRecall?: boolean;
 }) => KaylaState<T>;
 /**
- * Returns a mutable ref object whose `.current` property persists across entity refreshes.
+ * Creates a mutable reference that **persists across refreshes** and **never causes refresh** when `.current` is changed.
  *
  * **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**; reordering calls will corrupt internal ref storage.
- *
- * Changes to `.current` **never** trigger refresh or re-bind hooks — refs are stable for the entity's lifetime.
- *
- * **Primary use:** Hold mutable game state, methods, timers, audio nodes, previous values, etc.
- * For most entities, wrap your full logic in `useSelf()` instead (strongly recommended pattern).
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * Special case: pass the `self` symbol to get the current LEA entity:
+ * Ideal for: mutable game data (position, velocity, timers, audio nodes, DOM refs, previous values), methods, etc.
+ * Special usage: pass the {@link self} symbol to get a stable reference to the current entity's {@link KaylaRectEntity}.
  *
- * @template T The type of the ref's value
- * @param initialValue Initial value for `.current`, or `self` symbol for entity reference
- * @returns A ref object with mutable `.current` property
+ * @template T Type of value stored in `.current`
+ * @param initialValue Starting value — or {@link self} to receive the entity
+ * @returns Mutable ref object — changes to `.current` have **zero** render cost
  *
- * @example Entity reference
+ * @example
  * const entity = useRef(self);
- * entity.current.x += 10; // direct entity mutation, no refresh
+ * entity.current.pos.x += 120 * dt;     // direct mutation — no refresh
  *
- * @example Mutable counter
- * const timer = useRef(0);
- * useTick(delta => { timer.current += delta; });
+ * @example
+ * const elapsed = useRef(0);
+ * useTick(dt => { elapsed.current += dt; });
  */
 declare const useRef: {
     (initialValue: typeof selfSym): KaylaElementRef;
     <T>(initialValue: T | null): KaylaRef<T>;
 };
 /**
- * Opt-in: only refresh this component when one of the listed states changes.
+ * Opt-in: skip full refresh unless one of the listed states has changed since last refresh.
+ *
+ * **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.
  *
- * Call this **once** at the top level of your component (after all useState calls
- * you want to watch).
+ * Call **once**, after all relevant `useState` hooks.
+ * If none of the watched states changed → skips re-running component body, hooks, children.
  *
- * If none of the watched states change since last refresh → skip re-running
- * the component body, hook re-binding, child reconciliation, etc.
+ * @param deps Array of `useState` handles to watch
  *
  * @example
- * const health   = useState(100);
- * const level    = useState(1);
- * const isPaused = useState(false);
- *
- * useShouldRefresh([health, level, isPaused]);
+ * const health = useState(100);
+ * const level = useState(1);
+ * useShouldRefresh([health, level]);
  *
- * // Now the component only re-runs when one of those actually changes
+ * // now only refreshes when health or level actually changes
  */
 declare const useShouldRefresh: (deps: KaylaState<any>[]) => void;
 /**
@@ -768,255 +1005,480 @@ declare const useShouldRefresh: (deps: KaylaState<any>[]) => void;
  */
 declare const useEffect: (onEffect: KaylaInternals.KaylaFiber["onEffect"][number]) => void;
 /**
- * Runs the provided callback **exactly once** when the entity is first created/mounted.
+ * Registers a callback that runs on **every click anywhere** in any attached renderer.
  *
- * Unlike `useEffect`, this hook **never re-runs** on subsequent refreshes — even if structural state changes.
- * Ideal for true one-time initialization that should survive refreshes:
- * - Creating physics bodies / collision shapes
- * - Setting up audio contexts / WebGL resources
- * - Attaching global event listeners (pointer lock, resize observers)
- * - One-time asset preloading or data fetching
+ * **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.
  *
- * If the callback returns a cleanup function, it will be called **only when the entity is finally destroyed** (unuse).
+ * Useful for global input (pause menu toggle, debug shortcuts, drag anywhere…).
+ * Multiple `useGlobalClick` calls **stack** and run in declaration order.
  *
- * **This hook MUST be called at the top level of a component function.**
+ * @param callback Global click handler — receives world position and click type
  *
- * @param init - Callback that runs once on first mount. May return a cleanup function.
  * @example
- * useInitialization(() => {
- *   const audioCtx = new AudioContext();
- *   // one-time setup
+ * useGlobalClick((pos, type) => {
+ *   if (type === "right") {
+ *     isPaused.set(!isPaused.get());
+ *   }
+ * });
+ */
+declare const useGlobalClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick"][number]) => void;
+/**
+ * Registers a callback that runs **whenever the entity is clicked** (inside its bounds).
  *
- *   return () => {
- *     audioCtx.close(); // cleanup only on destroy
- *   };
+ * **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 `useClick` calls **stack** and run in declaration order.
+ *
+ * @param callback Click handler — receives world position and click type ("left" | "right" | "middle")
+ *
+ * @example
+ * useClick((pos, type) => {
+ *   if (type === "left") {
+ *     score.add(1);
+ *     playSound("collect");
+ *     // optional: spawn particle children on click
+ *   }
+ * });
+ *
+ * @see {@link useGlobalClick} — for clicks anywhere (not bound to this entity)
+ */
+declare const useClick: (onClick: KaylaInternals.KaylaFiber["onGlobalClick"][number]) => void;
+/**
+ * Runs a one-time initialization function **exactly once** when the entity is first mounted.
+ *
+ * Unlike `useEffect`, this **never re-runs** on refreshes — perfect for true setup that should survive structural changes.
+ *
+ * **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.
+ *
+ * If the callback returns a function, it is called **only on final entity destruction**.
+ *
+ * @param init One-time setup function — may return cleanup
+ *
+ * @example
+ * useInitialization(() => {
+ *   const body = physicsEngine.createBody({ ... });
+ *   return () => physicsEngine.destroyBody(body); // cleanup only on unmount
  * });
  */
 declare const useInitialization: (init: KaylaInternals.KaylaFiber["onInit"]) => void;
 /**
- * Returns a stable facade object giving convenient mutable access to the
- * current component's underlying rectangle entity properties.
+ * Returns a convenient, mutable facade for the current entity's rectangle properties.
  *
  * **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**; reordering calls will corrupt ref storage.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * The returned object is created only once per entity lifetime and always
- * points to the current {@link KaylaRectEntity}.
+ * Provides direct getters/setters for `x`, `y`, `width`, `height`, `z`, `pos` (live Vector2), `left`/`right`/`top`/`bottom`, plus helpers like `.isCollidingWith()` and `.isHovered()`.
  *
- * Prefer this over `useEntity()` when you just need position & size.
+ * **Recommended over `useEntity()` for most cases** — cleaner API, same performance, better discoverability.
  *
- * @returns {KaylaRect} Facade with `.pos`, `.x`, `.y`, `.width`, `.height`, `.z`, etc.
+ * @returns {KaylaRect} Mutable rect facade (changes never trigger refresh)
  *
  * @example
  * const rect = useRect();
+ *
  * useTick(dt => {
- *   rect.pos.x += 180 * dt;      // direct Vector2 mutation
- *   rect.y += Math.sin(rect.x * 0.01) * 60 * dt;   // alias usage
+ *   rect.x += 180 * dt;                    // alias setter
+ *   rect.pos.y = 300 + Math.sin(Date.now() * 0.001) * 80; // live Vector2
+ *   rect.z = Math.floor(rect.x / 100);     // sort by horizontal position
  * });
+ *
+ * useTick(() => {
+ *   if (rect.isHovered()) {
+ *     rect.width = 80; // visual feedback
+ *   }
+ * });
+ *
+ * @see {@link useEntity} — when you need the raw LEA entity methods/properties
  */
-declare const useRect: () => KaylaInternals.KaylaRect;
+declare const useRect: () => KaylaRect;
 /**
- * Registers a callback that runs on every game tick (update phase).
+ * Registers a function that runs on **every game tick** (update phase).
  *
  * **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**; reordering calls will corrupt tick registration.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * Multiple `useTick` calls **stack** — all run in declaration order every tick.
- * Call `event.preventDefault()` to skip remaining tick handlers for this entity (including default update).
+ * Multiple `useTick` calls **stack** and run in declaration order.
+ * Call `event.preventDefault()` to skip remaining tick handlers (including default entity update).
  *
- * **Use for:** physics, movement, AI, timers, collision checks, input polling.
+ * @param callback Update handler — receives delta time (seconds) and cancellable event
  *
- * @param callback Tick handler receiving delta time (seconds) and cancellable event
+ * @example Movement + simple boundary check
+ * useTick((dt, event) => {
+ *   rect.pos.x += 200 * dt;
+ *   if (rect.right > 800) {
+ *     rect.pos.x = 800 - rect.width;
+ *     event.preventDefault(); // skip default update if desired
+ *   }
+ * });
  */
 declare const useTick: (onTick: KaylaInternals.KaylaFiber["onTick"][number]) => void;
 /**
- * Registers a callback that runs on every render frame (paint phase).
+ * Registers a function that runs on **every render frame** (paint phase).
  *
  * **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**; reordering calls will corrupt paint registration.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * Multiple `usePaint` calls **stack** — all run in declaration order every frame.
- * Call `event.preventDefault()` to skip remaining paint handlers (including default rect fill).
+ * Multiple `usePaint` calls **stack** and run in declaration order.
+ * Call `event.preventDefault()` to skip remaining paint calls (including default rect fill).
  *
- * **Use for:** drawing sprites, particles, health bars, debug overlays, name tags.
+ * @param callback Paint handler — receives CanvasRenderingContext2D and cancellable event
  *
- * @param callback Paint handler receiving canvas context and cancellable event
+ * @example
+ * usePaint((ctx) => {
+ *   ctx.save();
+ *   ctx.translate(rect.x, rect.y);
+ *   ctx.fillStyle = "rgba(255,0,0,0.3)";
+ *   ctx.fillRect(-rect.width/2, -rect.height/2, rect.width, rect.height);
+ *   ctx.restore();
+ * });
  */
 declare const usePaint: (onPaint: KaylaInternals.KaylaFiber["onPaint"][number]) => void;
 /**
- * Defines the public API this entity exposes to its parent via the `exportsRef` prop.
+ * Exposes a public API (methods, getters, state handles…) to parent components via `exportsRef`.
  *
  * **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**; only **one** `useExports` call is allowed per component (later calls override earlier ones).
- *
- * The exporter function runs during every refresh; the returned object is assigned to `this.exports`.
- * Parent receives it via `exportsRef.current` (stable reference).
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * **Use for:** exposing methods (jump, takeDamage), getters (position, health), or state handles to parent.
+ * Only **one** `useExports` per component — later calls override earlier ones.
+ * The exporter function runs on every refresh.
  *
- * @template T The functional component type (used for type inference)
- * @param component The component function itself (required for TypeScript inference)
- * @param exporter Function returning the exportable values/methods
+ * @param component The component function itself (for TS inference)
+ * @param exporter Returns object of exportable values/methods
  *
  * @example
  * useExports(Player, () => ({
- *   jump: () => { ...  },
- *   getPosition: () => entity.current.pos.clone()
+ *   takeDamage: (amount: number) => { health -= amount; },
+ *   getHealth: () => health,
+ *   rect: useRect()   // or exportsRef.current?.rect
  * }));
+ *
+ * // Parent usage
+ * <Player exportsRef={enemyRef} />
+ * enemyRef.current?.takeDamage(25);
  */
 declare const useExports: <T extends FC<any, any>>(_fc: T, onExport: KaylaInternals.KaylaFiber<PropOfFC<T>, ExportsOfFC<T>>["onExport"]) => void;
 /**
- * Creates and returns a stable object (god-object) for holding most of an entity's state and logic.
+ * Creates a stable "god object" that holds most of an entity's mutable state and logic.
+ * The initializer runs **only once** — returned object is the **same reference** forever.
  *
  * **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**; reordering calls will corrupt ref storage.
- *
- * The initializer runs **only once** (on first entity creation); the returned object is the **same reference** on every refresh.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * **Recommended pattern:** Put nearly all mutable state, methods, and game logic here.
- * Use `useState` **only** for rare structural changes that should trigger refresh.
+ * **Recommended 2025–2026 pattern:** Put almost everything here (position, velocity, health, AI state, methods…).
+ * Use `useState` **only** for rare structural triggers.
  *
- * @template T The type of the god-object
- * @param init Factory function returning the object (called only once)
- * @returns The initialized god-object (stable across refreshes)
+ * @template T Type of your state/logic object
+ * @param init Factory called once — returns your stateful object
+ * @returns The same object instance on every render
  *
  * @example
  * const self = useSelf(() => ({
- *   pos: new Vector2(400, 300),
- *   vel: new Vector2(100, 0),
- *   tick(delta) { this.pos.x += this.vel.x * delta; }
+ *   pos: new LEA.Vector2(400, 300),
+ *   vel: new LEA.Vector2(180, 0),
+ *   health: 100,
+ *   hurt(dmg: number) {
+ *     this.health -= dmg;
+ *     if (this.health <= 0) {
+ *       // structural change → useState trigger
+ *       isDead.set(true);
+ *     }
+ *   }
  * }));
  *
- * useTick(delta => self.tick(delta));
+ * useTick(dt => {
+ *   self.pos.add(self.vel.clone().scale(dt));
+ * });
  */
 declare const useSelf: <T>(init: () => T) => T;
 /**
+ * Provides safe, controlled access to fiber-level operations and metadata.
+ *
+ * **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.
+ *
+ * Returned object is stable across refreshes.
+ * Use this instead of `useFiber()` when you need fiber introspection or manual control.
+ *
+ * @returns {KaylaFiberControl} Safe fiber control surface
+ *
+ * @example
+ * const control = useFiberControl();
+ * if (control.childrenCount > 120) {
+ *   control.setMaxChildren(100); // soft-enforces limit + logs warning
+ * }
+ *
+ * // Rare manual refresh (prefer useShouldRefresh + declarative patterns)
+ * if (someExternalCondition) control.refresh();
+ */
+declare const useFiberControl: () => KaylaFiberControl;
+/**
+ * **UNSAFE** — direct access to the internal `KaylaFiber` instance.
+ *
  * **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**; reordering calls will corrupt ref storage.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * Returns a safe control surface for the current fiber instance.
+ * **Avoid unless you have a very specific low-level need** (advanced debugging, custom reconciler experiments…).
+ * Prefer {@link useFiberControl} for almost everything.
  *
- * Provides limited, controlled access to fiber-level operations:
- * - Manually trigger a refresh
- * - Read the current number of direct children
- * - Set a safety limit on maximum allowed direct children (soft enforcement)
+ * @returns Current fiber (do **not** cache — may become stale)
+ */
+declare const useFiber: () => UnsafeKaylaFiber;
+/**
+ * Returns a stable ref to the underlying raw {@link KaylaRectEntity} (LEA entity).
  *
- * **This is the recommended way** to interact with fiber internals when needed.
- * Avoid using `useFiber()` (unsafe) unless you have a very specific reason.
+ * **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.
+ *
+ * Use when you need direct access to LEA-specific features not exposed on {@link KaylaRect} (custom flags, advanced transforms…).
  *
- * The returned object is stable across refreshes.
+ * **Most of the time prefer {@link useRect}** — it wraps the same entity with a nicer, game-oriented API.
  *
- * @returns {KaylaFiberControl}
+ * @returns Stable ref to the entity instance
  *
  * @example
- * const control = useFiberControl();
+ * const entityRef = useEntity();
+ * entityRef.current.setFlag("invincible", true);
  *
- * // Force refresh (rarely needed — prefer declarative + useShouldRefresh)
- * control.refresh();
+ * useTick(() => {
+ *   if (entityRef.current.getFlag("invincible")) {
+ *     // skip damage logic
+ *   }
+ * });
  *
- * // Monitor child count
- * if (control.childrenCount > 100) {
- *   console.warn("Too many children");
- *   control.setMaxChildren(80);
- * }
+ * @see {@link useRef}(`self`) — alternative way to get the same entity ref
+ * @see {@link useRect} — usually the better daily driver
  */
-declare const useFiberControl: () => KaylaInternals.KaylaFiberControl;
+declare const useEntity: () => KaylaElementRef;
 /**
- * **UNSAFE** — Returns direct access to the current `KaylaFiber` instance.
+ * Returns the current game instance this entity belongs to.
  *
  * **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**; reordering calls will corrupt ref storage.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
+ *
+ * Useful for accessing global timing, adding renderers/scenes dynamically, etc.
+ *
+ * @returns {KaylaGame} The game coordinator
  *
- * **Use with extreme caution** — this exposes internal implementation details.
- * Most use-cases should use `useFiberControl()` instead.
+ * @example
+ * const game = useCurrentGame();
+ * game.delay(3000).then(() => {
+ *   spawnNextLevel();
+ * });
+ */
+declare const useCurrentGame: () => KaylaInternals.KaylaGame;
+/**
+ * Returns the main (usually first) renderer attached to the current game.
+ *
+ * **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.
  *
- * Intended only for advanced debugging, testing, or very specific low-level needs.
+ * Handy for pointer → world coordinate conversion or canvas measurements.
  *
- * @returns {UnsafeKaylaFiber} The current fiber (may change on refresh — do not cache!)
+ * @returns Primary {@link KaylaRenderer}
  *
- * @see {@link useFiberControl} for the safe alternative
+ * @example
+ * const renderer = useCurrentRenderer();
+ * useTick(() => {
+ *   const mouseWorld = renderer.getMousePos();
+ *   rect.pos.copy(mouseWorld);
+ * });
  */
-declare const useFiber: () => UnsafeKaylaFiber;
+declare const useCurrentRenderer: () => KaylaInternals.KaylaRenderer;
 /**
+ * Returns the scene this component/entity was spawned into.
+ *
  * **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**; reordering calls will corrupt ref storage.
+ * The call order of all hooks is **strictly fixed** across every refresh; reordering calls will corrupt internal state.
  *
- * Returns a direct reference to the underlying {@link KaylaRectEntity} instance managed by this component.
+ * Useful when you need to interact with the scene directly (e.g. spawn additional root-level entities,
+ * check paused state, access scene-specific data, or manipulate the entity collection).
  *
- * The returned ref is **stable** for the entity's lifetime and allows low-level access to all LEA entity properties
- * (`x`, `y`, `z`, `width`, `height`, `pos`, custom data, etc.).
+ * @returns {KaylaScene} The scene wrapper managing this entity's lifecycle and siblings
  *
- * **Recommended alternative in 2025–2026 style:**
- * → Prefer {@link useRect} for most use-cases — it provides a cleaner, more convenient facade with the same mutability
- *   and **no performance difference**, but better readability and discoverability (`.x`, `.y`, `.pos`, `.width`, `.isCollidingWith(...)`).
+ * @example
+ * const scene = useCurrentScene();
  *
- * Use `useEntity()` only when you need:
- * - Direct access to LEA-specific properties/methods not exposed on {@link KaylaRect}
- * - `.current` typing as `KaylaRectEntity` (more precise than the facade)
- * - Passing the raw entity reference to external systems (physics, pooling, debugging)
+ * useInitialization(() => {
+ *   // Example: spawn a floating damage number when hit
+ *   const showDamage = (amount: number) => {
+ *     scene.spawn(
+ *       <DamagePopup x={rect.x} y={rect.y - 40} value={amount} />
+ *     );
+ *   };
+ *
+ *   // ... later in useExports or event handler
+ *   return { showDamage };
+ * });
+ */
+declare const useCurrentScene: () => KaylaInternals.KaylaScene;
+/**
+ * Returns the shared game ticker — the central update scheduler.
+ *
+ * **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.
  *
- * **This hook MUST be called at the top level of a component function.**
+ * Gives direct access to LEA's ticker for creating precise, game-time-aware timeouts, intervals,
+ * or one-shot scheduled tasks that respect pause / speed modifiers / fixed timestep.
  *
- * @returns {KaylaElementRef} Stable ref to the `KaylaRectEntity` instance
+ * @returns {LEA.LeaTickerII} The game's update ticker instance
  *
  * @example
- * ```ts
- * const entityRef = useEntity();
+ * const ticker = useCurrentTicker();
+ *
+ * useInitialization(() => {
+ *   const timeout = ticker.createTimeout(4500); // 4.5 seconds game time
  *
+ *   timeout.then(() => {
+ *     // cleanup logic or spawn explosion children
+ *     isDead.set(true);
+ *   });
+ *
+ *   return () => timeout.cancel(); // important: prevent memory leak on early destroy
+ * });
+ *
+ * @example
  * useTick(dt => {
- *   entityRef.current.pos.x += 200 * dt;
- *   entityRef.current.z = Math.sin(Date.now() * 0.001) * 10 + 10;
+ *   if (someCondition && !scheduled) {
+ *     ticker.createTimeout(0).then(() => doNextFrameThing());
+ *     scheduled = true;
+ *   }
  * });
- * ```
+ */
+declare const useCurrentTicker: () => LeaTickerII;
+/**
+ * Reads the current value of a Kayla context.
+ *
+ * **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.
  *
- * @see {@link useRect} — usually the better choice (cleaner API, includes collision helper)
- * @see {@link useRef} with `self` symbol — alternative way to get the entity ref
+ * Context lets you share global-ish data (theme, game mode, player reference, audio settings…)
+ * down the tree without passing props through every level.
+ *
+ * Returns the nearest ancestor `<Provider>`'s value — or the default value if no provider is found.
+ *
+ * @param context - The context object created via `createContext(defaultValue)`
+ * @returns The current context value (type-inferred from context)
+ *
+ * @example Using a theme context
+ * const ThemeContext = createContext({
+ *   bg: "#111",
+ *   accent: "#ff3366",
+ *   text: "#eee"
+ * });
+ *
+ * // Deep in UI tree:
+ * const theme = useContext(ThemeContext);
+ *
+ * usePaint(ctx => {
+ *   ctx.fillStyle = theme.bg;
+ *   ctx.fillRect(0, 0, rect.width, rect.height);
+ * });
+ *
+ * // Provider somewhere higher:
+ * <ThemeContext.Provider value={{ bg: "#000", accent: currentThemeColor, text: "#fff" }}>
+ *   <HUD />
+ *   <World />
+ * </ThemeContext.Provider>
+ *
+ * @see {@link createContext} — to create the context object
  */
-declare const useEntity: () => KaylaElementRef;
+declare const useContext: <T>(context: KaylaContext<T>) => T;
 /**
- * Special symbol used to obtain a reference to the current entity.
+ * Special symbol used with `useRef` to get a stable reference to the current entity's underlying LEA `KaylaRectEntity`.
  *
- * Pass this to `useRef` to get the underlying `KaylaRectEntity`:
+ * Pass this symbol directly as the initial value to `useRef(self)` — it is replaced with the actual entity instance once mounted.
  *
- * ```ts
+ * **Do NOT** use this symbol anywhere else — it's only meaningful as the argument to `useRef`.
+ *
+ * @example
  * const entity = useRef(self);
- * entity.current.x += 10;
- * ```
  *
- * @see {@link useRef}
+ * useTick(dt => {
+ *   entity.current.pos.x += 150 * dt;
+ *   entity.current.setFlag("invulnerable", true);
+ * });
+ *
+ * // Later — access raw LEA entity methods
+ * entity.current.getRect(); // or other LEA-specific stuff
+ *
+ * @see {@link useRef} — the hook that accepts this symbol
+ * @see {@link useEntity} — alternative that directly returns the ref (no symbol needed)
+ * @see {@link useRect} — usually more convenient for day-to-day position/size work
  */
 declare const selfSym: unique symbol;
 
 /**
- * Schedules a callback to run in the next microtask (via `Promise.resolve().then`).
- *
- * Used internally to defer entity refreshes safely and prevent synchronous re-entrancy.
- * Rarely needed directly by users.
+ * Schedules a callback to run in the **next microtask** (after the current call stack clears).
+ *
+ * **This is not a hook** — you can call it anywhere inside a component function, including inside `useTick`, `useInitialization`, `useEffect`, etc.
+ *
+ * Most useful when you need to:
+ * - Access `exportsRef.current`, child entities, or sibling fibers **immediately after** mount/refresh
+ * - Work around cases where the fiber tree isn't fully reconciled yet during the current execution
+ *
+ * @param callback Function to run asynchronously in the next microtask
+ *
+ * @example Accessing child exports right after spawn
+ * function Parent() {
+ *   const childrenRef = useRef<KaylaExports<any>[]>([]);
+ *
+ *   useInitialization(() => {
+ *     useNextStack(() => {
+ *       // Now children should be mounted & exports available
+ *       const kids = getChildrenEntities(); // or however you collect them
+ *       childrenRef.current = kids.map(k => k.exportsRef?.current).filter(Boolean);
+ *       console.log("Children ready:", childrenRef.current.length);
+ *     });
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <Child exportsRef={child1Ref} />
+ *       <Child exportsRef={child2Ref} />
+ *     </>
+ *   );
+ * }
  *
- * @param callback - The function to schedule
+ * @example Delaying something until after paint/tick phase
+ * useTick(dt => {
+ *   // ... movement logic ...
+ *   useNextStack(() => {
+ *     // check collisions or post-process after all ticks have run
+ *   });
+ * });
  */
 declare const useNextStack: (callback: () => void) => void;
 /**
- * A fragment component that simply returns its children.
+ * Fragment component — allows returning multiple children without creating an extra wrapper entity/rectangle.
  *
- * Useful for grouping entities without adding an extra wrapper entity.
- * Behaves like React.Fragment — no additional DOM/entity overhead.
+ * Behaves like React.Fragment: zero runtime cost, no additional `KaylaRectEntity` is spawned.
  *
- * @example
- * return (
- *   <KaylaFragment>
- *     <Enemy />
- *     <Coin />
- *   </KaylaFragment>
- * );
- *
- * // Or shorthand:
- * return (
- *   <>
- *     <Enemy />
- *     <Coin />
- *   </>
- * );
+ * **This is a regular functional component** — use it in JSX/TSX just like any other component.
+ *
+ * @example Grouping without extra entity overhead
+ * function Explosion() {
+ *   return (
+ *     <KaylaFragment>
+ *       <Particle x={0} y={0} color="yellow" />
+ *       <Particle x={-20} y={10} color="orange" />
+ *       <Particle x={15} y={-15} color="red" />
+ *     </KaylaFragment>
+ *   );
+ * }
+ *
+ * // Or using JSX fragment shorthand (preferred)
+ * function Explosion() {
+ *   return (
+ *     <>
+ *       <Particle x={0} y={0} color="yellow" />
+ *       <Particle x={-20} y={10} color="orange" />
+ *     </>
+ *   );
+ * }
  */
 declare const KaylaFragment: FC;
 declare namespace JSX {
@@ -1069,7 +1531,7 @@ declare function createReassignableObject<T extends object>(initial: T): Reassig
 declare function setLogLevel(level: KaylaInternals.GlobalKayla["logLevel"]): void;
 interface UnsafeKaylaFiber extends KaylaInternals.KaylaFiber<FCProps, FCExports> {
 }
-interface KaylaFiberControl extends KaylaInternals.KaylaFiberControl {
+interface KaylaFiberControl extends KaylaInternals.KaylaFiberControlIm {
 }
 /**
  * Configuration for a custom Kayla hook created via `createUseHook`.
@@ -1109,7 +1571,7 @@ interface KaylaCustomHookConfig<Return, Params = void> {
  * @param config Configuration with onUse + optional memoize/name
  * @returns A hook function you can call in components, optionally with params
  *
- * @example Basic memoized hook with no params
+ * @example
  * const useMyTimer = createUseHook({
  *   name: "useMyTimer",
  *   onUse: () => {
@@ -1119,7 +1581,7 @@ interface KaylaCustomHookConfig<Return, Params = void> {
  *   }
  * });
  *
- * @example Hook that accepts runtime params
+ * @example
  * const useMoveSpeed = createUseHook<number, { baseSpeed: number }>({
  *   name: "useMoveSpeed",
  *   onUse: (fiber, global, { baseSpeed }) => {
@@ -1139,6 +1601,9 @@ type Kayla_FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExp
 type Kayla_FCExports = FCExports;
 type Kayla_FCProps = FCProps;
 declare const Kayla_JSX: typeof JSX;
+type Kayla_KaylaClickType = KaylaClickType;
+type Kayla_KaylaContext<Context> = KaylaContext<Context>;
+declare const Kayla_KaylaContext: typeof KaylaContext;
 type Kayla_KaylaCustomHookConfig<Return, Params = void> = KaylaCustomHookConfig<Return, Params>;
 type Kayla_KaylaElement<Props extends FCProps> = KaylaElement<Props>;
 type Kayla_KaylaElementRef = KaylaElementRef;
@@ -1148,7 +1613,7 @@ type Kayla_KaylaFiberControl = KaylaFiberControl;
 declare const Kayla_KaylaFragment: typeof KaylaFragment;
 type Kayla_KaylaGame = KaylaGame;
 declare const Kayla_KaylaInternals: typeof KaylaInternals;
-type Kayla_KaylaRect = KaylaRect;
+declare const Kayla_KaylaRect: typeof KaylaRect;
 type Kayla_KaylaRef<T> = KaylaRef<T>;
 type Kayla_KaylaRenderer = KaylaRenderer;
 type Kayla_KaylaScene = KaylaScene;
@@ -1156,6 +1621,7 @@ type Kayla_KaylaState<T> = KaylaState<T>;
 type Kayla_PropOfFC<T extends FC<any, any>> = PropOfFC<T>;
 type Kayla_Reassignable<T extends Record<any, any>> = Reassignable<T>;
 type Kayla_UnsafeKaylaFiber = UnsafeKaylaFiber;
+declare const Kayla_createContext: typeof createContext;
 declare const Kayla_createElement: typeof createElement;
 declare const Kayla_createGame: typeof createGame;
 declare const Kayla_createReassignableObject: typeof createReassignableObject;
@@ -1163,12 +1629,19 @@ declare const Kayla_createRenderer: typeof createRenderer;
 declare const Kayla_createScene: typeof createScene;
 declare const Kayla_createUseHook: typeof createUseHook;
 declare const Kayla_setLogLevel: typeof setLogLevel;
+declare const Kayla_useClick: typeof useClick;
+declare const Kayla_useContext: typeof useContext;
+declare const Kayla_useCurrentGame: typeof useCurrentGame;
+declare const Kayla_useCurrentRenderer: typeof useCurrentRenderer;
+declare const Kayla_useCurrentScene: typeof useCurrentScene;
+declare const Kayla_useCurrentTicker: typeof useCurrentTicker;
 declare const Kayla_useDisposableRef: typeof useDisposableRef;
 declare const Kayla_useEffect: typeof useEffect;
 declare const Kayla_useEntity: typeof useEntity;
 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_useInitialization: typeof useInitialization;
 declare const Kayla_useNextStack: typeof useNextStack;
 declare const Kayla_usePaint: typeof usePaint;
@@ -1179,7 +1652,7 @@ declare const Kayla_useShouldRefresh: typeof useShouldRefresh;
 declare const Kayla_useState: typeof useState;
 declare const Kayla_useTick: typeof useTick;
 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_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_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_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_useDisposableRef as useDisposableRef, Kayla_useEffect as useEffect, Kayla_useEntity as useEntity, Kayla_useExports as useExports, Kayla_useFiber as useFiber, Kayla_useFiberControl as useFiberControl, 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 };
+  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_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, 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 };
 }
 
-export { useEntity as A, useExports as B, useFiber as C, useFiberControl as D, type ExportsOfFC as E, type FCProps as F, useInitialization as G, useNextStack as H, usePaint as I, JSX as J, Kayla as K, useRect as L, useRef as M, useSelf as N, useShouldRefresh as O, type PropOfFC as P, useState as Q, type Reassignable as R, useTick as S, type UnsafeKaylaFiber as U, type FC as a, type FCExports as b, type KaylaCustomHookConfig as c, type KaylaElement as d, type KaylaElementRef as e, type KaylaExportables as f, type KaylaExports as g, type KaylaFiberControl as h, KaylaFragment as i, KaylaGame as j, KaylaInternals as k, KaylaRect as l, type KaylaRef as m, KaylaRenderer as n, KaylaScene as o, type KaylaState as p, createElement as q, createGame as r, createReassignableObject as s, createRenderer as t, createScene as u, createUseHook as v, selfSym as w, setLogLevel as x, useDisposableRef as y, useEffect as z };
+export { useShouldRefresh as $, setLogLevel as A, useClick as B, useContext as C, useCurrentGame as D, type ExportsOfFC as E, type FCProps as F, useCurrentRenderer as G, useCurrentScene as H, useCurrentTicker as I, JSX as J, Kayla as K, useDisposableRef as L, useEffect as M, useEntity as N, useExports as O, type PropOfFC as P, useFiber as Q, type Reassignable as R, useFiberControl as S, useGlobalClick as T, type UnsafeKaylaFiber as U, useInitialization as V, useNextStack as W, usePaint as X, useRect as Y, useRef as Z, useSelf as _, type FCExports as a, useState as a0, useTick as a1, type FC as b, type KaylaClickType as c, KaylaContext as d, type KaylaCustomHookConfig as e, type KaylaElement as f, type KaylaElementRef as g, type KaylaExportables as h, type KaylaExports as i, type KaylaFiberControl as j, KaylaFragment as k, KaylaGame as l, KaylaInternals as m, KaylaRect as n, type KaylaRef as o, KaylaRenderer as p, KaylaScene as q, type KaylaState as r, createContext as s, createElement as t, createGame as u, createReassignableObject as v, createRenderer as w, createScene as x, createUseHook as y, selfSym as z };