@purposeinplay/payload-ai-translate 0.1.0

package/dist/views/TranslationHub/useBulkTranslateActive.js

@@ -0,0 +1,251 @@
+'use client';
+/**
+ * Shared polling hook for the bulk-translate "active batch" endpoint.
+ *
+ * Owns the 5s visibility-aware poll loop, the offline-banner threshold
+ * (F-UX-11: 3 consecutive failures → degraded), and the multi-admin
+ * synchronization expected by F-UX-05. The trigger, monitor, and
+ * terminal card all subscribe to the same single source of truth.
+ *
+ * A 404 from the endpoint is treated as "no active batch" — the
+ * endpoints are being built in parallel and we don't want the Hub to
+ * crash if a consumer integrates the UI before the backend lands.
+ *
+ * NEW-5 (v1.2.6): the hook previously owned its own `useEffect` +
+ * `setInterval` per mount. The Hub renders three consumers in parallel
+ * (`Hub.client.tsx` for the monitor/terminal card,
+ * `BulkTranslateTrigger.tsx` for the "is a run already active?" check,
+ * `BulkTranslatePostEnqueueTransition.tsx` after the modal closes), so
+ * the network panel showed pairs of requests every ~5s. The hook now
+ * delegates polling to a module-level singleton — one subscriber per
+ * `basePath`, ref-counted so the interval shuts down cleanly when the
+ * last consumer unmounts — and components receive the shared state via
+ * `useSyncExternalStore`. Single request per tick regardless of how
+ * many components subscribe.
+ */ import { useCallback, useSyncExternalStore } from 'react';
+import { readResponseError } from '../shared/fetch-error-body.js';
+// Active polling cadence — used while a bulk batch is in flight. The
+// trigger / monitor / terminal cards all expect ~5s updates so the
+// progress bar and per-doc status feels live.
+const POLL_INTERVAL_MS = 5000;
+// Idle cadence — used when there is no active batch. Pre-1.2.8 the
+// poll re-queued at POLL_INTERVAL_MS unconditionally, so any admin
+// session with the Translation Hub mounted (or any view that uses
+// `useBulkTranslateActive` — the Bulk Translate trigger button does)
+// kept hitting `/api/translation-hub/bulk-translate/active` every 5s
+// forever. Backing off to 60s when idle still gives the trigger
+// reasonable cross-tab freshness (if user A starts a run, user B's
+// idle tab sees it within a minute) without the constant background
+// chatter.
+const IDLE_POLL_INTERVAL_MS = 60_000;
+const OFFLINE_AFTER_FAILED_POLLS = 3;
+const registry = new Map();
+function getEntry(basePath) {
+    let entry = registry.get(basePath);
+    if (entry) return entry;
+    entry = {
+        state: {
+            data: null,
+            loading: true,
+            error: null,
+            failedPollStreak: 0
+        },
+        refCount: 0,
+        listeners: new Set(),
+        timer: undefined,
+        active: false,
+        onVisibility: undefined,
+        forcePoll: ()=>undefined
+    };
+    registry.set(basePath, entry);
+    return entry;
+}
+function emit(entry) {
+    for (const listener of entry.listeners){
+        listener();
+    }
+}
+function updateState(entry, patch) {
+    // Build a fresh state object so `useSyncExternalStore` consumers see
+    // a stable reference change and re-render.
+    entry.state = {
+        ...entry.state,
+        ...patch
+    };
+    emit(entry);
+}
+async function fetchOnce(basePath, entry) {
+    if (!entry.active) return;
+    try {
+        const res = await fetch(`${basePath}/api/translation-hub/bulk-translate/active`, {
+            credentials: 'include'
+        });
+        if (!entry.active) return;
+        if (res.status === 404) {
+            // Endpoint not yet deployed OR no active batch — both render
+            // the same "idle" state in the trigger.
+            updateState(entry, {
+                data: {
+                    batch: null
+                },
+                error: null,
+                failedPollStreak: 0,
+                loading: false
+            });
+            return;
+        }
+        if (!res.ok) {
+            throw new Error(await readResponseError(res));
+        }
+        const json = await res.json();
+        if (!entry.active) return;
+        updateState(entry, {
+            data: json,
+            error: null,
+            failedPollStreak: 0,
+            loading: false
+        });
+    } catch (e) {
+        if (!entry.active) return;
+        updateState(entry, {
+            error: e instanceof Error ? e.message : String(e),
+            failedPollStreak: entry.state.failedPollStreak + 1,
+            loading: false
+        });
+    } finally{
+        if (entry.active && typeof document !== 'undefined' && document.visibilityState === 'visible') {
+            // Cadence-aware polling: tight (5s) only while a batch is
+            // genuinely in flight. The /active endpoint keeps serving
+            // TERMINAL batches for the 24h revert-visibility window — those
+            // (and error states, where `data.batch` holds its stale value)
+            // must poll at the relaxed cadence. Fast-polling a finished
+            // batch for 24h multiplied the endpoint's per-poll unit scans
+            // across every open Hub tab and helped take prod down on
+            // 2026-06-10.
+            const batchStatus = entry.state.data?.batch?.status;
+            const isInFlight = batchStatus === 'queued' || batchStatus === 'running' || batchStatus === 'cancelling';
+            const nextDelay = isInFlight ? POLL_INTERVAL_MS : IDLE_POLL_INTERVAL_MS;
+            entry.timer = setTimeout(()=>fetchOnce(basePath, entry), nextDelay);
+        }
+    }
+}
+function startPolling(basePath, entry) {
+    if (entry.active) return;
+    entry.active = true;
+    entry.forcePoll = ()=>{
+        if (entry.timer) {
+            clearTimeout(entry.timer);
+            entry.timer = undefined;
+        }
+        void fetchOnce(basePath, entry);
+    };
+    entry.onVisibility = ()=>{
+        if (typeof document !== 'undefined' && document.visibilityState === 'visible' && entry.active) {
+            entry.forcePoll();
+        }
+    };
+    if (typeof document !== 'undefined') {
+        document.addEventListener('visibilitychange', entry.onVisibility);
+    }
+    void fetchOnce(basePath, entry);
+}
+function stopPolling(basePath, entry) {
+    entry.active = false;
+    if (entry.timer) {
+        clearTimeout(entry.timer);
+        entry.timer = undefined;
+    }
+    if (entry.onVisibility && typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', entry.onVisibility);
+    }
+    entry.onVisibility = undefined;
+    entry.forcePoll = ()=>undefined;
+    // Reset state so the next subscriber sees a fresh loading frame
+    // instead of stale cached data from a previous mount.
+    entry.state = {
+        data: null,
+        loading: true,
+        error: null,
+        failedPollStreak: 0
+    };
+    registry.delete(basePath);
+}
+/**
+ * Acquire a subscription slot for `basePath`. Increments the ref-count
+ * and starts polling on first subscriber. Returns an unsubscribe
+ * function that decrements + stops polling when the last subscriber
+ * unmounts. Exported for the test fixture; consumers should call
+ * `useBulkTranslateActive`.
+ */ export function subscribeToBulkActive(basePath, listener) {
+    const entry = getEntry(basePath);
+    entry.listeners.add(listener);
+    entry.refCount += 1;
+    if (entry.refCount === 1) {
+        startPolling(basePath, entry);
+    }
+    return ()=>{
+        entry.listeners.delete(listener);
+        entry.refCount -= 1;
+        if (entry.refCount <= 0) {
+            stopPolling(basePath, entry);
+        }
+    };
+}
+/** Test-only: read the current snapshot for a base path. */ export function getBulkActiveSnapshot(basePath) {
+    return getEntry(basePath).state;
+}
+/** Test-only: reset the registry between tests. */ export function __resetBulkActiveRegistryForTests() {
+    for (const [basePath, entry] of registry){
+        if (entry.timer) clearTimeout(entry.timer);
+        if (entry.onVisibility && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', entry.onVisibility);
+        }
+        registry.delete(basePath);
+    }
+}
+/** Test-only: snapshot of refcounts per base path. */ export function __getBulkActiveRefCountsForTests() {
+    const out = {};
+    for (const [basePath, entry] of registry){
+        out[basePath] = entry.refCount;
+    }
+    return out;
+}
+export function useBulkTranslateActive(basePath) {
+    // `useSyncExternalStore` is the React-recommended primitive for
+    // subscribing to an external store. The subscribe callback wires the
+    // refcount; the getSnapshot returns the current state object. React
+    // re-renders consumers when emit() fires.
+    const subscribe = useCallback((listener)=>subscribeToBulkActive(basePath, listener), [
+        basePath
+    ]);
+    const getSnapshot = useCallback(()=>getEntry(basePath).state, [
+        basePath
+    ]);
+    // SSR-safe server snapshot. The Hub renders client-only but Payload's
+    // admin shell hydrates from server-rendered markup, so a stable
+    // server snapshot avoids a hydration mismatch flash.
+    const getServerSnapshot = useCallback(()=>({
+            data: null,
+            loading: true,
+            error: null,
+            failedPollStreak: 0
+        }), []);
+    const state = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const refetch = useCallback(()=>{
+        getEntry(basePath).forcePoll();
+    }, [
+        basePath
+    ]);
+    return {
+        data: state.data,
+        loading: state.loading,
+        error: state.error,
+        isOffline: state.failedPollStreak >= OFFLINE_AFTER_FAILED_POLLS,
+        refetch
+    };
+}
+/**
+ * Exported for tests so they can compare against the same threshold the
+ * hook uses internally.
+ */ export const BULK_TRANSLATE_OFFLINE_THRESHOLD = OFFLINE_AFTER_FAILED_POLLS;
+export const BULK_TRANSLATE_POLL_INTERVAL_MS = POLL_INTERVAL_MS;

package/dist/views/TranslationHub/useFocusTrap.d.ts

@@ -0,0 +1,6 @@
+export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, options: {
+    /** If true, the trap is active. Skip work when surface is closed. */
+    enabled: boolean;
+    /** Invoked on Escape key. */
+    onEscape?: () => void;
+}): void;

package/dist/views/TranslationHub/useFocusTrap.js

@@ -0,0 +1,81 @@
+'use client';
+/**
+ * Minimal focus-trap implementation for the bulk-translate modal and
+ * drawer. Per F-UX-10 the spec requires:
+ *
+ *  - Focus the first interactive element when the surface opens.
+ *  - Tab / Shift+Tab loops within the surface.
+ *  - Escape triggers the close callback.
+ *  - Focus returns to the trigger element on close.
+ *
+ * We deliberately avoid pulling in a focus-trap library — the surface
+ * is small, the requirements are small, and the cms-plugins package
+ * already keeps third-party deps to a minimum.
+ */ import { useEffect } from 'react';
+const FOCUSABLE = [
+    'a[href]',
+    'button:not([disabled])',
+    'textarea:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])'
+].join(',');
+export function useFocusTrap(containerRef, options) {
+    const { enabled, onEscape } = options;
+    useEffect(()=>{
+        if (!enabled) {
+            return;
+        }
+        const node = containerRef.current;
+        if (!node) {
+            return;
+        }
+        // Save the element that owned focus before the surface opened so
+        // we can restore it on close. Useful for screen-reader users and
+        // anyone who triggered the surface via keyboard.
+        const previouslyFocused = document.activeElement;
+        // Focus first interactive element. RAF defers until paint so
+        // refs inside the surface are populated.
+        const raf = requestAnimationFrame(()=>{
+            const first = node.querySelector(FOCUSABLE);
+            if (first) {
+                first.focus();
+            }
+        });
+        function onKey(e) {
+            if (e.key === 'Escape') {
+                onEscape?.();
+                return;
+            }
+            if (e.key !== 'Tab') {
+                return;
+            }
+            const focusable = Array.from(node.querySelectorAll(FOCUSABLE)).filter((el)=>!el.hasAttribute('disabled'));
+            if (focusable.length === 0) {
+                return;
+            }
+            const first = focusable[0];
+            const last = focusable[focusable.length - 1];
+            const active = document.activeElement;
+            if (e.shiftKey && active === first) {
+                e.preventDefault();
+                last.focus();
+            } else if (!e.shiftKey && active === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+        document.addEventListener('keydown', onKey);
+        return ()=>{
+            cancelAnimationFrame(raf);
+            document.removeEventListener('keydown', onKey);
+            if (previouslyFocused && document.contains(previouslyFocused)) {
+                previouslyFocused.focus();
+            }
+        };
+    }, [
+        containerRef,
+        enabled,
+        onEscape
+    ]);
+}

package/dist/views/TranslationHub/useTranslationHubUsageSummary.d.ts

@@ -0,0 +1,77 @@
+export type UsageSummaryRangeKey = {
+    kind: '7d' | '30d' | '90d' | 'all';
+} | {
+    kind: 'custom';
+    from?: string;
+    to?: string;
+};
+export interface UsageSummaryShape {
+    totals: {
+        runs: number;
+        succeeded: number;
+        preserved: number;
+        failed: number;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        totalMatching: number;
+        truncated: boolean;
+    };
+    byCollection: Array<{
+        slug: string;
+        kind: 'collection' | 'global';
+        runs: number;
+        tokens: number;
+        costUsd: number;
+    }>;
+    byModel: Array<{
+        model: string;
+        runs: number;
+        tokens: number;
+        costUsd: number;
+    }>;
+    byLocale: Array<{
+        locale: string;
+        runs: number;
+        failed: number;
+    }>;
+    samples: Array<{
+        id: number | string;
+        createdAt: string;
+        slug: string;
+        kind: 'collection' | 'global';
+        documentId?: string | null;
+        status: 'succeeded' | 'failed';
+        model?: string | null;
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCostUsd?: number | null;
+        durationMs?: number | null;
+        error?: string | null;
+        failedCount: number;
+        succeededCount: number;
+        targetLocales?: Array<{
+            locale: string;
+            status?: 'succeeded' | 'failed' | null;
+        }> | null;
+    }>;
+}
+export interface UseTranslationHubUsageSummaryResult {
+    data: UsageSummaryShape | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+interface FetchState {
+    data: UsageSummaryShape | null;
+    loading: boolean;
+    error: string | null;
+}
+export declare function subscribeToTranslationHubUsageSummary(basePath: string, range: UsageSummaryRangeKey, listener: () => void): () => void;
+export declare function getTranslationHubUsageSummarySnapshot(basePath: string, range: UsageSummaryRangeKey): FetchState;
+/** Test-only: reset between tests. */
+export declare function __resetTranslationHubUsageSummaryRegistryForTests(): void;
+/** Test-only: snapshot of refcounts. */
+export declare function __getTranslationHubUsageSummaryRefCountsForTests(): Record<string, number>;
+export declare function useTranslationHubUsageSummary(basePath: string, range: UsageSummaryRangeKey): UseTranslationHubUsageSummaryResult;
+export {};

package/dist/views/TranslationHub/useTranslationHubUsageSummary.js

@@ -0,0 +1,267 @@
+'use client';
+/**
+ * Singleton fetcher for `/api/translation-hub/usage-summary` (ROUND2-4).
+ *
+ * Mirrors the singleton-registry pattern in `useBulkTranslateActive` —
+ * one module-level cache keyed by `(basePath, range)`, ref-counted
+ * subscribers, `useSyncExternalStore` for React reactivity. Multiple
+ * mounts of `StatusStrip` + `AuditPanel` (same Hub page, same range)
+ * share ONE network request instead of each component firing its own.
+ *
+ * Before this hook:
+ *   - StatusStrip and AuditPanel each owned their own `useEffect` +
+ *     `fetch()`.
+ *   - React 18 StrictMode dev-double-render produced two requests
+ *     within ~2.8 ms on every mount.
+ *   - A page that surfaced both consumers (Overview + Audit & Cost on
+ *     the same tab swap) doubled cost on the backend SUM-aggregation,
+ *     which runs across `translation_usage` — potentially thousands of
+ *     rows.
+ *
+ * With this hook:
+ *   - `useTranslationHubUsageSummary(basePath, range, from?, to?)`
+ *     returns `{ data, loading, error, refetch }`.
+ *   - Concurrent subscribers (same key) share one in-flight request
+ *     and one cached result.
+ *   - Range / from / to changes invalidate the cached entry and fire a
+ *     fresh request.
+ *   - Refetch is exposed for explicit user-driven reloads (none today
+ *     — this view is read-only — but matches the API surface of every
+ *     other hook in this plugin so future "Refresh" affordances drop
+ *     in cleanly).
+ */ import { useCallback, useSyncExternalStore } from 'react';
+import { readResponseError } from '../shared/fetch-error-body.js';
+const registry = new Map();
+/**
+ * ROUND3-2: TTL window during which an idle entry (refCount === 0)
+ * survives in the registry. Mirrors the staleTime semantics that
+ * TanStack Query exposes — when an editor flips Overview → Audit & Cost
+ * → Overview within this window the second mount serves from the warm
+ * cache instead of paying the SQL aggregation cost again. 60s strikes
+ * the same balance as the default TanStack `gcTime` shoulder.
+ */ const CACHE_TTL_MS = 60_000;
+/**
+ * ROUND3-3: retry policy on `fetchOnce` failures. Exponential backoff
+ * with three attempts — 1s, 3s, 9s — matches the upper bound on a
+ * transient network blip / 502 retry-after. After the third failure we
+ * stop auto-retrying and surface the error to the consumer; the
+ * `refetch()` button lets the editor try again on their schedule.
+ */ const MAX_RETRY_ATTEMPTS = 3;
+const RETRY_BACKOFF_MS = [
+    1_000,
+    3_000,
+    9_000
+];
+/**
+ * Build a stable key from the URL query params we'd send. We compose
+ * `basePath` + URL search so two `custom` ranges with different
+ * `from/to` stay isolated.
+ */ function buildKey(basePath, range) {
+    const params = new URLSearchParams();
+    if (range.kind === 'custom') {
+        params.set('range', 'custom');
+        if (range.from) params.set('from', range.from);
+        if (range.to) params.set('to', range.to);
+    } else {
+        params.set('range', range.kind);
+    }
+    return `${basePath}?${params.toString()}`;
+}
+function buildUrl(basePath, range) {
+    const params = new URLSearchParams();
+    if (range.kind === 'custom') {
+        params.set('range', 'custom');
+        if (range.from) params.set('from', range.from);
+        if (range.to) params.set('to', range.to);
+    } else {
+        params.set('range', range.kind);
+    }
+    return `${basePath}/api/translation-hub/usage-summary?${params.toString()}`;
+}
+function getEntry(key) {
+    let entry = registry.get(key);
+    if (entry) return entry;
+    entry = {
+        state: {
+            data: null,
+            loading: true,
+            error: null
+        },
+        refCount: 0,
+        listeners: new Set(),
+        hasFetched: false,
+        forceFetch: ()=>undefined,
+        evictTimer: null,
+        lastFetchedAt: 0,
+        failureStreak: 0,
+        retryTimer: null
+    };
+    registry.set(key, entry);
+    return entry;
+}
+function emit(entry) {
+    for (const listener of entry.listeners){
+        listener();
+    }
+}
+function updateState(entry, patch) {
+    entry.state = {
+        ...entry.state,
+        ...patch
+    };
+    emit(entry);
+}
+async function fetchOnce(basePath, range, key) {
+    const entry = getEntry(key);
+    if (entry.refCount === 0) return;
+    try {
+        const res = await fetch(buildUrl(basePath, range), {
+            credentials: 'include'
+        });
+        if (!res.ok) {
+            throw new Error(await readResponseError(res));
+        }
+        const json = await res.json();
+        if (entry.refCount === 0) return;
+        entry.failureStreak = 0;
+        entry.lastFetchedAt = Date.now();
+        updateState(entry, {
+            data: json,
+            loading: false,
+            error: null
+        });
+    } catch (e) {
+        if (entry.refCount === 0) return;
+        const message = e instanceof Error ? e.message : String(e);
+        // ROUND3-3: auto-retry transient failures with exponential backoff.
+        // After MAX_RETRY_ATTEMPTS we surface the error to the consumer
+        // and let the editor decide via the `refetch` affordance.
+        entry.failureStreak += 1;
+        if (entry.failureStreak < MAX_RETRY_ATTEMPTS) {
+            const delay = RETRY_BACKOFF_MS[entry.failureStreak - 1] ?? RETRY_BACKOFF_MS[RETRY_BACKOFF_MS.length - 1] ?? 9_000;
+            // Keep `loading: true` so consumers don't flash the error chrome
+            // between attempts. The error surfaces only when we run out of
+            // retries.
+            updateState(entry, {
+                loading: true,
+                error: null
+            });
+            if (entry.retryTimer) clearTimeout(entry.retryTimer);
+            entry.retryTimer = setTimeout(()=>{
+                entry.retryTimer = null;
+                if (entry.refCount === 0) return;
+                void fetchOnce(basePath, range, key);
+            }, delay);
+            return;
+        }
+        updateState(entry, {
+            loading: false,
+            error: message
+        });
+    }
+}
+export function subscribeToTranslationHubUsageSummary(basePath, range, listener) {
+    const key = buildKey(basePath, range);
+    const entry = getEntry(key);
+    entry.listeners.add(listener);
+    entry.refCount += 1;
+    // ROUND3-2: a pending eviction means we were within the TTL window
+    // when this new subscriber arrived. Cancel the timer so the cached
+    // payload survives and the subscriber gets a warm hit on the next
+    // `getSnapshot` call. No new request fires.
+    if (entry.evictTimer) {
+        clearTimeout(entry.evictTimer);
+        entry.evictTimer = null;
+    }
+    // First subscriber on this key fires the request. Subsequent
+    // subscribers re-use the same cached entry — that's the doubling
+    // fix.
+    if (!entry.hasFetched) {
+        entry.hasFetched = true;
+        entry.forceFetch = ()=>{
+            // Explicit user-driven refetch: reset failure streak so the
+            // backoff window starts fresh.
+            entry.failureStreak = 0;
+            if (entry.retryTimer) {
+                clearTimeout(entry.retryTimer);
+                entry.retryTimer = null;
+            }
+            updateState(entry, {
+                loading: true,
+                error: null
+            });
+            void fetchOnce(basePath, range, key);
+        };
+        void fetchOnce(basePath, range, key);
+    }
+    return ()=>{
+        entry.listeners.delete(listener);
+        entry.refCount -= 1;
+        if (entry.refCount <= 0) {
+            // ROUND3-2: defer eviction. Keep the cached entry alive for
+            // CACHE_TTL_MS so a quick tab-switch (Overview → Audit → Overview)
+            // or range-flip (7d → 30d → 7d) re-uses the warm payload instead
+            // of paying the SQL aggregation cost again. Any new subscriber
+            // arriving within the window cancels this timer above.
+            if (entry.evictTimer) clearTimeout(entry.evictTimer);
+            entry.evictTimer = setTimeout(()=>{
+                // Double-check refCount in case a subscriber raced in. If a new
+                // one is here, leave the entry alone.
+                const current = registry.get(key);
+                if (!current || current.refCount > 0) return;
+                if (current.retryTimer) clearTimeout(current.retryTimer);
+                registry.delete(key);
+            }, CACHE_TTL_MS);
+        }
+    };
+}
+export function getTranslationHubUsageSummarySnapshot(basePath, range) {
+    return getEntry(buildKey(basePath, range)).state;
+}
+/** Test-only: reset between tests. */ export function __resetTranslationHubUsageSummaryRegistryForTests() {
+    for (const entry of registry.values()){
+        if (entry.evictTimer) clearTimeout(entry.evictTimer);
+        if (entry.retryTimer) clearTimeout(entry.retryTimer);
+    }
+    registry.clear();
+}
+/** Test-only: snapshot of refcounts. */ export function __getTranslationHubUsageSummaryRefCountsForTests() {
+    const out = {};
+    for (const [key, entry] of registry){
+        out[key] = entry.refCount;
+    }
+    return out;
+}
+export function useTranslationHubUsageSummary(basePath, range) {
+    // `range` may be a fresh object each render — stringify into a stable
+    // key the hook subscriptions can dedupe on.
+    const key = buildKey(basePath, range);
+    const subscribe = useCallback((listener)=>subscribeToTranslationHubUsageSummary(basePath, range, listener), // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        basePath,
+        key
+    ]);
+    const getSnapshot = useCallback(()=>getEntry(key).state, [
+        key
+    ]);
+    // SSR snapshot — Payload's admin shell hydrates from server-rendered
+    // markup. Returning a stable "loading" state matches what the
+    // client-side render will show on first paint.
+    const getServerSnapshot = useCallback(()=>({
+            data: null,
+            loading: true,
+            error: null
+        }), []);
+    const state = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const refetch = useCallback(()=>{
+        getEntry(key).forceFetch();
+    }, [
+        key
+    ]);
+    return {
+        data: state.data,
+        loading: state.loading,
+        error: state.error,
+        refetch
+    };
+}