@n-dx/core 0.1.0

package/packages/web/dist/viewer/components/prd-tree/lazy-children.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Lazy rendering wrapper for collapsed tree branches.
+ *
+ * Defers DOM creation for child nodes until the parent is expanded by the
+ * user. On collapse, children are hidden via CSS immediately and then
+ * unmounted from the DOM after a short delay. Rapid expand/collapse cycles
+ * within the delay window reuse the existing DOM — preserving component
+ * state and avoiding expensive re-mounts.
+ *
+ * Lifecycle:
+ * 1. Initially collapsed → children not mounted (zero DOM cost)
+ * 2. Parent expanded → children mount, CSS class reveals them
+ * 3. Parent collapsed → CSS hides children; unmount scheduled after delay
+ * 4. Rapid re-expand before unmount → cancels timer, children stay mounted
+ *
+ * @see ./prd-tree.ts — TreeNodes component that wraps child branches
+ */
+import type { VNode, ComponentChildren } from "preact";
+/**
+ * Delay in milliseconds before unmounting children after a collapse.
+ * During this window, rapid re-expansion reuses the existing DOM (no re-mount).
+ * @internal Exported for testing.
+ */
+export declare const UNMOUNT_DELAY_MS = 300;
+export interface LazyChildrenProps {
+    /** Whether the parent node is currently expanded. */
+    isOpen: boolean;
+    /** Render function that produces the child VDOM tree. Only called when
+     *  children should be in the DOM — avoids VDOM creation when unmounted. */
+    renderChildren: () => ComponentChildren;
+}
+/**
+ * Wrapper that defers child DOM creation until the parent node is expanded.
+ *
+ * When `isOpen` transitions from false → true, children are mounted and
+ * revealed via a CSS class. When `isOpen` transitions from true → false,
+ * children are hidden immediately (CSS) and unmounted after
+ * {@link UNMOUNT_DELAY_MS} to handle rapid toggling without flicker.
+ */
+export declare function LazyChildren({ isOpen, renderChildren }: LazyChildrenProps): VNode | null;

package/packages/web/dist/viewer/components/prd-tree/lazy-children.js

@@ -0,0 +1,73 @@
+/**
+ * Lazy rendering wrapper for collapsed tree branches.
+ *
+ * Defers DOM creation for child nodes until the parent is expanded by the
+ * user. On collapse, children are hidden via CSS immediately and then
+ * unmounted from the DOM after a short delay. Rapid expand/collapse cycles
+ * within the delay window reuse the existing DOM — preserving component
+ * state and avoiding expensive re-mounts.
+ *
+ * Lifecycle:
+ * 1. Initially collapsed → children not mounted (zero DOM cost)
+ * 2. Parent expanded → children mount, CSS class reveals them
+ * 3. Parent collapsed → CSS hides children; unmount scheduled after delay
+ * 4. Rapid re-expand before unmount → cancels timer, children stay mounted
+ *
+ * @see ./prd-tree.ts — TreeNodes component that wraps child branches
+ */
+import { h } from "preact";
+import { useState, useEffect, useRef } from "preact/hooks";
+/**
+ * Delay in milliseconds before unmounting children after a collapse.
+ * During this window, rapid re-expansion reuses the existing DOM (no re-mount).
+ * @internal Exported for testing.
+ */
+export const UNMOUNT_DELAY_MS = 300;
+// ─── Component ──────────────────────────────────────────────────────────────
+/**
+ * Wrapper that defers child DOM creation until the parent node is expanded.
+ *
+ * When `isOpen` transitions from false → true, children are mounted and
+ * revealed via a CSS class. When `isOpen` transitions from true → false,
+ * children are hidden immediately (CSS) and unmounted after
+ * {@link UNMOUNT_DELAY_MS} to handle rapid toggling without flicker.
+ */
+export function LazyChildren({ isOpen, renderChildren }) {
+    // Whether children are currently mounted in the DOM.
+    const [mounted, setMounted] = useState(isOpen);
+    // Ref for the deferred-unmount timer.
+    const timerRef = useRef(null);
+    useEffect(() => {
+        if (isOpen) {
+            // Expanding: mount immediately, cancel any pending unmount.
+            if (timerRef.current !== null) {
+                clearTimeout(timerRef.current);
+                timerRef.current = null;
+            }
+            setMounted(true);
+        }
+        else {
+            // Collapsing: defer unmount so rapid re-expansion reuses the DOM.
+            timerRef.current = setTimeout(() => {
+                setMounted(false);
+                timerRef.current = null;
+            }, UNMOUNT_DELAY_MS);
+        }
+    }, [isOpen]);
+    // Cleanup timer if the component itself unmounts (e.g. parent is removed).
+    useEffect(() => {
+        return () => {
+            if (timerRef.current !== null) {
+                clearTimeout(timerRef.current);
+            }
+        };
+    }, []);
+    if (!mounted)
+        return null;
+    return h("div", {
+        class: `prd-children${isOpen ? "" : " prd-children-collapsed"}`,
+        role: "group",
+        "aria-hidden": isOpen ? undefined : "true",
+    }, renderChildren());
+}
+//# sourceMappingURL=lazy-children.js.map

package/packages/web/dist/viewer/components/prd-tree/lazy-children.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-children.js","sourceRoot":"","sources":["../../../../src/viewer/components/prd-tree/lazy-children.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAYpC,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,MAAM,EAAE,cAAc,EAAqB;IACxE,qDAAqD;IACrD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/C,sCAAsC;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAuC,IAAI,CAAC,CAAC;IAEpE,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,MAAM,EAAE,CAAC;YACX,4DAA4D;YAC5D,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC9B,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAC/B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;YAC1B,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,kEAAkE;YAClE,QAAQ,CAAC,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;gBACjC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAClB,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;YAC1B,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,2EAA2E;IAC3E,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC9B,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,OAAO,CAAC,CACN,KAAK,EACL;QACE,KAAK,EAAE,eAAe,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,yBAAyB,EAAE;QAC/D,IAAI,EAAE,OAAO;QACb,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM;KAC3C,EACD,cAAc,EAAE,CACjB,CAAC;AACJ,CAAC"}

package/packages/web/dist/viewer/components/prd-tree/levels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Level system helpers for the browser-bundled viewer.
+ *
+ * These mirror the canonical helpers in rex/src/schema/levels.ts but are
+ * self-contained for browser bundling. They use the same level strings
+ * as the rex types mirror in ./types.ts.
+ *
+ * @see packages/rex/src/schema/levels.ts — canonical source
+ * @see ./types.ts — viewer-side type definitions
+ */
+import type { ItemLevel } from "./types.js";
+/** Can this level exist at the tree root? Replaces: `level === "epic"` */
+export declare function isRootLevel(level: string): boolean;
+/**
+ * Is this a work item (actionable leaf-level)?
+ * Replaces: `level === "task" || level === "subtask"`
+ */
+export declare function isWorkItem(level: string): boolean;
+/**
+ * Is this a container level (groups other items)?
+ * Replaces: `level === "epic" || level === "feature"`
+ */
+export declare function isContainerLevel(level: string): boolean;
+/** Get the display label for a level. e.g. "epic" → "Epic" */
+export declare function getLevelLabel(level: string): string;
+/** Get the plural display label. e.g. "epic" → "Epics" */
+export declare function getLevelPlural(level: string): string;
+/** Get the emoji for a level. e.g. "epic" → "📦" */
+export declare function getLevelEmoji(level: string): string;
+/** Get the default child level. e.g. "epic" → "feature" */
+export declare function getChildLevel(level: string): ItemLevel | null;

package/packages/web/dist/viewer/components/prd-tree/levels.js

@@ -0,0 +1,72 @@
+/**
+ * Level system helpers for the browser-bundled viewer.
+ *
+ * These mirror the canonical helpers in rex/src/schema/levels.ts but are
+ * self-contained for browser bundling. They use the same level strings
+ * as the rex types mirror in ./types.ts.
+ *
+ * @see packages/rex/src/schema/levels.ts — canonical source
+ * @see ./types.ts — viewer-side type definitions
+ */
+// ── Semantic helpers ────────────────────────────────────────────────
+/** Can this level exist at the tree root? Replaces: `level === "epic"` */
+export function isRootLevel(level) {
+    return level === "epic";
+}
+/**
+ * Is this a work item (actionable leaf-level)?
+ * Replaces: `level === "task" || level === "subtask"`
+ */
+export function isWorkItem(level) {
+    return level === "task" || level === "subtask";
+}
+/**
+ * Is this a container level (groups other items)?
+ * Replaces: `level === "epic" || level === "feature"`
+ */
+export function isContainerLevel(level) {
+    return level === "epic" || level === "feature";
+}
+// ── Display helpers ─────────────────────────────────────────────────
+const LEVEL_LABELS = {
+    epic: "Epic",
+    feature: "Feature",
+    task: "Task",
+    subtask: "Subtask",
+};
+const LEVEL_LABELS_PLURAL = {
+    epic: "Epics",
+    feature: "Features",
+    task: "Tasks",
+    subtask: "Subtasks",
+};
+const LEVEL_EMOJI = {
+    epic: "\u{1F4E6}", // 📦
+    feature: "\u{2728}", // ✨
+    task: "\u{1F4CB}", // 📋
+    subtask: "\u{1F539}", // 🔹
+};
+/** Get the display label for a level. e.g. "epic" → "Epic" */
+export function getLevelLabel(level) {
+    return LEVEL_LABELS[level] ?? level;
+}
+/** Get the plural display label. e.g. "epic" → "Epics" */
+export function getLevelPlural(level) {
+    return LEVEL_LABELS_PLURAL[level] ?? `${level}s`;
+}
+/** Get the emoji for a level. e.g. "epic" → "📦" */
+export function getLevelEmoji(level) {
+    return LEVEL_EMOJI[level] ?? "\u2022";
+}
+// ── Hierarchy ───────────────────────────────────────────────────────
+const CHILD_LEVEL = {
+    epic: "feature",
+    feature: "task",
+    task: "subtask",
+    subtask: null,
+};
+/** Get the default child level. e.g. "epic" → "feature" */
+export function getChildLevel(level) {
+    return CHILD_LEVEL[level] ?? null;
+}
+//# sourceMappingURL=levels.js.map

package/packages/web/dist/viewer/components/prd-tree/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../../../../src/viewer/components/prd-tree/levels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,uEAAuE;AAEvE,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,KAAK,MAAM,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,SAAS,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,SAAS,CAAC;AACjD,CAAC;AAED,uEAAuE;AAEvE,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,MAAM,mBAAmB,GAA2B;IAClD,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,UAAU;CACpB,CAAC;AAEF,MAAM,WAAW,GAA2B;IAC1C,IAAI,EAAE,WAAW,EAAK,KAAK;IAC3B,OAAO,EAAE,UAAU,EAAI,IAAI;IAC3B,IAAI,EAAE,WAAW,EAAM,KAAK;IAC5B,OAAO,EAAE,WAAW,EAAG,KAAK;CAC7B,CAAC;AAEF,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;AACtC,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,mBAAmB,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,GAAG,CAAC;AACnD,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC;AACxC,CAAC;AAED,uEAAuE;AAEvE,MAAM,WAAW,GAAqC;IACpD,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AACpC,CAAC"}

package/packages/web/dist/viewer/components/prd-tree/listener-lifecycle.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Event listener lifecycle manager for tree node DOM elements.
+ *
+ * Provides centralized tracking and scope-based cleanup of event listeners
+ * registered on per-node DOM elements. Each listener is associated with a
+ * "scope" (typically a node ID) so that all listeners for a node can be
+ * batch-removed when the node is destroyed or culled off-screen.
+ *
+ * The manager ensures:
+ * - Event listeners are removed when nodes are destroyed (cull or unmount)
+ * - No memory leaks from orphaned listeners after tree data changes
+ * - Listener count stays proportional to visible nodes
+ * - Diagnostic state is available for memory profiling
+ *
+ * Framework-agnostic core — the Preact hook `useNodeListeners` is provided
+ * below for convenient integration with component lifecycles.
+ *
+ * @see ./prd-tree.ts    — PRDTree component that owns the manager instance
+ */
+/** A single tracked event listener registration. */
+export interface ListenerRecord {
+    target: EventTarget;
+    event: string;
+    handler: EventListenerOrEventListenerObject;
+    options?: boolean | AddEventListenerOptions;
+}
+/** Read-only diagnostic snapshot of manager state. */
+export interface ListenerLifecycleState {
+    /** Total number of active listeners tracked across all scopes. */
+    totalListeners: number;
+    /** Number of active scopes (typically = number of nodes with listeners). */
+    activeScopeCount: number;
+    /** Whether the manager has been disposed. */
+    disposed: boolean;
+}
+/**
+ * Centralized event listener lifecycle manager.
+ *
+ * Organizes listeners by scope (node ID). When a node is culled or destroyed,
+ * `cleanupScope()` removes all its listeners in one call. On tree unmount,
+ * `dispose()` cleans up everything.
+ *
+ * Usage:
+ * ```ts
+ * const manager = new ListenerLifecycleManager();
+ *
+ * // Register a listener tied to a node
+ * const cleanup = manager.addListener("node-1", element, "click", handler);
+ *
+ * // Remove all listeners for a node (e.g. when culled)
+ * manager.cleanupScope("node-1");
+ *
+ * // Tear down on tree unmount
+ * manager.dispose();
+ * ```
+ */
+export declare class ListenerLifecycleManager {
+    private scopes;
+    private _disposed;
+    /**
+     * Register a DOM event listener tied to a scope.
+     *
+     * The listener is added to the target immediately and tracked. Returns a
+     * cleanup function that removes the listener and its tracking entry.
+     * The cleanup function is idempotent — safe to call multiple times.
+     *
+     * After `dispose()`, this method is a no-op and returns a no-op cleanup.
+     */
+    addListener(scopeId: string, target: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
+    /**
+     * Remove all listeners for a given scope and clear its tracking.
+     *
+     * Called when a node is destroyed or culled off-screen. Safe to call
+     * with a scope that doesn't exist (no-op) or after dispose.
+     */
+    cleanupScope(scopeId: string): void;
+    /** Whether a scope has any active tracked listeners. */
+    hasScope(scopeId: string): boolean;
+    /**
+     * Dispose the manager, removing ALL tracked listeners across all scopes.
+     *
+     * After disposal, `addListener()` becomes a no-op. Safe to call multiple
+     * times — subsequent calls are no-ops.
+     */
+    dispose(): void;
+    /** Whether this manager has been disposed. */
+    get disposed(): boolean;
+    /** Get a diagnostic snapshot of current state. */
+    getState(): ListenerLifecycleState;
+}
+/**
+ * Hook for registering scope-aware event listeners with automatic cleanup.
+ *
+ * Returns an `addListener` function that registers listeners through the
+ * lifecycle manager. All listeners registered via this hook are automatically
+ * removed when the component unmounts or when the scope/manager changes.
+ *
+ * When no manager is provided (null), listeners are added directly to the
+ * target and tracked locally for cleanup on unmount — a safe fallback that
+ * still prevents leaks.
+ *
+ * @param manager  Shared lifecycle manager, or null to use local tracking only
+ * @param scopeId  Scope identifier (typically a node ID)
+ */
+export declare function useNodeListeners(manager: ListenerLifecycleManager | null, scopeId: string): (target: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void;

package/packages/web/dist/viewer/components/prd-tree/listener-lifecycle.js

@@ -0,0 +1,173 @@
+/**
+ * Event listener lifecycle manager for tree node DOM elements.
+ *
+ * Provides centralized tracking and scope-based cleanup of event listeners
+ * registered on per-node DOM elements. Each listener is associated with a
+ * "scope" (typically a node ID) so that all listeners for a node can be
+ * batch-removed when the node is destroyed or culled off-screen.
+ *
+ * The manager ensures:
+ * - Event listeners are removed when nodes are destroyed (cull or unmount)
+ * - No memory leaks from orphaned listeners after tree data changes
+ * - Listener count stays proportional to visible nodes
+ * - Diagnostic state is available for memory profiling
+ *
+ * Framework-agnostic core — the Preact hook `useNodeListeners` is provided
+ * below for convenient integration with component lifecycles.
+ *
+ * @see ./prd-tree.ts    — PRDTree component that owns the manager instance
+ */
+import { useEffect, useRef, useCallback } from "preact/hooks";
+// ─── ListenerLifecycleManager ────────────────────────────────────────────────
+/**
+ * Centralized event listener lifecycle manager.
+ *
+ * Organizes listeners by scope (node ID). When a node is culled or destroyed,
+ * `cleanupScope()` removes all its listeners in one call. On tree unmount,
+ * `dispose()` cleans up everything.
+ *
+ * Usage:
+ * ```ts
+ * const manager = new ListenerLifecycleManager();
+ *
+ * // Register a listener tied to a node
+ * const cleanup = manager.addListener("node-1", element, "click", handler);
+ *
+ * // Remove all listeners for a node (e.g. when culled)
+ * manager.cleanupScope("node-1");
+ *
+ * // Tear down on tree unmount
+ * manager.dispose();
+ * ```
+ */
+export class ListenerLifecycleManager {
+    scopes = new Map();
+    _disposed = false;
+    /**
+     * Register a DOM event listener tied to a scope.
+     *
+     * The listener is added to the target immediately and tracked. Returns a
+     * cleanup function that removes the listener and its tracking entry.
+     * The cleanup function is idempotent — safe to call multiple times.
+     *
+     * After `dispose()`, this method is a no-op and returns a no-op cleanup.
+     */
+    addListener(scopeId, target, event, handler, options) {
+        if (this._disposed)
+            return () => { };
+        target.addEventListener(event, handler, options);
+        const record = { target, event, handler, options };
+        let records = this.scopes.get(scopeId);
+        if (!records) {
+            records = [];
+            this.scopes.set(scopeId, records);
+        }
+        records.push(record);
+        let removed = false;
+        return () => {
+            if (removed)
+                return;
+            removed = true;
+            target.removeEventListener(event, handler, options);
+            const recs = this.scopes.get(scopeId);
+            if (recs) {
+                const idx = recs.indexOf(record);
+                if (idx >= 0)
+                    recs.splice(idx, 1);
+                if (recs.length === 0)
+                    this.scopes.delete(scopeId);
+            }
+        };
+    }
+    /**
+     * Remove all listeners for a given scope and clear its tracking.
+     *
+     * Called when a node is destroyed or culled off-screen. Safe to call
+     * with a scope that doesn't exist (no-op) or after dispose.
+     */
+    cleanupScope(scopeId) {
+        const records = this.scopes.get(scopeId);
+        if (!records)
+            return;
+        for (const { target, event, handler, options } of records) {
+            target.removeEventListener(event, handler, options);
+        }
+        this.scopes.delete(scopeId);
+    }
+    /** Whether a scope has any active tracked listeners. */
+    hasScope(scopeId) {
+        const records = this.scopes.get(scopeId);
+        return !!records && records.length > 0;
+    }
+    /**
+     * Dispose the manager, removing ALL tracked listeners across all scopes.
+     *
+     * After disposal, `addListener()` becomes a no-op. Safe to call multiple
+     * times — subsequent calls are no-ops.
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        for (const records of this.scopes.values()) {
+            for (const { target, event, handler, options } of records) {
+                target.removeEventListener(event, handler, options);
+            }
+        }
+        this.scopes.clear();
+    }
+    /** Whether this manager has been disposed. */
+    get disposed() {
+        return this._disposed;
+    }
+    /** Get a diagnostic snapshot of current state. */
+    getState() {
+        let totalListeners = 0;
+        for (const records of this.scopes.values()) {
+            totalListeners += records.length;
+        }
+        return {
+            totalListeners,
+            activeScopeCount: this.scopes.size,
+            disposed: this._disposed,
+        };
+    }
+}
+// ─── Preact hook ─────────────────────────────────────────────────────────────
+/**
+ * Hook for registering scope-aware event listeners with automatic cleanup.
+ *
+ * Returns an `addListener` function that registers listeners through the
+ * lifecycle manager. All listeners registered via this hook are automatically
+ * removed when the component unmounts or when the scope/manager changes.
+ *
+ * When no manager is provided (null), listeners are added directly to the
+ * target and tracked locally for cleanup on unmount — a safe fallback that
+ * still prevents leaks.
+ *
+ * @param manager  Shared lifecycle manager, or null to use local tracking only
+ * @param scopeId  Scope identifier (typically a node ID)
+ */
+export function useNodeListeners(manager, scopeId) {
+    const cleanupsRef = useRef([]);
+    // Cleanup on unmount or scope/manager change.
+    useEffect(() => {
+        return () => {
+            for (const cleanup of cleanupsRef.current)
+                cleanup();
+            cleanupsRef.current = [];
+        };
+    }, [manager, scopeId]);
+    return useCallback((target, event, handler, options) => {
+        if (manager) {
+            const cleanup = manager.addListener(scopeId, target, event, handler, options);
+            cleanupsRef.current.push(cleanup);
+        }
+        else {
+            // Fallback: track locally without a manager
+            target.addEventListener(event, handler, options);
+            cleanupsRef.current.push(() => target.removeEventListener(event, handler, options));
+        }
+    }, [manager, scopeId]);
+}
+//# sourceMappingURL=listener-lifecycle.js.map

package/packages/web/dist/viewer/components/prd-tree/listener-lifecycle.js.map

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

package/packages/web/dist/viewer/components/prd-tree/merge-preview.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Merge preview panel for PRD items.
+ *
+ * Shows a preview of what will happen when items are consolidated:
+ * - Which item survives (the target)
+ * - Which items are absorbed (removed)
+ * - Combined acceptance criteria, tags, description
+ * - Children that will be reparented
+ * - Dependencies that will be rewritten
+ *
+ * Lets the user optionally override the merged title/description
+ * before confirming.
+ */
+import type { PRDItemData } from "./types.js";
+export interface MergePreviewProps {
+    /** All selected items to merge (must be siblings at the same level). */
+    selectedItems: PRDItemData[];
+    /** Called after a successful merge (to refresh data). */
+    onMergeComplete: () => void;
+    /** Called to close the preview without merging. */
+    onCancel: () => void;
+}
+export declare function MergePreview({ selectedItems, onMergeComplete, onCancel }: MergePreviewProps): import("preact").VNode<import("preact").ClassAttributes<HTMLElement> & {
+    class: string;
+}>;