@purposeinplay/payload-ai-translate 0.1.0

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

@@ -0,0 +1,70 @@
+/**
+ * Alert-banner grouping for HUB-1 (v1.2.6).
+ *
+ * The Hub Overview used to render every un-dismissed alert as its own
+ * banner. With 10+ "Translation failed repeatedly" rows from a single
+ * cron-stuck batch, the alert stack consumed ~6 vertical screens before
+ * any other Hub content was visible. We now group alerts that share
+ * `(alertType, collection, locale, age-bucket)`, render at most 3
+ * groups expanded with a "+N more" affordance, and offer a single
+ * "Dismiss all" bulk action.
+ *
+ * Helpers exported for unit tests:
+ *
+ *   - `ageBucket(iso, now)` — bucket an alert by relative age so two
+ *     bursts of failures hours apart don't fold into one group.
+ *   - `groupAlerts(rows, now)` — pure reducer; returns ordered groups
+ *     keyed by `(alertType | collection | locale | age-bucket)`.
+ *   - `splitVisibleGroups(groups, max)` — split into the first N
+ *     groups + a tail to be summarised by "+N more".
+ *
+ * The grouping is deterministic and stable: groups appear in the same
+ * order as their newest member, so a new failure surface always
+ * appears at the top.
+ */
+export type AlertAgeBucket = '<5m' | '5–30m' | '30m–1h' | '1–6h' | '6–24h';
+export interface GroupableAlert {
+    id: number;
+    alertType: 'persistent-failure' | 'cost-guard-abort' | 'provider-outage';
+    collection?: string | null;
+    createdAt: string;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AlertGroup<T extends GroupableAlert = GroupableAlert> {
+    /** Stable, deterministic key — `${alertType}|${collection}|${locale}|${bucket}`. */
+    key: string;
+    alertType: T['alertType'];
+    collection: string | null;
+    locale: string | null;
+    bucket: AlertAgeBucket;
+    /** Alerts in the group, sorted newest-first (matches input ordering convention). */
+    alerts: T[];
+    /** The most-recent createdAt across the group — used for sort. */
+    newestCreatedAt: string;
+}
+/**
+ * Bucket an alert's age into a coarse band. Buckets are chosen so that
+ * fresh and old failures stay visually separable in the banner stack
+ * (an editor seeing two distinct "5m" and "6h" groups for the same
+ * locale knows the system is currently failing AND has been for a
+ * while).
+ */
+export declare function ageBucket(iso: string, now?: Date): AlertAgeBucket;
+/**
+ * Group alerts by `(alertType | collection | locale | age-bucket)`.
+ * Returns groups ordered by `newestCreatedAt` descending, so the most
+ * recent failure surface is always first in the stack — preserves the
+ * existing UX expectation that the top banner is the newest event.
+ */
+export declare function groupAlerts<T extends GroupableAlert>(rows: T[], now?: Date): AlertGroup<T>[];
+/**
+ * Slice the group list into the head shown expanded vs the tail
+ * summarised as "+N more". Keep at least 1 visible group so the user
+ * always has something to read. Tail is returned as a count of groups
+ * and total alerts so the caller can render whichever fits the UI.
+ */
+export declare function splitVisibleGroups<T extends GroupableAlert>(groups: AlertGroup<T>[], maxVisible?: number): {
+    visible: AlertGroup<T>[];
+    hiddenGroupCount: number;
+    hiddenAlertCount: number;
+};

package/dist/views/TranslationHub/alertGrouping.js

@@ -0,0 +1,99 @@
+/**
+ * Alert-banner grouping for HUB-1 (v1.2.6).
+ *
+ * The Hub Overview used to render every un-dismissed alert as its own
+ * banner. With 10+ "Translation failed repeatedly" rows from a single
+ * cron-stuck batch, the alert stack consumed ~6 vertical screens before
+ * any other Hub content was visible. We now group alerts that share
+ * `(alertType, collection, locale, age-bucket)`, render at most 3
+ * groups expanded with a "+N more" affordance, and offer a single
+ * "Dismiss all" bulk action.
+ *
+ * Helpers exported for unit tests:
+ *
+ *   - `ageBucket(iso, now)` — bucket an alert by relative age so two
+ *     bursts of failures hours apart don't fold into one group.
+ *   - `groupAlerts(rows, now)` — pure reducer; returns ordered groups
+ *     keyed by `(alertType | collection | locale | age-bucket)`.
+ *   - `splitVisibleGroups(groups, max)` — split into the first N
+ *     groups + a tail to be summarised by "+N more".
+ *
+ * The grouping is deterministic and stable: groups appear in the same
+ * order as their newest member, so a new failure surface always
+ * appears at the top.
+ */ /**
+ * Bucket an alert's age into a coarse band. Buckets are chosen so that
+ * fresh and old failures stay visually separable in the banner stack
+ * (an editor seeing two distinct "5m" and "6h" groups for the same
+ * locale knows the system is currently failing AND has been for a
+ * while).
+ */ export function ageBucket(iso, now = new Date()) {
+    const ms = now.getTime() - new Date(iso).getTime();
+    const m = Math.max(0, Math.floor(ms / 60_000));
+    if (m < 5) return '<5m';
+    if (m < 30) return '5–30m';
+    if (m < 60) return '30m–1h';
+    if (m < 6 * 60) return '1–6h';
+    return '6–24h';
+}
+/** Extract the locale dimension from an alert's metadata (or null). */ function localeOf(alert) {
+    const v = alert.metadata?.['locale'];
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+/**
+ * Group alerts by `(alertType | collection | locale | age-bucket)`.
+ * Returns groups ordered by `newestCreatedAt` descending, so the most
+ * recent failure surface is always first in the stack — preserves the
+ * existing UX expectation that the top banner is the newest event.
+ */ export function groupAlerts(rows, now = new Date()) {
+    const map = new Map();
+    for (const row of rows){
+        const collection = row.collection ?? null;
+        const locale = localeOf(row);
+        const bucket = ageBucket(row.createdAt, now);
+        const key = `${row.alertType}|${collection ?? '∅'}|${locale ?? '∅'}|${bucket}`;
+        const existing = map.get(key);
+        if (existing) {
+            existing.alerts.push(row);
+            if (row.createdAt > existing.newestCreatedAt) {
+                existing.newestCreatedAt = row.createdAt;
+            }
+        } else {
+            map.set(key, {
+                key,
+                alertType: row.alertType,
+                collection,
+                locale,
+                bucket,
+                alerts: [
+                    row
+                ],
+                newestCreatedAt: row.createdAt
+            });
+        }
+    }
+    return Array.from(map.values()).sort((a, b)=>a.newestCreatedAt < b.newestCreatedAt ? 1 : -1);
+}
+/**
+ * Slice the group list into the head shown expanded vs the tail
+ * summarised as "+N more". Keep at least 1 visible group so the user
+ * always has something to read. Tail is returned as a count of groups
+ * and total alerts so the caller can render whichever fits the UI.
+ */ export function splitVisibleGroups(groups, maxVisible = 3) {
+    const safeMax = Math.max(1, maxVisible);
+    if (groups.length <= safeMax) {
+        return {
+            visible: groups,
+            hiddenGroupCount: 0,
+            hiddenAlertCount: 0
+        };
+    }
+    const visible = groups.slice(0, safeMax);
+    const hidden = groups.slice(safeMax);
+    const hiddenAlertCount = hidden.reduce((sum, group)=>sum + group.alerts.length, 0);
+    return {
+        visible,
+        hiddenGroupCount: hidden.length,
+        hiddenAlertCount
+    };
+}

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

@@ -0,0 +1,20 @@
+import type { AdminViewServerProps } from 'payload';
+import type React from 'react';
+/**
+ * Server entry for the custom `/admin/translation` view.
+ *
+ * Wraps the client UI in Payload's `<DefaultTemplate>` so the page
+ * inherits the standard admin chrome (sidebar nav, top bar, breadcrumbs)
+ * — without it, the custom view replaces the entire admin layout and
+ * the operator has no way to navigate back to other surfaces.
+ *
+ * Auth (1.2.8): admin and editor roles. Pre-1.2.8 the gate was
+ * admin-only (Decision #31). Editors get a scoped variant of the Hub
+ * — own bulk runs in the Recent translations table, count-based KPI
+ * cards (no $ / tokens), Configuration / Audit & Cost / Advanced
+ * tabs hidden. Non-admin-non-editor users still see the friendly
+ * Access Denied page. The role is threaded into the client tree so
+ * rendering can adapt without a second roundtrip.
+ */
+export declare const TranslationHubView: React.FC<AdminViewServerProps>;
+export default TranslationHubView;

package/dist/views/TranslationHub/index.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DefaultTemplate } from '@payloadcms/next/templates';
+// Self-import via the package's external subpath. Keeps the "use client"
+// directive intact at runtime — see tsup.config.ts comment above the
+// `ai-translate-views-client` entry. Inlining `./Hub.client` would strip
+// the directive during bundling and break `useState` in production.
+import { TranslationHubClient } from '@purposeinplay/payload-ai-translate/views-client';
+import { redirect } from 'next/navigation';
+import { formatAdminURL } from 'payload/shared';
+/**
+ * Server entry for the custom `/admin/translation` view.
+ *
+ * Wraps the client UI in Payload's `<DefaultTemplate>` so the page
+ * inherits the standard admin chrome (sidebar nav, top bar, breadcrumbs)
+ * — without it, the custom view replaces the entire admin layout and
+ * the operator has no way to navigate back to other surfaces.
+ *
+ * Auth (1.2.8): admin and editor roles. Pre-1.2.8 the gate was
+ * admin-only (Decision #31). Editors get a scoped variant of the Hub
+ * — own bulk runs in the Recent translations table, count-based KPI
+ * cards (no $ / tokens), Configuration / Audit & Cost / Advanced
+ * tabs hidden. Non-admin-non-editor users still see the friendly
+ * Access Denied page. The role is threaded into the client tree so
+ * rendering can adapt without a second roundtrip.
+ */ export const TranslationHubView = ({ initPageResult, params, searchParams })=>{
+    const { req, visibleEntities, permissions } = initPageResult;
+    // Payload renders CUSTOM admin views as PUBLIC by default — unlike
+    // built-in collection/global routes, which redirect unauthenticated
+    // visitors to login. Without this check, anonymous visitors got the
+    // full admin shell (nav with every collection/global name) plus this
+    // view's role message. Mirror the built-in behaviour: no user → login,
+    // preserving the deep link via ?redirect=.
+    if (!req.user) {
+        const adminRoute = req.payload.config.routes?.admin ?? '/admin';
+        redirect(formatAdminURL({
+            adminRoute,
+            path: `/login?redirect=${encodeURIComponent(`${adminRoute}/translation`)}`
+        }));
+    }
+    const user = req.user;
+    const roles = user?.roles ?? [];
+    const isAdmin = roles.includes('admin');
+    const isEditor = roles.includes('editor');
+    const isPermitted = isAdmin || isEditor;
+    const role = isAdmin ? 'admin' : 'editor';
+    return /*#__PURE__*/ _jsx(DefaultTemplate, {
+        i18n: req.i18n,
+        locale: req.locale,
+        params: params,
+        payload: req.payload,
+        permissions: permissions,
+        searchParams: searchParams,
+        user: req.user ?? undefined,
+        visibleEntities: visibleEntities,
+        children: isPermitted ? /*#__PURE__*/ _jsx(TranslationHubClient, {
+            role: role,
+            currentUserId: user?.id != null ? String(user.id) : null,
+            currentUserEmail: user?.email ?? null,
+            locales: req.payload.config.localization ? {
+                defaultLocale: req.payload.config.localization.defaultLocale,
+                locales: req.payload.config.localization.locales.map((l)=>{
+                    if (typeof l === 'string') {
+                        return {
+                            code: l,
+                            label: l
+                        };
+                    }
+                    const rawLabel = l.label;
+                    let label = l.code;
+                    if (typeof rawLabel === 'string') {
+                        label = rawLabel;
+                    } else if (rawLabel) {
+                        label = Object.values(rawLabel)[0] ?? l.code;
+                    }
+                    return {
+                        code: l.code,
+                        label
+                    };
+                })
+            } : {
+                defaultLocale: 'en',
+                locales: []
+            }
+        }) : /*#__PURE__*/ _jsxs("div", {
+            style: {
+                padding: '2rem',
+                maxWidth: '600px',
+                margin: '4rem auto',
+                textAlign: 'center'
+            },
+            children: [
+                /*#__PURE__*/ _jsx("h1", {
+                    style: {
+                        fontSize: '1.5rem',
+                        color: 'var(--theme-elevation-1000)'
+                    },
+                    children: "Translation Hub"
+                }),
+                /*#__PURE__*/ _jsx("p", {
+                    style: {
+                        color: 'var(--theme-elevation-700)'
+                    },
+                    children: "You need an admin or editor role to access translation settings."
+                })
+            ]
+        })
+    });
+};
+export default TranslationHubView;

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

@@ -0,0 +1,53 @@
+/**
+ * Hub tab navigation helpers.
+ *
+ * NEW-4 (v1.2.6): the Hub tab strip rendered as plain `<button>`
+ * elements — no `role="tablist"`, no `role="tab"`, no
+ * `aria-selected`, no arrow-key navigation. Screen readers heard four
+ * generic buttons; the active tab was conveyed only by a visual
+ * `border-bottom`.
+ *
+ * This module owns the WAI-ARIA Authoring Practices tabs pattern's
+ * pure parts: the id naming helpers (tab id / panel id) and the
+ * keyboard-driven next-index resolver. The Hub.client component pulls
+ * them in, wires the actual ARIA attributes on the DOM nodes, and
+ * holds the focus refs (which are inherently a DOM concern).
+ *
+ * Tested in isolation in __tests__/tabNavigation.test.ts.
+ */
+/**
+ * Result of a keyboard event applied to the tab strip. `null` means
+ * the key was unhandled — the consumer should let the event bubble
+ * (e.g. Tab to leave the tablist, Shift+Tab, etc.).
+ */
+export type TabKeyAction = {
+    kind: 'move';
+    nextIndex: number;
+} | {
+    kind: 'ignore';
+} | null;
+/**
+ * Apply the WAI-ARIA Authoring Practices keyboard model for a
+ * horizontal tablist with wrap:
+ *   - ArrowLeft  → previous tab (wraps to last)
+ *   - ArrowRight → next tab (wraps to first)
+ *   - Home       → first tab
+ *   - End        → last tab
+ *
+ * Returns the next focused tab index, or `null` if the key is not one
+ * of the four navigation keys. `count` must be > 0 — caller ensures
+ * the tablist is non-empty before invoking.
+ */
+export declare function resolveTabKey(key: string, currentIndex: number, count: number): TabKeyAction;
+/**
+ * DOM id for the `<button role="tab">` that controls a given panel.
+ * Used by the panel via `aria-labelledby` so the tab's label voices
+ * the panel for screen readers.
+ */
+export declare function tabIdFor(tab: string): string;
+/**
+ * DOM id for the panel a tab controls. Used by the tab via
+ * `aria-controls` so AT can pair the two when the user activates the
+ * tab.
+ */
+export declare function panelIdFor(tab: string): string;

package/dist/views/TranslationHub/tabNavigation.js

@@ -0,0 +1,74 @@
+/**
+ * Hub tab navigation helpers.
+ *
+ * NEW-4 (v1.2.6): the Hub tab strip rendered as plain `<button>`
+ * elements — no `role="tablist"`, no `role="tab"`, no
+ * `aria-selected`, no arrow-key navigation. Screen readers heard four
+ * generic buttons; the active tab was conveyed only by a visual
+ * `border-bottom`.
+ *
+ * This module owns the WAI-ARIA Authoring Practices tabs pattern's
+ * pure parts: the id naming helpers (tab id / panel id) and the
+ * keyboard-driven next-index resolver. The Hub.client component pulls
+ * them in, wires the actual ARIA attributes on the DOM nodes, and
+ * holds the focus refs (which are inherently a DOM concern).
+ *
+ * Tested in isolation in __tests__/tabNavigation.test.ts.
+ */ /**
+ * Result of a keyboard event applied to the tab strip. `null` means
+ * the key was unhandled — the consumer should let the event bubble
+ * (e.g. Tab to leave the tablist, Shift+Tab, etc.).
+ */ /**
+ * Apply the WAI-ARIA Authoring Practices keyboard model for a
+ * horizontal tablist with wrap:
+ *   - ArrowLeft  → previous tab (wraps to last)
+ *   - ArrowRight → next tab (wraps to first)
+ *   - Home       → first tab
+ *   - End        → last tab
+ *
+ * Returns the next focused tab index, or `null` if the key is not one
+ * of the four navigation keys. `count` must be > 0 — caller ensures
+ * the tablist is non-empty before invoking.
+ */ export function resolveTabKey(key, currentIndex, count) {
+    if (count <= 0) {
+        return null;
+    }
+    switch(key){
+        case 'ArrowLeft':
+            return {
+                kind: 'move',
+                nextIndex: (currentIndex - 1 + count) % count
+            };
+        case 'ArrowRight':
+            return {
+                kind: 'move',
+                nextIndex: (currentIndex + 1) % count
+            };
+        case 'Home':
+            return {
+                kind: 'move',
+                nextIndex: 0
+            };
+        case 'End':
+            return {
+                kind: 'move',
+                nextIndex: count - 1
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * DOM id for the `<button role="tab">` that controls a given panel.
+ * Used by the panel via `aria-labelledby` so the tab's label voices
+ * the panel for screen readers.
+ */ export function tabIdFor(tab) {
+    return `translation-hub-tab-${tab}`;
+}
+/**
+ * DOM id for the panel a tab controls. Used by the tab via
+ * `aria-controls` so AT can pair the two when the user activates the
+ * tab.
+ */ export function panelIdFor(tab) {
+    return `translation-hub-panel-${tab}`;
+}

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

@@ -0,0 +1,33 @@
+/** 1h freshness — long enough that the editor sees the run after lunch
+ *  but short enough that an 8h-old "Revert this batch" affordance isn't
+ *  one accidental click away. */
+export declare const TERMINAL_BANNER_FRESHNESS_MS: number;
+/**
+ * Decide whether the terminal banner should still be shown for a batch
+ * based on its `completedAt` timestamp and the current time. Returns
+ * false for batches with no `completedAt` (defensive — a terminal-status
+ * batch should always have one, but we don't want to render a stale
+ * card if the field is missing).
+ */
+export declare function isTerminalBannerFresh(completedAt: string | null | undefined, now?: Date, freshnessMs?: number): boolean;
+/**
+ * Read the dismissed-batch-id set from localStorage. Returns an empty
+ * set on SSR / quota / parse failure.
+ */
+export declare function readDismissedBatchIds(): Set<string>;
+/**
+ * Persist the dismissed-batch-id set to localStorage. Bounds the
+ * persisted list to the last 50 ids so a power user dismissing dozens
+ * of runs over time doesn't grow the entry indefinitely. Swallows any
+ * write failures (quota, private-browsing).
+ */
+export declare function writeDismissedBatchIds(ids: Set<string>): void;
+/**
+ * Hook: returns `{ shouldShow, dismiss }` for the terminal banner of a
+ * given batch. `shouldShow` is true only when the batch is fresh
+ * (≤ 1h past completedAt) AND not in the dismissed set.
+ */
+export declare function useTerminalBannerVisibility(batchId: string | null, completedAt: string | null | undefined): {
+    shouldShow: boolean;
+    dismiss: () => void;
+};

package/dist/views/TranslationHub/terminalBannerVisibility.js

@@ -0,0 +1,124 @@
+/**
+ * Terminal-card freshness + dismissal logic.
+ *
+ * HUB-3 (v1.2.6): the "Bulk run complete · [Revert this batch]" banner
+ * used to persist indefinitely. A batch that completed 8 hours ago kept
+ * the destructive Revert button exposed on the Hub Overview. Two fixes
+ * applied here:
+ *
+ *   1. **Auto-hide after 1 hour past `completedAt`.** After 60 minutes
+ *      the editor has either acked the run or moved on; the row remains
+ *      reachable from `/admin/translation-runs` for the full 24h revert
+ *      window. The banner itself just stops being a sticky top-of-Hub
+ *      element.
+ *   2. **Dismiss-and-remember per batch id, per user.** The dismissed
+ *      list lives in localStorage. Dismissing a batch hides it forever
+ *      on that browser, including across reloads — the original
+ *      symptom that prompted the report.
+ *
+ * The helpers are pure / SSR-safe and exported for unit tests. The
+ * `useTerminalBannerVisibility` hook is the integration glue.
+ */ import { useCallback, useEffect, useMemo, useState } from 'react';
+const STORAGE_KEY = 'cms-plugins.ai-translate.terminalBannerDismissed';
+/** 1h freshness — long enough that the editor sees the run after lunch
+ *  but short enough that an 8h-old "Revert this batch" affordance isn't
+ *  one accidental click away. */ export const TERMINAL_BANNER_FRESHNESS_MS = 60 * 60 * 1000;
+/**
+ * Decide whether the terminal banner should still be shown for a batch
+ * based on its `completedAt` timestamp and the current time. Returns
+ * false for batches with no `completedAt` (defensive — a terminal-status
+ * batch should always have one, but we don't want to render a stale
+ * card if the field is missing).
+ */ export function isTerminalBannerFresh(completedAt, now = new Date(), freshnessMs = TERMINAL_BANNER_FRESHNESS_MS) {
+    if (!completedAt) {
+        return false;
+    }
+    const completedMs = new Date(completedAt).getTime();
+    if (!Number.isFinite(completedMs)) {
+        return false;
+    }
+    return now.getTime() - completedMs <= freshnessMs;
+}
+/**
+ * Read the dismissed-batch-id set from localStorage. Returns an empty
+ * set on SSR / quota / parse failure.
+ */ export function readDismissedBatchIds() {
+    if (typeof window === 'undefined') {
+        return new Set();
+    }
+    try {
+        const raw = window.localStorage.getItem(STORAGE_KEY);
+        if (!raw) {
+            return new Set();
+        }
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return new Set();
+        }
+        return new Set(parsed.filter((v)=>typeof v === 'string'));
+    } catch  {
+        return new Set();
+    }
+}
+/**
+ * Persist the dismissed-batch-id set to localStorage. Bounds the
+ * persisted list to the last 50 ids so a power user dismissing dozens
+ * of runs over time doesn't grow the entry indefinitely. Swallows any
+ * write failures (quota, private-browsing).
+ */ export function writeDismissedBatchIds(ids) {
+    if (typeof window === 'undefined') {
+        return;
+    }
+    try {
+        const list = Array.from(ids).slice(-50);
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(list));
+    } catch  {
+    // best-effort — quota / private-browsing failures are non-fatal.
+    }
+}
+/**
+ * Hook: returns `{ shouldShow, dismiss }` for the terminal banner of a
+ * given batch. `shouldShow` is true only when the batch is fresh
+ * (≤ 1h past completedAt) AND not in the dismissed set.
+ */ export function useTerminalBannerVisibility(batchId, completedAt) {
+    const [dismissedIds, setDismissedIds] = useState(()=>new Set());
+    // Defer localStorage read to mount so SSR renders deterministically
+    // (server can't see localStorage; client hydrates with the persisted
+    // set on first effect).
+    useEffect(()=>{
+        setDismissedIds(readDismissedBatchIds());
+    }, []);
+    const dismiss = useCallback(()=>{
+        if (!batchId) {
+            return;
+        }
+        setDismissedIds((prev)=>{
+            if (prev.has(batchId)) {
+                return prev;
+            }
+            const next = new Set(prev);
+            next.add(batchId);
+            writeDismissedBatchIds(next);
+            return next;
+        });
+    }, [
+        batchId
+    ]);
+    const shouldShow = useMemo(()=>{
+        if (!batchId) {
+            return false;
+        }
+        if (dismissedIds.has(batchId)) {
+            return false;
+        }
+        return isTerminalBannerFresh(completedAt ?? null);
+    }, [
+        batchId,
+        completedAt,
+        dismissedIds
+    ]);
+    return {
+        shouldShow,
+        dismiss
+    };
+}

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

@@ -0,0 +1,49 @@
+import type { BulkTranslateActiveResponse } from './BulkTranslate.types.js';
+interface UseBulkTranslateActiveResult {
+    /**
+     * The most recent successful response. `null` while loading or after
+     * a 404. Distinct from the `loading` flag so consumers can render a
+     * skeleton only on the very first request.
+     */
+    data: BulkTranslateActiveResponse | null;
+    /** True only during the first fetch. Subsequent polls update silently. */
+    loading: boolean;
+    /**
+     * Latest error message after a network/server failure. Reset to
+     * `null` on the next successful response. The 404 -> empty-batch
+     * shortcut does NOT populate this field.
+     */
+    error: string | null;
+    /** True after `OFFLINE_AFTER_FAILED_POLLS` consecutive failures. */
+    isOffline: boolean;
+    /** Forces an immediate poll. Used by the offline-banner retry button. */
+    refetch: () => void;
+}
+interface PollState {
+    data: BulkTranslateActiveResponse | null;
+    loading: boolean;
+    error: string | null;
+    failedPollStreak: number;
+}
+/**
+ * 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 declare function subscribeToBulkActive(basePath: string, listener: () => void): () => void;
+/** Test-only: read the current snapshot for a base path. */
+export declare function getBulkActiveSnapshot(basePath: string): PollState;
+/** Test-only: reset the registry between tests. */
+export declare function __resetBulkActiveRegistryForTests(): void;
+/** Test-only: snapshot of refcounts per base path. */
+export declare function __getBulkActiveRefCountsForTests(): Record<string, number>;
+export declare function useBulkTranslateActive(basePath: string): UseBulkTranslateActiveResult;
+/**
+ * Exported for tests so they can compare against the same threshold the
+ * hook uses internally.
+ */
+export declare const BULK_TRANSLATE_OFFLINE_THRESHOLD = 3;
+export declare const BULK_TRANSLATE_POLL_INTERVAL_MS = 5000;
+export {};