@purposeinplay/payload-ai-translate 0.1.0

package/dist/views/shared/EditorError.d.ts

@@ -0,0 +1,97 @@
+import type React from 'react';
+import { type EditorErrorContext } from '../../lib/error-messages.js';
+/**
+ * Plain-English error render component. Every editor-facing error site
+ * (AlertBanner, UsageTable expanded row, BulkRunsHub DrillDown failed-unit
+ * detail, FailureDrawer rows, action toasts) routes through this rather
+ * than dumping raw `err.message` text or internal codes like
+ * `permanent.config`.
+ *
+ * What it gives the editor:
+ *  - A friendly title + body (from `editorMessageFor(code, context)`).
+ *  - An optional action CTA — what to actually do next.
+ *  - When `details` is non-empty: a collapsible "Show technical details"
+ *    `<details>` element holding the raw provider / validator string.
+ *    Collapsed by default; engineering can expand to debug.
+ *  - When the code is a permanent failure (`bulk.permanent.*`,
+ *    `cost-guard.*`): an inline expandable "Why won't this work?" block
+ *    explaining the failure mode, and (if `onRetry` is supplied) a
+ *    disabled retry button with the same explanation as its tooltip.
+ *
+ * What it explicitly avoids:
+ *  - Showing the raw `code` string anywhere visible.
+ *  - Showing the raw `details` string at the top level.
+ *  - Encouraging a retry click on a permanent failure (which would just
+ *    fail again with the same root cause).
+ */
+type EditorErrorTone = 'error' | 'warning' | 'info' | 'muted';
+export type EditorErrorProps = {
+    /**
+     * Editor-facing code from `lib/error-messages.ts`. Renders the catalogue
+     * message for it. When omitted or unknown the catalogue falls back to a
+     * generic "Something went wrong" message — never undefined/blank.
+     */
+    code: string | null | undefined;
+    /**
+     * Context for templating the code's message (count, locale, $spent,
+     * etc.). Each formatter in the catalogue uses what it needs and ignores
+     * the rest, so over-supplying is safe.
+     */
+    context?: EditorErrorContext;
+    /**
+     * Raw provider / validator / exception text. When non-empty, surfaces
+     * as a collapsible "Show technical details" disclosure under the body.
+     * Never rendered at the top level — engineering-only detail.
+     */
+    details?: string | null;
+    /**
+     * Visual severity. Default is inferred from the code: permanent
+     * failures + persistent alerts render as `error`, cost-guards and
+     * soft-skips as `warning`, markers (cancel/reset) as `muted`.
+     */
+    tone?: EditorErrorTone;
+    /**
+     * Compact layout for in-table / inline contexts (no banner background,
+     * no border, tighter spacing). The action CTA still renders. Use this
+     * inside an already-styled card (e.g. UsageTable expanded row).
+     */
+    compact?: boolean;
+    /**
+     * Hide the action CTA (e.g. when the surrounding component already
+     * provides its own Retry / Open Document button and the CTA copy
+     * would duplicate it).
+     */
+    hideAction?: boolean;
+    /**
+     * Optional retry callback. When supplied:
+     *   - For non-permanent codes: renders an enabled "Try again" button
+     *     that calls this callback.
+     *   - For permanent codes: renders the button disabled with the
+     *     "Why won't this work?" explanation as tooltip + inline block.
+     * When omitted, no retry surface renders.
+     */
+    onRetry?: () => void;
+    /** Loading state for the retry button. */
+    retryPending?: boolean;
+    /**
+     * Inline `style` overrides for the outer container. Used by callers
+     * that need to slot the component into a specific layout.
+     */
+    style?: React.CSSProperties;
+};
+export declare const EditorError: React.FC<EditorErrorProps>;
+/**
+ * Lightweight one-liner for in-table / chip / status-cell contexts.
+ * Renders ONLY the title from `editorMessageFor`. When you need more
+ * (body, action, details disclosure), use `<EditorError>` instead.
+ *
+ * Useful for spaces where the row already has its own row-level affordance
+ * and we just want the friendly text in place of `failureCode` or
+ * `reason` strings.
+ */
+export declare const EditorErrorChip: React.FC<{
+    code: string | null | undefined;
+    context?: EditorErrorContext;
+    title?: string;
+}>;
+export {};

package/dist/views/shared/EditorError.js

@@ -0,0 +1,205 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { editorMessageFor, isPermanentFailure } from '../../lib/error-messages.js';
+const TONE_COLORS = {
+    error: {
+        bg: 'var(--theme-error-100, #fee2e2)',
+        border: 'var(--theme-error-500, #b91c1c)',
+        fg: 'var(--theme-error-500, #b91c1c)'
+    },
+    warning: {
+        bg: 'var(--theme-warning-100, #fef3c7)',
+        border: 'var(--theme-warning-500, #d97706)',
+        fg: 'var(--theme-warning-500, #d97706)'
+    },
+    info: {
+        bg: 'var(--theme-elevation-50, #f1f5f9)',
+        border: 'var(--theme-elevation-200, #cbd5e1)',
+        fg: 'var(--theme-elevation-800, #1e293b)'
+    },
+    muted: {
+        bg: 'transparent',
+        border: 'var(--theme-elevation-100, #e5e7eb)',
+        fg: 'var(--theme-elevation-700, #475569)'
+    }
+};
+/**
+ * Default tone derived from the code prefix. Callers can override via
+ * the `tone` prop when context warrants (e.g. an error-tone banner for
+ * a soft-skip when many fields failed).
+ */ function defaultToneForCode(code) {
+    if (!code) return 'error';
+    if (code.startsWith('marker.')) return 'muted';
+    if (code.startsWith('soft-skip.')) return 'warning';
+    if (code.startsWith('cost-guard.')) return 'warning';
+    if (code === 'alert.cost-guard-abort') return 'warning';
+    if (code === 'bulk.transient.rate_limited') return 'warning';
+    if (code === 'bulk.transient.provider') return 'warning';
+    if (code === 'bulk.permanent.deleted') return 'info';
+    return 'error';
+}
+export const EditorError = ({ code, context, details, tone, compact = false, hideAction = false, onRetry, retryPending = false, style })=>{
+    const message = editorMessageFor(code ?? undefined, context ?? {});
+    const resolvedTone = tone ?? defaultToneForCode(code);
+    const colors = TONE_COLORS[resolvedTone];
+    const permanent = isPermanentFailure(code);
+    const [explanationOpen, setExplanationOpen] = useState(false);
+    const containerStyle = compact ? {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '0.35rem',
+        padding: 0,
+        background: 'transparent',
+        border: 'none',
+        borderRadius: 0,
+        ...style
+    } : {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '0.5rem',
+        padding: '0.75rem 1rem',
+        background: colors.bg,
+        border: `1px solid ${colors.border}`,
+        borderRadius: '6px',
+        ...style
+    };
+    return /*#__PURE__*/ _jsxs("div", {
+        style: containerStyle,
+        children: [
+            /*#__PURE__*/ _jsx("div", {
+                style: {
+                    fontSize: compact ? '0.8rem' : '0.875rem',
+                    fontWeight: 600,
+                    color: colors.fg,
+                    lineHeight: 1.3
+                },
+                children: message.title
+            }),
+            /*#__PURE__*/ _jsx("div", {
+                style: {
+                    fontSize: compact ? '0.75rem' : '0.8rem',
+                    color: 'var(--theme-elevation-900)',
+                    lineHeight: 1.5
+                },
+                children: message.body
+            }),
+            !hideAction && message.action && /*#__PURE__*/ _jsx("div", {
+                style: {
+                    fontSize: compact ? '0.7rem' : '0.75rem',
+                    color: 'var(--theme-elevation-700)',
+                    fontStyle: 'italic'
+                },
+                children: message.action
+            }),
+            permanent && message.explanation && /*#__PURE__*/ _jsxs("div", {
+                style: {
+                    marginTop: '0.15rem'
+                },
+                children: [
+                    /*#__PURE__*/ _jsx("button", {
+                        "aria-expanded": explanationOpen,
+                        onClick: ()=>setExplanationOpen((v)=>!v),
+                        style: {
+                            background: 'transparent',
+                            border: 'none',
+                            padding: 0,
+                            cursor: 'pointer',
+                            color: colors.fg,
+                            fontSize: '0.75rem',
+                            fontWeight: 500,
+                            textDecoration: 'underline'
+                        },
+                        type: "button",
+                        children: explanationOpen ? 'Hide explanation' : 'Why won’t this work?'
+                    }),
+                    explanationOpen && /*#__PURE__*/ _jsx("div", {
+                        style: {
+                            fontSize: '0.75rem',
+                            color: 'var(--theme-elevation-800)',
+                            lineHeight: 1.5,
+                            marginTop: '0.35rem',
+                            padding: '0.5rem 0.65rem',
+                            background: 'var(--theme-elevation-50, #f8fafc)',
+                            borderLeft: `2px solid ${colors.border}`,
+                            borderRadius: '3px'
+                        },
+                        children: message.explanation
+                    })
+                ]
+            }),
+            onRetry && /*#__PURE__*/ _jsx("div", {
+                style: {
+                    marginTop: '0.25rem'
+                },
+                children: /*#__PURE__*/ _jsx("button", {
+                    disabled: permanent || retryPending,
+                    onClick: onRetry,
+                    style: {
+                        padding: '0.3rem 0.7rem',
+                        background: permanent ? 'var(--theme-elevation-100, #e5e7eb)' : colors.fg,
+                        color: permanent ? 'var(--theme-elevation-600, #64748b)' : '#fff',
+                        border: 'none',
+                        borderRadius: '4px',
+                        fontSize: '0.75rem',
+                        fontWeight: 500,
+                        cursor: permanent || retryPending ? 'not-allowed' : 'pointer',
+                        opacity: retryPending ? 0.6 : 1
+                    },
+                    title: permanent ? message.explanation ?? 'This error won’t be fixed by retrying.' : undefined,
+                    type: "button",
+                    children: retryPending ? 'Retrying…' : 'Try again'
+                })
+            }),
+            details && /*#__PURE__*/ _jsxs("details", {
+                style: {
+                    marginTop: '0.25rem',
+                    fontSize: '0.7rem',
+                    color: 'var(--theme-elevation-600, #64748b)'
+                },
+                children: [
+                    /*#__PURE__*/ _jsx("summary", {
+                        style: {
+                            cursor: 'pointer',
+                            userSelect: 'none',
+                            padding: '0.1rem 0'
+                        },
+                        children: "Show technical details"
+                    }),
+                    /*#__PURE__*/ _jsx("pre", {
+                        style: {
+                            marginTop: '0.35rem',
+                            padding: '0.5rem 0.65rem',
+                            background: 'var(--theme-elevation-50, #f8fafc)',
+                            border: '1px solid var(--theme-elevation-100, #e5e7eb)',
+                            borderRadius: '3px',
+                            fontSize: '0.7rem',
+                            fontFamily: 'ui-monospace, SFMono-Regular, monospace',
+                            whiteSpace: 'pre-wrap',
+                            wordBreak: 'break-word',
+                            maxHeight: '12rem',
+                            overflowY: 'auto',
+                            margin: 0
+                        },
+                        children: details
+                    })
+                ]
+            })
+        ]
+    });
+};
+/**
+ * Lightweight one-liner for in-table / chip / status-cell contexts.
+ * Renders ONLY the title from `editorMessageFor`. When you need more
+ * (body, action, details disclosure), use `<EditorError>` instead.
+ *
+ * Useful for spaces where the row already has its own row-level affordance
+ * and we just want the friendly text in place of `failureCode` or
+ * `reason` strings.
+ */ export const EditorErrorChip = ({ code, context, title })=>{
+    const message = editorMessageFor(code ?? undefined, context ?? {});
+    return /*#__PURE__*/ _jsx("span", {
+        title: title ?? message.body,
+        children: message.title
+    });
+};

package/dist/views/shared/ModelCell.d.ts

@@ -0,0 +1,18 @@
+import type React from 'react';
+/**
+ * Renders a usage-row `model` value in a table cell. Real OpenRouter
+ * model ids (`provider/model`) render verbatim; falsy / provider-only
+ * fallbacks (`'openrouter'`, `null`, `''`) collapse to a friendly
+ * italic "Failed before model selection" — the run never reached a
+ * specific model.
+ *
+ * Used by:
+ *   - `TranslationHub/UsageTable.tsx` (Overview → Recent translations)
+ *   - `TranslationHub/AuditPanel.tsx`  (Audit & Cost → Recent failures)
+ *
+ * Kept in sync via this single component so both surfaces agree on the
+ * same copy / styling. See ROUND4-1.
+ */
+export declare const ModelCell: React.FC<{
+    model: string | null | undefined;
+}>;

package/dist/views/shared/ModelCell.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { isRealModelId } from '../TranslationHub/AuditPanel.helpers.js';
+/**
+ * Renders a usage-row `model` value in a table cell. Real OpenRouter
+ * model ids (`provider/model`) render verbatim; falsy / provider-only
+ * fallbacks (`'openrouter'`, `null`, `''`) collapse to a friendly
+ * italic "Failed before model selection" — the run never reached a
+ * specific model.
+ *
+ * Used by:
+ *   - `TranslationHub/UsageTable.tsx` (Overview → Recent translations)
+ *   - `TranslationHub/AuditPanel.tsx`  (Audit & Cost → Recent failures)
+ *
+ * Kept in sync via this single component so both surfaces agree on the
+ * same copy / styling. See ROUND4-1.
+ */ export const ModelCell = ({ model })=>{
+    if (isRealModelId(model)) {
+        return /*#__PURE__*/ _jsx(_Fragment, {
+            children: model
+        });
+    }
+    return /*#__PURE__*/ _jsx("span", {
+        style: {
+            color: 'var(--theme-elevation-500)',
+            fontStyle: 'italic',
+            fontFamily: 'inherit'
+        },
+        title: "The run failed before a specific model was selected — typically a configuration or provider error.",
+        children: "Failed before model selection"
+    });
+};

package/dist/views/shared/docHref.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Build a Payload admin URL for a single document, optionally pinned
+ * to a target locale via `?locale=`. Used by every Hub surface that
+ * links into a translated document so the user lands on the locale
+ * they want to verify (not the source locale).
+ *
+ * Centralising avoids the 3 drifted copies previously living in
+ * UsageTable / AuditPanel / BatchRow / FailureDrawer (none of which
+ * appended `?locale=`).
+ */
+export declare function docHref(basePath: string, collectionSlug: string, documentId: string | number, locale?: string | null): string;
+/**
+ * Build a Payload admin URL for a global. Globals are addressed by slug
+ * only; the locale param works the same way.
+ */
+export declare function globalHref(basePath: string, globalSlug: string, locale?: string | null): string;

package/dist/views/shared/docHref.js

@@ -0,0 +1,26 @@
+/**
+ * Build a Payload admin URL for a single document, optionally pinned
+ * to a target locale via `?locale=`. Used by every Hub surface that
+ * links into a translated document so the user lands on the locale
+ * they want to verify (not the source locale).
+ *
+ * Centralising avoids the 3 drifted copies previously living in
+ * UsageTable / AuditPanel / BatchRow / FailureDrawer (none of which
+ * appended `?locale=`).
+ */ export function docHref(basePath, collectionSlug, documentId, locale) {
+    const base = `${basePath}/admin/collections/${encodeURIComponent(collectionSlug)}/${encodeURIComponent(String(documentId))}`;
+    if (locale && locale.length > 0) {
+        return `${base}?locale=${encodeURIComponent(locale)}`;
+    }
+    return base;
+}
+/**
+ * Build a Payload admin URL for a global. Globals are addressed by slug
+ * only; the locale param works the same way.
+ */ export function globalHref(basePath, globalSlug, locale) {
+    const base = `${basePath}/admin/globals/${encodeURIComponent(globalSlug)}`;
+    if (locale && locale.length > 0) {
+        return `${base}?locale=${encodeURIComponent(locale)}`;
+    }
+    return base;
+}

package/dist/views/shared/fetch-error-body.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read a structured error body from a non-OK Response. The plugin's
+ * endpoint helper (`endpoints/translation-hub/_helpers.ts:errorResponse`)
+ * returns `{ error: { code, message } }` on failure. This returns just
+ * the editor-facing `message`; callers wanting the `code` for catalogue
+ * rendering (`editorMessageFor(code)`) should use `readResponseErrorBody`.
+ *
+ * Falls back to a generic friendly message when the body isn't structured —
+ * never throws.
+ *
+ * 1.2.5 change: stopped appending `(${code})` to the message. The code
+ * was leaking engineering jargon to editors; callers that need it now
+ * pull it via the structured `readResponseErrorBody` helper.
+ */
+export declare function readResponseError(res: Response): Promise<string>;
+/**
+ * Structured variant. Returns both `code` and `message` so callers can
+ * render via the editor-facing catalogue (`editorMessageFor(code)`)
+ * with the raw `message` as a disclosure fallback. Use this at every
+ * Hub UI fetch site that surfaces the error inside an `<EditorError>`.
+ */
+export declare function readResponseErrorBody(res: Response): Promise<{
+    code: string | undefined;
+    message: string;
+}>;

package/dist/views/shared/fetch-error-body.js

@@ -0,0 +1,42 @@
+/**
+ * Read a structured error body from a non-OK Response. The plugin's
+ * endpoint helper (`endpoints/translation-hub/_helpers.ts:errorResponse`)
+ * returns `{ error: { code, message } }` on failure. This returns just
+ * the editor-facing `message`; callers wanting the `code` for catalogue
+ * rendering (`editorMessageFor(code)`) should use `readResponseErrorBody`.
+ *
+ * Falls back to a generic friendly message when the body isn't structured —
+ * never throws.
+ *
+ * 1.2.5 change: stopped appending `(${code})` to the message. The code
+ * was leaking engineering jargon to editors; callers that need it now
+ * pull it via the structured `readResponseErrorBody` helper.
+ */ export async function readResponseError(res) {
+    const parsed = await readResponseErrorBody(res);
+    return parsed.message;
+}
+/**
+ * Structured variant. Returns both `code` and `message` so callers can
+ * render via the editor-facing catalogue (`editorMessageFor(code)`)
+ * with the raw `message` as a disclosure fallback. Use this at every
+ * Hub UI fetch site that surfaces the error inside an `<EditorError>`.
+ */ export async function readResponseErrorBody(res) {
+    try {
+        const body = await res.json();
+        if (body && typeof body === 'object') {
+            const err = body.error;
+            if (err && typeof err.message === 'string' && err.message.length > 0) {
+                return {
+                    code: err.code,
+                    message: err.message
+                };
+            }
+        }
+    } catch  {
+    // Body wasn't JSON / stream consumed elsewhere. Fall through.
+    }
+    return {
+        code: undefined,
+        message: res.status >= 500 ? 'The server returned an error. Try again, or contact engineering if it keeps happening.' : 'The request couldn’t be completed. Try again, or refresh the page.'
+    };
+}

package/dist/views/shared/filterPillStyle.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared filter-pill style helper.
+ *
+ * Used by every filter / range / status pill row in the Translation Hub
+ * and BulkRunsHub surfaces (FilterBar, BatchRow drill-down chips,
+ * SummaryStrip, StatusStrip, AuditPanel). Extracted to fix v1.2.6
+ * BugIndex BR-5 + NEW-21:
+ *
+ *   - Before: active pill bg = `elevation-150` / `-200`, sitting beside
+ *     inactive pills whose border is also `elevation-150` / `-200`. The
+ *     adjacent UI non-text contrast was 1.0:1 — active state was only
+ *     signalled by font-weight. WCAG 1.4.11 requires ≥ 3:1 for
+ *     state-bearing UI.
+ *   - After: active pill bg = `elevation-1000` (near-black) + text
+ *     `elevation-50` (near-white) on light theme. The state contrast vs
+ *     inactive pill borders is ≥ 7:1, well above the AA non-text bar,
+ *     and the active pill reads as a distinct chip at a glance even
+ *     without font-weight signalling.
+ *
+ * Keep the helper small. Each pill row sets its own padding / font-size
+ * to match the surrounding surface — only the colour tokens are unified.
+ */
+import type React from 'react';
+export type FilterPillColors = {
+    background: React.CSSProperties['background'];
+    color: React.CSSProperties['color'];
+    border: React.CSSProperties['border'];
+};
+/**
+ * Resolve a pill's background / text / border colours from its active
+ * state. The active state uses `--theme-elevation-1000` (near-black on
+ * light theme, near-white on dark) so it never blends with the inactive
+ * pills' borders — fixes BR-5 and NEW-21.
+ */
+export declare function filterPillColors(isActive: boolean): FilterPillColors;

package/dist/views/shared/filterPillStyle.js

@@ -0,0 +1,40 @@
+/**
+ * Shared filter-pill style helper.
+ *
+ * Used by every filter / range / status pill row in the Translation Hub
+ * and BulkRunsHub surfaces (FilterBar, BatchRow drill-down chips,
+ * SummaryStrip, StatusStrip, AuditPanel). Extracted to fix v1.2.6
+ * BugIndex BR-5 + NEW-21:
+ *
+ *   - Before: active pill bg = `elevation-150` / `-200`, sitting beside
+ *     inactive pills whose border is also `elevation-150` / `-200`. The
+ *     adjacent UI non-text contrast was 1.0:1 — active state was only
+ *     signalled by font-weight. WCAG 1.4.11 requires ≥ 3:1 for
+ *     state-bearing UI.
+ *   - After: active pill bg = `elevation-1000` (near-black) + text
+ *     `elevation-50` (near-white) on light theme. The state contrast vs
+ *     inactive pill borders is ≥ 7:1, well above the AA non-text bar,
+ *     and the active pill reads as a distinct chip at a glance even
+ *     without font-weight signalling.
+ *
+ * Keep the helper small. Each pill row sets its own padding / font-size
+ * to match the surrounding surface — only the colour tokens are unified.
+ */ /**
+ * Resolve a pill's background / text / border colours from its active
+ * state. The active state uses `--theme-elevation-1000` (near-black on
+ * light theme, near-white on dark) so it never blends with the inactive
+ * pills' borders — fixes BR-5 and NEW-21.
+ */ export function filterPillColors(isActive) {
+    if (isActive) {
+        return {
+            background: 'var(--theme-elevation-1000)',
+            color: 'var(--theme-elevation-50)',
+            border: '1px solid var(--theme-elevation-1000)'
+        };
+    }
+    return {
+        background: 'transparent',
+        color: 'var(--theme-elevation-700)',
+        border: '1px solid var(--theme-elevation-200)'
+    };
+}

package/dist/views/shared/format.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared cost / duration formatters for Translation Hub + Bulk Translate
+ * Runs surfaces. v1.2.6 BugIndex NEW-17 + NEW-18 + NEW-10.
+ *
+ * Before extracting these, every surface (Hub Overview, Audit, Runs,
+ * batch rows, drill-down) rolled its own threshold logic. The result:
+ *   - Hub Overview "Estimated cost" showed `$0.54`
+ *   - Audit "Total spend" showed `53.6¢`
+ *   - Runs "Last 7 days cost" showed `$0.51`
+ *   - Batch row Cost column showed `12.4¢`
+ *   - Drill-down unit-detail showed `2.1¢`
+ *   - Bucket-row duration showed `964m 6s` with no hours carryover
+ *
+ * Same underlying value (cents, ms), five different formats.
+ *
+ * The contract here is the only contract going forward. Every cost /
+ * duration render site MUST import `formatCost` / `formatDuration`. Do
+ * NOT roll new threshold rules at the call site.
+ *
+ * `formatCost` rule (1.2.8):
+ *   - All values render as `$X.YY[YY]` (USD, dollar sign always present).
+ *   - Sub-cent values use up to 4 decimals so editors can tell a
+ *     0.46¢ run from a 0.88¢ run — but the unit is consistently $,
+ *     never the ¢ glyph (it was being mis-read as `$X.YY¢` on dense
+ *     tables and made per-doc costs look 100× higher than they were).
+ *   - Values ≥ $0.01 stay at the standard 2-decimal $X.YY form.
+ *
+ *   Wait — that was the OLD rule. The Group F brief locks this in:
+ *   `$X.XX` with 2 decimals; switch to `Y.Y¢` ONLY when value < $0.01
+ *   (or, equivalently, < 1¢).
+ *
+ *   So: < $0.01 → `Y.YY¢`, else `$X.XX`.
+ *
+ * `formatDuration` rule:
+ *   ms → s → m → h → d, carrying everywhere. Show two units of
+ *   precision when the next-down unit would otherwise be lost
+ *   (e.g. `16h 38m`, `5m 16s`, `42s`).
+ */
+/**
+ * Render a USD value with consistent rules.
+ *
+ * @param usd Dollars (e.g. 0.124 means 12.4 cents). `null` / `undefined`
+ *   / non-finite → `'—'`. Negative → coerced to `0`.
+ * @returns
+ *   - `'—'` when missing or non-finite
+ *   - `'$0.00'` when exactly zero
+ *   - `'$0.YYYY'` (USD, four decimals) when 0 < value < $0.01
+ *   - `'$X.XX'` (USD, two decimals) otherwise
+ *
+ * Tests pin the boundaries — see `__tests__/format.test.ts`.
+ */
+export declare function formatCost(usd: number | null | undefined): string;
+/**
+ * Render a duration in ms with full carry-over from ms → s → m → h → d.
+ *
+ * @param ms Duration in milliseconds. `null` / `undefined` / non-finite
+ *   → `'—'`. Zero → `'—'` by convention (matches the legacy `fmtUsd`
+ *   behaviour the call sites relied on). Negative → coerced to `0` →
+ *   `'—'`.
+ * @returns
+ *   - `'—'` when missing / non-finite / non-positive
+ *   - `'Nms'` when < 1s
+ *   - `'N.Ns'` when < 10s (one decimal, e.g. `3.4s`)
+ *   - `'Ns'` when < 60s
+ *   - `'Nm Ss'` when < 1h (e.g. `5m 16s`)
+ *   - `'Nh Mm'` when < 24h (e.g. `16h 38m`)
+ *   - `'Nd Hh'` when ≥ 24h (e.g. `2d 4h`)
+ *
+ * The rule is the same one BatchRow.tsx implemented for batch-level
+ * durations; lifting it here so BucketRow stops capping at minutes and
+ * rendering `964m 6s`. See NEW-18.
+ *
+ * Tests pin the boundaries — see `__tests__/format.test.ts`.
+ */
+export declare function formatDuration(ms: number | null | undefined): string;