@kayelaa/canvas 0.1.1 → 0.1.2

package/dist/kayla-SPtfCppr.d.cts

@@ -0,0 +1,783 @@
+import { a as LeaGameII, b as LeaRendererII, V as Vector2, R as RectLeaEntity, c as LeaSceneII } from './lea-DvxsutSf.cjs';
+
+/**
+ * Base props interface that every Kayla component can receive.
+ *
+ * Extend this when defining custom component props:
+ *
+ * ```ts
+ * interface MyProps extends FCProps {
+ *   speed: number;
+ * }
+ * ```
+ */
+type FCProps = {
+    key?: string;
+    children?: KaylaElement<any>[];
+    ref?: KaylaRef<KaylaInternals.KaylaRectEntity>;
+    exportsRef?: KaylaRef<KaylaExports<any>>;
+} & Record<string, unknown>;
+type FCExports = {} & Record<string, KaylaExportables>;
+interface FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExports> {
+    (props: Props & {
+        ref?: KaylaElementRef;
+        exportsRef?: KaylaRef<KaylaExports<Exports>>;
+    }): KaylaElement<any>[] | KaylaElement<any> | void;
+    displayName?: string | undefined;
+}
+/**
+ * Creates a new game instance that coordinates scenes, renderers, and a shared ticker.
+ *
+ * The game manages the global update loop (via `updateHz`) and allows attaching multiple renderers
+ * and scenes. Start the game with `game.start()` to begin ticking and rendering.
+ *
+ * @param config - Configuration options
+ * @param config.width - Logical viewport width (used for entity coordinates)
+ * @param config.height - Logical viewport height
+ * @param config.updateHz - Tick frequency:
+ *   - `"frames"` = run updates every render frame (RAF-synced, variable timestep)
+ *   - number = fixed timestep in Hz (e.g. 60)
+ * @returns A `KaylaGame` instance
+ *
+ * @example
+ * const game = createGame({ width: 800, height: 600, updateHz: 60 });
+ * game.start();
+ */
+declare function createGame({ width, height, updateHz: hz, }: {
+    width: number;
+    height: number;
+    updateHz?: number | "frames";
+}): KaylaInternals.KaylaGame;
+/**
+ * Creates a scene that manages a collection of entities and their update/draw lifecycle.
+ *
+ * Scenes handle z-sorted drawing, paused state, and entity addition/removal.
+ * Use `scene.spawn()` to mount a root component tree.
+ *
+ * @param name - Unique identifier for the scene
+ * @returns A `KaylaScene` wrapper with `.spawn()` and other methods
+ *
+ * @example
+ * const scene = createScene("main");
+ * scene.spawn(<GameWorld />);
+ */
+declare function createScene(name: string): KaylaInternals.KaylaScene;
+/**
+ * Creates a renderer that drives the canvas draw loop and handles pointer tracking.
+ *
+ * The renderer automatically clears the canvas each frame and emits a `"draw"` event
+ * where scenes can paint. Call `renderer.start()` to begin the RAF loop.
+ *
+ * @param canvas - The target `<canvas>` element
+ * @returns A `KaylaRenderer` instance
+ *
+ * @example
+ * const canvas = document.getElementById("game") as HTMLCanvasElement;
+ * const renderer = createRenderer(canvas);
+ * renderer.start();
+ */
+declare function createRenderer(canvas: HTMLCanvasElement): KaylaRenderer;
+/**
+ * Creates a Kayla element descriptor (virtual representation of an entity/component).
+ *
+ * This is the JSX factory used internally by the transpiler. You rarely call it directly,
+ * but it powers declarative trees passed to `scene.spawn()`.
+ *
+ * @template Props - Props type accepted by the component
+ * @param fc - The functional component
+ * @param props - Props including `key`, `ref`, `exportsRef`, `children`, etc.
+ * @returns Element descriptor
+ *
+ * @example
+ * const elem = createElement(Player, { x: 400, y: 300 });
+ * scene.spawn(elem);
+ */
+declare function createElement<Props extends FCProps>(fc: FC<Props>, props: Props): KaylaElement<Props>;
+interface KaylaElement<Props extends FCProps> {
+    type: FC<Props>;
+    props: Props;
+}
+/**
+ * Read-only view of a state value created via `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.
+ *
+ * **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`).
+ *
+ * @template T - Type of the stored value
+ */
+interface KaylaState<T> extends KaylaInternals.KaylaState<T> {
+}
+/**
+ * Mutable reference object whose `.current` property persists across component refreshes.
+ *
+ * Returned by `useRef` and `useSelf`. Changes to `.current` **never** trigger refresh,
+ * making it safe for hot mutable data (position, velocity, timers, DOM nodes, etc.).
+ *
+ * @template T - Type of the referenced value
+ */
+interface KaylaRef<T> extends KaylaInternals.KaylaRef<T> {
+}
+/**
+ * Game instance that coordinates scenes, renderers, and the shared ticker.
+ *
+ * @extends LeaGameII
+ */
+interface KaylaGame extends KaylaInternals.KaylaGame {
+}
+/**
+ * Scene wrapper that manages entity lifecycle and delegates to the underlying LEA scene.
+ *
+ * @extends LeaSceneII (via internal delegation)
+ */
+interface KaylaScene extends KaylaInternals.KaylaScene {
+}
+/**
+ * Renderer wrapper that extends LEA renderer with game integration and pointer utilities.
+ *
+ * @extends LeaRendererII
+ */
+interface KaylaRenderer extends KaylaInternals.KaylaRenderer {
+}
+/**
+ * Internal APIs, do not use outside.
+ */
+declare namespace KaylaInternals {
+    /**
+     * Game instance that coordinates scenes, renderers, and the shared ticker.
+     *
+     * @extends LeaGameII
+     */
+    class KaylaGame extends LeaGameII {
+        #private;
+        constructor(width: number, height: number, hz: typeof Infinity | number);
+        /**
+         * Whether the game has been started.
+         */
+        get started(): boolean;
+        /**
+         * Starts the game: starts all attached renderers and the ticker.
+         */
+        start(): void;
+        /**
+         * Stops the game: stops all attached renderers and the ticker.
+         */
+        stop(): void;
+        /**
+         * Attaches a renderer to the game.
+         *
+         * If the game is already started, the renderer is started immediately.
+         *
+         * @param renderer - The renderer to attach
+         */
+        addRenderer(renderer: KaylaRenderer): void;
+        /**
+         * Detaches a renderer from the game.
+         *
+         * If the game is running, the renderer is stopped.
+         *
+         * @param renderer - The renderer to detach
+         */
+        deleteRenderer(renderer: KaylaRenderer): void;
+    }
+    /**
+     * Renderer wrapper that extends LEA renderer with game integration and pointer utilities.
+     *
+     * @extends LeaRendererII
+     */
+    class KaylaRenderer extends LeaRendererII {
+        #private;
+        /**
+         * The attached game instance (set via `attachTo`).
+         */
+        game?: KaylaGame;
+        /**
+         * Current canvas-space pointer X coordinate.
+         */
+        pointerX: number;
+        /**
+         * Current canvas-space pointer Y coordinate.
+         */
+        pointerY: number;
+        constructor(canvas: HTMLCanvasElement);
+        listenPointerUpdates(): void;
+        unlistenPointerUpdates(): void;
+        /**
+         * Transforms canvas-space coordinates to world-space coordinates.
+         *
+         * @param mx - Mouse X in canvas pixels
+         * @param my - Mouse Y in canvas pixels
+         * @returns World-space position
+         */
+        pointerPosToWorldPos(mx: number, my: number): Vector2;
+        /**
+         * Returns the current pointer position in world coordinates.
+         *
+         * Requires `listenPointerUpdates()` to have been called.
+         *
+         * @returns World-space position
+         */
+        getMousePos(): Vector2;
+        /**
+         * Registers a draw callback that receives a normalized `KaylaEvent`.
+         *
+         * @param callback - Paint handler
+         * @returns Unsubscribe function
+         */
+        useDraw(callback: KaylaInternalComponent["onPaint"][number]): () => void;
+        /**
+         * Attaches this renderer to a game.
+         *
+         * Sets `renderer.game` and adds it to `game.#renderers`.
+         *
+         * @param game - The game to attach to
+         */
+        attachTo(game: KaylaGame): void;
+        /**
+         * Detaches this renderer from its game (if attached).
+         */
+        detach(): void;
+    }
+    class GlobalKayla {
+        current?: KaylaInternalComponent;
+        saves: {
+            current?: GlobalKayla["current"];
+        }[];
+        constructor();
+        useTick(onTick: KaylaInternalComponent["onTick"][number]): void;
+        usePaint(onPaint: KaylaInternalComponent["onPaint"][number]): void;
+        useEntity(): KaylaElementRef;
+        useSelf<T>(init: () => T): T;
+        useState<T>(initialValue?: T, { alwaysRecall }?: {
+            alwaysRecall?: boolean;
+        }): KaylaState<T>;
+        useRef(initialValue: typeof selfSym): KaylaElementRef;
+        useRef<T>(initialValue: T | null): KaylaRef<T>;
+        useEffect(onEffect: KaylaInternalComponent["onEffect"][number]): void;
+        useExports<T extends FC<any, any>>(fc: T, onExport: KaylaInternalComponent<PropOfFC<T>, ExportsOfFC<T>>["onExport"]): void;
+        save(): void;
+        restore(): void;
+    }
+    class KaylaEvent {
+        #private;
+        preventDefault(): void;
+        isPrevented(): boolean;
+    }
+    /**
+     * Read-only view of a state value created via `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.
+     *
+     * **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`).
+     *
+     * @template T - Type of the stored value
+     */
+    class KaylaState<T> {
+        #private;
+        alwaysRecall: boolean;
+        constructor(current: KaylaInternalComponent<any>, initialValue?: T, { alwaysRecall }?: {
+            alwaysRecall?: boolean;
+        });
+        get(this: KaylaState<T>): T;
+        /**
+         * Adds a number to the current value (only available when `T` is `number`).
+         *
+         * Convenience method that calls `.set(get() + added)`.
+         * Behaves exactly like `.set()` regarding refresh overhead.
+         *
+         * @param added - Value to add
+         * @param options - Optional control over refresh
+         * @param options.recall - Force refresh (default: false)
+         */
+        add(this: KaylaState<number>, added: number, { recall }?: {
+            recall?: boolean;
+        }): void;
+        /**
+         * Multiplies the current value by a number (only available when `T` is `number`).
+         *
+         * Convenience method that calls `.set(get() * multiplier)`.
+         * Behaves exactly like `.set()` regarding refresh overhead.
+         *
+         * @param multiplier - Value to multiply by
+         * @param options - Optional control over refresh
+         * @param options.recall - Force refresh (default: false)
+         */
+        multiply(this: KaylaState<number>, added: number, { recall }?: {
+            recall?: boolean;
+        }): void;
+        /**
+         * Updates the state value.
+         *
+         * If the new value differs from the current one (strict `!==` comparison),
+         * and either `recall: true` is passed or `alwaysRecall` was set at creation,
+         * this triggers a component refresh.
+         *
+         * Refreshing re-runs the entire component function, re-binds hooks,
+         * and may re-mount/unmount children — avoid in hot paths.
+         *
+         * @param newValue - The new state value
+         * @param options - Optional control over refresh behavior
+         * @param options.recall - Force a refresh even if `alwaysRecall` is false (default: false)
+         */
+        set(this: KaylaState<T>, s: T, { recall }?: {
+            recall?: boolean;
+        }): void;
+        /**
+         * The current value of the state.
+         *
+         * Reading this property is always safe and does not trigger side effects.
+         *
+         * @readonly
+         */
+        get value(): T;
+        /**
+         * Timestamp (milliseconds since epoch) of the last time the state was changed via `.set()`.
+         *
+         * Useful for dependency tracking or knowing when the value was last mutated.
+         *
+         * @readonly
+         */
+        get lastChanged(): number;
+    }
+    /**
+     * Mutable reference object whose `.current` property persists across component refreshes.
+     *
+     * Returned by `useRef` and `useSelf`. Changes to `.current` **never** trigger refresh,
+     * making it safe for hot mutable data (position, velocity, timers, DOM nodes, etc.).
+     *
+     * @template T - Type of the referenced value
+     */
+    class KaylaRef<T> {
+        #private;
+        constructor(current: KaylaInternalComponent<any>, initialValue?: T);
+        /**
+         * The mutable value held by the ref.
+         *
+         * Reading or writing this property has **no side effects** — it does **not** trigger
+         * component refresh, re-render, or hook re-registration.
+         *
+         * When initialized with the `self` symbol via `useRef(self)`, this becomes a reference
+         * to the underlying `KaylaRectEntity`.
+         *
+         * @type {T}
+         */
+        get current(): T;
+        set current(s: T);
+    }
+    class KaylaInternalComponent<Props extends FCProps = {}, Exports extends FCExports = FCExports> {
+        state: KaylaState<unknown>[];
+        refs: KaylaRef<unknown>[];
+        global: GlobalKayla;
+        callProps: Props;
+        scene: KaylaScene;
+        exports: KaylaExports<Exports>;
+        constructor(globalKayla: GlobalKayla, scene: KaylaScene, element: KaylaElement<Props>);
+        get key(): string;
+        set key(s: string);
+        get children(): KaylaElement<any>[];
+        set children(s: KaylaElement<any>[]);
+        entity?: KaylaRectEntity;
+        onExport: () => KaylaExports<Exports>;
+        onEffect: Array<() => (() => void) | void>;
+        onUnEffect: Array<() => void>;
+        onEffectDeps?: KaylaState<any>[] | undefined;
+        onPaint: Array<(ctx: CanvasRenderingContext2D, event: KaylaEvent) => void>;
+        onTick: Array<(deltaS: number, event: KaylaEvent) => void>;
+        fc?: FC<any>;
+        useStateCallIndex: number;
+        useEffectCallIndex: number;
+        useDrawCallIndex: number;
+        useStepCallIndex: number;
+        useRefCallIndex: number;
+        lastStateDeps: Array<{
+            stateRef: KaylaState<any>;
+            stamp: number;
+        }>;
+        refresh(): void;
+        lastChildren: KaylaInternalComponent<any>[];
+        isFirstUse: boolean;
+        use(): void;
+        unuse(): void;
+    }
+    class KaylaRectEntity extends RectLeaEntity {
+        #private;
+        constructor(component: KaylaInternalComponent, name: string);
+        update(_delta: number): void;
+        draw(ctx: CanvasRenderingContext2D): void;
+    }
+    class KaylaScene {
+        #private;
+        constructor(scene: LeaSceneII);
+        /**
+         * Returns the underlying LEA scene instance.
+         */
+        getScene(): LeaSceneII;
+        private drawHandler;
+        /**
+         * Attaches this scene to a game instance.
+         *
+         * @param game - The game to attach to
+         */
+        attachTo(game: LeaGameII): void;
+        /**
+         * Mounts a root component tree into the scene.
+         *
+         * Triggers component execution, entity creation, and hook registration.
+         *
+         * @param elem - Root Kayla element (usually JSX)
+         */
+        spawn(elem: KaylaElement<any>): void;
+        /**
+         * Detaches this scene from its game (if attached).
+         */
+        detach(): void;
+        private tickHandler;
+    }
+    const singleGlobalInstance: GlobalKayla;
+}
+/**
+ * Returns a stateful value and a setter to update it.
+ *
+ * **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
+ */
+declare const useState: <T>(initialValue?: T, { alwaysRecall }?: {
+    alwaysRecall?: boolean;
+}) => KaylaInternals.KaylaState<T>;
+/**
+ * Returns a mutable ref object whose `.current` property persists across entity refreshes.
+ *
+ * **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).
+ *
+ * Special case: pass the `self` symbol to get the current LEA entity:
+ *
+ * @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
+ *
+ * @example Entity reference
+ * const entity = useRef(self);
+ * entity.current.x += 10; // direct entity mutation, no refresh
+ *
+ * @example Mutable counter
+ * const timer = useRef(0);
+ * useTick(delta => { timer.current += delta; });
+ */
+declare const useRef: {
+    (initialValue: typeof selfSym): KaylaElementRef;
+    <T>(initialValue: T | null): KaylaInternals.KaylaRef<T>;
+};
+/**
+ * Registers an effect that runs after entity creation and after every 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**; reordering calls will corrupt effect registration.
+ *
+ * The effect callback runs **synchronously** after refresh completes.
+ * If it returns a function, that cleanup runs **before** the next effect execution or when the entity is destroyed.
+ *
+ * Multiple `useEffect` calls **stack** — all run in declaration order.
+ * Effects are **re-registered** on every refresh (no dependency array in current version).
+ *
+ * **Use only for true side-effects** (event listeners, intervals, tweens, audio nodes, physics setup).
+ * For game logic, use `useTick` / `usePaint` / `useSelf` instead.
+ *
+ * @param effect Imperative function that may return a cleanup
+ */
+declare const useEffect: (onEffect: KaylaInternals.KaylaInternalComponent["onEffect"][number]) => void;
+/**
+ * Registers a callback 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.
+ *
+ * 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).
+ *
+ * **Use for:** physics, movement, AI, timers, collision checks, input polling.
+ *
+ * @param callback Tick handler receiving delta time (seconds) and cancellable event
+ */
+declare const useTick: (onTick: KaylaInternals.KaylaInternalComponent["onTick"][number]) => void;
+/**
+ * Registers a callback 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.
+ *
+ * Multiple `usePaint` calls **stack** — all run in declaration order every frame.
+ * Call `event.preventDefault()` to skip remaining paint handlers (including default rect fill).
+ *
+ * **Use for:** drawing sprites, particles, health bars, debug overlays, name tags.
+ *
+ * @param callback Paint handler receiving canvas context and cancellable event
+ */
+declare const usePaint: (onPaint: KaylaInternals.KaylaInternalComponent["onPaint"][number]) => void;
+/**
+ * Defines the public API this entity exposes to its parent via the `exportsRef` prop.
+ *
+ * **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).
+ *
+ * **Use for:** exposing methods (jump, takeDamage), getters (position, health), or state handles to parent.
+ *
+ * @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
+ *
+ * @example
+ * useExports(Player, () => ({
+ *   jump: () => { ...  },
+ *   getPosition: () => entity.current.pos.clone()
+ * }));
+ */
+declare const useExports: <T extends FC<any, any>>(fc: T, onExport: KaylaInternals.KaylaInternalComponent<PropOfFC<T>, ExportsOfFC<T>>["onExport"]) => void;
+/**
+ * Creates and returns a stable object (god-object) for holding most of an entity's state and logic.
+ *
+ * **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.
+ *
+ * **Recommended pattern:** Put nearly all mutable state, methods, and game logic here.
+ * Use `useState` **only** for rare structural changes that should trigger refresh.
+ *
+ * @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)
+ *
+ * @example
+ * const self = useSelf(() => ({
+ *   pos: new Vector2(400, 300),
+ *   vel: new Vector2(100, 0),
+ *   tick(delta) { this.pos.x += this.vel.x * delta; }
+ * }));
+ *
+ * useTick(delta => self.tick(delta));
+ */
+declare const useSelf: <T>(init: () => T) => T;
+/**
+ * Returns a direct reference to the underlying LEA entity instance managed by this component.
+ *
+ * **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 state.
+ *
+ * The returned reference is **stable** for the entity's lifetime and allows direct mutation of `x`, `y`, `z`, `width`, `height`, etc.
+ *
+ * @returns Reference to the `KaylaRectEntity` instance
+ */
+declare const useEntity: () => KaylaElementRef;
+/**
+ * Special symbol used to obtain a reference to the current entity.
+ *
+ * Pass this to `useRef` to get the underlying `KaylaRectEntity`:
+ *
+ * ```ts
+ * const entity = useRef(self);
+ * entity.current.x += 10;
+ * ```
+ *
+ * @see {@link useRef}
+ */
+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.
+ *
+ * @param callback - The function to schedule
+ */
+declare const useNextStack: (callback: () => void) => void;
+/**
+ * A fragment component that simply returns its children.
+ *
+ * Useful for grouping entities without adding an extra wrapper entity.
+ * Behaves like React.Fragment — no additional DOM/entity overhead.
+ *
+ * @example
+ * return (
+ *   <KaylaFragment>
+ *     <Enemy />
+ *     <Coin />
+ *   </KaylaFragment>
+ * );
+ *
+ * // Or shorthand:
+ * return (
+ *   <>
+ *     <Enemy />
+ *     <Coin />
+ *   </>
+ * );
+ */
+declare const KaylaFragment: FC;
+declare namespace JSX {
+    type Element = KaylaElement<any>;
+    interface IntrinsicElements {
+    }
+    type ElementType = FC<any>;
+}
+/**
+ * Marker type for values that can be exported from a component via `useExports`.
+ *
+ * Currently supports `KaylaState` or `KaylaRef` instances.
+ */
+type KaylaExportables = KaylaState<any> | KaylaRef<any>;
+/**
+ * Shape of the object returned by a component's `useExports` callback.
+ *
+ * @template StateMap - Record mapping export names to exportable values
+ */
+type KaylaExports<StateMap extends Record<string, KaylaExportables>> = {
+    [K in keyof StateMap]: StateMap[K];
+};
+type PropOfFC<T extends FC<any, any>> = T extends FC<infer Props, any> ? Props : never;
+type ExportsOfFC<T extends FC<any, any>> = T extends FC<any, infer Exports> ? Exports : never;
+/**
+ * Creates a temporary ref object **outside** of component context.
+ *
+ * Unlike `useRef`, this ref **does not persist** across entity refreshes — it is recreated
+ * every time the component function runs. Use for one-off values or render-pass temporaries.
+ *
+ * @template T - Type of the ref's value
+ * @param initialValue - Initial value for `.current`
+ * @returns A fresh `KaylaRef` instance
+ *
+ * @example
+ * const temp = useDisposableRef({ count: 0 });
+ * // temp.current is only valid for this render
+ */
+declare function useDisposableRef<T>(initialValue: T): KaylaInternals.KaylaRef<T>;
+/**
+ * Reference type returned by `useEntity()` or passed via `ref` prop.
+ *
+ * Provides direct access to the underlying `KaylaRectEntity` (LEA entity wrapper).
+ */
+interface KaylaElementRef extends KaylaRef<KaylaInternals.KaylaRectEntity> {
+}
+
+type kaylaInternals_ExportsOfFC<T extends FC<any, any>> = ExportsOfFC<T>;
+type kaylaInternals_FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExports> = FC<Props, Exports>;
+type kaylaInternals_FCExports = FCExports;
+type kaylaInternals_FCProps = FCProps;
+declare const kaylaInternals_JSX: typeof JSX;
+type kaylaInternals_KaylaElement<Props extends FCProps> = KaylaElement<Props>;
+type kaylaInternals_KaylaElementRef = KaylaElementRef;
+type kaylaInternals_KaylaExportables = KaylaExportables;
+type kaylaInternals_KaylaExports<StateMap extends Record<string, KaylaExportables>> = KaylaExports<StateMap>;
+declare const kaylaInternals_KaylaFragment: typeof KaylaFragment;
+type kaylaInternals_KaylaGame = KaylaGame;
+declare const kaylaInternals_KaylaInternals: typeof KaylaInternals;
+type kaylaInternals_KaylaRef<T> = KaylaRef<T>;
+type kaylaInternals_KaylaRenderer = KaylaRenderer;
+type kaylaInternals_KaylaScene = KaylaScene;
+type kaylaInternals_KaylaState<T> = KaylaState<T>;
+type kaylaInternals_PropOfFC<T extends FC<any, any>> = PropOfFC<T>;
+declare const kaylaInternals_createElement: typeof createElement;
+declare const kaylaInternals_createGame: typeof createGame;
+declare const kaylaInternals_createRenderer: typeof createRenderer;
+declare const kaylaInternals_createScene: typeof createScene;
+declare const kaylaInternals_useDisposableRef: typeof useDisposableRef;
+declare const kaylaInternals_useEffect: typeof useEffect;
+declare const kaylaInternals_useEntity: typeof useEntity;
+declare const kaylaInternals_useExports: typeof useExports;
+declare const kaylaInternals_useNextStack: typeof useNextStack;
+declare const kaylaInternals_usePaint: typeof usePaint;
+declare const kaylaInternals_useRef: typeof useRef;
+declare const kaylaInternals_useSelf: typeof useSelf;
+declare const kaylaInternals_useState: typeof useState;
+declare const kaylaInternals_useTick: typeof useTick;
+declare namespace kaylaInternals {
+  export { type kaylaInternals_ExportsOfFC as ExportsOfFC, type kaylaInternals_FC as FC, type kaylaInternals_FCExports as FCExports, type kaylaInternals_FCProps as FCProps, kaylaInternals_JSX as JSX, type kaylaInternals_KaylaElement as KaylaElement, type kaylaInternals_KaylaElementRef as KaylaElementRef, type kaylaInternals_KaylaExportables as KaylaExportables, type kaylaInternals_KaylaExports as KaylaExports, kaylaInternals_KaylaFragment as KaylaFragment, type kaylaInternals_KaylaGame as KaylaGame, kaylaInternals_KaylaInternals as KaylaInternals, type kaylaInternals_KaylaRef as KaylaRef, type kaylaInternals_KaylaRenderer as KaylaRenderer, type kaylaInternals_KaylaScene as KaylaScene, type kaylaInternals_KaylaState as KaylaState, type kaylaInternals_PropOfFC as PropOfFC, kaylaInternals_createElement as createElement, kaylaInternals_createGame as createGame, kaylaInternals_createRenderer as createRenderer, kaylaInternals_createScene as createScene, selfSym as self, kaylaInternals_useDisposableRef as useDisposableRef, kaylaInternals_useEffect as useEffect, kaylaInternals_useEntity as useEntity, kaylaInternals_useExports as useExports, kaylaInternals_useNextStack as useNextStack, kaylaInternals_usePaint as usePaint, kaylaInternals_useRef as useRef, kaylaInternals_useSelf as useSelf, kaylaInternals_useState as useState, kaylaInternals_useTick as useTick };
+}
+
+declare namespace UI {
+    interface UIProps extends FCProps {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        onClick?: () => void;
+    }
+    const UIComponent: FC<UIProps>;
+}
+
+type Kayla_ExportsOfFC<T extends FC<any, any>> = ExportsOfFC<T>;
+type Kayla_FC<Props extends FCProps = FCProps, Exports extends FCExports = FCExports> = FC<Props, Exports>;
+type Kayla_FCExports = FCExports;
+type Kayla_FCProps = FCProps;
+declare const Kayla_JSX: typeof JSX;
+type Kayla_KaylaElement<Props extends FCProps> = KaylaElement<Props>;
+type Kayla_KaylaElementRef = KaylaElementRef;
+type Kayla_KaylaExportables = KaylaExportables;
+type Kayla_KaylaExports<StateMap extends Record<string, KaylaExportables>> = KaylaExports<StateMap>;
+declare const Kayla_KaylaFragment: typeof KaylaFragment;
+type Kayla_KaylaGame = KaylaGame;
+declare const Kayla_KaylaInternals: typeof KaylaInternals;
+type Kayla_KaylaRef<T> = KaylaRef<T>;
+type Kayla_KaylaRenderer = KaylaRenderer;
+type Kayla_KaylaScene = KaylaScene;
+type Kayla_KaylaState<T> = KaylaState<T>;
+type Kayla_PropOfFC<T extends FC<any, any>> = PropOfFC<T>;
+declare const Kayla_UI: typeof UI;
+declare const Kayla_createElement: typeof createElement;
+declare const Kayla_createGame: typeof createGame;
+declare const Kayla_createRenderer: typeof createRenderer;
+declare const Kayla_createScene: typeof createScene;
+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_useNextStack: typeof useNextStack;
+declare const Kayla_usePaint: typeof usePaint;
+declare const Kayla_useRef: typeof useRef;
+declare const Kayla_useSelf: typeof useSelf;
+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, kaylaInternals as Kayla, type Kayla_KaylaElement as KaylaElement, type Kayla_KaylaElementRef as KaylaElementRef, type Kayla_KaylaExportables as KaylaExportables, type Kayla_KaylaExports as KaylaExports, Kayla_KaylaFragment as KaylaFragment, type Kayla_KaylaGame as KaylaGame, Kayla_KaylaInternals as KaylaInternals, 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, Kayla_UI as UI, Kayla_createElement as createElement, Kayla_createGame as createGame, Kayla_createRenderer as createRenderer, Kayla_createScene as createScene, selfSym as self, Kayla_useDisposableRef as useDisposableRef, Kayla_useEffect as useEffect, Kayla_useEntity as useEntity, Kayla_useExports as useExports, Kayla_useNextStack as useNextStack, Kayla_usePaint as usePaint, Kayla_useRef as useRef, Kayla_useSelf as useSelf, Kayla_useState as useState, Kayla_useTick as useTick };
+}
+
+export { useSelf as A, useState as B, useTick as C, type ExportsOfFC as E, type FC as F, JSX as J, Kayla as K, type PropOfFC as P, UI as U, type FCExports as a, type FCProps as b, type KaylaElement as c, type KaylaElementRef as d, type KaylaExportables as e, type KaylaExports as f, KaylaFragment as g, KaylaGame as h, KaylaInternals as i, KaylaRef as j, kaylaInternals as k, KaylaRenderer as l, KaylaScene as m, KaylaState as n, createElement as o, createGame as p, createRenderer as q, createScene as r, selfSym as s, useEffect as t, useDisposableRef as u, useEntity as v, useExports as w, useNextStack as x, usePaint as y, useRef as z };