@n-dx/core 0.1.0

package/packages/web/dist/viewer/hooks/use-prd-actions.js

@@ -0,0 +1,250 @@
+/**
+ * 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 { useState, useCallback } from "preact/hooks";
+import { h } from "preact";
+import { TaskDetail } from "../components/prd-tree/task-detail.js";
+import { findItemById } from "../components/prd-tree/tree-utils.js";
+import { applyItemUpdate } from "../components/prd-tree/tree-differ.js";
+import { useItemSelection } from "./use-item-selection.js";
+import { useDeleteActions } from "./use-delete-actions.js";
+/**
+ * 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 function usePRDActions({ data, setData, fetchPRDData, fetchTaskUsage, showToast, onSelectItem, onDetailContent, taskUsageById, weeklyBudget, showTokenBudget, navigateTo, }) {
+    const [activeTab, setActiveTab] = useState(null);
+    const [addParentId, setAddParentId] = useState(null);
+    // ── Selection (delegated to sub-hook) ─────────────────────────────
+    const { selectedItemId, setSelectedItemId, bulkSelectedIds, setBulkSelectedIds, selectedItems, handleSelectItem, handleBulkSelect, clearBulkSelection, handleNavigateToItem, } = useItemSelection({ data, onSelectItem });
+    // ── Deletion (delegated to sub-hook) ──────────────────────────────
+    const { deleteTarget, setDeleteTarget, deletingItemId, handleRemoveItemFromTree, handleConfirmDelete, handleRemoveFromDetail, } = useDeleteActions({
+        data,
+        setData,
+        fetchPRDData,
+        fetchTaskUsage,
+        showToast,
+        selectedItemId,
+        setSelectedItemId,
+        setBulkSelectedIds,
+        onDetailContent,
+    });
+    // ── Item update (optimistic + reconcile) ─────────────────────────
+    const handleItemUpdate = useCallback(async (id, updates) => {
+        setData((prev) => {
+            if (!prev)
+                return prev;
+            const newItems = applyItemUpdate(prev.items, id, updates);
+            return newItems === prev.items ? prev : { ...prev, items: newItems };
+        });
+        try {
+            const res = await fetch(`/api/rex/items/${id}`, {
+                method: "PATCH",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(updates),
+            });
+            if (!res.ok) {
+                console.error("Failed to update item:", await res.text());
+                await fetchPRDData();
+                return;
+            }
+            await fetchPRDData();
+            await fetchTaskUsage();
+        }
+        catch (err) {
+            console.error("Failed to update item:", err);
+            await fetchPRDData();
+        }
+    }, [setData, fetchPRDData, fetchTaskUsage]);
+    // ── Add child (from detail panel) ────────────────────────────────
+    const handleAddChild = useCallback(async (input) => {
+        const res = await fetch("/api/rex/items", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (!res.ok) {
+            const errBody = await res.json().catch(() => ({ error: "Failed to add item" }));
+            throw new Error(errBody.error || `HTTP ${res.status}`);
+        }
+        const result = await res.json();
+        showToast(`Created ${result.level}: ${result.title}`);
+        await fetchPRDData();
+        await fetchTaskUsage();
+    }, [fetchPRDData, fetchTaskUsage, showToast]);
+    // ── Execute task ─────────────────────────────────────────────────
+    const handleExecuteTask = useCallback(async (taskId) => {
+        const res = await fetch("/api/hench/execute", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ taskId }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw new Error(body.error || `HTTP ${res.status}`);
+        }
+        showToast(`Hench execution started for task`);
+    }, [showToast]);
+    // ── Add item (command bar form) ──────────────────────────────────
+    const handleAddItem = useCallback(async (input) => {
+        const res = await fetch("/api/rex/items", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (!res.ok) {
+            const errBody = await res.json().catch(() => ({ error: "Failed to add item" }));
+            throw new Error(errBody.error || `HTTP ${res.status}`);
+        }
+        const result = await res.json();
+        showToast(`Created ${result.level}: ${result.title}`);
+        setActiveTab(null);
+        setAddParentId(null);
+        await fetchPRDData();
+        await fetchTaskUsage();
+    }, [fetchPRDData, fetchTaskUsage, showToast]);
+    // ── Inline add item (tree node form) ─────────────────────────────
+    const handleInlineAddItem = useCallback(async (input) => {
+        const res = await fetch("/api/rex/items", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (!res.ok) {
+            const errBody = await res.json().catch(() => ({ error: "Failed to add item" }));
+            throw new Error(errBody.error || `HTTP ${res.status}`);
+        }
+        const result = await res.json();
+        showToast(`Created ${result.level}: ${result.title}`);
+        await fetchPRDData();
+        await fetchTaskUsage();
+    }, [fetchPRDData, fetchTaskUsage, showToast]);
+    // ── Merge/prune completion ───────────────────────────────────────
+    const handleMergeComplete = useCallback(() => {
+        setActiveTab(null);
+        setBulkSelectedIds(new Set());
+        showToast("Items merged successfully");
+        fetchPRDData();
+        fetchTaskUsage();
+    }, [setBulkSelectedIds, fetchPRDData, fetchTaskUsage, showToast]);
+    const handlePruneComplete = useCallback(() => {
+        setActiveTab(null);
+        showToast("Completed items pruned and archived");
+        fetchPRDData();
+        fetchTaskUsage();
+    }, [fetchPRDData, fetchTaskUsage, showToast]);
+    const handleOpenMerge = useCallback(() => {
+        setActiveTab("merge");
+    }, []);
+    // ── Detail panel sync ────────────────────────────────────────────
+    // This is called as a side effect to keep the detail panel in sync
+    // with the current selection and data state.
+    const syncDetailContent = useCallback(() => {
+        if (!data || !selectedItemId || !onDetailContent) {
+            if (onDetailContent)
+                onDetailContent(null);
+            return;
+        }
+        const item = findItemById(data.items, selectedItemId);
+        if (!item) {
+            onDetailContent(null);
+            return;
+        }
+        // Keep the detail header in sync with the current item title
+        if (onSelectItem) {
+            onSelectItem({
+                type: "prd",
+                title: item.title,
+                id: item.id,
+                level: item.level,
+                status: item.status,
+                description: item.description,
+                acceptanceCriteria: item.acceptanceCriteria,
+                priority: item.priority,
+                tags: item.tags,
+                blockedBy: item.blockedBy,
+                startedAt: item.startedAt,
+                completedAt: item.completedAt,
+            });
+        }
+        onDetailContent(h(TaskDetail, {
+            item,
+            taskUsage: taskUsageById[item.id],
+            weeklyBudget,
+            showTokenBudget: showTokenBudget ?? false,
+            allItems: data.items,
+            onUpdate: handleItemUpdate,
+            onNavigateToItem: handleNavigateToItem,
+            onExecuteTask: handleExecuteTask,
+            onPrdChanged: () => {
+                fetchPRDData();
+                fetchTaskUsage();
+            },
+            onAddChild: handleAddChild,
+            onRemove: handleRemoveFromDetail,
+            navigateTo,
+        }));
+    }, [
+        data,
+        selectedItemId,
+        taskUsageById,
+        weeklyBudget,
+        showTokenBudget,
+        onSelectItem,
+        onDetailContent,
+        handleItemUpdate,
+        handleNavigateToItem,
+        handleExecuteTask,
+        fetchPRDData,
+        fetchTaskUsage,
+        handleAddChild,
+        handleRemoveFromDetail,
+        navigateTo,
+    ]);
+    return {
+        selectedItemId,
+        activeTab,
+        setActiveTab,
+        addParentId,
+        setAddParentId,
+        bulkSelectedIds,
+        selectedItems,
+        deleteTarget,
+        setDeleteTarget,
+        deletingItemId,
+        handleItemUpdate,
+        handleSelectItem,
+        handleBulkSelect,
+        clearBulkSelection,
+        handleNavigateToItem,
+        handleAddChild,
+        handleExecuteTask,
+        handleAddItem,
+        handleInlineAddItem,
+        handleRemoveItemFromTree,
+        handleConfirmDelete,
+        handleRemoveFromDetail,
+        handleMergeComplete,
+        handlePruneComplete,
+        handleOpenMerge,
+        syncDetailContent,
+    };
+}
+//# sourceMappingURL=use-prd-actions.js.map

package/packages/web/dist/viewer/hooks/use-prd-actions.js.map

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

package/packages/web/dist/viewer/hooks/use-prd-data.d.ts

@@ -0,0 +1,45 @@
+/**
+ * PRD data fetching hook with structural sharing, dedup, and rate limiting.
+ *
+ * Encapsulates all PRD + task-usage data fetching logic extracted from
+ * PRDView. Manages:
+ *
+ * - PRD document state (data, loading, error)
+ * - Task usage and weekly budget state
+ * - Request deduplication (concurrent callers share one in-flight request)
+ * - Rate limiting (max 2 requests/sec per endpoint)
+ * - Structural sharing via diffDocument (unchanged items keep references)
+ * - Visibility-aware polling for task usage
+ * - Cleanup of rate limiter timers on unmount
+ *
+ * @see ../components/prd-tree/tree-differ.ts — structural sharing implementation
+ * @see ../messaging/fetch-pipeline.ts — composed dedup + rate limiting
+ */
+import type { PRDDocumentData } from "../components/prd-tree/types.js";
+import type { TaskUsageSummary, WeeklyBudgetResolution } from "../components/prd-tree/types.js";
+export interface PRDDataState {
+    /** Current PRD document, or null if not yet loaded. */
+    data: PRDDocumentData | null;
+    /** Setter for optimistic updates from WebSocket/actions. */
+    setData: (updater: PRDDocumentData | null | ((prev: PRDDocumentData | null) => PRDDocumentData | null)) => void;
+    /** True while the initial fetch is in flight. */
+    loading: boolean;
+    /** Error message, or null. */
+    error: string | null;
+    /** Setter for error state (used by WebSocket pipeline). */
+    setError: (error: string | null) => void;
+    /** Per-task usage summaries keyed by task ID. */
+    taskUsageById: Record<string, TaskUsageSummary>;
+    /** Resolved weekly budget (for utilization calculations). */
+    weeklyBudget: WeeklyBudgetResolution | null;
+    /** Fetch/reconcile PRD data from server. Rate-limited and deduped. */
+    fetchPRDData: () => Promise<void>;
+    /** Fetch/reconcile task usage data from server. Rate-limited and deduped. */
+    fetchTaskUsage: () => Promise<void>;
+}
+/**
+ * Hook managing all PRD data loading, polling, and state.
+ *
+ * @param prdData - Optional pre-loaded PRD data (skips initial fetch).
+ */
+export declare function usePRDData(prdData?: PRDDocumentData | null): PRDDataState;

package/packages/web/dist/viewer/hooks/use-prd-data.js

@@ -0,0 +1,159 @@
+/**
+ * PRD data fetching hook with structural sharing, dedup, and rate limiting.
+ *
+ * Encapsulates all PRD + task-usage data fetching logic extracted from
+ * PRDView. Manages:
+ *
+ * - PRD document state (data, loading, error)
+ * - Task usage and weekly budget state
+ * - Request deduplication (concurrent callers share one in-flight request)
+ * - Rate limiting (max 2 requests/sec per endpoint)
+ * - Structural sharing via diffDocument (unchanged items keep references)
+ * - Visibility-aware polling for task usage
+ * - Cleanup of rate limiter timers on unmount
+ *
+ * @see ../components/prd-tree/tree-differ.ts — structural sharing implementation
+ * @see ../messaging/fetch-pipeline.ts — composed dedup + rate limiting
+ */
+import { useState, useEffect, useCallback, useRef } from "preact/hooks";
+import { resolveTaskUtilization } from "../components/prd-tree/task-utilization.js";
+import { diffDocument } from "../components/prd-tree/tree-differ.js";
+import { usePolling } from "./use-polling.js";
+import { createFetchPipeline } from "../messaging/index.js";
+function normalizeWeeklyBudgetResolution(value) {
+    const source = value?.source;
+    const budget = value?.budget;
+    return {
+        budget: typeof budget === "number" && Number.isFinite(budget) ? budget : null,
+        source: source ?? "missing_budget",
+    };
+}
+/**
+ * Convert server-side incremental task usage into client-side summaries
+ * with utilization metadata applied.
+ */
+function applyUtilizationToTaskUsage(serverUsage, weeklyBudget) {
+    const byTask = {};
+    for (const [taskId, usage] of Object.entries(serverUsage)) {
+        byTask[taskId] = {
+            totalTokens: usage.totalTokens,
+            runCount: usage.runCount,
+            utilization: resolveTaskUtilization(usage.totalTokens, weeklyBudget),
+        };
+    }
+    return byTask;
+}
+function applyWeeklyBudget(taskUsageById, weeklyBudget) {
+    const next = {};
+    for (const [taskId, summary] of Object.entries(taskUsageById)) {
+        next[taskId] = {
+            ...summary,
+            utilization: resolveTaskUtilization(summary.totalTokens, weeklyBudget),
+        };
+    }
+    return next;
+}
+/**
+ * Hook managing all PRD data loading, polling, and state.
+ *
+ * @param prdData - Optional pre-loaded PRD data (skips initial fetch).
+ */
+export function usePRDData(prdData) {
+    const [data, setData] = useState(prdData ?? null);
+    const [loading, setLoading] = useState(!prdData);
+    const [error, setError] = useState(null);
+    const [taskUsageById, setTaskUsageById] = useState({});
+    const [weeklyBudget, setWeeklyBudget] = useState(null);
+    /** Mutable ref so the dedup-wrapped fetchTaskUsage always reads the latest budget. */
+    const weeklyBudgetRef = useRef(weeklyBudget);
+    weeklyBudgetRef.current = weeklyBudget;
+    // ── PRD data fetching (dedup + rate-limited) ─────────────────────
+    const prdPipeline = useRef(createFetchPipeline(async () => {
+        try {
+            const res = await fetch("/data/prd.json");
+            if (!res.ok) {
+                if (res.status === 404) {
+                    setError("No PRD data found. Run 'rex init' then 'rex analyze' to create one.");
+                }
+                else {
+                    setError(`Failed to load PRD data (${res.status})`);
+                }
+                return;
+            }
+            const json = await res.json();
+            setData((prev) => diffDocument(prev, json));
+            setError(null);
+        }
+        catch (_err) {
+            setError("Could not fetch PRD data. Is the server running?");
+        }
+    }, { minIntervalMs: 500 }));
+    const fetchPRDData = useCallback(async () => {
+        await prdPipeline.current.execute();
+    }, []);
+    // ── Task usage fetching (dedup + rate-limited) ─────────────────
+    const usagePipeline = useRef(createFetchPipeline(async () => {
+        const [taskUsageResult, utilizationResult] = await Promise.allSettled([
+            fetch("/api/hench/task-usage"),
+            fetch("/api/token/utilization"),
+        ]);
+        let resolvedWeeklyBudget = weeklyBudgetRef.current;
+        if (utilizationResult.status === "fulfilled" && utilizationResult.value.ok) {
+            try {
+                const json = await utilizationResult.value.json();
+                resolvedWeeklyBudget = normalizeWeeklyBudgetResolution(json.weeklyBudget);
+                setWeeklyBudget(resolvedWeeklyBudget);
+                setTaskUsageById((prev) => applyWeeklyBudget(prev, resolvedWeeklyBudget));
+            }
+            catch {
+                // Keep prior budget state on parse errors.
+            }
+        }
+        if (taskUsageResult.status === "fulfilled" && taskUsageResult.value.ok) {
+            try {
+                const json = await taskUsageResult.value.json();
+                setTaskUsageById(applyUtilizationToTaskUsage(json.taskUsage ?? {}, resolvedWeeklyBudget));
+            }
+            catch {
+                // Keep existing values on parse errors.
+            }
+        }
+    }, { minIntervalMs: 500 }));
+    const fetchTaskUsage = useCallback(async () => {
+        await usagePipeline.current.execute();
+    }, []);
+    // ── Initial fetch ────────────────────────────────────────────────
+    useEffect(() => {
+        if (prdData) {
+            setData(prdData);
+            setLoading(false);
+            fetchTaskUsage();
+            return;
+        }
+        fetchPRDData().then(() => setLoading(false));
+        fetchTaskUsage();
+    }, [prdData, fetchPRDData, fetchTaskUsage]);
+    // ── Visibility-aware polling ─────────────────────────────────────
+    usePolling("prd:task-usage", fetchTaskUsage, 10_000);
+    // ── Cleanup ──────────────────────────────────────────────────────
+    useEffect(() => {
+        const prd = prdPipeline.current;
+        const usage = usagePipeline.current;
+        return () => {
+            prd.dispose();
+            usage.dispose();
+        };
+    }, []);
+    return {
+        data,
+        setData,
+        loading,
+        error,
+        setError,
+        taskUsageById,
+        weeklyBudget,
+        fetchPRDData,
+        fetchTaskUsage,
+    };
+}
+//# sourceMappingURL=use-prd-data.js.map

package/packages/web/dist/viewer/hooks/use-prd-data.js.map

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

package/packages/web/dist/viewer/hooks/use-prd-deep-link.d.ts

@@ -0,0 +1,45 @@
+/**
+ * PRD deep-link resolution hook.
+ *
+ * Handles auto-selection and highlighting of a specific task when the
+ * view loads with an initialTaskId (from a shareable URL like /prd/:id).
+ *
+ * Responsibilities:
+ * - Finds the target item in the tree once data is loaded
+ * - Expands ancestor nodes so the target is visible
+ * - Selects and highlights the target with a timed animation
+ * - Shows an error banner if the task ID is not found
+ * - Cleans up the URL on error (reverts to /prd)
+ *
+ * Extracted from PRDView to isolate deep-link side effects from the
+ * component's render and CRUD logic.
+ */
+import type { PRDDocumentData, PRDItemData } from "../components/prd-tree/types.js";
+export interface PRDDeepLinkDeps {
+    /** Task ID from the URL, or null if no deep link. */
+    initialTaskId?: string | null;
+    /** True while the initial data fetch is in flight. */
+    loading: boolean;
+    /** Current PRD document data. */
+    data: PRDDocumentData | null;
+    /** Callback to select/open a PRD item. */
+    onSelectItem: (item: PRDItemData) => void;
+}
+export interface PRDDeepLinkState {
+    /** Error message when the deep-linked task is not found. */
+    deepLinkError: string | null;
+    /** Dismiss the deep-link error banner. */
+    setDeepLinkError: (error: string | null) => void;
+    /** Task ID currently highlighted by the deep-link animation. */
+    highlightedTaskId: string | null;
+    /** IDs to force-expand in the tree (ancestors of the deep-linked task). */
+    deepLinkExpandIds: Set<string> | null;
+}
+/**
+ * Hook that resolves deep-link navigation for PRD tasks.
+ *
+ * Consumes the initialTaskId exactly once after data loads. If the
+ * target exists, it expands ancestors, selects the item, and runs a
+ * highlight animation. If not found, shows an error banner.
+ */
+export declare function usePRDDeepLink({ initialTaskId, loading, data, onSelectItem, }: PRDDeepLinkDeps): PRDDeepLinkState;

package/packages/web/dist/viewer/hooks/use-prd-deep-link.js

@@ -0,0 +1,60 @@
+/**
+ * PRD deep-link resolution hook.
+ *
+ * Handles auto-selection and highlighting of a specific task when the
+ * view loads with an initialTaskId (from a shareable URL like /prd/:id).
+ *
+ * Responsibilities:
+ * - Finds the target item in the tree once data is loaded
+ * - Expands ancestor nodes so the target is visible
+ * - Selects and highlights the target with a timed animation
+ * - Shows an error banner if the task ID is not found
+ * - Cleans up the URL on error (reverts to /prd)
+ *
+ * Extracted from PRDView to isolate deep-link side effects from the
+ * component's render and CRUD logic.
+ */
+import { useState, useEffect, useRef } from "preact/hooks";
+import { findItemById, getAncestorIds } from "../components/prd-tree/tree-utils.js";
+/**
+ * Hook that resolves deep-link navigation for PRD tasks.
+ *
+ * Consumes the initialTaskId exactly once after data loads. If the
+ * target exists, it expands ancestors, selects the item, and runs a
+ * highlight animation. If not found, shows an error banner.
+ */
+export function usePRDDeepLink({ initialTaskId, loading, data, onSelectItem, }) {
+    const [deepLinkError, setDeepLinkError] = useState(null);
+    const [highlightedTaskId, setHighlightedTaskId] = useState(null);
+    const [deepLinkExpandIds, setDeepLinkExpandIds] = useState(null);
+    /** Whether the initial deep-link has been consumed. */
+    const deepLinkConsumedRef = useRef(false);
+    // Wrap onSelectItem in a ref to avoid re-triggering the effect
+    const onSelectItemRef = useRef(onSelectItem);
+    onSelectItemRef.current = onSelectItem;
+    useEffect(() => {
+        if (deepLinkConsumedRef.current || !initialTaskId || loading || !data)
+            return;
+        deepLinkConsumedRef.current = true;
+        const item = findItemById(data.items, initialTaskId);
+        if (!item) {
+            setDeepLinkError(`Task "${initialTaskId}" not found`);
+            // Clean URL back to /prd
+            history.replaceState({ view: "prd", file: null, zone: null, runId: null, taskId: null }, "", "/prd");
+            return;
+        }
+        // Expand ancestor nodes so the target is visible
+        const ancestors = getAncestorIds(data.items, initialTaskId);
+        if (ancestors.length > 0) {
+            setDeepLinkExpandIds(new Set(ancestors));
+        }
+        // Select and highlight the item
+        setHighlightedTaskId(initialTaskId);
+        onSelectItemRef.current(item);
+        // Clear highlight after animation completes
+        const timer = setTimeout(() => setHighlightedTaskId(null), 3000);
+        return () => clearTimeout(timer);
+    }, [initialTaskId, loading, data]);
+    return { deepLinkError, setDeepLinkError, highlightedTaskId, deepLinkExpandIds };
+}
+//# sourceMappingURL=use-prd-deep-link.js.map

package/packages/web/dist/viewer/hooks/use-prd-deep-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-prd-deep-link.js","sourceRoot":"","sources":["../../../src/viewer/hooks/use-prd-deep-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAe,MAAM,cAAc,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAwBpF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,aAAa,EACb,OAAO,EACP,IAAI,EACJ,YAAY,GACI;IAChB,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACxE,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAChF,MAAM,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,GAAG,QAAQ,CAAqB,IAAI,CAAC,CAAC;IAErF,uDAAuD;IACvD,MAAM,mBAAmB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAE1C,+DAA+D;IAC/D,MAAM,eAAe,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IAC7C,eAAe,CAAC,OAAO,GAAG,YAAY,CAAC;IAEvC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,mBAAmB,CAAC,OAAO,IAAI,CAAC,aAAa,IAAI,OAAO,IAAI,CAAC,IAAI;YAAE,OAAO;QAC9E,mBAAmB,CAAC,OAAO,GAAG,IAAI,CAAC;QAEnC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,gBAAgB,CAAC,SAAS,aAAa,aAAa,CAAC,CAAC;YACtD,yBAAyB;YACzB,OAAO,CAAC,YAAY,CAClB,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAClE,EAAE,EACF,MAAM,CACP,CAAC;YACF,OAAO;QACT,CAAC;QAED,iDAAiD;QACjD,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QAC5D,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,oBAAoB,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,gCAAgC;QAChC,oBAAoB,CAAC,aAAa,CAAC,CAAC;QACpC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAE9B,4CAA4C;QAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QACjE,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAEnC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,CAAC;AACnF,CAAC"}

package/packages/web/dist/viewer/hooks/use-prd-websocket.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PRD WebSocket real-time update hook.
+ *
+ * Sets up a five-layer message processing pipeline for real-time PRD
+ * updates via WebSocket:
+ *
+ *   raw WS → buffer gate → throttle → coalescer → DOM gate → batcher → RAF → render
+ *
+ * Each layer has a specific role:
+ *
+ * 0. **Response buffer gate** — drops messages when tab is hidden, flushes
+ *    downstream buffers to free memory, reconciles on resume.
+ * 1. **Throttle** — per-type trailing-edge debounce for high-frequency
+ *    rex message types (prd-changed, item-updated, item-deleted).
+ * 2. **Coalescer** — batches throttled output into a single reconciliation
+ *    flush instead of N separate fetches.
+ * 3. **DOM update gate** — queues state updates when tab is hidden,
+ *    replays them in a single batch when visible again.
+ * 4. **Update batcher** — collects setData calls into a single RAF
+ *    callback per animation frame.
+ *
+ * Extracted from PRDView to isolate WebSocket side effects from the
+ * component's render logic.
+ *
+ * @see ../messaging/message-coalescer.ts
+ * @see ../messaging/message-throttle.ts
+ * @see ../performance/dom-update-gate.ts
+ * @see ../performance/update-batcher.ts
+ * @see ../performance/response-buffer-gate.ts
+ */
+import type { PRDDocumentData } from "../components/prd-tree/types.js";
+export interface PRDWebSocketDeps {
+    /** Setter for PRD document state (supports functional 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>;
+}
+/**
+ * Hook that manages the WebSocket connection and message processing
+ * pipeline for real-time PRD updates.
+ *
+ * All parameters are expected to be stable references (wrapped in
+ * useCallback or similar). The effect re-runs when any dependency changes.
+ */
+export declare function usePRDWebSocket({ setData, fetchPRDData, fetchTaskUsage }: PRDWebSocketDeps): void;