@datum-cloud/datum-ui 1.3.1 → 1.4.0

package/dist/components/features/stepper/stepper.d.ts

@@ -30,15 +30,8 @@ declare namespace Stepper {
             Controls: (props: AsChildProps<'div'>) => React.ReactElement;
         };
     }
-    interface CircleStepIndicatorProps {
-        currentStep: number;
-        totalSteps: number;
-        size?: number;
-        strokeWidth?: number;
-    }
 }
 type AsChildProps<T extends React.ElementType> = React.ComponentProps<T> & {
     asChild?: boolean;
 };
 export { defineStepper };
-//# sourceMappingURL=stepper.d.ts.map

package/dist/components/features/stepper/utils.d.ts

@@ -0,0 +1,8 @@
+import type * as Stepperize from '@stepperize/react';
+import * as React from 'react';
+export declare function scrollIntoStepperPanel(node: HTMLDivElement | null, tracking?: boolean): void;
+export declare function useStepChildren(children: React.ReactNode): Map<string, React.ReactNode>;
+export declare function extractChildren(children: React.ReactNode): Map<string, React.ReactNode>;
+export declare function onStepKeyDown(e: React.KeyboardEvent<HTMLButtonElement>, nextStep: Stepperize.Step | undefined, prevStep: Stepperize.Step | undefined, instanceId: string): void;
+export declare function stepDomId(instanceId: string, stepId: string): string;
+export declare function getStepState(currentIndex: number, stepIndex: number): "active" | "inactive" | "completed";

package/dist/components/features/tag-input/index.d.ts

@@ -1,2 +1 @@
 export * from './tag-input';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/tag-input/parse.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+/**
+ * Used for identifying split characters when pasting.
+ * Splits on: newlines, tabs, semicolons, commas, and pipes.
+ * Does NOT split on dots (.) or slashes (/) to preserve email addresses and URLs.
+ */
+export declare const SPLITTER_REGEX: RegExp;
+/**
+ * Used for trimming leading/trailing whitespace and special characters.
+ * Preserves alphanumeric characters, dots, @, hyphens, and underscores.
+ */
+export declare const FORMATTING_REGEX: RegExp;
+/** Default keys that confirm the current input as a tag. */
+export declare const DEFAULT_DELIMITERS: string[];
+/** A function that normalizes a tag value before validation and adding. */
+export type Normalizer = (value: string) => string | null;
+/**
+ * Split a pasted string into candidate tag values.
+ * Trims each value, drops empties, and strips wrapping quote/angle characters.
+ */
+export declare function splitByDelimiters(text: string): string[];
+/**
+ * Trim then apply an optional normalizer.
+ * Returns `null` for empty or normalizer-rejected values.
+ */
+export declare function normalizeTag(raw: string, normalizer?: Normalizer): string | null;
+export interface ValidateResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Validate a single tag value against an optional Zod schema.
+ * Returns `{ ok: true }` when no validator is supplied.
+ */
+export declare function validateTag(value: string, validator?: z.ZodType<string>): ValidateResult;
+export interface ProcessPastedOptions {
+    normalizer?: Normalizer;
+    validator?: z.ZodType<string>;
+    maxItems?: number;
+}
+export interface ProcessPastedResult {
+    /** Normalized, de-duplicated, validated values ready to add. */
+    validValues: string[];
+    /** True when at least one candidate failed schema validation. */
+    hadInvalid: boolean;
+    /** True when candidates were dropped because the max-items limit was reached. */
+    exceededMax: boolean;
+}
+/**
+ * Normalize, de-duplicate, validate and cap a list of pasted candidate values.
+ *
+ * Applies the same normalizer used for single-value entry (so casing rules etc.
+ * are consistent) and reports when values were dropped for validation or the
+ * max-items limit so the caller can surface feedback.
+ */
+export declare function processPastedValues(rawValues: string[], existing: string[], { normalizer, validator, maxItems }?: ProcessPastedOptions): ProcessPastedResult;

package/dist/components/features/tag-input/tag-input-field.d.ts

@@ -0,0 +1,16 @@
+import type * as React from 'react';
+import type { UseTagsInputResult } from './use-tags-input';
+interface TagInputFieldProps {
+    value: string[];
+    placeholder?: string;
+    input: UseTagsInputResult;
+}
+/**
+ * Presentational layer for {@link TagsInput}: renders the tag chips and the
+ * text input, wiring them to the handlers produced by `useTagsInput`.
+ */
+export declare function TagInputField({ value, placeholder, input }: TagInputFieldProps): React.JSX.Element;
+export declare namespace TagInputField {
+    var displayName: string;
+}
+export {};

package/dist/components/features/tag-input/tag-input.d.ts

@@ -1,5 +1,6 @@
+import type { z } from 'zod';
+import type { Normalizer } from './parse';
 import * as React from 'react';
-import { z } from 'zod';
 interface TagsInputProps extends React.HTMLAttributes<HTMLDivElement> {
     value: string[];
     onValueChange: (value: string[]) => void;
@@ -16,7 +17,7 @@ interface TagsInputProps extends React.HTMLAttributes<HTMLDivElement> {
      * Runs after trimming. Returning a falsy value rejects the tag.
      * Useful for case normalization, e.g. (v) => v.toLowerCase()
      */
-    normalizer?: (value: string) => string | null;
+    normalizer?: Normalizer;
     /**
      * Optional Zod schema for validating individual tag values
      */
@@ -46,4 +47,3 @@ export declare namespace TagsInput {
     var displayName: string;
 }
 export {};
-//# sourceMappingURL=tag-input.d.ts.map

package/dist/components/features/tag-input/use-tags-input.d.ts

@@ -0,0 +1,38 @@
+import type { z } from 'zod';
+import type { Normalizer } from './parse';
+import * as React from 'react';
+export interface UseTagsInputOptions {
+    value: string[];
+    onValueChange: (value: string[]) => void;
+    maxItems?: number;
+    minItems?: number;
+    delimiters?: string[];
+    normalizer?: Normalizer;
+    validator?: z.ZodType<string>;
+    onValidationError?: (error: string | null) => void;
+    dir?: string;
+}
+export interface UseTagsInputResult {
+    inputValue: string;
+    setInputValue: React.Dispatch<React.SetStateAction<string>>;
+    activeIndex: number;
+    setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
+    validationError: string | null;
+    setValidationError: React.Dispatch<React.SetStateAction<string | null>>;
+    disableInput: boolean;
+    disableButton: boolean;
+    removeValue: (val: string) => void;
+    handlePaste: (e: React.ClipboardEvent<HTMLInputElement>) => void;
+    handleSelect: (e: React.SyntheticEvent<HTMLInputElement>) => void;
+    handleKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+    handleChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    handleBlur: (e: React.FocusEvent<HTMLInputElement>) => void;
+    mousePreventDefault: (e: React.MouseEvent) => void;
+}
+/**
+ * Owns all state and event handlers for {@link TagsInput}.
+ *
+ * Keeping this in a hook lets the pure parsing/validation logic live in
+ * `parse.ts` while the component stays a thin provider + presentation layer.
+ */
+export declare function useTagsInput({ value, onValueChange, maxItems, minItems, delimiters, normalizer, validator, onValidationError, dir, }: UseTagsInputOptions): UseTagsInputResult;

package/dist/components/features/task-queue/constants.d.ts

@@ -5,4 +5,3 @@ export declare const TASK_QUEUE_DEFAULTS: {
     readonly retryable: true;
 };
 export declare const TASK_STORAGE_KEY = "datum-task-queue";
-//# sourceMappingURL=constants.d.ts.map

package/dist/components/features/task-queue/core/index.d.ts

@@ -7,4 +7,3 @@ export { TaskQueueDropdown } from './task-queue-dropdown';
 export { TaskQueueTrigger } from './task-queue-trigger';
 export { TaskSummaryDialog } from './task-summary-dialog';
 export type { TaskSummaryDialogProps } from './task-summary-dialog';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/task-queue/core/task-panel-actions.d.ts

@@ -4,4 +4,3 @@ interface TaskPanelActionsProps {
 }
 export declare function TaskPanelActions({ task }: TaskPanelActionsProps): import("react").JSX.Element | null;
 export {};
-//# sourceMappingURL=task-panel-actions.d.ts.map

package/dist/components/features/task-queue/core/task-panel-counter.d.ts

@@ -7,4 +7,3 @@ interface TaskPanelCounterProps {
 }
 export declare function TaskPanelCounter({ total, completed, failed, status }: TaskPanelCounterProps): import("react").JSX.Element | null;
 export {};
-//# sourceMappingURL=task-panel-counter.d.ts.map

package/dist/components/features/task-queue/core/task-panel-header.d.ts

@@ -1,2 +1 @@
 export declare function TaskPanelHeader(): import("react").JSX.Element;
-//# sourceMappingURL=task-panel-header.d.ts.map

package/dist/components/features/task-queue/core/task-panel-item.d.ts

@@ -6,4 +6,3 @@ interface TaskPanelItemProps {
 }
 export declare function TaskPanelItem({ task, contextLabel, onCancel }: TaskPanelItemProps): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=task-panel-item.d.ts.map

package/dist/components/features/task-queue/core/task-panel.d.ts

@@ -3,4 +3,3 @@
  * TaskPanel is kept for backward compatibility but is no longer used in the main layout.
  */
 export declare function TaskPanel(): import("react").JSX.Element | null;
-//# sourceMappingURL=task-panel.d.ts.map

package/dist/components/features/task-queue/core/task-queue-dropdown.d.ts

@@ -1,2 +1 @@
 export declare function TaskQueueDropdown(): import("react").JSX.Element;
-//# sourceMappingURL=task-queue-dropdown.d.ts.map

package/dist/components/features/task-queue/core/task-queue-trigger.d.ts

@@ -6,4 +6,3 @@ export declare function TaskQueueTrigger({ ref, tasks, ...props }: TaskQueueTrig
     ref?: React.RefObject<HTMLButtonElement | null>;
 }): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=task-queue-trigger.d.ts.map

package/dist/components/features/task-queue/core/task-summary-dialog.d.ts

@@ -21,4 +21,3 @@ type TaskIdMode = BaseProps & {
 export type TaskSummaryDialogProps = ItemsMode | TaskIdMode;
 export declare function TaskSummaryDialog(props: TaskSummaryDialogProps): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=task-summary-dialog.d.ts.map

package/dist/components/features/task-queue/engine/executor.d.ts

@@ -1,4 +1,4 @@
-import type { Task, TaskContext, TaskOutcome } from '../types';
+import type { Task, TaskContext, TaskOutcome, TaskProcessor } from '../types';
 export interface ExecutorCallbacks {
     onUpdate: (task: Task) => void;
     onCancelReady?: (setCancelled: (v: boolean) => void) => void;
@@ -10,5 +10,4 @@ export declare function createTaskContext<TItem = unknown, TResult = unknown>(ta
     setCancelled: (v: boolean) => void;
     getShouldStop: () => boolean;
 };
-export declare function executeTask<TResult = unknown>(task: Task<TResult>, callbacks: ExecutorCallbacks): Promise<TaskOutcome<TResult>>;
-//# sourceMappingURL=executor.d.ts.map
+export declare function executeTask<TResult = unknown>(inputTask: Task<TResult>, processor: TaskProcessor<TResult> | undefined, callbacks: ExecutorCallbacks): Promise<TaskOutcome<TResult>>;

package/dist/components/features/task-queue/engine/index.d.ts

@@ -2,4 +2,3 @@ export { createTaskContext, executeTask } from './executor';
 export { TaskQueue } from './queue';
 export { detectStorage, LocalTaskStorage, RedisTaskStorage } from './storage';
 export type { TaskStorage } from './storage';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/task-queue/engine/queue.d.ts

@@ -4,20 +4,52 @@ export declare class TaskQueue {
     private concurrency;
     private runningCount;
     private listeners;
-    private taskResolvers;
     private snapshot;
     private notifyScheduled;
-    private processors;
-    private cancelFunctions;
-    private onCompleteCallbacks;
-    private taskTimeouts;
-    private _activeSummary;
-    private _summaryRenderContent;
+    /**
+     * Consolidated, engine-only runtime state (processor, live callbacks, timers)
+     * keyed by task id. Never serialized — persisted tasks only carry the
+     * serializable {@link TaskView} half.
+     */
+    private runtimes;
+    private summary;
+    private disposed;
+    private unsubscribeExternal?;
+    /** Unique id for this queue instance, used to claim ownership of tasks it runs. */
+    private readonly instanceId;
+    /** True when the backend broadcasts writes across tabs (localStorage). */
+    private sharedStorage;
+    /** Keepalive that re-stamps this instance's live tasks in shared storage. */
+    private heartbeatTimer?;
     constructor(config?: TaskQueueConfig);
     subscribe: (listener: () => void) => (() => void);
     getSnapshot: () => Task[];
     private notify;
     private updateSnapshot;
+    /**
+     * Mark tasks a previous session left in a non-terminal state (no live
+     * processor exists for them) as failed, so they become dismissible and stop
+     * triggering the beforeunload guard instead of being stuck forever.
+     */
+    private reconcileOrphans;
+    /**
+     * True when a non-terminal task is claimed by a *different* instance whose
+     * heartbeat is still fresh — i.e. another live tab is running it. A task
+     * without an ownership stamp (legacy, or persisted by a now-dead session) is
+     * not "live foreign" and remains eligible for reconciliation.
+     */
+    private isLiveForeignTask;
+    /** Stamp this instance's ownership on a task before it is written to shared storage. */
+    private withOwnership;
+    /** Start the heartbeat keepalive if shared storage is in use and it is not already running. */
+    private ensureHeartbeat;
+    /**
+     * Refresh the ownership timestamp on every non-terminal task this instance is
+     * actively running, so other tabs keep seeing them as live. Self-stops once
+     * this instance has no more active tasks.
+     */
+    private beat;
+    private stopHeartbeat;
     enqueue: <TItem = unknown, TResult = unknown>(options: EnqueueOptions<TItem, TResult>) => TaskHandle<TResult>;
     cancel: (taskId: string) => void;
     retry: (taskId: string) => void;
@@ -32,11 +64,23 @@ export declare class TaskQueue {
     closeSummary: () => void;
     getActiveSummary: () => TaskSummaryData | null;
     getSummaryRenderContent: () => SummaryRenderContent | undefined;
+    /**
+     * Fully tear down the queue: cancel in-flight and pending tasks, clear all
+     * timers and listeners. Call from the provider on unmount so a re-mounted
+     * provider does not leave orphaned timers/listeners behind.
+     */
+    dispose(): void;
     private buildProcessor;
     private processOneItem;
     private drain;
     private runTask;
+    /**
+     * Resolve a task's awaited handle and fire its onComplete callback exactly
+     * once. When {@link keepForRetry} is false the runtime is discarded.
+     */
+    private finalize;
+    private failOrphan;
     private handleTaskTimeout;
     private clearTaskTimeout;
+    private cleanupRuntime;
 }
-//# sourceMappingURL=queue.d.ts.map

package/dist/components/features/task-queue/engine/storage/detect-storage.d.ts

@@ -16,4 +16,3 @@ interface DetectStorageOptions {
  */
 export declare function detectStorage(options?: DetectStorageOptions): TaskStorage;
 export {};
-//# sourceMappingURL=detect-storage.d.ts.map

package/dist/components/features/task-queue/engine/storage/index.d.ts

@@ -3,4 +3,3 @@ export { LocalTaskStorage } from './local-storage';
 export { MemoryTaskStorage } from './memory-storage';
 export { RedisTaskStorage } from './redis-storage';
 export type { TaskStorage } from './storage';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/task-queue/engine/storage/local-storage.d.ts

@@ -1,12 +1,16 @@
-import type { Task, TaskStorage } from '../../types';
+import type { TaskStorage, TaskView } from '../../types';
 export declare class LocalTaskStorage implements TaskStorage {
     private key;
     constructor(key?: string);
-    getAll(): Task[];
-    get(id: string): Task | undefined;
-    set(id: string, task: Task): void;
+    getAll(): TaskView[];
+    get(id: string): TaskView | undefined;
+    set(id: string, task: TaskView): void;
     remove(id: string): void;
     clear(): void;
+    /**
+     * Notify when another tab writes to the same storage key, so this instance's
+     * consumers can re-read and converge instead of showing stale state.
+     */
+    onExternalChange(callback: () => void): () => void;
     private persist;
 }
-//# sourceMappingURL=local-storage.d.ts.map

package/dist/components/features/task-queue/engine/storage/memory-storage.d.ts

@@ -15,4 +15,3 @@ export declare class MemoryTaskStorage implements TaskStorage {
     remove(id: string): void;
     clear(): void;
 }
-//# sourceMappingURL=memory-storage.d.ts.map

package/dist/components/features/task-queue/engine/storage/redis-storage.d.ts

@@ -1,4 +1,4 @@
-import type { RedisClient, Task, TaskStorage } from '../../types';
+import type { RedisClient, TaskStorage, TaskView } from '../../types';
 export declare class RedisTaskStorage implements TaskStorage {
     private client;
     private key;
@@ -6,18 +6,23 @@ export declare class RedisTaskStorage implements TaskStorage {
     private initialized;
     private initPromise;
     private ttl;
+    private readyCallbacks;
+    private pendingSync;
+    private writeChain;
     constructor(client: RedisClient, key?: string, ttl?: number);
     /**
      * Wait for initialization to complete.
      * Call this before accessing data if you need guaranteed consistency.
      */
     waitForInit(): Promise<void>;
+    /** Invoke `callback` once persisted data has been loaded into the cache. */
+    onReady(callback: () => void): void;
     private initialize;
-    getAll(): Task[];
-    get(id: string): Task | undefined;
-    set(id: string, task: Task): void;
+    getAll(): TaskView[];
+    get(id: string): TaskView | undefined;
+    set(id: string, task: TaskView): void;
     remove(id: string): void;
     clear(): void;
-    private syncToRedis;
+    private scheduleSync;
+    private flush;
 }
-//# sourceMappingURL=redis-storage.d.ts.map

package/dist/components/features/task-queue/engine/storage/serialize.d.ts

@@ -0,0 +1,12 @@
+import type { TaskView } from '../../types';
+/**
+ * Strip a task down to its JSON-serializable fields before persisting.
+ *
+ * Drops the non-serializable members: the in-memory `_processor` reference and
+ * the two fields that can hold React elements or functions — `icon`
+ * (`ReactNode`) and `completionActions` (a `ButtonProps[]` or callback). Left in
+ * place, a `ReactNode` icon sends `JSON.stringify` into circular-reference
+ * territory and throws, aborting the whole persist. `_originalItems` is kept so
+ * retry can resume against the full input set.
+ */
+export declare function toSerializableTask(task: TaskView): Omit<TaskView, 'icon' | 'completionActions' | '_processor'>;

package/dist/components/features/task-queue/engine/storage/storage.d.ts

@@ -1,2 +1 @@
 export type { TaskStorage } from '../../types';
-//# sourceMappingURL=storage.d.ts.map

package/dist/components/features/task-queue/engine/summary-store.d.ts

@@ -0,0 +1,17 @@
+import type { SummaryRenderContent, TaskSummaryData, TaskSummaryItem } from '../types';
+/**
+ * Holds the summary-dialog UI state that is intentionally decoupled from the
+ * task-scheduling engine. Keeping this separate from {@link TaskQueue} means the
+ * scheduler is not responsible for presentation state.
+ */
+export declare class SummaryStore {
+    private activeSummary;
+    private globalRenderContent;
+    constructor(globalRenderContent?: SummaryRenderContent);
+    show(title: string, items: TaskSummaryItem[], options?: {
+        renderContent?: SummaryRenderContent;
+    }): void;
+    close(): void;
+    getActive(): TaskSummaryData | null;
+    getGlobalRenderContent(): SummaryRenderContent | undefined;
+}

package/dist/components/features/task-queue/hooks/index.d.ts

@@ -1,3 +1,2 @@
 export { useTaskQueue } from './use-task-queue';
 export { type CurrentScope, getContextLabel, matchesCurrentScope, type TasksWithLabels, useCurrentScope, useTasksWithLabels, } from './use-task-scope';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/task-queue/hooks/use-task-queue.d.ts

@@ -1,3 +1,2 @@
 import type { TaskQueueAPI, UseTaskQueueOptions } from '../types';
 export declare function useTaskQueue(options?: UseTaskQueueOptions): TaskQueueAPI;
-//# sourceMappingURL=use-task-queue.d.ts.map

package/dist/components/features/task-queue/hooks/use-task-scope.d.ts

@@ -49,4 +49,3 @@ export declare function useTasksWithLabels(tasks: Task[], params: {
     projectId?: string;
     orgId?: string;
 }): TasksWithLabels;
-//# sourceMappingURL=use-task-scope.d.ts.map

package/dist/components/features/task-queue/index.d.ts

@@ -6,4 +6,3 @@ export type { CurrentScope, TasksWithLabels } from './hooks';
 export { TaskQueueProvider } from './provider';
 export type { EnqueueOptions, ItemContext, ProcessItemEnqueueOptions, ProcessorEnqueueOptions, RedisClient, Task, TaskCompletionInfo, TaskContext, TaskHandle, TaskMetadata, TaskOutcome, TaskQueueAPI, TaskQueueConfig, TaskStatus, TaskStorage, TaskSummaryData, TaskSummaryItem, UseTaskQueueOptions, } from './types';
 export { createOrgMetadata, createProjectMetadata, createUserMetadata } from './utils';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/task-queue/provider/index.d.ts

@@ -1,2 +1 @@
 export { TaskQueueContext, TaskQueueProvider } from './task-queue-provider';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/features/task-queue/provider/task-queue-provider.d.ts

@@ -11,4 +11,3 @@ interface TaskQueueProviderProps {
 }
 export declare function TaskQueueProvider({ children, config }: TaskQueueProviderProps): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=task-queue-provider.d.ts.map

package/dist/components/features/task-queue/types.d.ts

@@ -1,6 +1,15 @@
 import type { ReactNode } from 'react';
-import type { ButtonProps } from '../../base/button/button';
+import type { ButtonProps } from '../../base/button';
 export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** Terminal states a task can settle into. Shared by every "outcome" shape. */
+export type TerminalTaskStatus = Extract<TaskStatus, 'completed' | 'failed' | 'cancelled'>;
+/** Canonical per-item result status used across item-result shapes. */
+export type ItemStatus = 'succeeded' | 'failed';
+/** A single failed item recorded on a task/outcome/context. */
+export interface FailedItem {
+    id?: string;
+    message: string;
+}
 export interface TaskMetadata {
     /** Scope type: 'project' | 'org' | 'user' | custom */
     scope?: string;
@@ -12,8 +21,8 @@ export interface TaskMetadata {
     orgId?: string;
     /** Human-readable organization name */
     orgName?: string;
-    /** Extensible - any additional context */
-    [key: string]: unknown;
+    /** Extensible bag for any additional, consumer-defined context. */
+    extra?: Record<string, unknown>;
 }
 export interface TaskCompletionInfo<TItem = unknown> {
     status: TaskStatus;
@@ -21,12 +30,12 @@ export interface TaskCompletionInfo<TItem = unknown> {
     failed: number;
     items: Array<{
         id: string;
-        status: 'succeeded' | 'failed';
+        status: ItemStatus;
         message?: string;
         data: TItem;
     }>;
 }
-export interface Task<TResult = unknown> {
+export interface Task<TResult = unknown, TItem = unknown> {
     id: string;
     title: string;
     status: TaskStatus;
@@ -38,31 +47,51 @@ export interface Task<TResult = unknown> {
     completed: number;
     failed: number;
     succeededItems: string[];
-    failedItems: Array<{
-        id?: string;
-        message: string;
-    }>;
+    failedItems: FailedItem[];
     errorStrategy: 'continue' | 'stop';
     cancelable: boolean;
     retryable: boolean;
     confirmBeforeUnload: boolean;
     result?: TResult;
-    completionActions?: ButtonProps[] | ((result: TResult, info: TaskCompletionInfo) => ButtonProps[]);
+    completionActions?: ButtonProps[] | ((result: TResult, info: TaskCompletionInfo<TItem>) => ButtonProps[]);
     retryOf?: string;
     retryCount: number;
-    _processor?: (ctx: TaskContext<unknown, TResult>) => Promise<void>;
+    _processor?: TaskProcessor<TResult>;
     _originalItems?: unknown[];
     createdAt: number;
     startedAt?: number;
     completedAt?: number;
 }
+/**
+ * The serializable public view of a task — everything storage persists and the
+ * UI renders. Non-serializable engine internals live in {@link TaskRuntime}.
+ */
+export type TaskView<TResult = unknown, TItem = unknown> = Task<TResult, TItem>;
+export type TaskProcessor<TResult = unknown> = (ctx: TaskContext<unknown, TResult>) => Promise<void>;
+/**
+ * Engine-internal, non-serializable runtime state for a single task.
+ *
+ * Held only inside the queue engine and never written to storage. Keeping this
+ * separate from the serializable {@link TaskView} means a persisted task never
+ * carries live functions or timers.
+ */
+export interface TaskRuntime {
+    processor: TaskProcessor;
+    originalItems?: unknown[];
+    getItemId?: (item: unknown) => string | undefined;
+    onComplete?: (outcome: TaskOutcome) => void | Promise<void>;
+    resolve?: (outcome: TaskOutcome) => void;
+    setCancelled?: (cancelled: boolean) => void;
+    timeoutId?: ReturnType<typeof setTimeout>;
+    /** Configured timeout in ms; undefined means "no timeout". */
+    timeoutMs?: number;
+    /** Set once a timeout has fired so the settling processor can't overwrite it. */
+    timedOut?: boolean;
+}
 export interface TaskContext<TItem = unknown, TResult = unknown> {
     readonly items: TItem[];
     readonly cancelled: boolean;
-    readonly failedItems: Array<{
-        id?: string;
-        message: string;
-    }>;
+    readonly failedItems: readonly FailedItem[];
     /** Mark current item as succeeded. Pass itemId to enable retry of remaining items on cancel. */
     succeed: (itemId?: string) => void;
     /** Mark current item as failed. Pass itemId and message for retry support. */
@@ -81,13 +110,10 @@ export interface ItemContext {
     fail: (itemId?: string, message?: string) => void;
 }
 export interface TaskOutcome<TResult = unknown> {
-    status: 'completed' | 'failed' | 'cancelled';
+    status: TerminalTaskStatus;
     completed: number;
     failed: number;
-    failedItems: Array<{
-        id?: string;
-        message: string;
-    }>;
+    failedItems: FailedItem[];
     result?: TResult;
 }
 interface BaseEnqueueOptions<TItem = unknown, TResult = unknown> {
@@ -132,7 +158,11 @@ interface BaseEnqueueOptions<TItem = unknown, TResult = unknown> {
     confirmBeforeUnload?: boolean;
     completionActions?: ButtonProps[] | ((result: TResult, info: TaskCompletionInfo<TItem>) => ButtonProps[]);
     onComplete?: (outcome: TaskOutcome<TResult>) => void | Promise<void>;
-    /** Timeout in milliseconds. Default: 300000 (5 minutes) */
+    /**
+     * Timeout in milliseconds, measured from when the task starts running (not
+     * from enqueue). Default: 300000 (5 minutes). Pass `0` or a negative value to
+     * disable the timeout entirely.
+     */
     timeout?: number;
 }
 /** Full control mode - consumer handles iteration */
@@ -173,11 +203,23 @@ export interface TaskQueueConfig {
     summaryRenderContent?: SummaryRenderContent;
 }
 export interface TaskStorage {
-    getAll: () => Task[];
-    get: (id: string) => Task | undefined;
-    set: (id: string, task: Task) => void;
+    getAll: () => TaskView[];
+    get: (id: string) => TaskView | undefined;
+    set: (id: string, task: TaskView) => void;
     remove: (id: string) => void;
     clear: () => void;
+    /**
+     * Optional hook invoked once an async backend (e.g. Redis) has loaded its
+     * persisted data into the in-memory cache. Lets the engine surface and
+     * reconcile pre-existing tasks after initialization resolves.
+     */
+    onReady?: (callback: () => void) => void;
+    /**
+     * Optional subscription for external mutations to a shared backend (e.g.
+     * another browser tab writing to the same localStorage key). Returns an
+     * unsubscribe function.
+     */
+    onExternalChange?: (callback: () => void) => () => void;
 }
 export interface TaskSummaryItem {
     id: string;
@@ -210,4 +252,3 @@ export interface UseTaskQueueOptions {
     status?: TaskStatus;
 }
 export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/components/features/task-queue/utils/index.d.ts

@@ -34,4 +34,3 @@ export declare function createOrgMetadata(org: {
  * Use this when enqueueing tasks that operate on user-level resources.
  */
 export declare function createUserMetadata(extra?: Record<string, unknown>): TaskMetadata;
-//# sourceMappingURL=index.d.ts.map