@n-dx/web 0.1.0

package/dist/viewer/hooks/use-pan-zoom.js

@@ -0,0 +1,110 @@
+/**
+ * usePanZoom — SVG viewport panning and zooming hook.
+ *
+ * Handles:
+ * - Trackpad/mouse wheel scrolling (pan) and pinch-to-zoom (ctrl+wheel)
+ * - Mouse-drag panning on the SVG background
+ * - Programmatic zoom-in, zoom-out, and fit-to-content controls
+ */
+import { useState, useCallback, useRef, useEffect } from "preact/hooks";
+/**
+ * Hook that manages SVG pan/zoom state and interaction handlers.
+ *
+ * @param fitVB - The "fit to content" viewBox dimensions
+ */
+export function usePanZoom(fitVB) {
+    const svgRef = useRef(null);
+    const [panning, setPanning] = useState(false);
+    const panStart = useRef(null);
+    const [viewBox, setViewBox] = useState(fitVB);
+    useEffect(() => {
+        setViewBox(fitVB);
+    }, [fitVB]);
+    const handleWheel = useCallback((e) => {
+        e.preventDefault();
+        const svg = svgRef.current;
+        if (!svg)
+            return;
+        const rect = svg.getBoundingClientRect();
+        // ctrlKey = pinch-zoom on trackpad (or ctrl+scroll on mouse) → zoom
+        if (e.ctrlKey) {
+            const fx = (e.clientX - rect.left) / rect.width;
+            const fy = (e.clientY - rect.top) / rect.height;
+            // Clamp deltaY to reduce sensitivity: ±2px max effect per event
+            const clamped = Math.max(-2, Math.min(2, e.deltaY));
+            const zoomFactor = 1 + clamped * 0.02;
+            setViewBox((vb) => {
+                const newW = vb.w * zoomFactor;
+                const newH = vb.h * zoomFactor;
+                const newX = vb.x + (vb.w - newW) * fx;
+                const newY = vb.y + (vb.h - newH) * fy;
+                return { x: newX, y: newY, w: newW, h: newH };
+            });
+            return;
+        }
+        // Regular scroll / two-finger drag on trackpad → pan
+        setViewBox((vb) => {
+            const scaleX = vb.w / rect.width;
+            const scaleY = vb.h / rect.height;
+            return {
+                ...vb,
+                x: vb.x + e.deltaX * scaleX,
+                y: vb.y + e.deltaY * scaleY,
+            };
+        });
+    }, []);
+    const startPan = useCallback((e) => {
+        setPanning(true);
+        panStart.current = { x: e.clientX, y: e.clientY, vbx: viewBox.x, vby: viewBox.y };
+    }, [viewBox]);
+    const movePan = useCallback((e) => {
+        if (!panning || !panStart.current || !svgRef.current)
+            return;
+        const rect = svgRef.current.getBoundingClientRect();
+        const scaleX = viewBox.w / rect.width;
+        const scaleY = viewBox.h / rect.height;
+        const dx = (e.clientX - panStart.current.x) * scaleX;
+        const dy = (e.clientY - panStart.current.y) * scaleY;
+        setViewBox((vb) => ({
+            ...vb,
+            x: panStart.current.vbx - dx,
+            y: panStart.current.vby - dy,
+        }));
+    }, [panning, viewBox.w, viewBox.h]);
+    const endPan = useCallback(() => {
+        setPanning(false);
+        panStart.current = null;
+    }, []);
+    const handleZoomIn = useCallback(() => {
+        setViewBox((vb) => ({
+            x: vb.x + vb.w * 0.1,
+            y: vb.y + vb.h * 0.1,
+            w: vb.w * 0.8,
+            h: vb.h * 0.8,
+        }));
+    }, []);
+    const handleZoomOut = useCallback(() => {
+        setViewBox((vb) => ({
+            x: vb.x - vb.w * 0.125,
+            y: vb.y - vb.h * 0.125,
+            w: vb.w * 1.25,
+            h: vb.h * 1.25,
+        }));
+    }, []);
+    const handleFit = useCallback(() => {
+        setViewBox(fitVB);
+    }, [fitVB]);
+    return {
+        viewBox,
+        panning,
+        svgRef,
+        handleWheel,
+        startPan,
+        movePan,
+        endPan,
+        handleZoomIn,
+        handleZoomOut,
+        handleFit,
+    };
+}
+//# sourceMappingURL=use-pan-zoom.js.map

package/dist/viewer/hooks/use-pan-zoom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-pan-zoom.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-pan-zoom.ts"],"names":[],"mappings":"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"}

package/dist/viewer/hooks/use-persistent-filter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Persistent status filter state for the PRD tree.
+ *
+ * Stores the active status filter selection in a module-level variable
+ * so it survives component mount/unmount cycles (e.g. when the user
+ * navigates from the PRD tree to the Rex Dashboard and back).
+ *
+ * The hook returns the current state and a setter, mirroring useState.
+ */
+import type { ItemStatus } from "../components/prd-tree/types.js";
+export interface PersistentFilterState {
+    /** Currently active (visible) statuses. */
+    activeStatuses: Set<ItemStatus>;
+    /** Update the active statuses (also persists across remounts). */
+    setActiveStatuses: (statuses: Set<ItemStatus>) => void;
+}
+/**
+ * Hook that provides filter state which persists across view switches.
+ *
+ * On first mount (or after a full page reload), the default "Active Work"
+ * filter is used. Subsequent mounts within the same page session restore
+ * the last selection.
+ */
+export declare function usePersistentFilter(): PersistentFilterState;

package/dist/viewer/hooks/use-persistent-filter.js

@@ -0,0 +1,37 @@
+/**
+ * Persistent status filter state for the PRD tree.
+ *
+ * Stores the active status filter selection in a module-level variable
+ * so it survives component mount/unmount cycles (e.g. when the user
+ * navigates from the PRD tree to the Rex Dashboard and back).
+ *
+ * The hook returns the current state and a setter, mirroring useState.
+ */
+import { useState, useCallback } from "preact/hooks";
+import { defaultStatusFilter } from "../components/prd-tree/status-filter.js";
+// ── Module-level persistent state ────────────────────────────────────
+//
+// This variable outlives any single component instance. When the PRD
+// view unmounts (e.g. navigating to the dashboard) and remounts, the
+// hook reads from here instead of resetting to the default.
+let persistedStatuses = null;
+/** Get the persisted filter state, or the default if none has been set. */
+function getPersistedStatuses() {
+    return persistedStatuses ?? defaultStatusFilter();
+}
+/**
+ * Hook that provides filter state which persists across view switches.
+ *
+ * On first mount (or after a full page reload), the default "Active Work"
+ * filter is used. Subsequent mounts within the same page session restore
+ * the last selection.
+ */
+export function usePersistentFilter() {
+    const [activeStatuses, setActiveStatusesLocal] = useState(getPersistedStatuses);
+    const setActiveStatuses = useCallback((statuses) => {
+        persistedStatuses = statuses;
+        setActiveStatusesLocal(statuses);
+    }, []);
+    return { activeStatuses, setActiveStatuses };
+}
+//# sourceMappingURL=use-persistent-filter.js.map

package/dist/viewer/hooks/use-persistent-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-persistent-filter.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-persistent-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAE9E,wEAAwE;AACxE,EAAE;AACF,qEAAqE;AACrE,qEAAqE;AACrE,4DAA4D;AAE5D,IAAI,iBAAiB,GAA2B,IAAI,CAAC;AAErD,2EAA2E;AAC3E,SAAS,oBAAoB;IAC3B,OAAO,iBAAiB,IAAI,mBAAmB,EAAE,CAAC;AACpD,CAAC;AAWD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,CAAC,cAAc,EAAE,sBAAsB,CAAC,GAAG,QAAQ,CACvD,oBAAoB,CACrB,CAAC;IAEF,MAAM,iBAAiB,GAAG,WAAW,CAAC,CAAC,QAAyB,EAAE,EAAE;QAClE,iBAAiB,GAAG,QAAQ,CAAC;QAC7B,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAC/C,CAAC"}

package/dist/viewer/hooks/use-polling-suspension.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Preact hook for tracking polling suspension state.
+ *
+ * Provides reactive state about whether polling is globally suspended
+ * due to memory pressure. Components use this to display suspension
+ * indicators and offer manual refresh options when auto-refresh is
+ * disabled.
+ */
+export interface UsePollingSuspensionResult {
+    /** Whether polling is currently globally suspended. */
+    isSuspended: boolean;
+    /** Number of sources currently in suspended state. */
+    suspendedCount: number;
+    /** Total number of registered polling sources. */
+    sourceCount: number;
+    /** Current generation counter (increments on suspend/resume cycles). */
+    generation: number;
+}
+/**
+ * Hook that provides real-time polling suspension state.
+ *
+ * Subscribes to the centralized polling-state manager and re-renders
+ * when suspension state changes. Returns `isSuspended: false` when
+ * no sources are registered or when polling is running normally.
+ *
+ * Usage:
+ * ```tsx
+ * const { isSuspended, suspendedCount } = usePollingSuspension();
+ * if (isSuspended) return h(PollingSuspensionIndicator, { ... });
+ * ```
+ */
+export declare function usePollingSuspension(): UsePollingSuspensionResult;

package/dist/viewer/hooks/use-polling-suspension.js

@@ -0,0 +1,41 @@
+/**
+ * Preact hook for tracking polling suspension state.
+ *
+ * Provides reactive state about whether polling is globally suspended
+ * due to memory pressure. Components use this to display suspension
+ * indicators and offer manual refresh options when auto-refresh is
+ * disabled.
+ */
+import { useState, useEffect } from "preact/hooks";
+import { onPollingStateChange, getPollingState, } from "../polling/index.js";
+/**
+ * Hook that provides real-time polling suspension state.
+ *
+ * Subscribes to the centralized polling-state manager and re-renders
+ * when suspension state changes. Returns `isSuspended: false` when
+ * no sources are registered or when polling is running normally.
+ *
+ * Usage:
+ * ```tsx
+ * const { isSuspended, suspendedCount } = usePollingSuspension();
+ * if (isSuspended) return h(PollingSuspensionIndicator, { ... });
+ * ```
+ */
+export function usePollingSuspension() {
+    const [snapshot, setSnapshot] = useState(getPollingState);
+    useEffect(() => {
+        const unsubscribe = onPollingStateChange((newSnapshot) => {
+            setSnapshot(newSnapshot);
+        });
+        // Sync with current state in case it changed between render and effect.
+        setSnapshot(getPollingState());
+        return unsubscribe;
+    }, []);
+    return {
+        isSuspended: snapshot.globalSuspended,
+        suspendedCount: snapshot.suspendedCount,
+        sourceCount: snapshot.sourceCount,
+        generation: snapshot.generation,
+    };
+}
+//# sourceMappingURL=use-polling-suspension.js.map

package/dist/viewer/hooks/use-polling-suspension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-polling-suspension.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-polling-suspension.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,oBAAoB,EACpB,eAAe,GAEhB,MAAM,qBAAqB,CAAC;AAa7B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAuB,eAAe,CAAC,CAAC;IAEhF,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,WAAW,GAAG,oBAAoB,CAAC,CAAC,WAAW,EAAE,EAAE;YACvD,WAAW,CAAC,WAAW,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,wEAAwE;QACxE,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;QAE/B,OAAO,WAAW,CAAC;IACrB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO;QACL,WAAW,EAAE,QAAQ,CAAC,eAAe;QACrC,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}

package/dist/viewer/hooks/use-polling.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Preact hook for visibility-aware polling.
+ *
+ * Wraps the polling manager to provide a simple hook interface for
+ * components that need periodic data fetching. Pollers registered
+ * through this hook are automatically suspended when the tab is
+ * backgrounded and resumed when it regains focus.
+ *
+ * Usage:
+ * ```tsx
+ * // Replace:
+ * //   useEffect(() => {
+ * //     const id = setInterval(fetchData, 5000);
+ * //     return () => clearInterval(id);
+ * //   }, []);
+ * //
+ * // With:
+ * usePolling("my-component", fetchData, 5000);
+ * ```
+ */
+/**
+ * Register a visibility-aware polling interval.
+ *
+ * The callback is called every `intervalMs` milliseconds while the tab
+ * is visible. When the tab is backgrounded, the interval is suspended
+ * and resumed on reactivation.
+ *
+ * The callback reference is kept up to date via a ref, so it's safe to
+ * pass an inline function or a callback that changes on every render —
+ * the interval timer is NOT recreated on callback changes.
+ *
+ * @param key - Unique identifier for this poller. Must be stable across
+ *              renders (use a string literal or useMemo).
+ * @param callback - Function to call on each tick. May be async.
+ * @param intervalMs - Polling interval in milliseconds.
+ * @param enabled - Optional flag to conditionally enable/disable polling.
+ *                  Defaults to true. When false, the poller is unregistered.
+ */
+export declare function usePolling(key: string, callback: () => void, intervalMs: number, enabled?: boolean): void;

package/dist/viewer/hooks/use-polling.js

@@ -0,0 +1,55 @@
+/**
+ * Preact hook for visibility-aware polling.
+ *
+ * Wraps the polling manager to provide a simple hook interface for
+ * components that need periodic data fetching. Pollers registered
+ * through this hook are automatically suspended when the tab is
+ * backgrounded and resumed when it regains focus.
+ *
+ * Usage:
+ * ```tsx
+ * // Replace:
+ * //   useEffect(() => {
+ * //     const id = setInterval(fetchData, 5000);
+ * //     return () => clearInterval(id);
+ * //   }, []);
+ * //
+ * // With:
+ * usePolling("my-component", fetchData, 5000);
+ * ```
+ */
+import { useEffect, useRef } from "preact/hooks";
+import { registerPoller, unregisterPoller } from "../polling/index.js";
+/**
+ * Register a visibility-aware polling interval.
+ *
+ * The callback is called every `intervalMs` milliseconds while the tab
+ * is visible. When the tab is backgrounded, the interval is suspended
+ * and resumed on reactivation.
+ *
+ * The callback reference is kept up to date via a ref, so it's safe to
+ * pass an inline function or a callback that changes on every render —
+ * the interval timer is NOT recreated on callback changes.
+ *
+ * @param key - Unique identifier for this poller. Must be stable across
+ *              renders (use a string literal or useMemo).
+ * @param callback - Function to call on each tick. May be async.
+ * @param intervalMs - Polling interval in milliseconds.
+ * @param enabled - Optional flag to conditionally enable/disable polling.
+ *                  Defaults to true. When false, the poller is unregistered.
+ */
+export function usePolling(key, callback, intervalMs, enabled = true) {
+    // Keep the callback ref current so the interval always calls the
+    // latest version without needing to recreate the timer.
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        if (!enabled) {
+            unregisterPoller(key);
+            return;
+        }
+        const unregister = registerPoller(key, () => callbackRef.current(), intervalMs);
+        return unregister;
+    }, [key, intervalMs, enabled]);
+}
+//# sourceMappingURL=use-polling.js.map

package/dist/viewer/hooks/use-polling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-polling.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-polling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,QAAoB,EACpB,UAAkB,EAClB,UAAmB,IAAI;IAEvB,iEAAiE;IACjE,wDAAwD;IACxD,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IAE/B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,cAAc,CAC/B,GAAG,EACH,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,EAC3B,UAAU,CACX,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AACjC,CAAC"}

package/dist/viewer/hooks/use-prd-actions.d.ts

@@ -0,0 +1,126 @@
+/**
+ * PRD CRUD action hooks — item update, add, delete, merge, and prune.
+ *
+ * Composes focused sub-hooks for selection and deletion, adding
+ * mutation handlers (update, add, execute) and detail panel sync.
+ *
+ * Each handler follows the optimistic update pattern:
+ *
+ * 1. Apply the change locally for instant UI feedback
+ * 2. Send the request to the server
+ * 3. Reconcile with authoritative server state
+ * 4. On failure, revert by re-fetching from server
+ *
+ * @see ./use-item-selection.ts — selection, bulk select, navigation
+ * @see ./use-delete-actions.ts — optimistic delete, modal, detail panel remove
+ * @see ../components/prd-tree/tree-differ.ts — applyItemUpdate (structural sharing)
+ */
+import type { VNode } from "preact";
+import type { PRDDocumentData, PRDItemData } from "../components/prd-tree/types.js";
+import type { TaskUsageSummary, WeeklyBudgetResolution } from "../components/prd-tree/types.js";
+import type { AddItemInput } from "../components/prd-tree/add-item-form.js";
+import type { InlineAddInput } from "../components/prd-tree/inline-add-form.js";
+import type { DetailItem, NavigateTo } from "../types.js";
+/** Active tab in the command bar. */
+export type CommandTab = null | "add" | "merge" | "prune";
+export interface PRDActionsDeps {
+    /** Current PRD document data. */
+    data: PRDDocumentData | null;
+    /** Setter for optimistic local state updates. */
+    setData: (updater: PRDDocumentData | null | ((prev: PRDDocumentData | null) => PRDDocumentData | null)) => void;
+    /** Fetch/reconcile PRD data from server. */
+    fetchPRDData: () => Promise<void>;
+    /** Fetch/reconcile task usage data from server. */
+    fetchTaskUsage: () => Promise<void>;
+    /** Show a toast notification. */
+    showToast: (message: string, type?: "success" | "error", duration?: number) => void;
+    /** External callback for item selection (parent layout). */
+    onSelectItem?: (detail: DetailItem | null) => void;
+    /** External callback for detail panel content (parent layout). */
+    onDetailContent?: (content: VNode<any> | null) => void;
+    /** Per-task usage summaries. */
+    taskUsageById: Record<string, TaskUsageSummary>;
+    /** Resolved weekly budget. */
+    weeklyBudget: WeeklyBudgetResolution | null;
+    /** Whether to show token budget UI (budget bar, percentage, limit label). */
+    showTokenBudget?: boolean;
+    /** Navigation callback for deep-linking to other views (e.g. hench-runs). */
+    navigateTo?: NavigateTo;
+}
+export interface PRDActionsState {
+    /** Currently selected item ID. */
+    selectedItemId: string | null;
+    /** Active command bar tab. */
+    activeTab: CommandTab;
+    /** Set the active command bar tab. */
+    setActiveTab: (tab: CommandTab) => void;
+    /** Parent ID for the add-item form. */
+    addParentId: string | null;
+    /** Set the parent ID for the add-item form. */
+    setAddParentId: (id: string | null) => void;
+    /** Set of item IDs selected for bulk operations. */
+    bulkSelectedIds: Set<string>;
+    /** Items resolved from bulk selection (for merge preview). */
+    selectedItems: PRDItemData[];
+    /** Item pending delete confirmation. */
+    deleteTarget: PRDItemData | null;
+    /** Set the item pending delete confirmation. */
+    setDeleteTarget: (item: PRDItemData | null) => void;
+    /** ID of item currently being deleted (loading state). */
+    deletingItemId: string | null;
+    /** Update an item's fields (optimistic + server reconciliation). */
+    handleItemUpdate: (id: string, updates: Partial<PRDItemData>) => Promise<void>;
+    /** Select an item (opens detail panel). */
+    handleSelectItem: (item: PRDItemData) => void;
+    /**
+     * Multi-select handler for bulk operations.
+     * Ctrl/Cmd+click toggles individual items, Shift+click selects a
+     * contiguous range from the anchor, plain click selects only that item.
+     * `visibleIds` provides the flat ordering of currently visible nodes
+     * (needed for shift-range computation).
+     */
+    handleBulkSelect: (item: PRDItemData, modifiers: {
+        ctrlKey: boolean;
+        shiftKey: boolean;
+    }, visibleIds: string[]) => void;
+    /** Clear all bulk-selected items. */
+    clearBulkSelection: () => void;
+    /** Navigate to an item by ID (from detail panel links). */
+    handleNavigateToItem: (id: string) => void;
+    /** Add a child item from the detail panel. */
+    handleAddChild: (input: {
+        title: string;
+        parentId: string;
+        level: string;
+        description?: string;
+        priority?: string;
+    }) => Promise<void>;
+    /** Start a hench execution for a task. */
+    handleExecuteTask: (taskId: string) => Promise<void>;
+    /** Add an item from the command bar form. */
+    handleAddItem: (input: AddItemInput) => Promise<void>;
+    /** Add an item from the inline tree form. */
+    handleInlineAddItem: (input: InlineAddInput) => Promise<void>;
+    /** Remove an item from the tree node (opens modal). */
+    handleRemoveItemFromTree: (item: PRDItemData) => void;
+    /** Confirm deletion from the modal dialog. */
+    handleConfirmDelete: (id: string) => Promise<void>;
+    /** Remove an item from the detail panel. */
+    handleRemoveFromDetail: (id: string) => Promise<void>;
+    /** Called when merge completes successfully. */
+    handleMergeComplete: () => void;
+    /** Called when prune completes successfully. */
+    handlePruneComplete: () => void;
+    /** Open the merge preview panel. */
+    handleOpenMerge: () => void;
+    /** Synchronize the detail panel content with current state. */
+    syncDetailContent: () => void;
+}
+/**
+ * Hook providing all PRD CRUD action handlers and related UI state.
+ *
+ * Composes {@link useItemSelection} for selection/navigation and
+ * {@link useDeleteActions} for optimistic deletion, then adds
+ * mutation handlers and detail panel synchronization.
+ */
+export declare function usePRDActions({ data, setData, fetchPRDData, fetchTaskUsage, showToast, onSelectItem, onDetailContent, taskUsageById, weeklyBudget, showTokenBudget, navigateTo, }: PRDActionsDeps): PRDActionsState;