@keenmate/svelte-treeview 5.0.0-rc11 → 5.0.0-rc12

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0-rc12] - 2026-06-28 [PUBLISHED]
+
+Showcase / docs polish (a context-menu doc note and a theming-playground CSS fix surfaced by manual review of `/examples/theming` and `/examples/tree-editor`), plus one library correctness fix: keyboard copy/cut/paste threw on default `$state` data.
+
+### Fixed
+- **Context menu: three fixes surfaced by driving the library menu from the Windows Explorer demo's right pane**. (1) **Re-opening on a different node no longer leaves the menu stuck** — the Floating-UI positioning `$effect` in `Tree.svelte` only depended on `contextMenuVisible`, so a second right-click on another node (visible stays `true`) didn't re-run it; `autoUpdate` stayed anchored to the first node's coordinates and only recomputes on scroll/resize, so the menu sat at the old spot until you left-clicked to close it (`visible → false`) and right-clicked again. The effect now also tracks `contextMenuX` / `contextMenuY` / `contextMenuNode`, so it tears down and re-anchors when the menu jumps nodes. (2) **Clicking a menu item now auto-closes the menu** — `ContextMenuLevel` (the `getContextMenuItemsCallback` render path) ran the item's `onclick` but never dismissed the menu, relying on each consumer to call the provided `close()` in every handler (the test/demo callbacks did so 15×). Leaf-item activation (click + Enter/Space) now closes the menu in a `finally`, so `close()` is optional — calling it anyway is harmless. Items that act incrementally (a toggle, a multi-step action) can opt out with the new `shouldCloseOnClick: false` and keep the menu open, dismissing it themselves via the captured `close` when finished (see Added). The snippet-based `ContextMenuItem` path is unchanged (its contract still hands `close` to the consumer). (3) **Dropped a `binding_property_non_reactive` warning** — `ContextMenuLevel` held item element refs in a plain array while `bind:this={itemEls[i]}` wrote into it; it's now `$state`, which also lets the submenu-positioning effect re-run once the parent item attaches. Regression coverage: `e2e/context-menu.spec.ts` gains a reposition-on-second-right-click case; `e2e/windows-explorer.spec.ts` asserts a menu item with no manual `close()` still dismisses the menu.
+- **A copied node now stays on the clipboard across multiple pastes — `pasteNodes` only clears the clipboard on cut**: `pasteNodes` called `clearClipboard()` unconditionally after every paste, so a `copy` was single-use — paste once and the clipboard was empty, contradicting every file manager / IDE (Finder, Explorer, VS Code) where a copy can be pasted repeatedly. Now the clipboard is cleared only when `clip.operation === 'cut'` (a move is one-shot — its source nodes were just removed); a `copy` persists so it can be pasted again (each paste re-runs `beforePasteCallback`, so successive pastes into the same parent get `Copy 1`, `Copy 2`, … via the demo's collision-naming, which strips any prior ` Copy N` first so repeats don't compound into `Copy 1 Copy 1`). Applied to both the auto-handled path and the `shouldAutoHandlePaste=false` forwarding path; cut-dimming (`cutPaths`) is still cleared on every paste. This brings svelte-treeview into parity with `@keenmate/web-treeview`, whose `pasteNodes` already clears the clipboard only inside its `if (operation === 'cut')` block — svelte-treeview was the diverging side. Regression coverage in `e2e/clipboard.spec.ts`: a copy pasted twice adds two nodes, and a cut's second paste is a no-op (clipboard emptied by the move).
+- **Keyboard copy/cut/paste (`copyNodes` / `cutNodes`) no longer throw on `$state` data — `structuredClone` can't clone a Svelte reactive proxy**: `TreeController._collectClipboardEntry` snapshotted each node's data with `structuredClone(node.data)`. For any consumer passing the default deeply-reactive `$state` array (the common case), `node.data` is a `Proxy`, and `structuredClone` throws `DataCloneError: ... could not be cloned` — so the copy silently failed and a subsequent paste found an empty clipboard. Swapped both clone sites (the root entry and the recursive descendant walk) to `$state.snapshot(...)`, which deproxies reactive state into a plain deep clone and is a no-op-style passthrough for already-plain data, so it's correct whether the consumer uses `$state`, `$state.raw`, or unproxied arrays. Surfaced while wiring Ctrl/Cmd+C/X/V into `/examples/tree-editor` (which uses plain `$state`). Regression coverage: new `e2e/clipboard.spec.ts` against a new `/test/clipboard` fixture that deliberately uses plain `$state` data — copy→paste duplicates a node, cut→paste moves it (count unchanged), cut dims + Escape un-dims, and Ctrl+click multi-select copies several nodes at once.
+- **Brand themes in the `/examples/theming` "Dark Mode Playground" no longer lose their surface in per-instance light mode — Glass in particular stopped rendering white-on-white**: the demo's generic per-instance surface rules (`:global(.playground-wrapper:has(.stv__container[data-theme='light'])) { background: #f9fafb }` and the matching dark variant) carried specificity `(0,3,0)`, which outranks every brand theme's *base* rule `:global(.playground-wrapper.brand-X)` at `(0,2,0)`. In **inherit** and **dark** modes nothing collided — there's no light `:has()` match, and each brand owns a higher-specificity `.brand-X:has(...dark)` rule that wins — but in **light** mode the brand themes have no light-variant rule, so the generic gray override won and reverted the wrapper to plain `#f9fafb`. Most brand themes degraded quietly (their `--base-*` tokens still themed the tree, dark text stayed readable), but **Glass** forces `--base-text-color-1: #ffffff`, so picking `theme="light"` left white labels on a now-white surface — the node text vanished, only the emoji icons showed. Fix scopes the four generic `:has()` surface-flip rules (two wrapper, two tree) to `.brand-default` only: the unstyled default theme is the sole case that needs the generic flip, and every real brand theme already covers all three modes via its base rule (light) and `.brand-X:has(...dark)` variant (dark). Regression coverage: new `e2e/theming-brand.spec.ts` (6 cases) asserts each gradient brand (material / neon / soft / glass / forest) keeps a `linear-gradient` wrapper surface across inherit / dark / light, with a dedicated check that Glass light mode renders its `rgb(102, 126, 234)` purple — the existing `e2e/theming.spec.ts` only exercised dark-mode *signal precedence* via a synthetic Debug theme and never touched the real brand themes, which is why this slipped through.
+
+### Added
+- **`ContextMenuItem.shouldCloseOnClick?: boolean` (default `true`) — per-item opt-out of the new auto-close**: the callback menu now auto-closes after a leaf item is activated (see Fixed), which is the right default for one-shot commands (Open, Delete, Copy path). But some items act *incrementally* — a toggle, a counter, a multi-step action — and want the menu to stay open so the user can click again or read updated state. Setting `shouldCloseOnClick: false` on a `ContextMenuItem` suppresses the auto-close for that entry only; the handler then owns dismissal and calls the `close` callback it captured from `getContextMenuItemsCallback(node, close, …)` (or the snippet's `close` prop) when it's done. Named per the codebase's `should*` boolean-prop convention (sibling fields `isDisabled` / `isVisible`). Implemented in `ContextMenuLevel.svelte` by gating both the click and Enter/Space `finally` close on `item.shouldCloseOnClick !== false`. The `/test/context-menu` fixture gains a "Bump (stays open)" item that increments a counter without closing; `e2e/context-menu.spec.ts` asserts the menu survives repeated clicks of it and that a normal item still dismisses afterward.
+- **Data-driven per-node class hooks `nodeClass?: (node) => string` and `nodeContentClass?: (node) => string`**: previously the only per-row class hooks were *state* classes (`highlightedNodeClass` / `focusedNodeClass` / `dragOverNodeClass`) — there was no way to tag a row from its own data (e.g. `is-folder` / `is-file`, a status colour, a grid-participation class) without reaching into `[data-tree-path="…"]` selectors. These two callbacks run per node and return class(es) applied to `.stv__node` (`nodeClass`) and `.stv__node-content` (`nodeContentClass`); they recompute on the node's `_rev` bump like the rest of the render. Plumbed through `NodeConfig` (stable context reference, no prop-drilling) so they don't defeat flat-mode diffing. Wired end-to-end on `<Tree>` (prop → `$effect` sync → `update()` passthrough) and on the `createTreeController` props. New `/test/node-class` fixture + `e2e/node-class.spec.ts` (3 cases) assert the classes land on the right elements and are stylable from app CSS. Motivated by the Explorer demo's right pane needing folder/file row styling.
+- **Public `onNodeDoubleClick?: (node) => void` `<Tree>` event — a real double-click notification, reliable in flat rendering where the native `dblclick` is not**: there was previously no way for a consumer to react to a node double-click. The controller already did manual double-click *detection* (tracking last path + timestamp on the controller, 400ms window) but only internally and only for `clickBehavior="select"`, where a double toggles expand/collapse — and it deliberately avoids the browser's native `dblclick` because the first click bumps `node._rev`, the flat-mode `{#each}` destroys and recreates the row, and the second click lands on a fresh element so the browser refuses to synthesize a `dblclick`. That detection is now generalized to **every** `clickBehavior` and fires the new `onNodeDoubleClick` event; `select` mode additionally keeps its built-in expand/collapse-on-double. On a detected double the second click is consumed (early return) so the gesture reads as a single open rather than a re-toggle — a double therefore fires `onNodeClick` once (the first click) plus `onNodeDoubleClick` once. Detection is gated to genuine UI clicks (a new internal `uiClick` flag on the click path), so programmatic `highlightNode` / `selectNode` calls can never be mistaken for a double-click. Wired end-to-end through `<Tree>` (prop → `$effect` sync → `update()` passthrough) and dogfooded in the Windows Explorer demo's nav tree (double-click a folder opens it in the right pane). New `/test/double-click` fixture + `e2e/double-click.spec.ts` (4 cases) cover firing in both `select` and `expand-and-focus` modes, the single-click negative, and the two-different-nodes negative.
+- **Windows File Explorer demo at `/examples/custom-layout`** (`WindowsExplorer.svelte`): a near-complete dual-pane Explorer clone where **both panes are `<Tree>` instances** with custom `nodeTemplate` renderers, showcasing how far the renderer composes. The left nav pane is a hierarchical `<Tree>` fed a folders-only slice (`leafIconClass=""` so childless folders show no marker, like Explorer); the right pane is a **flat `<Tree>`** rendering the details list (Name / Date modified / Type / Size) as a 4-column grid — the columns line up because each row's `.stv__node-content` is a CSS grid sharing the sticky header's track template inside one scroll area (toggle icons hidden, indent zeroed via `--stv-node-indent-per-level: 0`). The right pane gets **selection** (`selectionMode="multi"` + `bind:highlightedPaths`), **keyboard navigation**, the **right-click context menu** (`getContextMenuItemsCallback` → Open / Copy path / Rename / Delete / New folder / Select all), **double-click-to-open** (`onNodeDoubleClick`), and **per-row folder/file classes** (`nodeClass`) all from the library — replacing the earlier hand-rolled list, custom selection set, debounced click handler and bespoke floating menu. The two panes stay in sync through the tree's public API — `expandNodes()` + `focusNode()` — driven from `onNodeClick` / `onNodeDoubleClick`. The dataset models a real `C:\Windows` install (~30 folders, multi-level subfolders + files). Also: per-column sorting (folders-first); **recursive search** across the current folder's subtree with each hit's location shown and **wildcard globs** (`*.dll`, `img?.jpg`); and working New folder / Rename / Delete that mutate the data and restore nav-tree expansion via `getExpandedPaths()` / `setExpandedPaths()`. Rendered as the first card on the existing Custom Layout page (the iOS-Files and Notepad++ demos remain below). Smoke-covered by `e2e/windows-explorer.spec.ts` (12 cases).
+- **Public `onCopy` / `onCut` / `onPaste` `<Tree>` events — post-operation clipboard notifications, symmetric with the `beforeCopy/Cut/Paste` interceptors**: these belong to the library's **Events** family (`on*`), distinct from the `before*Callback` interceptor and `get*Callback` provider families. The controller already fired an `onPaste` handler, but it was only reachable through `createTreeController` props — the `<Tree>` component never forwarded it, and there were no copy/cut equivalents at all. Added `onCopy?: (paths: string[]) => void` and `onCut?: (paths: string[]) => void` (fired after `copyNodes` / `cutNodes` succeed, with the final paths post-interceptor) on the controller, and forwarded all three (`onCopy`, `onCut`, `onPaste`) as `<Tree>` props with the usual `$effect` sync + `update()` passthrough. This completes the clipboard surface: `before*Callback` to rewrite/block, `on*` to react. The "Copy N"-on-collision rename is done in `beforePasteCallback` (mutating the clipboard entries' data before insert), not in `onPaste` — the `on*` events fire after the tree has already changed. Documented in `docs/usage.md` (event table + a new clipboard-interceptor table).
+- **`/examples/tree-editor` gains multi-select + keyboard copy/cut/paste (Ctrl/Cmd + C / X / V)**: the editor now sets `selectionMode="multi"` (Ctrl/Cmd+click and Shift+click extend `highlightedPaths`) and wires the clipboard through the documented `onTreeKeydown(event, controller)` hook. The library already implemented the operations (`copyNodes` / `cutNodes` / `pasteNodes` / `cancelCut`, a shared cross-tree clipboard, and `Escape`→cancel-cut) but intentionally leaves the key *bindings* to the consumer, because paste needs an app-specific `transformData` (the demo assigns fresh ids so pasted copies don't collide) and a target path (the focused node, or root). Copy/cut act on the highlight set when present, else the focused node; paste lands as a child of the focused node. Cut nodes dim until pasted (the demo renders this from a local set in its `nodeTemplate` — the controller exposes `cutPaths` but doesn't paint dimming itself), and `mod` is `event.ctrlKey || event.metaKey` so it works with Cmd on macOS. The demo also wires the new `onCopy` / `onCut` / `onPaste` events (for its activity log) and a `beforePasteCallback` that (a) appends `"Copy 1"` / `"Copy 2"` / … to a pasted copy whose name already exists under the target — stripping any prior ` Copy N` first so repeated pastes number sequentially instead of compounding (only the root is renamed; descendants keep their names; a move keeps the name), and (b) redirects a paste that lands on the copied node itself — Ctrl/Cmd+C then Ctrl/Cmd+V without moving focus — into that node's parent, so the copy drops in as a sibling ("duplicate in the same folder"). Because `beforePasteCallback` runs before the paste-into-self guard, the redirect also sidesteps that guard cleanly.
+
+### Changed
+- **Context Menu Examples page leads with a "Positioning is handled by Floating UI" note**: a short explainer (moved to sit directly below the page header, above the first example card) documenting that the root menu and submenus are placed by `@floating-ui/dom` via `computePosition` + `offset` / `flip` / `shift` / `autoUpdate`, that submenus flip left when there's no room on the right, and that `contextMenuXOffset` / `contextMenuYOffset` feed the root menu's cursor offset.
+- **`/examples/tree-editor` polish**: single click now selects without expanding and double-click toggles expand (`clickBehavior="select"`, was the default `'expand-and-focus'`), and the code-example import was corrected from a default import (`import Tree from …`) to the named `import { Tree } from '@keenmate/svelte-treeview'` — `Tree` is a named export, so the default form resolved to `undefined`.
+
 ## [5.0.0-rc11] - 2026-06-25 [PUBLISHED]
 
 Consolidated release folding the work previously staged under the unpublished rc12 and rc13 headings (npm's last published `rc` was rc10; the rc12/rc13 labels were never shipped, so this lands as rc11). Three themes: a `/validate-web-component` alignment sweep against the BlissFramework `web-components` guidelines (BEM/prefix `ltree`→`stv` rename, `is*/should*` boolean naming, dark-mode Strategy-B rewrite, README split), the three-level selection / highlight / focus API normalization, and a batch of drag-drop and highlight-marker correctness fixes. Within-RC references to "rc12" below denote earlier iterations of this same unpublished cycle.

package/README.md

@@ -31,6 +31,16 @@ svelte-treeview is broader (two rendering modes, easier vertical guide lines via
 
 Browse interactive code examples and the full API reference at **[svelte-treeview.keenmate.dev](https://svelte-treeview.keenmate.dev)**
 
+## What's New in v5.0.0-rc12
+
+- **Context menus — items auto-close on click, with a `shouldCloseOnClick` opt-out, plus a reposition fix** — Activating a leaf item in a `getContextMenuItemsCallback` menu now dismisses the menu in a `finally`, so handlers no longer need to call the provided `close()` themselves (the test/demo callbacks were doing it 15×); calling it anyway is harmless. Items that act incrementally — a toggle, a counter, a multi-step action — opt out with the new `ContextMenuItem.shouldCloseOnClick: false` (default `true`, named per the `should*` convention) and keep the menu open, dismissing it via the captured `close` when finished. Also fixed: re-opening the menu on a *different* node no longer leaves it stuck at the first node's coordinates — the Floating-UI positioning effect now tracks the menu's X/Y/node, not just its visibility — and a `binding_property_non_reactive` warning is gone.
+- **Per-node class hooks — `nodeClass` and `nodeContentClass` callbacks** — Two new data-driven callbacks let you tag a row from its own data (`is-folder`/`is-file`, a status color, a grid class) without reaching into `[data-tree-path="…"]` selectors. They run per node, return class(es) applied to `.stv__node` and `.stv__node-content` respectively, and recompute on the node's `_rev` bump like the rest of the render. Plumbed through `NodeConfig` so they don't defeat flat-mode diffing, and wired end-to-end on `<Tree>` (prop → `$effect` sync → `update()` passthrough) and on `createTreeController`.
+- **Double-click — a real `onNodeDoubleClick` event, reliable in flat rendering** — There was previously no way to react to a node double-click; the native `dblclick` is unreliable in flat mode because the first click bumps `_rev` and recreates the row out from under the browser. The controller's existing manual detection (last-path + timestamp, 400ms window) is now generalized to *every* `clickBehavior` and fires the new `onNodeDoubleClick`; `select` mode still toggles expand/collapse on a double. Detection is gated to genuine UI clicks, so programmatic `highlightNode`/`selectNode` can never be mistaken for a double.
+- **Clipboard events — `onCopy` / `onCut` / `onPaste` on `<Tree>`** — Post-operation notifications symmetric with the `beforeCopy/Cut/Paste` interceptors complete the clipboard surface (`before*Callback` to rewrite or block, `on*` to react). `onPaste` existed on the controller but `<Tree>` never forwarded it and there were no copy/cut equivalents; all three are now controller events forwarded as `<Tree>` props with the usual sync + `update()` passthrough. `/examples/tree-editor` gains multi-select and keyboard Ctrl/Cmd+C/X/V wired through the documented `onTreeKeydown` hook.
+- **Clipboard correctness — a copy now survives repeated pastes, and `$state` data no longer throws** — `pasteNodes` used to clear the clipboard after *every* paste, making a copy single-use (contradicting Finder/Explorer/VS Code); it now clears only on `cut` (a move is one-shot), so a copy can be pasted repeatedly. Separately, copy/cut threw `DataCloneError` on the common default `$state` data because `structuredClone` can't clone a Svelte reactive proxy — both clone sites now use `$state.snapshot(...)`, which deproxies reactive state and passes plain data through unchanged. Both fixed with new Playwright coverage.
+- **New demo — Windows File Explorer, where both panes are `<Tree>` instances** — A near-complete dual-pane Explorer clone at `/examples/custom-layout`: a hierarchical nav `<Tree>` on the left and a *flat* `<Tree>` rendering the details list as a 4-column CSS grid on the right, with selection, keyboard nav, right-click menu, double-click-to-open, and per-row folder/file classes all driven from the library — replacing the earlier hand-rolled list and bespoke menu. It dogfoods this release's new surfaces (`nodeClass`, `onNodeDoubleClick`, the context-menu auto-close) and stays in sync through the public `expandNodes()` / `focusNode()` API.
+- **Theming — brand themes keep their surface in per-instance light mode** — In the `/examples/theming` "Dark Mode Playground", the demo's generic `:has()` surface rules (specificity `(0,3,0)`) outranked each brand theme's base rule `(0,2,0)`, so picking `theme="light"` reverted the wrapper to plain gray — and Glass, which forces white text, rendered white-on-white with the labels vanishing. The four generic surface-flip rules are now scoped to `.brand-default` only; every real brand theme already covers all three modes. New `e2e/theming-brand.spec.ts` (6 cases) guards each gradient brand across inherit/dark/light.
+
 ## What's New in v5.0.0-rc11
 
 - **Selection model — three symmetric imperative families (highlight / select / focus)** — The imperative API had drifted into aliases and asymmetries: `selectNode`/`selectNodes` secretly drove the *highlight* set, the highlight set cleared with `clearHighlight()` while checkboxes cleared with `deselectAll()`, and `highlightNodes()` silently replaced rather than added. The surface is now three concerns × one shape — **highlight** (`highlightNode`/`highlightNodes`/`setHighlightedPaths`/`highlightAll`/`clearHighlight`) for the UI multi-select set, **select** (`selectNode`/`selectNodes`/`setSelectedPaths`/`selectAll`/`deselectNode`/`clearSelection`) for the checkbox set, and **focus** (`focusNode`/`clearFocus`) for the single cursor. Two shared types, `HighlightMode` and `TreeMutationOptions { silent? }`, replace the inline literals. Breaking within the RC: `deselectAll` → `clearSelection`, `highlightNodes` is now additive, and `selectNode`/`selectNodes` are now real checkbox setters.
@@ -41,16 +51,6 @@ Browse interactive code examples and the full API reference at **[svelte-treevie
 - **Context menus — positioning ported to `@floating-ui/dom`** — Root menu and submenus are now placed by `computePosition` + `autoUpdate` with `flip()`/`shift()` instead of raw inline `left/top` and CSS `:hover`, so menus flip above the cursor near the viewport bottom and submenus slide sideways instead of clipping. `contextMenuXOffset`/`contextMenuYOffset` keep their exact semantics.
 - **Docs — README cut to ~350 lines with topical docs split out** — The README dropped from 1103 to 347 lines: Advanced Usage, Styling, and API Reference moved into `docs/usage.md`, `docs/theming.md`, `docs/examples.md`, and `docs/accessibility.md`, with a new intro and a Demos & docs link block up top.
 
-## What's New in v5.0.0-rc10
-
-- **Built-in dark mode — all four canonical signals covered** — a `dark-mode.css` partial flips the tree's surface, text, border, and accent palette when any of the canonical signals is active: OS preference (`prefers-color-scheme: dark`), page `<html style="color-scheme: dark">` resolved via `light-dark()`, framework theme classes (`[data-theme="dark"]`, `[data-bs-theme="dark"]`, `.dark`), and the new per-instance `theme` prop. Symmetric `light` selectors let a single tree force light on an otherwise-dark page. Zero JavaScript — pure CSS resolution.
-- **`theme` prop on `<Tree>` — per-instance dark/light override** — `'dark' | 'light' | null | undefined`. Forwarded to the root `.stv__container` as `data-theme`, where per-instance CSS selectors take over and beat ambient signals. Leave `undefined` to inherit from the page. (rc10 originally landed this on `.ltree-container`; the BEM rename to `.stv__container` shipped in rc12.)
-- **CSS variables rescoped from `:root` to `.stv__container` — subtree theming actually works** — mirrors the `:host`-scoped pattern from sibling `@keenmate/*` components and is the only way `--base-*` theming flows at subtree scope. A wrapper around the tree that sets `--base-accent-color: red` now re-tints the tree (it previously had no effect because the substitution was frozen at `:root`). Multiple trees on the same page can be themed differently via wrapper-scoped `--base-*` overrides. Consumer note: setting `--stv-*` directly on a wrapper no longer cascades — use `--base-*` on the wrapper or target `.stv__container` explicitly.
-- **`--stv-bg` — the tree paints its own surface** — `.stv__container` gets a `background: var(--stv-bg)` so consumers don't need to wrap the tree in a colored container for a visible surface. Override to `transparent` to restore the pre-rc10 layered behavior. Companion `--stv-elevated-bg` reads through the `--base-elevated-bg` chain for floating chrome (context menu).
-- **CSS file layout aligned with the Bliss web-component guidelines** — all `_xxx.css` partials renamed to `xxx.css`, `main.css` now declares `@layer variables, component, overrides;` and imports each partial into the matching layer. Consumers' unlayered overrides automatically beat every rule in the library — no `!important` needed. Note: if your app ships an unlayered universal CSS reset (`* { padding: 0 }` from normalize / Bootstrap / Tailwind preflight / etc.), wrap it in a low-priority `@layer reset` or the tree's defaults won't apply.
-- **`getIsDropAllowedCallback` prop + `getIsDraggableCallback` seeded at insert-time** — callback variant for `isDropAllowedMember`, matching the pattern rc09 introduced for `getIsExpandedCallback` / `getIsSelectableCallback` / `getIsSelectedCallback`. Also, the existing `getIsDraggableCallback` prop is now actually applied during the seed walk — previously it was only consumed lazily in some paths.
-- **Bug fixes — virtual scroll + `clickBehavior='select'` double-click** — virtual scroll no longer gets stuck at bottom after a filter shrinks the tree. Double-click to expand in `clickBehavior='select'` mode finally works (the browser's native `dblclick` event couldn't fire because the first click destroyed the row via the focus re-render; the controller now detects the double manually).
-
 ## v5.0: Core/Renderer Split + Virtual Scroll
 
 > [!IMPORTANT]

package/dist/components/ContextMenuLevel.svelte

@@ -16,7 +16,9 @@
 
 	let openIdx = $state<number | null>(null);
 	let hideTimeout: ReturnType<typeof setTimeout> | null = null;
-	const itemEls: HTMLElement[] = [];
+	// $state so `bind:this={itemEls[i]}` writes are reactive and the submenu
+	// positioning $effect re-runs once the parent item element is attached.
+	let itemEls = $state<HTMLElement[]>([]);
 	let submenuEl = $state<HTMLElement | null>(null);
 
 	function cancelHide() {
@@ -82,6 +84,13 @@
 					await item.onclick?.();
 				} catch (error) {
 					console.error('Context menu callback error:', error);
+				} finally {
+					// Auto-close after activating a leaf item — selecting an entry dismisses
+					// the menu, like every native/desktop menu. Consumers no longer need to
+					// call the close callback themselves (doing so anyway is harmless).
+					// Opt out with shouldCloseOnClick: false to keep the menu open for incremental
+					// actions; the handler then dismisses it via its captured close callback.
+					if (item.shouldCloseOnClick !== false) closeContextMenu();
 				}
 			}}
 			onkeydown={async (e) => {
@@ -91,6 +100,8 @@
 						await item.onclick?.();
 					} catch (error) {
 						console.error('Context menu callback error:', error);
+					} finally {
+						if (item.shouldCloseOnClick !== false) closeContextMenu();
 					}
 				}
 			}}

package/dist/components/Node.svelte

@@ -62,6 +62,10 @@
 	const leafIconClass = $derived(config.leafIconClass);
 	const highlightedNodeClass = $derived(config.highlightedNodeClass);
 	const focusedNodeClass = $derived(config.focusedNodeClass);
+	// Data-driven per-row classes. The callbacks read node data; recompute when the
+	// node's _rev bumps (same trigger the rest of the render uses).
+	const customNodeClass = $derived(config.nodeClass ? (config.nodeClass(node) ?? '') : '');
+	const customNodeContentClass = $derived(config.nodeContentClass ? (config.nodeContentClass(node) ?? '') : '');
 	// dragOverNodeClass is applied to the DOM directly by the controller
 	// (see hoveredNodeForDrop $effect in TreeController) — no per-Node binding.
 	const isCopyAllowed = $derived(config.isCopyAllowed);
@@ -333,7 +337,7 @@
 
 <!-- svelte-ignore a11y_no_static_element_interactions -->
 <div
-	class="stv__node"
+	class="stv__node {customNodeClass}"
 	id="{node.treeId}-{node.id}"
 	data-tree-path="{node.path}"
 	style={indentStyle}
@@ -378,7 +382,7 @@
 		<!-- svelte-ignore a11y_click_events_have_key_events -->
 		<!-- svelte-ignore a11y_no_static_element_interactions -->
 		<div
-			class="stv__node-content {node.isHighlighted ? highlightedNodeClass : ''} {node.isFocused && focusedNodeClass ? focusedNodeClass : ''}"
+			class="stv__node-content {node.isHighlighted ? highlightedNodeClass : ''} {node.isFocused && focusedNodeClass ? focusedNodeClass : ''} {customNodeContentClass}"
 			class:stv__node-content--highlighted={node.isHighlighted && !highlightedNodeClass}
 			class:stv__node-content--focused={node.isFocused}
 			class:stv__clickable={node.isSelectable}

package/dist/components/Tree.svelte

@@ -148,11 +148,17 @@
 
 		// EVENTS (on* = fire-and-forget notifications)
 		onNodeClick?: (node: LTreeNode<T>) => void;
+		onNodeDoubleClick?: (node: LTreeNode<T>) => void;
 		onHighlightChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
 		onSelectionChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
 		onNodeDragStart?: (node: LTreeNode<T>, event: DragEvent) => void;
 		onNodeDragOver?: (node: LTreeNode<T>, event: DragEvent) => void;
 		onNodeDrop?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void;
+		// Post-operation clipboard notifications (fired AFTER the op). onCopy/onCut
+		// receive the final paths; onPaste receives the PasteResult.
+		onCopy?: (paths: string[]) => void;
+		onCut?: (paths: string[]) => void;
+		onPaste?: (result: import('../core/TreeController.svelte.js').PasteResult<T>) => void;
 
 		// INTERCEPTORS (before*Callback = can modify/block)
 		/**
@@ -178,6 +184,10 @@
 		bodyClass?: string | null | undefined;
 		highlightedNodeClass?: string | null | undefined;
 		focusedNodeClass?: string | null | undefined;
+		/** Data-driven per-row class hook. Return extra class(es) for `.stv__node`. */
+		nodeClass?: (node: LTreeNode<T>) => string | null | undefined;
+		/** Data-driven per-row class hook. Return extra class(es) for `.stv__node-content`. */
+		nodeContentClass?: (node: LTreeNode<T>) => string | null | undefined;
 		dragOverNodeClass?: string | null | undefined;
 		expandIconClass?: string | null | undefined;
 		collapseIconClass?: string | null | undefined;
@@ -296,11 +306,15 @@
 
 		// EVENTS
 		onNodeClick,
+		onNodeDoubleClick,
 		onHighlightChange,
 		onSelectionChange,
 		onNodeDragStart,
 		onNodeDragOver,
 		onNodeDrop,
+		onCopy,
+		onCut,
+		onPaste,
 		// INTERCEPTORS
 		beforeDropCallback,
 		beforeCopyCallback,
@@ -318,6 +332,8 @@
 		toggleIconMode = 'rotate',
 		highlightedNodeClass,
 		focusedNodeClass,
+		nodeClass,
+		nodeContentClass,
 		dragOverNodeClass,
 		scrollHighlightTimeout = 4000,
 		scrollHighlightClass = 'stv__node-content--scroll-highlight',
@@ -405,11 +421,15 @@
 		shouldAutoHandlePaste,
 		isAccordionExpand,
 		onNodeClick,
+		onNodeDoubleClick,
 		onHighlightChange,
 		onSelectionChange,
 		onNodeDragStart,
 		onNodeDragOver,
 		onNodeDrop,
+		onCopy,
+		onCut,
+		onPaste,
 		beforeDropCallback,
 		beforeCopyCallback,
 		beforeCutCallback,
@@ -419,6 +439,8 @@
 		bodyClass,
 		highlightedNodeClass,
 		focusedNodeClass,
+		nodeClass,
+		nodeContentClass,
 		dragOverNodeClass,
 		expandIconClass,
 		collapseIconClass,
@@ -463,6 +485,13 @@
 	let contextMenuEl = $state<HTMLDivElement | null>(null);
 	$effect(() => {
 		if (!controller.contextMenuVisible || !contextMenuEl) return;
+		// Track position + target so the effect re-runs (tears down the old autoUpdate
+		// and re-anchors) when a right-click moves the menu to a DIFFERENT node while
+		// it's already open — otherwise autoUpdate only recomputes on scroll/resize and
+		// the menu stays stuck at the first node's position.
+		void controller.contextMenuX;
+		void controller.contextMenuY;
+		void controller.contextMenuNode;
 		const xOff = controller.contextMenuXOffset ?? 0;
 		const yOff = controller.contextMenuYOffset ?? 0;
 		const virtualRef = {
@@ -523,6 +552,8 @@
 	$effect(() => { controller.leafIconClass = leafIconClass ?? 'stv__toggle-icon--leaf'; });
 	$effect(() => { controller.toggleIconMode = toggleIconMode ?? 'rotate'; });
 	$effect(() => { controller.highlightedNodeClass = highlightedNodeClass; });
+	$effect(() => { controller.nodeClass = nodeClass; });
+	$effect(() => { controller.nodeContentClass = nodeContentClass; });
 	$effect(() => { controller.focusedNodeClass = focusedNodeClass; });
 	$effect(() => { controller.dragOverNodeClass = dragOverNodeClass; });
 	$effect(() => { controller.dropZoneMode = dropZoneMode ?? 'glow'; });
@@ -536,11 +567,15 @@
 
 	// Callback sync
 	$effect(() => { controller.onNodeClickHandler = onNodeClick; });
+	$effect(() => { controller.onNodeDoubleClickHandler = onNodeDoubleClick; });
 	$effect(() => { controller.onHighlightChangeHandler = onHighlightChange; });
 	$effect(() => { controller.onSelectionChangeHandler = onSelectionChange; });
 	$effect(() => { controller.onNodeDragStartHandler = onNodeDragStart; });
 	$effect(() => { controller.onNodeDragOverHandler = onNodeDragOver; });
 	$effect(() => { controller.onNodeDropHandler = onNodeDrop; });
+	$effect(() => { controller.onCopyHandler = onCopy; });
+	$effect(() => { controller.onCutHandler = onCut; });
+	$effect(() => { controller.onPasteHandler = onPaste; });
 	$effect(() => { controller.beforeDropHandler = beforeDropCallback; });
 	$effect(() => { controller.beforeCopyHandler = beforeCopyCallback; });
 	$effect(() => { controller.beforeCutHandler = beforeCutCallback; });
@@ -825,11 +860,15 @@
 				| "shouldDisplayDebugInformation"
 				| "shouldDisplayContextMenuInDebugMode"
 				| "onNodeClick"
+				| "onNodeDoubleClick"
 				| "onHighlightChange"
 				| "onSelectionChange"
 				| "onNodeDragStart"
 				| "onNodeDragOver"
 				| "onNodeDrop"
+				| "onCopy"
+				| "onCut"
+				| "onPaste"
 				| "beforeDropCallback"
 				| "beforeCopyCallback"
 				| "beforeCutCallback"
@@ -847,6 +886,8 @@
 				| "leafIconClass"
 				| "toggleIconMode"
 				| "highlightedNodeClass"
+				| "nodeClass"
+				| "nodeContentClass"
 				| "focusedNodeClass"
 				| "dragOverNodeClass"
 				| "scrollHighlightTimeout"
@@ -904,11 +945,15 @@
 		if (updates.shouldDisplayDebugInformation !== undefined) shouldDisplayDebugInformation = updates.shouldDisplayDebugInformation;
 		if (updates.shouldDisplayContextMenuInDebugMode !== undefined) shouldDisplayContextMenuInDebugMode = updates.shouldDisplayContextMenuInDebugMode;
 		if (updates.onNodeClick !== undefined) onNodeClick = updates.onNodeClick;
+		if (updates.onNodeDoubleClick !== undefined) onNodeDoubleClick = updates.onNodeDoubleClick;
 		if (updates.onHighlightChange !== undefined) onHighlightChange = updates.onHighlightChange;
 		if (updates.onSelectionChange !== undefined) onSelectionChange = updates.onSelectionChange;
 		if (updates.onNodeDragStart !== undefined) onNodeDragStart = updates.onNodeDragStart;
 		if (updates.onNodeDragOver !== undefined) onNodeDragOver = updates.onNodeDragOver;
 		if (updates.onNodeDrop !== undefined) onNodeDrop = updates.onNodeDrop;
+		if (updates.onCopy !== undefined) onCopy = updates.onCopy;
+		if (updates.onCut !== undefined) onCut = updates.onCut;
+		if (updates.onPaste !== undefined) onPaste = updates.onPaste;
 		if (updates.beforeDropCallback !== undefined) beforeDropCallback = updates.beforeDropCallback;
 		if (updates.beforeCopyCallback !== undefined) beforeCopyCallback = updates.beforeCopyCallback;
 		if (updates.beforeCutCallback !== undefined) beforeCutCallback = updates.beforeCutCallback;
@@ -926,6 +971,8 @@
 		if (updates.leafIconClass !== undefined) leafIconClass = updates.leafIconClass;
 		if (updates.toggleIconMode !== undefined) toggleIconMode = updates.toggleIconMode;
 		if (updates.highlightedNodeClass !== undefined) highlightedNodeClass = updates.highlightedNodeClass;
+		if (updates.nodeClass !== undefined) nodeClass = updates.nodeClass;
+		if (updates.nodeContentClass !== undefined) nodeContentClass = updates.nodeContentClass;
 		if (updates.focusedNodeClass !== undefined) focusedNodeClass = updates.focusedNodeClass;
 		if (updates.dragOverNodeClass !== undefined) dragOverNodeClass = updates.dragOverNodeClass;
 		if (updates.scrollHighlightTimeout !== undefined) scrollHighlightTimeout = updates.scrollHighlightTimeout;

package/dist/components/Tree.svelte.d.ts

@@ -103,11 +103,15 @@ declare function $$render<T>(): {
         shouldAutoHandlePaste?: boolean;
         isAccordionExpand?: boolean;
         onNodeClick?: (node: LTreeNode<T>) => void;
+        onNodeDoubleClick?: (node: LTreeNode<T>) => void;
         onHighlightChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
         onSelectionChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
         onNodeDragStart?: (node: LTreeNode<T>, event: DragEvent) => void;
         onNodeDragOver?: (node: LTreeNode<T>, event: DragEvent) => void;
         onNodeDrop?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void;
+        onCopy?: (paths: string[]) => void;
+        onCut?: (paths: string[]) => void;
+        onPaste?: (result: import("../core/TreeController.svelte.js").PasteResult<T>) => void;
         /**
          * Called before a drop is processed. Return false to cancel the drop.
          * Return { position, operation } to override the drop position or operation.
@@ -136,6 +140,10 @@ declare function $$render<T>(): {
         bodyClass?: string | null | undefined;
         highlightedNodeClass?: string | null | undefined;
         focusedNodeClass?: string | null | undefined;
+        /** Data-driven per-row class hook. Return extra class(es) for `.stv__node`. */
+        nodeClass?: (node: LTreeNode<T>) => string | null | undefined;
+        /** Data-driven per-row class hook. Return extra class(es) for `.stv__node-content`. */
+        nodeContentClass?: (node: LTreeNode<T>) => string | null | undefined;
         dragOverNodeClass?: string | null | undefined;
         expandIconClass?: string | null | undefined;
         collapseIconClass?: string | null | undefined;
@@ -325,11 +333,15 @@ declare function $$render<T>(): {
             shouldAutoHandlePaste?: boolean;
             isAccordionExpand?: boolean;
             onNodeClick?: (node: LTreeNode<T>) => void;
+            onNodeDoubleClick?: (node: LTreeNode<T>) => void;
             onHighlightChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
             onSelectionChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
             onNodeDragStart?: (node: LTreeNode<T>, event: DragEvent) => void;
             onNodeDragOver?: (node: LTreeNode<T>, event: DragEvent) => void;
             onNodeDrop?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void;
+            onCopy?: (paths: string[]) => void;
+            onCut?: (paths: string[]) => void;
+            onPaste?: (result: import("../core/TreeController.svelte.js").PasteResult<T>) => void;
             /**
              * Called before a drop is processed. Return false to cancel the drop.
              * Return { position, operation } to override the drop position or operation.
@@ -358,6 +370,10 @@ declare function $$render<T>(): {
             bodyClass?: string | null | undefined;
             highlightedNodeClass?: string | null | undefined;
             focusedNodeClass?: string | null | undefined;
+            /** Data-driven per-row class hook. Return extra class(es) for `.stv__node`. */
+            nodeClass?: (node: LTreeNode<T>) => string | null | undefined;
+            /** Data-driven per-row class hook. Return extra class(es) for `.stv__node-content`. */
+            nodeContentClass?: (node: LTreeNode<T>) => string | null | undefined;
             dragOverNodeClass?: string | null | undefined;
             expandIconClass?: string | null | undefined;
             collapseIconClass?: string | null | undefined;
@@ -371,7 +387,7 @@ declare function $$render<T>(): {
             onTreeKeydown?: (event: KeyboardEvent, controller: TreeController<T>) => boolean | void;
             /** Override individual navigation methods (e.g. for custom ArrowDown/Up behavior) */
             navigationOverrides?: TreeNavigationOverrides<T>;
-        }, "treeId" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "getIsExpandedCallback" | "isSelectableMember" | "getIsSelectableCallback" | "isSelectedMember" | "getIsSelectedCallback" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "getIsDropAllowedCallback" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "orderMember" | "isSorted" | "sortCallback" | "data" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "selectionMode" | "shouldShowCheckboxes" | "checkboxMode" | "shouldClickToggleCheckbox" | "beforeCheckboxToggleCallback" | "rangeSelectionMode" | "shouldUseInternalSearchIndex" | "initializeIndexCallback" | "searchText" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayDebugInformation" | "shouldDisplayContextMenuInDebugMode" | "onNodeClick" | "onHighlightChange" | "onSelectionChange" | "onNodeDragStart" | "onNodeDragOver" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "getContextMenuItemsCallback" | "isVirtualScrollEnabled" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "bodyClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "highlightedNodeClass" | "focusedNodeClass" | "dragOverNodeClass" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset" | "isAccordionExpand">>) => void;
+        }, "treeId" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "getIsExpandedCallback" | "isSelectableMember" | "getIsSelectableCallback" | "isSelectedMember" | "getIsSelectedCallback" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "getIsDropAllowedCallback" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "orderMember" | "isSorted" | "sortCallback" | "data" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "selectionMode" | "shouldShowCheckboxes" | "checkboxMode" | "shouldClickToggleCheckbox" | "beforeCheckboxToggleCallback" | "rangeSelectionMode" | "shouldUseInternalSearchIndex" | "initializeIndexCallback" | "searchText" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayDebugInformation" | "shouldDisplayContextMenuInDebugMode" | "onNodeClick" | "onNodeDoubleClick" | "onHighlightChange" | "onSelectionChange" | "onNodeDragStart" | "onNodeDragOver" | "onNodeDrop" | "onCopy" | "onCut" | "onPaste" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "getContextMenuItemsCallback" | "isVirtualScrollEnabled" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "bodyClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "highlightedNodeClass" | "nodeClass" | "nodeContentClass" | "focusedNodeClass" | "dragOverNodeClass" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset" | "isAccordionExpand">>) => void;
     };
     bindings: "data" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "searchText" | "insertResult" | "isRendering";
     slots: {};
@@ -557,11 +573,15 @@ declare class __sveltets_Render<T> {
             shouldAutoHandlePaste?: boolean;
             isAccordionExpand?: boolean;
             onNodeClick?: ((node: LTreeNode<T>) => void) | undefined;
+            onNodeDoubleClick?: ((node: LTreeNode<T>) => void) | undefined;
             onHighlightChange?: ((paths: Set<string>, nodes: LTreeNode<T>[]) => void) | undefined;
             onSelectionChange?: ((paths: Set<string>, nodes: LTreeNode<T>[]) => void) | undefined;
             onNodeDragStart?: ((node: LTreeNode<T>, event: DragEvent) => void) | undefined;
             onNodeDragOver?: ((node: LTreeNode<T>, event: DragEvent) => void) | undefined;
             onNodeDrop?: ((dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void) | undefined;
+            onCopy?: ((paths: string[]) => void) | undefined;
+            onCut?: ((paths: string[]) => void) | undefined;
+            onPaste?: ((result: import("../core/TreeController.svelte.js").PasteResult<T>) => void) | undefined;
             /**
              * Called before a drop is processed. Return false to cancel the drop.
              * Return { position, operation } to override the drop position or operation.
@@ -590,6 +610,10 @@ declare class __sveltets_Render<T> {
             bodyClass?: string | null | undefined;
             highlightedNodeClass?: string | null | undefined;
             focusedNodeClass?: string | null | undefined;
+            /** Data-driven per-row class hook. Return extra class(es) for `.stv__node`. */
+            nodeClass?: ((node: LTreeNode<T>) => string | null | undefined) | undefined;
+            /** Data-driven per-row class hook. Return extra class(es) for `.stv__node-content`. */
+            nodeContentClass?: ((node: LTreeNode<T>) => string | null | undefined) | undefined;
             dragOverNodeClass?: string | null | undefined;
             expandIconClass?: string | null | undefined;
             collapseIconClass?: string | null | undefined;
@@ -603,7 +627,7 @@ declare class __sveltets_Render<T> {
             onTreeKeydown?: ((event: KeyboardEvent, controller: TreeController<T>) => boolean | void) | undefined;
             /** Override individual navigation methods (e.g. for custom ArrowDown/Up behavior) */
             navigationOverrides?: Partial<import("../core/navigation.js").TreeNavigation<T>> | undefined;
-        }, "treeId" | "data" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "getIsExpandedCallback" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "orderMember" | "isSorted" | "sortCallback" | "isSelectableMember" | "getIsSelectableCallback" | "isSelectedMember" | "getIsSelectedCallback" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "getIsDropAllowedCallback" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "shouldDisplayDebugInformation" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "beforeCheckboxToggleCallback" | "getContextMenuItemsCallback" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "selectionMode" | "shouldShowCheckboxes" | "checkboxMode" | "shouldClickToggleCheckbox" | "rangeSelectionMode" | "initializeIndexCallback" | "searchText" | "shouldUseInternalSearchIndex" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayContextMenuInDebugMode" | "isVirtualScrollEnabled" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "isAccordionExpand" | "onNodeClick" | "onNodeDragStart" | "onNodeDragOver" | "onHighlightChange" | "onSelectionChange" | "bodyClass" | "highlightedNodeClass" | "focusedNodeClass" | "dragOverNodeClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset">>) => void;
+        }, "treeId" | "data" | "treePathSeparator" | "idMember" | "pathMember" | "parentPathMember" | "levelMember" | "hasChildrenMember" | "isExpandedMember" | "getIsExpandedCallback" | "displayValueMember" | "getDisplayValueCallback" | "searchValueMember" | "getSearchValueCallback" | "orderMember" | "isSorted" | "sortCallback" | "isSelectableMember" | "getIsSelectableCallback" | "isSelectedMember" | "getIsSelectedCallback" | "isDraggableMember" | "getIsDraggableCallback" | "isDropAllowedMember" | "getIsDropAllowedCallback" | "isCollapsibleMember" | "getIsCollapsibleCallback" | "shouldDisplayDebugInformation" | "onNodeDrop" | "beforeDropCallback" | "beforeCopyCallback" | "beforeCutCallback" | "beforePasteCallback" | "beforeCheckboxToggleCallback" | "getContextMenuItemsCallback" | "focusedNode" | "highlightedPaths" | "selectedPaths" | "expandLevel" | "clickBehavior" | "selectionMode" | "shouldShowCheckboxes" | "checkboxMode" | "shouldClickToggleCheckbox" | "rangeSelectionMode" | "initializeIndexCallback" | "searchText" | "shouldUseInternalSearchIndex" | "indexerBatchSize" | "indexerTimeout" | "shouldDisplayContextMenuInDebugMode" | "isVirtualScrollEnabled" | "virtualRowHeight" | "virtualOverscan" | "virtualContainerHeight" | "dragDropMode" | "dropZoneMode" | "isAccordionExpand" | "onNodeClick" | "onNodeDoubleClick" | "onNodeDragStart" | "onNodeDragOver" | "onHighlightChange" | "onSelectionChange" | "onCopy" | "onCut" | "onPaste" | "bodyClass" | "highlightedNodeClass" | "focusedNodeClass" | "nodeClass" | "nodeContentClass" | "dragOverNodeClass" | "expandIconClass" | "collapseIconClass" | "leafIconClass" | "toggleIconMode" | "scrollHighlightTimeout" | "scrollHighlightClass" | "contextMenuXOffset" | "contextMenuYOffset">>) => void;
     };
 }
 interface $$IsomorphicComponent {

package/dist/constants.generated.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "5.0.0-rc11";
+export declare const VERSION = "5.0.0-rc12";
 export declare const PACKAGE_NAME = "@keenmate/svelte-treeview";
 export declare const AUTHOR = "KeenMate";
 export declare const LICENSE = "MIT";

package/dist/constants.generated.js

@@ -1,6 +1,6 @@
 // Auto-generated file - do not edit manually
 // Generated by scripts/generate-constants.js
-export const VERSION = "5.0.0-rc11";
+export const VERSION = "5.0.0-rc12";
 export const PACKAGE_NAME = "@keenmate/svelte-treeview";
 export const AUTHOR = "KeenMate";
 export const LICENSE = "MIT";

package/dist/core/TreeController.svelte.d.ts

@@ -46,6 +46,8 @@ export interface NodeConfig {
     highlightedNodeClass: string | null | undefined;
     focusedNodeClass: string | null | undefined;
     dragOverNodeClass: string | null | undefined;
+    nodeClass: ((node: LTreeNode<any>) => string | null | undefined) | undefined;
+    nodeContentClass: ((node: LTreeNode<any>) => string | null | undefined) | undefined;
     dropZoneMode: 'floating' | 'glow';
     dropZoneLayout: 'around' | 'above' | 'below' | 'wave' | 'wave2';
     dropZoneStart: number | string;
@@ -152,11 +154,14 @@ export interface TreeControllerProps<T> {
     shouldAutoHandlePaste?: boolean;
     isAccordionExpand?: boolean;
     onNodeClick?: (node: LTreeNode<T>) => void;
+    onNodeDoubleClick?: (node: LTreeNode<T>) => void;
     onNodeDragStart?: (node: LTreeNode<T>, event: DragEvent) => void;
     onNodeDragOver?: (node: LTreeNode<T>, event: DragEvent) => void;
     onNodeDrop?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => void;
     onHighlightChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
     onSelectionChange?: (paths: Set<string>, nodes: LTreeNode<T>[]) => void;
+    onCopy?: (paths: string[]) => void;
+    onCut?: (paths: string[]) => void;
     onPaste?: (result: PasteResult<T>) => void;
     beforeDropCallback?: (dropNode: LTreeNode<T> | null, draggedNode: LTreeNode<T>, position: DropPosition, event: DragEvent | TouchEvent, operation: DropOperation) => boolean | {
         position?: DropPosition;
@@ -176,6 +181,8 @@ export interface TreeControllerProps<T> {
     bodyClass?: string | null | undefined;
     highlightedNodeClass?: string | null | undefined;
     focusedNodeClass?: string | null | undefined;
+    nodeClass?: (node: LTreeNode<T>) => string | null | undefined;
+    nodeContentClass?: (node: LTreeNode<T>) => string | null | undefined;
     dragOverNodeClass?: string | null | undefined;
     expandIconClass?: string | null | undefined;
     collapseIconClass?: string | null | undefined;
@@ -200,14 +207,15 @@ export declare class TreeController<T> {
      *  from the focused node. Set on first Shift action, advances on subsequent
      *  Shift actions, cleared on any plain navigation. Not exposed via props. */
     private _shiftCursor;
-    /** Manual double-click detection state for clickBehavior='select'. We can't
-     *  rely on the browser's native dblclick event in this mode because the first
-     *  click triggers focus → _setFocusedNode bumps node._rev → flat-mode {#each}
-     *  destroys and recreates the row, so the second click lands on a different
-     *  DOM element and the browser refuses to synthesize a dblclick. Tracking
-     *  the click on the controller (which survives the re-render) sidesteps that. */
-    private _lastSelectClickPath;
-    private _lastSelectClickTime;
+    /** Manual double-click detection state. We can't rely on the browser's native
+     *  dblclick event because the first click triggers focus → _setFocusedNode bumps
+     *  node._rev → flat-mode {#each} destroys and recreates the row, so the second
+     *  click lands on a different DOM element and the browser refuses to synthesize a
+     *  dblclick. Tracking the click on the controller (which survives the re-render)
+     *  sidesteps that. Drives both the public onNodeDoubleClick event (all
+     *  clickBehaviors) and the built-in expand/collapse-on-double for 'select' mode. */
+    private _lastClickPath;
+    private _lastClickTime;
     selectedPaths: Set<string>;
     insertResult: InsertArrayResult<T> | null | undefined;
     searchText: string | null | undefined;
@@ -228,11 +236,14 @@ export declare class TreeController<T> {
     shouldAutoHandleMove: boolean;
     shouldAutoHandlePaste: boolean;
     onNodeClickHandler: ((node: LTreeNode<T>) => void) | undefined;
+    onNodeDoubleClickHandler: ((node: LTreeNode<T>) => void) | undefined;
     onHighlightChangeHandler: ((paths: Set<string>, nodes: LTreeNode<T>[]) => void) | undefined;
     onSelectionChangeHandler: ((paths: Set<string>, nodes: LTreeNode<T>[]) => void) | undefined;
     onNodeDragStartHandler: ((node: LTreeNode<T>, event: DragEvent) => void) | undefined;
     onNodeDragOverHandler: ((node: LTreeNode<T>, event: DragEvent) => void) | undefined;
     onNodeDropHandler: TreeControllerProps<T>['onNodeDrop'];
+    onCopyHandler: ((paths: string[]) => void) | undefined;
+    onCutHandler: ((paths: string[]) => void) | undefined;
     onPasteHandler: ((result: PasteResult<T>) => void) | undefined;
     onRenderStartHandler: (() => void) | undefined;
     onRenderProgressHandler: ((stats: RenderStats) => void) | undefined;
@@ -254,6 +265,8 @@ export declare class TreeController<T> {
     toggleIconMode: ToggleIconMode;
     highlightedNodeClass: string | null | undefined;
     focusedNodeClass: string | null | undefined;
+    nodeClass: ((node: LTreeNode<any>) => string | null | undefined) | undefined;
+    nodeContentClass: ((node: LTreeNode<any>) => string | null | undefined) | undefined;
     dragOverNodeClass: string | null | undefined;
     dropZoneMode: "floating" | "glow";
     dropZoneLayout: "around" | "above" | "below" | "wave" | "wave2";

package/dist/core/TreeController.svelte.js

@@ -26,6 +26,8 @@ export class TreeController {
         leafIconClass: 'stv__toggle-icon--leaf',
         highlightedNodeClass: undefined,
         focusedNodeClass: undefined,
+        nodeClass: undefined,
+        nodeContentClass: undefined,
         dragOverNodeClass: undefined,
         dropZoneMode: 'glow',
         dropZoneLayout: 'around',
@@ -46,14 +48,15 @@ export class TreeController {
      *  from the focused node. Set on first Shift action, advances on subsequent
      *  Shift actions, cleared on any plain navigation. Not exposed via props. */
     _shiftCursor = null;
-    /** Manual double-click detection state for clickBehavior='select'. We can't
-     *  rely on the browser's native dblclick event in this mode because the first
-     *  click triggers focus → _setFocusedNode bumps node._rev → flat-mode {#each}
-     *  destroys and recreates the row, so the second click lands on a different
-     *  DOM element and the browser refuses to synthesize a dblclick. Tracking
-     *  the click on the controller (which survives the re-render) sidesteps that. */
-    _lastSelectClickPath = null;
-    _lastSelectClickTime = 0;
+    /** Manual double-click detection state. We can't rely on the browser's native
+     *  dblclick event because the first click triggers focus → _setFocusedNode bumps
+     *  node._rev → flat-mode {#each} destroys and recreates the row, so the second
+     *  click lands on a different DOM element and the browser refuses to synthesize a
+     *  dblclick. Tracking the click on the controller (which survives the re-render)
+     *  sidesteps that. Drives both the public onNodeDoubleClick event (all
+     *  clickBehaviors) and the built-in expand/collapse-on-double for 'select' mode. */
+    _lastClickPath = null;
+    _lastClickTime = 0;
     selectedPaths = $state.raw(new Set());
     insertResult = $state.raw(null);
     searchText = $state(undefined);
@@ -77,11 +80,14 @@ export class TreeController {
     shouldAutoHandlePaste = $state(true);
     // Event handlers (on* = fire-and-forget)
     onNodeClickHandler;
+    onNodeDoubleClickHandler;
     onHighlightChangeHandler;
     onSelectionChangeHandler;
     onNodeDragStartHandler;
     onNodeDragOverHandler;
     onNodeDropHandler;
+    onCopyHandler;
+    onCutHandler;
     onPasteHandler;
     onRenderStartHandler;
     onRenderProgressHandler;
@@ -106,6 +112,8 @@ export class TreeController {
     toggleIconMode = $state('rotate');
     highlightedNodeClass = $state(undefined);
     focusedNodeClass = $state(undefined);
+    nodeClass = $state(undefined);
+    nodeContentClass = $state(undefined);
     dragOverNodeClass = $state(undefined);
     dropZoneMode = $state('glow');
     dropZoneLayout = $state('around');
@@ -238,6 +246,8 @@ export class TreeController {
         this.toggleIconMode = props.toggleIconMode ?? 'rotate';
         this.highlightedNodeClass = props.highlightedNodeClass;
         this.focusedNodeClass = props.focusedNodeClass;
+        this.nodeClass = props.nodeClass;
+        this.nodeContentClass = props.nodeContentClass;
         this.dragOverNodeClass = props.dragOverNodeClass;
         this.dropZoneMode = props.dropZoneMode ?? 'glow';
         this.dropZoneLayout = props.dropZoneLayout ?? 'around';
@@ -255,11 +265,14 @@ export class TreeController {
         this.virtualContainerHeight = props.virtualContainerHeight;
         // Store callbacks
         this.onNodeClickHandler = props.onNodeClick;
+        this.onNodeDoubleClickHandler = props.onNodeDoubleClick;
         this.onHighlightChangeHandler = props.onHighlightChange;
         this.onSelectionChangeHandler = props.onSelectionChange;
         this.onNodeDragStartHandler = props.onNodeDragStart;
         this.onNodeDragOverHandler = props.onNodeDragOver;
         this.onNodeDropHandler = props.onNodeDrop;
+        this.onCopyHandler = props.onCopy;
+        this.onCutHandler = props.onCut;
         this.onPasteHandler = props.onPaste;
         this.beforeDropHandler = props.beforeDropCallback;
         this.beforeCopyHandler = props.beforeCopyCallback;
@@ -294,7 +307,7 @@ export class TreeController {
             : null;
         // ── Create stable nodeCallbacks ─────────────────────────────────
         this.nodeCallbacks = {
-            onNodeClicked: (node, modifiers) => this._onNodeClicked(node, modifiers),
+            onNodeClicked: (node, modifiers) => this._onNodeClicked(node, modifiers, { uiClick: true }),
             onCheckboxToggle: (node, options) => this._onCheckboxToggle(node, options),
             onNodeRightClicked: this._onNodeRightClicked.bind(this),
             onNodeDragStart: this._onNodeDragStart.bind(this),
@@ -318,6 +331,8 @@ export class TreeController {
             toggleIconMode: this.toggleIconMode,
             highlightedNodeClass: this.highlightedNodeClass,
             focusedNodeClass: this.focusedNodeClass,
+            nodeClass: this.nodeClass,
+            nodeContentClass: this.nodeContentClass,
             dragOverNodeClass: this.dragOverNodeClass,
             dropZoneMode: this.dropZoneMode,
             dropZoneLayout: this.dropZoneLayout,
@@ -348,6 +363,8 @@ export class TreeController {
                 toggleIconMode: this.toggleIconMode,
                 highlightedNodeClass: this.highlightedNodeClass,
                 focusedNodeClass: this.focusedNodeClass,
+                nodeClass: this.nodeClass,
+                nodeContentClass: this.nodeContentClass,
                 dragOverNodeClass: this.dragOverNodeClass,
                 dropZoneMode: this.dropZoneMode,
                 dropZoneLayout: this.dropZoneLayout,
@@ -757,13 +774,17 @@ export class TreeController {
     _collectClipboardEntry(node) {
         const descendants = [];
         const sep = this.treePathSeparator;
+        // $state.snapshot deproxies Svelte reactive state into a plain deep clone.
+        // structuredClone alone throws ("could not be cloned") when node.data is a
+        // $state proxy — which it is for any consumer passing default $state data.
+        const snapshot = (data) => $state.snapshot(data);
         const walk = (n) => {
             for (const child of Object.values(n.children)) {
                 // relativePath = everything after sourcePath + separator
                 const rel = child.path.substring(node.path.length);
                 descendants.push({
                     relativePath: rel,
-                    data: structuredClone(child.data)
+                    data: snapshot(child.data)
                 });
                 walk(child);
             }
@@ -772,7 +793,7 @@ export class TreeController {
         return {
             sourceTreeId: this.treeId,
             sourcePath: node.path,
-            data: structuredClone(node.data),
+            data: snapshot(node.data),
             descendants
         };
     }
@@ -808,6 +829,7 @@ export class TreeController {
             sourceTreeId: this.treeId
         });
         uiLogger.debug(`[clipboard] Copied ${entries.length} node(s)`);
+        this.onCopyHandler?.(pathsToUse);
     }
     /**
      * Cut nodes to the shared clipboard. Nodes are dimmed but NOT removed until paste.
@@ -851,6 +873,7 @@ export class TreeController {
         });
         this.cutPaths = cutSet;
         uiLogger.debug(`[clipboard] Cut ${entries.length} node(s), dimming ${cutSet.size} paths`);
+        this.onCutHandler?.(pathsToUse);
     }
     /**
      * Paste clipboard content under (or beside) the target node.
@@ -901,9 +924,12 @@ export class TreeController {
                 targetPath,
                 position
             };
-            // Clear clipboard and cut state
+            // Clear cut-dimming. A CUT is a one-shot move, so clear the clipboard;
+            // a COPY stays on the clipboard so it can be pasted again (Finder /
+            // Explorer / VS Code convention).
             this.cutPaths = new Set();
-            clearClipboard();
+            if (clip.operation === 'cut')
+                clearClipboard();
             uiLogger.debug(`[clipboard] shouldAutoHandlePaste=false — forwarding ${clip.entries.length} entries to consumer`);
             this.onPasteHandler?.(result);
             return result;
@@ -950,9 +976,12 @@ export class TreeController {
         tick().then(() => {
             this._skipInsertArray = false;
         });
-        // Clear clipboard and cut state
+        // Clear cut-dimming. A CUT is a one-shot move (sources were just removed), so
+        // clear the clipboard; a COPY stays on the clipboard so it can be pasted again
+        // (Finder / Explorer / VS Code convention).
         this.cutPaths = new Set();
-        clearClipboard();
+        if (clip.operation === 'cut')
+            clearClipboard();
         const result = {
             success: totalCount > 0,
             count: totalCount,
@@ -1414,6 +1443,10 @@ export class TreeController {
             this.highlightedNodeClass = updates.highlightedNodeClass;
         if (updates.focusedNodeClass !== undefined)
             this.focusedNodeClass = updates.focusedNodeClass;
+        if (updates.nodeClass !== undefined)
+            this.nodeClass = updates.nodeClass;
+        if (updates.nodeContentClass !== undefined)
+            this.nodeContentClass = updates.nodeContentClass;
         if (updates.dragOverNodeClass !== undefined)
             this.dragOverNodeClass = updates.dragOverNodeClass;
         if (updates.dropZoneMode !== undefined)
@@ -1445,6 +1478,8 @@ export class TreeController {
         // Callbacks
         if (updates.onNodeClick !== undefined)
             this.onNodeClickHandler = updates.onNodeClick;
+        if (updates.onNodeDoubleClick !== undefined)
+            this.onNodeDoubleClickHandler = updates.onNodeDoubleClick;
         if (updates.onNodeDragStart !== undefined)
             this.onNodeDragStartHandler = updates.onNodeDragStart;
         if (updates.onNodeDragOver !== undefined)
@@ -1459,6 +1494,10 @@ export class TreeController {
             this.beforePasteHandler = updates.beforePasteCallback;
         if (updates.onNodeDrop !== undefined)
             this.onNodeDropHandler = updates.onNodeDrop;
+        if (updates.onCopy !== undefined)
+            this.onCopyHandler = updates.onCopy;
+        if (updates.onCut !== undefined)
+            this.onCutHandler = updates.onCut;
         if (updates.onPaste !== undefined)
             this.onPasteHandler = updates.onPaste;
         if (updates.getContextMenuItemsCallback !== undefined)
@@ -1473,31 +1512,39 @@ export class TreeController {
         if (this.contextMenuVisible) {
             this.closeContextMenu();
         }
-        // Manual dblclick detection for clickBehavior='select' — see the comment
-        // on _lastSelectClickPath for why the browser's native dblclick can't be
-        // trusted in this mode. Threshold matches Windows' default double-click
-        // interval (500ms is the system default; we use a slightly tighter 400ms
-        // to avoid coupling unrelated clicks).
-        if (this.clickBehavior === 'select' && !modifiers?.ctrl && !modifiers?.shift) {
+        // Manual double-click detection — see the comment on _lastClickPath for why the
+        // browser's native dblclick can't be trusted (focus bumps node._rev → flat-mode
+        // row is recreated → the 2nd click lands on a fresh element). Runs for every
+        // clickBehavior so onNodeDoubleClick fires consistently; the built-in
+        // expand/collapse-on-double-click only applies to clickBehavior='select' (the
+        // other modes already toggle on single click). On a detected double we consume
+        // the 2nd click (return early) so the gesture is a single open, not a re-toggle.
+        // Threshold = 400ms, a touch tighter than Windows' 500ms default to avoid
+        // coupling unrelated clicks. Gated on uiClick so programmatic highlight/select
+        // API calls never get mistaken for a double-click.
+        if (options?.uiClick && !modifiers?.ctrl && !modifiers?.shift) {
             const now = Date.now();
-            const isDouble = this._lastSelectClickPath === node.path &&
-                now - this._lastSelectClickTime < 400;
+            const isDouble = this._lastClickPath === node.path &&
+                now - this._lastClickTime < 400;
             if (isDouble) {
-                this._lastSelectClickPath = null;
-                this._lastSelectClickTime = 0;
-                const canonical = this.tree.getNodeByPath(node.path) ?? node;
-                if (canonical.hasChildren && canonical.isCollapsible !== false) {
-                    if (canonical.isExpanded) {
-                        this.collapseNodes(canonical.path);
-                    }
-                    else {
-                        this.expandNodes(canonical.path);
+                this._lastClickPath = null;
+                this._lastClickTime = 0;
+                this.onNodeDoubleClickHandler?.(node);
+                if (this.clickBehavior === 'select') {
+                    const canonical = this.tree.getNodeByPath(node.path) ?? node;
+                    if (canonical.hasChildren && canonical.isCollapsible !== false) {
+                        if (canonical.isExpanded) {
+                            this.collapseNodes(canonical.path);
+                        }
+                        else {
+                            this.expandNodes(canonical.path);
+                        }
                     }
                 }
                 return;
             }
-            this._lastSelectClickPath = node.path;
-            this._lastSelectClickTime = now;
+            this._lastClickPath = node.path;
+            this._lastClickTime = now;
         }
         // In single mode, mouse Ctrl/Shift+click degrade to plain click. Programmatic
         // callers (highlightNode with mode='toggle'/'range') pass forceMultiSemantics

package/dist/ltree/types.d.ts

@@ -51,6 +51,15 @@ export interface ContextMenuItem {
     isVisible?: boolean;
     className?: string;
     onclick?: () => void | Promise<void>;
+    /**
+     * Whether activating this item auto-closes the menu. Default `true` —
+     * selecting an entry dismisses the menu like every native/desktop menu.
+     * Set `false` for items that act incrementally (toggle a flag, run a
+     * multi-step action) and want the menu to stay open; the handler is then
+     * responsible for dismissing it via the `close` callback passed to
+     * getContextMenuItemsCallback (or the snippet's close prop).
+     */
+    shouldCloseOnClick?: boolean;
     children?: ContextMenuEntry[];
 }
 export type ContextMenuEntry = ContextMenuItem | ContextMenuDivider;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@keenmate/svelte-treeview",
-	"version": "5.0.0-rc11",
+	"version": "5.0.0-rc12",
 	"scripts": {
 		"dev": "vite dev --port 17777",
 		"build": "vite build && npm run prepack",