@dreamboard-games/ui-sdk 0.0.41

package/dist/hooks/useInteractionByKey.js

@@ -0,0 +1,263 @@
+import { useEffect, useMemo, useRef } from "react";
+import { useArmedInteraction, useInteractionDraft, useInteractionSubmitting, useInteractionUiStore, } from "../context/InteractionDraftContext.js";
+import { useClientParamSchema } from "../context/ClientParamSchemaContext.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import { ValidationError, validationErrorFromUnknown, } from "../errors/ValidationError.js";
+import { applyInteractionInputDefaults, hasInteractionFieldErrors, inputByKey, isInputValueReady, interactionArmScope, interactionInputKeys, mergeInteractionFieldErrors, validateInteractionInputDomains, } from "../utils/interaction-inputs.js";
+/**
+ * Look up an interaction descriptor by phase-qualified key on the controlling seat's
+ * inbox and return a bound {@link InteractionHandle}. Returns `null`
+ * when no matching descriptor is currently projected.
+ *
+ * Prefer this over manual `inbox.bySurface.panel?.find(...)` + sentinel
+ * descriptor patterns — it keeps hook-call order stable and guarantees
+ * the handle reflects the freshest descriptor.
+ *
+ * Types:
+ * - `Key` narrows the key literal. When called from the workspace-local
+ *   `useInteractionByKey` re-export generated in `ui-contract.ts`, `Key` is
+ *   constrained to the generated `InteractionKey` union so typos become
+ *   compile errors.
+ * - `Params` is the params shape (`InteractionParamsOf<Key>` in the
+ *   generated re-export). It flows through to `draft`, `submit`,
+ *   `validate`, and `setInput` for compile-time safety.
+ *
+ * ```tsx
+ * // from the generated workspace re-export
+ * const handle = useInteractionByKey("play.placeThingCard");
+ * if (!handle) return <Waiting/>;
+ * handle.setInput("cardId", card.id); // typed to ThingsDeckCardId
+ * await handle.submit();
+ * ```
+ */
+export function useInteractionByKey(interactionKey) {
+    const runtime = useRuntimeContext();
+    const { controllingPlayerId } = usePluginSession();
+    const store = useInteractionUiStore();
+    const submittingRef = useRef(false);
+    const autoSubmitSignatureRef = useRef(null);
+    const descriptors = usePluginState((state) => state.gameplay.availableInteractions ?? []);
+    const simultaneousPhase = usePluginState((state) => state.gameplay.simultaneousPhase);
+    const descriptor = useMemo(() => {
+        if (!interactionKey)
+            return null;
+        return descriptors.find((d) => d.interactionKey === interactionKey) ?? null;
+    }, [descriptors, interactionKey]);
+    const armScope = descriptor
+        ? interactionArmScope(descriptor)
+        : "interaction:missing";
+    const resolvedPhaseName = descriptor?.phaseName;
+    const resolvedInteractionId = descriptor?.interactionId ?? "";
+    const resolvedInteractionKey = descriptor?.interactionKey ?? "";
+    const paramsSchema = useClientParamSchema(resolvedPhaseName, resolvedInteractionId);
+    const draft = useInteractionDraft(resolvedInteractionKey);
+    const armedId = useArmedInteraction(armScope);
+    const submitting = useInteractionSubmitting(resolvedInteractionKey);
+    const handle = useMemo(() => {
+        if (!descriptor)
+            return null;
+        const typedDraft = draft;
+        const typedValues = applyInteractionInputDefaults(descriptor, typedDraft);
+        const inputKeys = interactionInputKeys(descriptor);
+        const isReady = inputKeys.length === 0
+            ? true
+            : inputKeys.every((key) => {
+                const input = inputByKey(descriptor, key);
+                const value = typedValues[key];
+                return input
+                    ? isInputValueReady(input, value)
+                    : value !== null && value !== undefined;
+            });
+        const isArmed = armedId === descriptor.interactionKey;
+        const submitted = controllingPlayerId !== null &&
+            simultaneousPhase?.phaseName === descriptor.phaseName &&
+            simultaneousPhase.interactionId === descriptor.interactionId &&
+            simultaneousPhase.sealedPlayerIds.includes(controllingPlayerId);
+        const status = submitted
+            ? "submitted"
+            : submitting
+                ? "submitting"
+                : "open";
+        const requirePlayer = () => {
+            if (!controllingPlayerId) {
+                throw new Error("useInteractionByKey: no controlling player available");
+            }
+            return controllingPlayerId;
+        };
+        const submit = async (params) => {
+            if (status !== "open" || submittingRef.current) {
+                throw new ValidationError(status === "submitted" ? "ALREADY_SUBMITTED" : "SUBMITTING", status === "submitted"
+                    ? "Interaction has already been submitted."
+                    : "Interaction submission is already in progress.");
+            }
+            submittingRef.current = true;
+            store.setSubmitting(descriptor.interactionKey, true);
+            const finalParams = applyInteractionInputDefaults(descriptor, params ?? typedValues);
+            try {
+                await runtime.submitInteraction(requirePlayer(), descriptor.interactionId, finalParams);
+                store.clearInput(descriptor.interactionKey);
+                if (store.getArmed(armScope) === descriptor.interactionKey) {
+                    store.arm(armScope, null);
+                }
+            }
+            catch (error) {
+                throw validationErrorFromUnknown(error);
+            }
+            finally {
+                submittingRef.current = false;
+                store.setSubmitting(descriptor.interactionKey, false);
+            }
+        };
+        const validate = async (params) => {
+            const finalParams = applyInteractionInputDefaults(descriptor, params ?? typedValues);
+            const result = await runtime.validateInteraction(requirePlayer(), descriptor.interactionId, finalParams);
+            if (!result.valid) {
+                throw new ValidationError(result.errorCode, result.message);
+            }
+        };
+        const validateDraft = () => {
+            const rawDraft = { ...typedValues };
+            const missing = inputKeys.filter((key) => {
+                const input = inputByKey(descriptor, key);
+                const value = rawDraft[key];
+                return input
+                    ? !isInputValueReady(input, value)
+                    : value === null || value === undefined;
+            });
+            const domainFieldErrors = validateInteractionInputDomains(descriptor, rawDraft);
+            if (!paramsSchema) {
+                if (missing.length > 0 ||
+                    hasInteractionFieldErrors(domainFieldErrors)) {
+                    return {
+                        ok: false,
+                        fieldErrors: domainFieldErrors,
+                        formErrors: [],
+                        missing,
+                    };
+                }
+                return {
+                    ok: true,
+                    params: rawDraft,
+                    fieldErrors: {},
+                    formErrors: [],
+                    missing: [],
+                };
+            }
+            const result = paramsSchema.safeParse(rawDraft);
+            if (result.success) {
+                if (hasInteractionFieldErrors(domainFieldErrors)) {
+                    return {
+                        ok: false,
+                        fieldErrors: domainFieldErrors,
+                        formErrors: [],
+                        missing,
+                    };
+                }
+                return {
+                    ok: true,
+                    params: result.data,
+                    fieldErrors: {},
+                    formErrors: [],
+                    missing: [],
+                };
+            }
+            const fieldErrors = {};
+            const formErrors = [];
+            for (const issue of result.error.issues) {
+                const [first] = issue.path;
+                if (typeof first === "string" && inputKeys.includes(first)) {
+                    const key = first;
+                    fieldErrors[key] = [...(fieldErrors[key] ?? []), issue.message];
+                }
+                else {
+                    formErrors.push(issue.message);
+                }
+            }
+            return {
+                ok: false,
+                fieldErrors: mergeInteractionFieldErrors(fieldErrors, domainFieldErrors),
+                formErrors,
+                missing,
+            };
+        };
+        const validateDraftServer = async () => {
+            await validate({ ...typedValues });
+        };
+        const submitDraft = async () => {
+            const validation = validateDraft();
+            if (!validation.ok) {
+                const message = validation.formErrors[0] ??
+                    Object.values(validation.fieldErrors).flat()[0] ??
+                    (validation.missing.length > 0
+                        ? "Required inputs are missing"
+                        : "Draft validation failed");
+                throw new ValidationError("INVALID_DRAFT", message);
+            }
+            await submit(validation.params);
+        };
+        return {
+            descriptor,
+            commit: descriptor.commit,
+            available: descriptor.available,
+            unavailableReason: descriptor.unavailableReason,
+            status,
+            submit,
+            validate,
+            validateDraft,
+            validateDraftServer,
+            submitDraft,
+            draft: typedDraft,
+            values: typedValues,
+            setInput: (key, value) => store.setInput(descriptor.interactionKey, key, value),
+            clearInput: (key) => store.clearInput(descriptor.interactionKey, key),
+            isReady,
+            isArmed,
+            arm: () => store.arm(armScope, descriptor.interactionKey),
+            disarm: () => {
+                if (store.getArmed(armScope) === descriptor.interactionKey) {
+                    store.arm(armScope, null);
+                }
+            },
+        };
+    }, [
+        descriptor,
+        draft,
+        armedId,
+        armScope,
+        runtime,
+        store,
+        controllingPlayerId,
+        paramsSchema,
+        simultaneousPhase,
+        submitting,
+    ]);
+    useEffect(() => {
+        if (!handle) {
+            autoSubmitSignatureRef.current = null;
+            return;
+        }
+        if (handle.commit.mode !== "autoWhenReady") {
+            autoSubmitSignatureRef.current = null;
+            return;
+        }
+        if (!handle.available || handle.status !== "open" || !handle.isReady) {
+            if (!handle.isReady)
+                autoSubmitSignatureRef.current = null;
+            return;
+        }
+        const validation = handle.validateDraft();
+        if (!validation.ok)
+            return;
+        const signature = `${handle.descriptor.interactionKey}:${JSON.stringify(validation.params)}`;
+        if (autoSubmitSignatureRef.current === signature)
+            return;
+        autoSubmitSignatureRef.current = signature;
+        void handle.submit(validation.params).catch(() => {
+            // Runtime error channels surface the failure. Keep the draft intact and
+            // suppress repeated attempts until the player changes the draft.
+        });
+    }, [handle]);
+    return handle;
+}

package/dist/hooks/useInteractionHandle.d.ts

@@ -0,0 +1,103 @@
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+/**
+ * Anything that can be used as a submit params object. Subset of TS
+ * objects so generic defaults and `keyof Params & string` hold.
+ */
+export type InteractionParamsShape = Record<string, unknown>;
+export type InteractionHandleStatus = "open" | "submitting" | "submitted";
+export type DraftValidation<Params extends InteractionParamsShape = InteractionParamsShape> = {
+    ok: true;
+    params: Params;
+    fieldErrors: Partial<Record<keyof Params & string, readonly string[]>>;
+    formErrors: readonly string[];
+    missing: ReadonlyArray<keyof Params & string>;
+} | {
+    ok: false;
+    fieldErrors: Partial<Record<keyof Params & string, readonly string[]>>;
+    formErrors: readonly string[];
+    missing: ReadonlyArray<keyof Params & string>;
+};
+/**
+ * Bound handle around an {@link InteractionDescriptor}. Surfaces call into
+ * this hook to submit/validate an interaction, track draft input state for
+ * multi-step prompts, and arm/disarm themselves on a surface.
+ *
+ * Availability flags are mirrored from the authoritative descriptor; UI
+ * MUST NOT recompute eligibility locally.
+ *
+ * When the surrounding workspace knows the concrete params shape (e.g.
+ * obtained from the generated `InteractionParamsOf<Id>` alias), parameterise
+ * this handle on `Params` so `submit`, `draft`, and `setInput` are all
+ * statically typed. The default `Record<string, unknown>` preserves the
+ * loosely-typed fallback for generic infrastructure.
+ */
+export interface InteractionHandle<Params extends InteractionParamsShape = InteractionParamsShape, DefaultedKeys extends keyof Params & string = never> {
+    descriptor: InteractionDescriptor;
+    /** Draft commit policy projected by the reducer. */
+    commit: InteractionDescriptor["commit"];
+    /**
+     * Submit the interaction. When `params` is omitted the current draft (as
+     * mutated by {@link InteractionHandle.setInput}) is used instead, which is
+     * the common case for multi-input prompts.
+     */
+    submit: (params?: Params) => Promise<void>;
+    /** Run server validation using `params` (or the current draft by default). */
+    validate: (params?: Params) => Promise<void>;
+    /** Run local generated client-schema validation against the current draft. */
+    validateDraft: () => DraftValidation<Params>;
+    /** Run server validation against the current draft. */
+    validateDraftServer: () => Promise<void>;
+    /**
+     * Validate the current draft locally, submit parsed params, then clear the
+     * draft only when submission succeeds.
+     */
+    submitDraft: () => Promise<void>;
+    /** Mirrors `descriptor.available`. */
+    available: boolean;
+    /** Mirrors `descriptor.unavailableReason`. */
+    unavailableReason?: string;
+    /** Local/authoritative progress for this interaction. */
+    status: InteractionHandleStatus;
+    /** Live draft values for this interaction. Empty object when unset. */
+    draft: Readonly<Partial<Params>>;
+    /**
+     * Draft values with authored input defaults applied. Fields with declared
+     * defaults are typed as present; other draft fields remain partial.
+     */
+    values: Readonly<Partial<Params> & Pick<Params, DefaultedKeys>>;
+    /** Set a single input on the draft. */
+    setInput: <K extends keyof Params & string>(key: K, value: Params[K]) => void;
+    /** Clear a single input (or the whole draft when `key` is omitted). */
+    clearInput: (key?: keyof Params & string) => void;
+    /**
+     * True when every key declared on `descriptor.inputs` has a value in
+     * the draft. Falls back to `true` when the descriptor declares no inputs.
+     */
+    isReady: boolean;
+    /**
+     * True when this interaction is the currently armed one on its surface.
+     * Armed interactions are the ones that surfaces like `BoardSurface` use
+     * to highlight eligible targets and route clicks.
+     */
+    isArmed: boolean;
+    /** Arm this interaction on its surface (disarms any previously armed). */
+    arm: () => void;
+    /** Disarm this interaction (if it was armed). */
+    disarm: () => void;
+}
+/**
+ * Bind an {@link InteractionDescriptor} to submit/validate helpers plus
+ * draft + arming state. Use this from any surface; draft state is shared
+ * across components through {@link InteractionUiProvider}, which
+ * `PluginRuntime` auto-mounts.
+ *
+ * Example:
+ * ```tsx
+ * const handle = useInteractionHandle(placeThing);
+ * handle.setInput("cardId", card.id);
+ * handle.setInput("ringId", ring.id);
+ * if (handle.isReady) await handle.submit();
+ * ```
+ */
+export declare function useInteractionHandle<Params extends InteractionParamsShape = InteractionParamsShape, DefaultedKeys extends keyof Params & string = never>(descriptor: InteractionDescriptor): InteractionHandle<Params, DefaultedKeys>;
+//# sourceMappingURL=useInteractionHandle.d.ts.map

package/dist/hooks/useInteractionHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInteractionHandle.d.ts","sourceRoot":"","sources":["../../src/hooks/useInteractionHandle.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useInteractionHandle.js

@@ -0,0 +1,254 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useArmedInteraction, useInteractionDraft, useInteractionSubmitting, useInteractionUiStore, } from "../context/InteractionDraftContext.js";
+import { useClientParamSchema } from "../context/ClientParamSchemaContext.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import { ValidationError, validationErrorFromUnknown, } from "../errors/ValidationError.js";
+import { applyInteractionInputDefaults, hasInteractionFieldErrors, inputByKey, isInputValueReady, interactionArmScope, interactionInputKeys, mergeInteractionFieldErrors, validateInteractionInputDomains, } from "../utils/interaction-inputs.js";
+/**
+ * Bind an {@link InteractionDescriptor} to submit/validate helpers plus
+ * draft + arming state. Use this from any surface; draft state is shared
+ * across components through {@link InteractionUiProvider}, which
+ * `PluginRuntime` auto-mounts.
+ *
+ * Example:
+ * ```tsx
+ * const handle = useInteractionHandle(placeThing);
+ * handle.setInput("cardId", card.id);
+ * handle.setInput("ringId", ring.id);
+ * if (handle.isReady) await handle.submit();
+ * ```
+ */
+export function useInteractionHandle(descriptor) {
+    const runtime = useRuntimeContext();
+    const { controllingPlayerId } = usePluginSession();
+    const store = useInteractionUiStore();
+    const submittingRef = useRef(false);
+    const autoSubmitSignatureRef = useRef(null);
+    const simultaneousPhase = usePluginState((state) => state.gameplay.simultaneousPhase);
+    const { interactionId, interactionKey, phaseName } = descriptor;
+    const armScope = interactionArmScope(descriptor);
+    const inputKeys = useMemo(() => interactionInputKeys(descriptor), [descriptor]);
+    const paramsSchema = useClientParamSchema(phaseName, interactionId);
+    const draft = useInteractionDraft(interactionKey);
+    const values = useMemo(() => applyInteractionInputDefaults(descriptor, draft), [descriptor, draft]);
+    const armedId = useArmedInteraction(armScope);
+    const isArmed = armedId === interactionKey;
+    const submitting = useInteractionSubmitting(interactionKey);
+    const submitted = controllingPlayerId !== null &&
+        simultaneousPhase?.phaseName === phaseName &&
+        simultaneousPhase.interactionId === interactionId &&
+        simultaneousPhase.sealedPlayerIds.includes(controllingPlayerId);
+    const status = submitted
+        ? "submitted"
+        : submitting
+            ? "submitting"
+            : "open";
+    const isReady = useMemo(() => {
+        const required = inputKeys;
+        if (required.length === 0)
+            return true;
+        return required.every((key) => {
+            const input = inputByKey(descriptor, key);
+            const value = values[key];
+            return input
+                ? isInputValueReady(input, value)
+                : value !== null && value !== undefined;
+        });
+    }, [descriptor, values, inputKeys]);
+    const requirePlayer = useCallback(() => {
+        if (!controllingPlayerId) {
+            throw new Error("useInteractionHandle: no controlling player available");
+        }
+        return controllingPlayerId;
+    }, [controllingPlayerId]);
+    const submit = useCallback(async (params) => {
+        if (status !== "open" || submittingRef.current) {
+            throw new ValidationError(status === "submitted" ? "ALREADY_SUBMITTED" : "SUBMITTING", status === "submitted"
+                ? "Interaction has already been submitted."
+                : "Interaction submission is already in progress.");
+        }
+        submittingRef.current = true;
+        store.setSubmitting(interactionKey, true);
+        const finalParams = applyInteractionInputDefaults(descriptor, params ?? values);
+        try {
+            await runtime.submitInteraction(requirePlayer(), interactionId, finalParams);
+            store.clearInput(interactionKey);
+            if (store.getArmed(armScope) === interactionKey) {
+                store.arm(armScope, null);
+            }
+        }
+        catch (error) {
+            throw validationErrorFromUnknown(error);
+        }
+        finally {
+            submittingRef.current = false;
+            store.setSubmitting(interactionKey, false);
+        }
+    }, [
+        descriptor,
+        values,
+        runtime,
+        requirePlayer,
+        interactionId,
+        interactionKey,
+        armScope,
+        store,
+        status,
+    ]);
+    const validate = useCallback(async (params) => {
+        const finalParams = applyInteractionInputDefaults(descriptor, params ?? values);
+        const result = await runtime.validateInteraction(requirePlayer(), interactionId, finalParams);
+        if (!result.valid) {
+            throw new ValidationError(result.errorCode, result.message);
+        }
+    }, [descriptor, values, runtime, requirePlayer, interactionId]);
+    const validateDraft = useCallback(() => {
+        const rawDraft = { ...values };
+        const required = inputKeys;
+        const missing = required.filter((key) => {
+            const input = inputByKey(descriptor, key);
+            const value = rawDraft[key];
+            return input
+                ? !isInputValueReady(input, value)
+                : value === null || value === undefined;
+        });
+        const domainFieldErrors = validateInteractionInputDomains(descriptor, rawDraft);
+        if (!paramsSchema) {
+            if (missing.length > 0 || hasInteractionFieldErrors(domainFieldErrors)) {
+                return {
+                    ok: false,
+                    fieldErrors: domainFieldErrors,
+                    formErrors: [],
+                    missing,
+                };
+            }
+            return {
+                ok: true,
+                params: rawDraft,
+                fieldErrors: {},
+                formErrors: [],
+                missing: [],
+            };
+        }
+        const result = paramsSchema.safeParse(rawDraft);
+        if (result.success) {
+            if (hasInteractionFieldErrors(domainFieldErrors)) {
+                return {
+                    ok: false,
+                    fieldErrors: domainFieldErrors,
+                    formErrors: [],
+                    missing,
+                };
+            }
+            return {
+                ok: true,
+                params: result.data,
+                fieldErrors: {},
+                formErrors: [],
+                missing: [],
+            };
+        }
+        const fieldErrors = {};
+        const formErrors = [];
+        const missingSet = new Set(missing);
+        for (const issue of result.error.issues) {
+            const [first] = issue.path;
+            if (typeof first === "string" && required.includes(first)) {
+                if (missingSet.has(first))
+                    continue;
+                const key = first;
+                fieldErrors[key] = [...(fieldErrors[key] ?? []), issue.message];
+            }
+            else {
+                formErrors.push(issue.message);
+            }
+        }
+        return {
+            ok: false,
+            fieldErrors: mergeInteractionFieldErrors(fieldErrors, domainFieldErrors),
+            formErrors,
+            missing,
+        };
+    }, [descriptor, values, inputKeys, paramsSchema]);
+    const validateDraftServer = useCallback(async () => {
+        await validate({ ...values });
+    }, [values, validate]);
+    const submitDraft = useCallback(async () => {
+        const validation = validateDraft();
+        if (!validation.ok) {
+            const message = validation.formErrors[0] ??
+                Object.values(validation.fieldErrors).flat()[0] ??
+                (validation.missing.length > 0
+                    ? "Required inputs are missing"
+                    : "Draft validation failed");
+            throw new ValidationError("INVALID_DRAFT", message);
+        }
+        await submit(validation.params);
+    }, [submit, validateDraft]);
+    useEffect(() => {
+        if (descriptor.commit.mode !== "autoWhenReady") {
+            autoSubmitSignatureRef.current = null;
+            return;
+        }
+        if (!descriptor.available || status !== "open" || !isReady) {
+            if (!isReady)
+                autoSubmitSignatureRef.current = null;
+            return;
+        }
+        const validation = validateDraft();
+        if (!validation.ok)
+            return;
+        const signature = `${interactionKey}:${JSON.stringify(validation.params)}`;
+        if (autoSubmitSignatureRef.current === signature)
+            return;
+        autoSubmitSignatureRef.current = signature;
+        void submit(validation.params).catch(() => {
+            // Runtime error channels surface the failure. Keep the draft intact and
+            // suppress repeated attempts until the player changes the draft.
+        });
+    }, [
+        descriptor.available,
+        descriptor.commit.mode,
+        interactionKey,
+        isReady,
+        status,
+        submit,
+        validateDraft,
+    ]);
+    const setInput = useCallback((key, value) => {
+        store.setInput(interactionKey, key, value);
+    }, [store, interactionKey]);
+    const clearInput = useCallback((key) => {
+        store.clearInput(interactionKey, key);
+    }, [store, interactionKey]);
+    const arm = useCallback(() => {
+        store.arm(armScope, interactionKey);
+    }, [store, armScope, interactionKey]);
+    const disarm = useCallback(() => {
+        if (store.getArmed(armScope) === interactionKey) {
+            store.arm(armScope, null);
+        }
+    }, [store, armScope, interactionKey]);
+    return {
+        descriptor,
+        commit: descriptor.commit,
+        available: descriptor.available,
+        unavailableReason: descriptor.unavailableReason,
+        status,
+        submit,
+        validate,
+        validateDraft,
+        validateDraftServer,
+        submitDraft,
+        draft,
+        values,
+        setInput,
+        clearInput,
+        isReady,
+        isArmed,
+        arm,
+        disarm,
+    };
+}

package/dist/hooks/useIsMobile.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hook to detect if the user is on a mobile/small screen device
+ * @param breakpoint - The width threshold in pixels (default: 768)
+ * @returns boolean indicating if the screen is mobile-sized
+ */
+export declare function useIsMobile(breakpoint?: number): boolean;
+//# sourceMappingURL=useIsMobile.d.ts.map

package/dist/hooks/useIsMobile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsMobile.d.ts","sourceRoot":"","sources":["../../src/hooks/useIsMobile.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,GAAE,MAA0B,GAAG,OAAO,CAyB3E"}

package/dist/hooks/useIsMobile.js

@@ -0,0 +1,29 @@
+import { useState, useEffect } from "react";
+const MOBILE_BREAKPOINT = 768;
+/**
+ * Hook to detect if the user is on a mobile/small screen device
+ * @param breakpoint - The width threshold in pixels (default: 768)
+ * @returns boolean indicating if the screen is mobile-sized
+ */
+export function useIsMobile(breakpoint = MOBILE_BREAKPOINT) {
+    const [isMobile, setIsMobile] = useState(() => {
+        // SSR-safe: default to false if window is not available
+        if (typeof window === "undefined")
+            return false;
+        return window.innerWidth < breakpoint;
+    });
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const mediaQuery = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+        const handleChange = (e) => {
+            setIsMobile(e.matches);
+        };
+        // Set initial value
+        handleChange(mediaQuery);
+        // Listen for changes
+        mediaQuery.addEventListener("change", handleChange);
+        return () => mediaQuery.removeEventListener("change", handleChange);
+    }, [breakpoint]);
+    return isMobile;
+}

package/dist/hooks/useIsMyTurn.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns whether the currently controlled player is one of the engine-tracked
+ * active players for the current gameplay snapshot.
+ */
+export declare function useIsMyTurn(): boolean;
+//# sourceMappingURL=useIsMyTurn.d.ts.map

package/dist/hooks/useIsMyTurn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsMyTurn.d.ts","sourceRoot":"","sources":["../../src/hooks/useIsMyTurn.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAOrC"}