@appstrata/react 0.1.0

package/dist/provider.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AppStrataProvider - React Context provider for AppStrata.
+ *
+ * Wraps the app and provides the SignagePlayer instance and ContextStore
+ * to all child components via React Context.
+ *
+ * Usage:
+ * ```tsx
+ * import { AppStrataProvider } from "@appstrata/react";
+ *
+ * root.render(
+ *   <AppStrataProvider>
+ *     <App />
+ *   </AppStrataProvider>
+ * );
+ * ```
+ */
+import type { ReactNode } from "react";
+import type { SignagePlayer } from "@appstrata/core";
+import { ContextStore } from "./store.js";
+/**
+ * Internal context value shape.
+ * @internal
+ */
+export interface AppStrataContextValue {
+    player: SignagePlayer;
+    store: ContextStore;
+}
+/**
+ * React Context for AppStrata.
+ * @internal
+ */
+export declare const AppStrataContext: import("react").Context<AppStrataContextValue | null>;
+/**
+ * Props for AppStrataProvider.
+ */
+export interface AppStrataProviderProps {
+    children: ReactNode;
+    /**
+     * Optional custom SignagePlayer instance.
+     * If not provided, uses getPlayer() from @appstrata/web (default singleton).
+     * Useful for testing or providing a custom player implementation.
+     */
+    player?: SignagePlayer;
+}
+/**
+ * AppStrataProvider - Required wrapper for all AppStrata React hooks.
+ *
+ * Creates a ContextStore and wires the player's onInit and onContextChange
+ * events to update the store. All hooks read from this store.
+ *
+ * The player instance is obtained via getPlayer() which returns a singleton,
+ * so no useState is needed.
+ */
+export declare function AppStrataProvider({ children, player: playerProp }: AppStrataProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,uDAAoD,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,sBAAsB,2CA4BzF"}

package/dist/provider.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AppStrataProvider - React Context provider for AppStrata.
+ *
+ * Wraps the app and provides the SignagePlayer instance and ContextStore
+ * to all child components via React Context.
+ *
+ * Usage:
+ * ```tsx
+ * import { AppStrataProvider } from "@appstrata/react";
+ *
+ * root.render(
+ *   <AppStrataProvider>
+ *     <App />
+ *   </AppStrataProvider>
+ * );
+ * ```
+ */
+import { createContext, useEffect, useMemo } from "react";
+import { getPlayer } from "@appstrata/web";
+import { ContextStore } from "./store.js";
+/**
+ * React Context for AppStrata.
+ * @internal
+ */
+export const AppStrataContext = createContext(null);
+/**
+ * AppStrataProvider - Required wrapper for all AppStrata React hooks.
+ *
+ * Creates a ContextStore and wires the player's onInit and onContextChange
+ * events to update the store. All hooks read from this store.
+ *
+ * The player instance is obtained via getPlayer() which returns a singleton,
+ * so no useState is needed.
+ */
+export function AppStrataProvider({ children, player: playerProp }) {
+    // Use provided player or default to singleton from @appstrata/web
+    const player = playerProp ?? getPlayer();
+    // Create store once - stable reference
+    const store = useMemo(() => new ContextStore(), []);
+    useEffect(() => {
+        // Wire player events to store
+        player.onInit((context) => {
+            store.setContext(context);
+        });
+        player.onContextChange?.((context) => {
+            store.setContext(context);
+        });
+    }, [player, store]);
+    const value = useMemo(() => ({ player, store }), [player, store]);
+    return (_jsx(AppStrataContext.Provider, { value: value, children: children }));
+}

package/dist/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ContextStore - Unified store for AppContext with granular subscriptions.
+ *
+ * Receives the complete AppContext on every update (from onInit and onContextChange)
+ * and uses deep comparison to determine which parts actually changed.
+ * This enables granular re-renders: components using useConfig() only re-render
+ * when config changes, not when device info changes.
+ *
+ * Compatible with React's useSyncExternalStore API.
+ *
+ * @internal
+ */
+import type { AppContext, Resource, DeviceInfo } from "@appstrata/core";
+type Listener = () => void;
+export declare class ContextStore {
+    private context;
+    private listeners;
+    private configListeners;
+    private resourcesListeners;
+    private deviceListeners;
+    getSnapshot: () => AppContext | null;
+    getConfigSnapshot: () => Record<string, unknown> | null;
+    getResourcesSnapshot: () => Resource[] | null;
+    getDeviceSnapshot: () => DeviceInfo | null;
+    subscribe: (listener: Listener) => (() => void);
+    subscribeConfig: (listener: Listener) => (() => void);
+    subscribeResources: (listener: Listener) => (() => void);
+    subscribeDevice: (listener: Listener) => (() => void);
+    setContext(next: AppContext): void;
+    private notify;
+}
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGxE,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAE3B,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,eAAe,CAAuB;IAM9C,WAAW,QAAO,UAAU,GAAG,IAAI,CAAiB;IACpD,iBAAiB,QAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAiC;IACvF,oBAAoB,QAAO,QAAQ,EAAE,GAAG,IAAI,CAAoC;IAChF,iBAAiB,QAAO,UAAU,GAAG,IAAI,CAAiC;IAM1E,SAAS,GAAI,UAAU,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAG5C;IAEF,eAAe,GAAI,UAAU,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAGlD;IAEF,kBAAkB,GAAI,UAAU,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAGrD;IAEF,eAAe,GAAI,UAAU,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAGlD;IAMF,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAmBlC,OAAO,CAAC,MAAM;CAKf"}

package/dist/store.js

@@ -0,0 +1,72 @@
+/**
+ * ContextStore - Unified store for AppContext with granular subscriptions.
+ *
+ * Receives the complete AppContext on every update (from onInit and onContextChange)
+ * and uses deep comparison to determine which parts actually changed.
+ * This enables granular re-renders: components using useConfig() only re-render
+ * when config changes, not when device info changes.
+ *
+ * Compatible with React's useSyncExternalStore API.
+ *
+ * @internal
+ */
+import { deepEqual } from "./deep-equal.js";
+export class ContextStore {
+    constructor() {
+        this.context = null;
+        this.listeners = new Set();
+        this.configListeners = new Set();
+        this.resourcesListeners = new Set();
+        this.deviceListeners = new Set();
+        // ═══════════════════════════════════════════════════════════════════
+        // SNAPSHOT GETTERS (for useSyncExternalStore)
+        // ═══════════════════════════════════════════════════════════════════
+        this.getSnapshot = () => this.context;
+        this.getConfigSnapshot = () => this.context?.config ?? null;
+        this.getResourcesSnapshot = () => this.context?.resources ?? null;
+        this.getDeviceSnapshot = () => this.context?.device ?? null;
+        // ═══════════════════════════════════════════════════════════════════
+        // SUBSCRIBE METHODS (for useSyncExternalStore)
+        // ═══════════════════════════════════════════════════════════════════
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => this.listeners.delete(listener);
+        };
+        this.subscribeConfig = (listener) => {
+            this.configListeners.add(listener);
+            return () => this.configListeners.delete(listener);
+        };
+        this.subscribeResources = (listener) => {
+            this.resourcesListeners.add(listener);
+            return () => this.resourcesListeners.delete(listener);
+        };
+        this.subscribeDevice = (listener) => {
+            this.deviceListeners.add(listener);
+            return () => this.deviceListeners.delete(listener);
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // CONTEXT UPDATE
+    // ═══════════════════════════════════════════════════════════════════
+    setContext(next) {
+        const prev = this.context;
+        this.context = next;
+        // Always notify full context subscribers
+        this.notify(this.listeners);
+        // Only notify granular subscribers if their data actually changed
+        if (!deepEqual(next.config, prev?.config)) {
+            this.notify(this.configListeners);
+        }
+        if (!deepEqual(next.resources, prev?.resources)) {
+            this.notify(this.resourcesListeners);
+        }
+        if (!deepEqual(next.device, prev?.device)) {
+            this.notify(this.deviceListeners);
+        }
+    }
+    notify(listeners) {
+        for (const listener of listeners) {
+            listener();
+        }
+    }
+}

package/dist/use-interaction.d.ts

@@ -0,0 +1,35 @@
+/**
+ * useInteraction - React hook for the AppStrata Interaction API.
+ *
+ * Event subscription hook that auto-subscribes on mount and
+ * unsubscribes on unmount. No-op if the "interaction" capability
+ * is unsupported.
+ */
+import type { InteractionEvent } from "@appstrata/core";
+/**
+ * Return type for useInteraction.
+ */
+export interface UseInteractionResult {
+    /** Whether the player supports the "interaction" capability (null = not yet initialized) */
+    supported: boolean | null;
+}
+/**
+ * Subscribe to interaction events (hardware buttons, remote controls, sensors).
+ *
+ * Auto-subscribes on mount, auto-unsubscribes on unmount.
+ * No-op if the "interaction" capability is unsupported.
+ *
+ * @param handler - Event handler called for each interaction event
+ * @returns Object with `supported` boolean
+ *
+ * @example
+ * ```tsx
+ * const { supported } = useInteraction((event) => {
+ *   if (event.type === "key" && event.key === "enter") {
+ *     handleSelect();
+ *   }
+ * });
+ * ```
+ */
+export declare function useInteraction(handler: (event: InteractionEvent) => void): UseInteractionResult;
+//# sourceMappingURL=use-interaction.d.ts.map

package/dist/use-interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-interaction.d.ts","sourceRoot":"","sources":["../src/use-interaction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GACzC,oBAAoB,CAmBtB"}

package/dist/use-interaction.js

@@ -0,0 +1,46 @@
+/**
+ * useInteraction - React hook for the AppStrata Interaction API.
+ *
+ * Event subscription hook that auto-subscribes on mount and
+ * unsubscribes on unmount. No-op if the "interaction" capability
+ * is unsupported.
+ */
+import { useEffect, useRef } from "react";
+import { usePlayer, useCapability } from "./hooks.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// HOOK
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Subscribe to interaction events (hardware buttons, remote controls, sensors).
+ *
+ * Auto-subscribes on mount, auto-unsubscribes on unmount.
+ * No-op if the "interaction" capability is unsupported.
+ *
+ * @param handler - Event handler called for each interaction event
+ * @returns Object with `supported` boolean
+ *
+ * @example
+ * ```tsx
+ * const { supported } = useInteraction((event) => {
+ *   if (event.type === "key" && event.key === "enter") {
+ *     handleSelect();
+ *   }
+ * });
+ * ```
+ */
+export function useInteraction(handler) {
+    const player = usePlayer();
+    const supported = useCapability("interaction");
+    // Use ref to always call the latest handler without re-subscribing
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => {
+        if (!supported || !player.interaction)
+            return;
+        const unsubscribe = player.interaction.onEvent((event) => {
+            handlerRef.current(event);
+        });
+        return unsubscribe;
+    }, [supported, player]);
+    return { supported };
+}

package/dist/use-media-cache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * useMediaCache - React hook for the AppStrata Media Cache API.
+ *
+ * Data-fetching hook that wraps player.mediaCache.download.
+ * When the capability is unsupported, automatically falls back to using
+ * the original URL as localPath (auto-passthrough), so the app never
+ * needs to branch -- file.localPath always works.
+ */
+import type { MediaFile } from "@appstrata/core";
+/**
+ * Options for useMediaCache.
+ */
+export interface UseMediaCacheOptions {
+    /**
+     * Custom fallback when mediaCache is unsupported.
+     * If not provided, auto-passthrough is used (original URL as localPath).
+     */
+    fallback?: (url: string) => Promise<MediaFile>;
+}
+/**
+ * Return type for useMediaCache.
+ */
+export interface UseMediaCacheResult {
+    /** Cached file info, or auto-passthrough file when unsupported */
+    file: MediaFile | null;
+    /** Whether a download is in progress */
+    loading: boolean;
+    /** Error from the last download attempt */
+    error: Error | null;
+    /** Whether the player supports the "mediaCache" capability (null = not yet initialized) */
+    supported: boolean | null;
+    /** Manually trigger a re-download */
+    refetch: () => Promise<void>;
+}
+/**
+ * Download and cache a media file via the player's Media Cache API.
+ *
+ * Downloads on mount and when the URL changes. Pass `url: null` to skip.
+ *
+ * When the capability is unsupported:
+ * - Without custom fallback: auto-passthrough (original URL as localPath)
+ * - With custom fallback: calls the fallback function
+ *
+ * @param url - URL of media file, or null to skip
+ * @param options - Optional custom fallback
+ *
+ * @example
+ * ```tsx
+ * // Most convenient: just works everywhere
+ * const { file, loading } = useMediaCache("https://example.com/hero.mp4");
+ * // file.localPath is always usable
+ * if (file) return <video src={file.localPath} />;
+ * ```
+ */
+export declare function useMediaCache(url: string | null, options?: UseMediaCacheOptions): UseMediaCacheResult;
+//# sourceMappingURL=use-media-cache.d.ts.map

package/dist/use-media-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-media-cache.d.ts","sourceRoot":"","sources":["../src/use-media-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMjD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,2FAA2F;IAC3F,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,qCAAqC;IACrC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAiCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CA0CrB"}

package/dist/use-media-cache.js

@@ -0,0 +1,100 @@
+/**
+ * useMediaCache - React hook for the AppStrata Media Cache API.
+ *
+ * Data-fetching hook that wraps player.mediaCache.download.
+ * When the capability is unsupported, automatically falls back to using
+ * the original URL as localPath (auto-passthrough), so the app never
+ * needs to branch -- file.localPath always works.
+ */
+import { useState, useEffect, useCallback, useRef } from "react";
+import { usePlayer, useCapability } from "./hooks.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Create a passthrough MediaFile using the original URL as localPath.
+ * Used when mediaCache is unsupported and no custom fallback is provided.
+ */
+function createPassthroughFile(url) {
+    // Extract filename from URL, or use a fallback
+    let fileName;
+    try {
+        const urlObj = new URL(url);
+        fileName = urlObj.pathname.split("/").pop() || "media";
+    }
+    catch {
+        fileName = "media";
+    }
+    return {
+        md5: "",
+        localPath: url,
+        fileName,
+        size: 0,
+        status: "cached",
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// HOOK
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Download and cache a media file via the player's Media Cache API.
+ *
+ * Downloads on mount and when the URL changes. Pass `url: null` to skip.
+ *
+ * When the capability is unsupported:
+ * - Without custom fallback: auto-passthrough (original URL as localPath)
+ * - With custom fallback: calls the fallback function
+ *
+ * @param url - URL of media file, or null to skip
+ * @param options - Optional custom fallback
+ *
+ * @example
+ * ```tsx
+ * // Most convenient: just works everywhere
+ * const { file, loading } = useMediaCache("https://example.com/hero.mp4");
+ * // file.localPath is always usable
+ * if (file) return <video src={file.localPath} />;
+ * ```
+ */
+export function useMediaCache(url, options) {
+    const player = usePlayer();
+    const supported = useCapability("mediaCache");
+    const [file, setFile] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const doDownload = useCallback(async () => {
+        if (!url)
+            return;
+        // Wait for player to initialize before resolving
+        if (supported === null)
+            return;
+        setLoading(true);
+        setError(null);
+        try {
+            if (supported && player.mediaCache) {
+                const result = await player.mediaCache.download(url);
+                setFile(result);
+            }
+            else if (optionsRef.current?.fallback) {
+                const result = await optionsRef.current.fallback(url);
+                setFile(result);
+            }
+            else {
+                // Auto-passthrough: use original URL as localPath
+                setFile(createPassthroughFile(url));
+            }
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [url, supported, player]);
+    useEffect(() => {
+        doDownload();
+    }, [doDownload]);
+    return { file, loading, error, supported, refetch: doDownload };
+}

package/dist/use-proxy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * useProxy - React hook for the AppStrata Proxy API.
+ *
+ * Data-fetching hook that wraps player.proxy.fetch with React state management.
+ * Supports the full ProxyRequest options (method, headers, body, cache) and
+ * an optional fallback function for when the proxy capability is unsupported.
+ */
+import type { ProxyRequest } from "@appstrata/core";
+/**
+ * Options for useProxy, extending ProxyRequest options.
+ */
+export interface UseProxyOptions<T> {
+    /** HTTP method (default: GET) */
+    method?: ProxyRequest["method"];
+    /** Request headers */
+    headers?: ProxyRequest["headers"];
+    /** Request body (for POST/PUT) */
+    body?: ProxyRequest["body"];
+    /** Caching options */
+    cache?: ProxyRequest["cache"];
+    /**
+     * Fallback function called when the proxy capability is unsupported.
+     * Receives the full ProxyRequest so fallback logic can replicate the request.
+     */
+    fallback?: (request: ProxyRequest) => Promise<T>;
+}
+/**
+ * Return type for useProxy.
+ */
+export interface UseProxyResult<T> {
+    /** Fetched data (parsed response), null while loading or if unsupported without fallback */
+    data: T | null;
+    /** Whether a fetch is in progress */
+    loading: boolean;
+    /** Error from the last fetch attempt */
+    error: Error | null;
+    /** Whether the player supports the "proxy" capability (null = not yet initialized) */
+    supported: boolean | null;
+    /** Manually trigger a refetch */
+    refetch: () => Promise<void>;
+}
+/**
+ * Fetch data through the player's proxy API.
+ *
+ * Fetches on mount and when the URL changes. Pass `url: null` to skip fetching.
+ *
+ * @param url - URL to fetch, or null to skip
+ * @param options - Proxy request options and optional fallback
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, error, supported } = useProxy<WeatherData>(
+ *   "https://api.weather.com/current",
+ *   {
+ *     method: "GET",
+ *     headers: { "Accept": "application/json" },
+ *     cache: { maxAge: 300, staleIfError: true },
+ *     fallback: (req) => fetch(req.url, {
+ *       method: req.method,
+ *       headers: req.headers,
+ *       body: req.body,
+ *     }).then(r => r.json()),
+ *   }
+ * );
+ * ```
+ */
+export declare function useProxy<T = unknown>(url: string | null, options?: UseProxyOptions<T>): UseProxyResult<T>;
+//# sourceMappingURL=use-proxy.d.ts.map

package/dist/use-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-proxy.d.ts","sourceRoot":"","sources":["../src/use-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAMpD;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iCAAiC;IACjC,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC,sBAAsB;IACtB,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAClC,kCAAkC;IAClC,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5B,sBAAsB;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,4FAA4F;IAC5F,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,iCAAiC;IACjC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAClC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CAsDnB"}

package/dist/use-proxy.js

@@ -0,0 +1,90 @@
+/**
+ * useProxy - React hook for the AppStrata Proxy API.
+ *
+ * Data-fetching hook that wraps player.proxy.fetch with React state management.
+ * Supports the full ProxyRequest options (method, headers, body, cache) and
+ * an optional fallback function for when the proxy capability is unsupported.
+ */
+import { useState, useEffect, useCallback, useRef } from "react";
+import { usePlayer, useCapability } from "./hooks.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// HOOK
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Fetch data through the player's proxy API.
+ *
+ * Fetches on mount and when the URL changes. Pass `url: null` to skip fetching.
+ *
+ * @param url - URL to fetch, or null to skip
+ * @param options - Proxy request options and optional fallback
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, error, supported } = useProxy<WeatherData>(
+ *   "https://api.weather.com/current",
+ *   {
+ *     method: "GET",
+ *     headers: { "Accept": "application/json" },
+ *     cache: { maxAge: 300, staleIfError: true },
+ *     fallback: (req) => fetch(req.url, {
+ *       method: req.method,
+ *       headers: req.headers,
+ *       body: req.body,
+ *     }).then(r => r.json()),
+ *   }
+ * );
+ * ```
+ */
+export function useProxy(url, options) {
+    const player = usePlayer();
+    const supported = useCapability("proxy");
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Keep options in a ref to avoid re-fetching on every render
+    // when options object is recreated
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const doFetch = useCallback(async () => {
+        if (!url)
+            return;
+        // Wait for player to initialize before resolving
+        if (supported === null)
+            return;
+        const currentOptions = optionsRef.current;
+        const request = {
+            url,
+            method: currentOptions?.method,
+            headers: currentOptions?.headers,
+            body: currentOptions?.body,
+            cache: currentOptions?.cache,
+        };
+        setLoading(true);
+        setError(null);
+        try {
+            if (supported && player.proxy) {
+                const response = await player.proxy.fetch(request);
+                const json = await response.json();
+                setData(json);
+            }
+            else if (currentOptions?.fallback) {
+                const result = await currentOptions.fallback(request);
+                setData(result);
+            }
+            else {
+                // Genuinely unsupported, no fallback: leave data as null
+                setData(null);
+            }
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [url, supported, player]);
+    useEffect(() => {
+        doFetch();
+    }, [doFetch]);
+    return { data, loading, error, supported, refetch: doFetch };
+}

package/dist/use-static.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useStatic - React hook for the AppStrata Static API.
+ *
+ * Convenience hook that returns capability-checked methods.
+ * All methods are safe no-ops if the "static" capability is unsupported.
+ */
+/**
+ * Return type for useStatic.
+ */
+export interface UseStaticResult {
+    /** Whether the player supports the "static" capability (null = not yet initialized) */
+    supported: boolean | null;
+    /** Signal that app is ready for static capture */
+    markStatic: () => void;
+    /** Signal semi-static with refresh interval */
+    markSemiStatic: (refreshIntervalSeconds: number) => void;
+    /** Disable static mode */
+    disableStatic: () => void;
+}
+/**
+ * Access the Static API with safe no-op methods when unsupported.
+ *
+ * Eliminates the need for `player.static?.markStatic()` optional chaining.
+ *
+ * @example
+ * ```tsx
+ * const { markStatic, markSemiStatic, supported } = useStatic();
+ *
+ * useEffect(() => {
+ *   if (isStaticContent) markStatic();
+ *   else markSemiStatic(3600); // refresh hourly
+ * }, [isStaticContent]);
+ * ```
+ */
+export declare function useStatic(): UseStaticResult;
+//# sourceMappingURL=use-static.d.ts.map