@keenmate/svelte-treeview 5.0.0-rc07 → 5.0.0-rc09

package/dist/core/TreeController.svelte.js

@@ -20,6 +20,7 @@ export class TreeController {
         clickBehavior: 'expand-and-focus',
         showCheckboxes: false,
         checkboxMode: 'independent',
+        clickTogglesCheckbox: false,
         expandIconClass: 'ltree-icon-expand',
         collapseIconClass: 'ltree-icon-collapse',
         leafIconClass: 'ltree-icon-leaf',
@@ -41,7 +42,10 @@ export class TreeController {
     data = $state.raw([]);
     focusedNode = $state.raw(null);
     highlightedPaths = $state.raw(new Set());
-    lastHighlightedPath = null;
+    /** Hidden internal cursor used by Shift+Arrow / Shift+click to extend ranges
+     *  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;
     selectedPaths = $state.raw(new Set());
     insertResult = $state.raw(null);
     searchText = $state(undefined);
@@ -84,8 +88,10 @@ export class TreeController {
     getContextMenuItemsHandler;
     // Visual config (for nodeConfig updates)
     clickBehavior = $state('expand-and-focus');
+    selectionMode = $state('single');
     showCheckboxes = $state(false);
     checkboxMode = $state('independent');
+    clickTogglesCheckbox = $state(false);
     expandIconClass = $state('ltree-icon-expand');
     collapseIconClass = $state('ltree-icon-collapse');
     leafIconClass = $state('ltree-icon-leaf');
@@ -207,8 +213,10 @@ export class TreeController {
         this.autoHandlePaste = props.autoHandlePaste ?? true;
         this.accordionExpand = props.accordionExpand ?? false;
         this.clickBehavior = props.clickBehavior ?? 'expand-and-focus';
+        this.selectionMode = props.selectionMode ?? 'single';
         this.showCheckboxes = props.showCheckboxes ?? false;
         this.checkboxMode = props.checkboxMode ?? 'independent';
+        this.clickTogglesCheckbox = props.clickTogglesCheckbox ?? false;
         this.beforeCheckboxToggleHandler = props.beforeCheckboxToggleCallback;
         this.expandIconClass = props.expandIconClass ?? 'ltree-icon-expand';
         this.collapseIconClass = props.collapseIconClass ?? 'ltree-icon-collapse';
@@ -249,7 +257,7 @@ export class TreeController {
         this.onRenderCompleteHandler = props.onRenderComplete;
         // ── Create LTree ────────────────────────────────────────────────
         // svelte-ignore non_reactive_update
-        this.tree = createLTree(props.idMember, props.pathMember, props.parentPathMember, props.levelMember, props.hasChildrenMember, props.isExpandedMember, props.isSelectableMember, props.isSelectedMember, props.isDraggableMember, props.getIsDraggableCallback, props.isDropAllowedMember, props.allowedDropPositionsMember, props.displayValueMember, props.getDisplayValueCallback, props.searchValueMember, props.getSearchValueCallback, props.getAllowedDropPositionsCallback, props.isCollapsibleMember, props.getIsCollapsibleCallback, props.orderMember, this.treeId, this.treePathSeparator, props.expandLevel, props.shouldUseInternalSearchIndex, props.initializeIndexCallback, props.indexerBatchSize, props.indexerTimeout, {
+        this.tree = createLTree(props.idMember, props.pathMember, props.parentPathMember, props.levelMember, props.hasChildrenMember, props.isExpandedMember, props.getIsExpandedCallback, props.isSelectableMember, props.getIsSelectableCallback, props.isSelectedMember, props.getIsSelectedCallback, props.isDraggableMember, props.getIsDraggableCallback, props.isDropAllowedMember, props.allowedDropPositionsMember, props.displayValueMember, props.getDisplayValueCallback, props.searchValueMember, props.getSearchValueCallback, props.getAllowedDropPositionsCallback, props.isCollapsibleMember, props.getIsCollapsibleCallback, props.orderMember, this.treeId, this.treePathSeparator, props.expandLevel, props.shouldUseInternalSearchIndex, props.initializeIndexCallback, props.indexerBatchSize, props.indexerTimeout, {
             shouldDisplayDebugInformation: props.shouldDisplayDebugInformation,
             isSorted: props.isSorted,
             sortCallback: props.sortCallback
@@ -273,7 +281,7 @@ export class TreeController {
         // ── Create stable nodeCallbacks ─────────────────────────────────
         this.nodeCallbacks = {
             onNodeClicked: (node, modifiers) => this._onNodeClicked(node, modifiers),
-            onCheckboxToggle: (node) => this._onCheckboxToggle(node),
+            onCheckboxToggle: (node, options) => this._onCheckboxToggle(node, options),
             onNodeRightClicked: this._onNodeRightClicked.bind(this),
             onNodeDragStart: this._onNodeDragStart.bind(this),
             onNodeDragOver: this._onNodeDragOver.bind(this),
@@ -289,6 +297,7 @@ export class TreeController {
             clickBehavior: this.clickBehavior,
             showCheckboxes: this.showCheckboxes,
             checkboxMode: this.checkboxMode,
+            clickTogglesCheckbox: this.clickTogglesCheckbox,
             expandIconClass: this.expandIconClass,
             collapseIconClass: this.collapseIconClass,
             leafIconClass: this.leafIconClass,
@@ -318,6 +327,7 @@ export class TreeController {
             Object.assign(this.nodeConfig, {
                 clickBehavior: this.clickBehavior,
                 showCheckboxes: this.showCheckboxes,
+                clickTogglesCheckbox: this.clickTogglesCheckbox,
                 expandIconClass: this.expandIconClass,
                 collapseIconClass: this.collapseIconClass,
                 leafIconClass: this.leafIconClass,
@@ -353,7 +363,7 @@ export class TreeController {
                 this.vsDetectedHeight = null;
                 this.insertResult = this.tree.insertArray(this.data);
                 // Seed selectedPaths from node.isSelected flags written by insertArray
-                if (this.tree.isSelectedMember) {
+                if (this.tree.isSelectedMember || this.tree.getIsSelectedCallback) {
                     const seeded = new Set();
                     const walk = (node) => {
                         if (node.isSelected)
@@ -498,6 +508,26 @@ export class TreeController {
                 this.isDebugMenuActive = false;
             }
         });
+        // Mirror hoveredNodeForDrop → dragOverNodeClass on a single DOM element.
+        // Direct classList mutation (same approach as the touch path's updateDropTarget) so
+        // the cost is O(1) per node-crossing — no per-Node prop propagation across the tree.
+        let prevHoveredDragPath = null;
+        let prevDragOverClass = null;
+        $effect(() => {
+            const current = this.hoveredNodeForDrop?.path ?? null;
+            const cls = this.dragOverNodeClass ?? null;
+            if (current === prevHoveredDragPath && cls === prevDragOverClass)
+                return;
+            const root = this.containerElement ?? document;
+            if (prevHoveredDragPath && prevDragOverClass) {
+                root.querySelector(`[data-tree-path="${prevHoveredDragPath}"] .ltree-node-content`)?.classList.remove(prevDragOverClass);
+            }
+            if (current && cls) {
+                root.querySelector(`[data-tree-path="${current}"] .ltree-node-content`)?.classList.add(cls);
+            }
+            prevHoveredDragPath = current;
+            prevDragOverClass = cls;
+        });
     }
     // ── Virtual scroll handler ──────────────────────────────────────────
     handleVirtualScroll = (event) => {
@@ -510,17 +540,17 @@ export class TreeController {
         });
     };
     // ── Public API methods ──────────────────────────────────────────────
-    async expandNodes(nodePath) {
-        this.tree.expandNodes(nodePath);
+    async expandNodes(nodePath, options) {
+        this.tree.expandNodes(nodePath, options);
     }
-    async collapseNodes(nodePath) {
-        this.tree.collapseNodes(nodePath);
+    async collapseNodes(nodePath, options) {
+        this.tree.collapseNodes(nodePath, options);
     }
-    expandAll(nodePath) {
-        this.tree?.expandAll(nodePath);
+    expandAll(nodePath, options) {
+        this.tree?.expandAll(nodePath, options);
     }
-    collapseAll(nodePath) {
-        this.tree?.collapseAll(nodePath);
+    collapseAll(nodePath, options) {
+        this.tree?.collapseAll(nodePath, options);
     }
     filterNodes(searchTextVal, searchOptions) {
         this.tree?.filterNodes(searchTextVal, searchOptions);
@@ -1256,10 +1286,14 @@ export class TreeController {
             this.virtualContainerHeight = updates.virtualContainerHeight;
         if (updates.clickBehavior !== undefined)
             this.clickBehavior = updates.clickBehavior ?? 'expand-and-focus';
+        if (updates.selectionMode !== undefined)
+            this.selectionMode = updates.selectionMode ?? 'single';
         if (updates.showCheckboxes !== undefined)
             this.showCheckboxes = updates.showCheckboxes ?? false;
         if (updates.checkboxMode !== undefined)
             this.checkboxMode = updates.checkboxMode ?? 'independent';
+        if (updates.clickTogglesCheckbox !== undefined)
+            this.clickTogglesCheckbox = updates.clickTogglesCheckbox ?? false;
         if (updates.beforeCheckboxToggleCallback !== undefined)
             this.beforeCheckboxToggleHandler = updates.beforeCheckboxToggleCallback;
         if (updates.expandIconClass !== undefined)
@@ -1327,14 +1361,22 @@ export class TreeController {
             this.onSelectionChangeHandler = updates.onSelectionChange;
     }
     // ── Internal event handlers ─────────────────────────────────────────
-    async _onNodeClicked(node, modifiers) {
+    async _onNodeClicked(node, modifiers, options) {
         if (this.contextMenuVisible) {
             this.closeContextMenu();
         }
-        const ctrl = modifiers?.ctrl ?? false;
-        const shift = modifiers?.shift ?? false;
-        uiLogger.debug(`[highlight] Click on ${node.path}`, { ctrl, shift, lastAnchor: this.lastHighlightedPath, prevCount: this.highlightedPaths.size });
-        if (ctrl) {
+        // In single mode, mouse Ctrl/Shift+click degrade to plain click. Programmatic
+        // callers (highlightNode with mode='toggle'/'range') pass forceMultiSemantics
+        // to opt out of the gate — the API contract should not depend on selectionMode.
+        const isMulti = options?.forceMultiSemantics || this.selectionMode === 'multi';
+        const ctrl = isMulti && (modifiers?.ctrl ?? false);
+        const shift = isMulti && (modifiers?.shift ?? false);
+        const silent = options?.silent ?? false;
+        uiLogger.debug(`[highlight] Click on ${node.path}`, { ctrl, shift, mode: this.selectionMode, shiftCursor: this._shiftCursor, prevCount: this.highlightedPaths.size });
+        // !isSelectable blocks highlight (and therefore the mirror in no-checkbox mode).
+        // Focus still moves so consumers can show detail panels for unselectable rows.
+        const canHighlight = node.isSelectable;
+        if (ctrl && canHighlight) {
             // Toggle this node in/out of highlight
             const newPaths = new Set([...this.highlightedPaths]);
             if (newPaths.has(node.path)) {
@@ -1347,42 +1389,82 @@ export class TreeController {
             }
             node._rev = (node._rev || 0) + 1;
             this.highlightedPaths = newPaths;
-            this.lastHighlightedPath = node.path;
+            this._shiftCursor = node.path;
         }
-        else if (shift && this.lastHighlightedPath) {
-            // Range highlight from lastHighlightedPath to this node
-            const rangePaths = this._getNodesBetween(this.lastHighlightedPath, node.path);
-            // Clear previous highlights
+        else if (shift && canHighlight && (this._shiftCursor || this.focusedNode)) {
+            // Range highlight from the shift cursor (or focused node if no cursor yet) to this node
+            const anchor = this._shiftCursor ?? this.focusedNode.path;
+            const rangePaths = this._getNodesBetween(anchor, node.path);
             this._clearAllHighlightFlags();
             const newPaths = new Set();
             for (const path of rangePaths) {
-                newPaths.add(path);
                 const n = this.tree.getNodeByPath(path);
-                if (n) {
-                    n.isHighlighted = true;
-                    n._rev = (n._rev || 0) + 1;
-                }
+                if (!n || !n.isSelectable)
+                    continue;
+                newPaths.add(path);
+                n.isHighlighted = true;
+                n._rev = (n._rev || 0) + 1;
             }
             this.highlightedPaths = newPaths;
-            // Don't update lastHighlightedPath on shift+click (anchor stays)
+            // Anchor stays put on shift+click — _shiftCursor unchanged
         }
-        else {
-            // Normal click: clear all highlights, highlight only this node
+        else if (canHighlight) {
+            // Plain click (or Ctrl/Shift+click in single mode → treated as plain):
+            // clear all highlights, highlight only this node.
             this._clearAllHighlightFlags();
             node.isHighlighted = true;
             node._rev = (node._rev || 0) + 1;
-            const newPaths = new Set();
-            newPaths.add(node.path);
-            this.highlightedPaths = newPaths;
-            this.lastHighlightedPath = node.path;
+            this.highlightedPaths = new Set([node.path]);
+            this._shiftCursor = node.path;
         }
-        // Update focus
+        else {
+            // Not selectable: clear any prior highlights but don't highlight this row.
+            if (this.highlightedPaths.size > 0) {
+                this._clearAllHighlightFlags();
+                this.highlightedPaths = new Set();
+            }
+            this._shiftCursor = null;
+        }
+        // Update focus (always — focus is independent of selectability)
         this._setFocusedNode(node);
-        this.onNodeClickHandler?.(node);
-        this._notifyHighlightChanged();
+        if (!silent) {
+            this.onNodeClickHandler?.(node);
+            this._notifyHighlightChanged();
+            this._mirrorHighlightToSelected();
+        }
         this.tree.refresh();
-        // Focus the tree container so keyboard navigation works after clicking a node
-        this.containerElement?.focus();
+        // Focus the tree container so keyboard navigation works after clicking a node.
+        // Skip in silent mode — programmatic highlight (e.g. from URL params) shouldn't
+        // steal focus from whatever the user is currently interacting with.
+        if (!silent) {
+            this.containerElement?.focus();
+        }
+    }
+    /**
+     * Top-level paths within `highlightedPaths` — paths whose nearest highlighted
+     * ancestor is NOT in the highlighted set. Used by multi-drag to figure out
+     * which subtrees actually need to move (descendants ride along inside).
+     */
+    _getTopLevelHighlightedPaths() {
+        const paths = this.highlightedPaths;
+        if (paths.size === 0)
+            return [];
+        const sep = this.treePathSeparator;
+        const result = [];
+        for (const p of paths) {
+            let cursor = p;
+            let absorbed = false;
+            while (cursor.includes(sep)) {
+                cursor = cursor.substring(0, cursor.lastIndexOf(sep));
+                if (paths.has(cursor)) {
+                    absorbed = true;
+                    break;
+                }
+            }
+            if (!absorbed)
+                result.push(p);
+        }
+        return result;
     }
     /** Get all descendant paths of a node (depth-first) */
     _getDescendantPaths(node) {
@@ -1397,7 +1479,7 @@ export class TreeController {
         return result;
     }
     /** Handle checkbox toggle with cascade and interceptor support */
-    _onCheckboxToggle(node) {
+    _onCheckboxToggle(node, options) {
         // In cascade mode, indeterminate → check all (not fully selected yet)
         const newChecked = this.checkboxMode === 'cascade' && node.visualState === VisualState.indeterminate
             ? true
@@ -1452,27 +1534,30 @@ export class TreeController {
             n._rev = (n._rev || 0) + 1;
         }
         this.selectedPaths = newPaths;
-        this._setFocusedNode(node);
-        // Update visual states for toggled nodes and their ancestors
-        // Collect unique root paths to update (the top-level nodes that were directly toggled)
-        const rootPaths = isMultiHighlighted ? [...this.highlightedPaths] : [node.path];
-        for (const rp of rootPaths) {
-            const rn = this.tree.getNodeByPath(rp);
-            if (!rn)
-                continue;
-            if (this.checkboxMode === 'cascade') {
+        if (!options?.skipFocus)
+            this._setFocusedNode(node);
+        // Update visual states for toggled nodes and their ancestors.
+        // Only in cascade mode — in independent mode, checkboxes are standalone and
+        // parents must not be auto-checked just because their descendants are.
+        if (this.checkboxMode === 'cascade') {
+            const rootPaths = isMultiHighlighted ? [...this.highlightedPaths] : [node.path];
+            for (const rp of rootPaths) {
+                const rn = this.tree.getNodeByPath(rp);
+                if (!rn)
+                    continue;
                 const vs = this._computeVisualState(rn);
                 if (rn.visualState !== vs) {
                     rn.visualState = vs;
                     rn._rev = (rn._rev || 0) + 1;
                 }
+                this._updateAncestorVisualStates(rp);
             }
-            this._updateAncestorVisualStates(rp);
         }
         this.onNodeClickHandler?.(node);
         this._notifySelectionChanged();
         this.tree.refresh();
-        this.containerElement?.focus();
+        if (!options?.skipFocus)
+            this.containerElement?.focus();
     }
     /** Walk up from a node path and set visualState on each ancestor based on descendant selection */
     _updateAncestorVisualStates(startPath) {
@@ -1534,15 +1619,60 @@ export class TreeController {
     }
     /** Set focused node, clearing previous focus flag */
     _setFocusedNode(node) {
-        if (this.focusedNode && this.focusedNode.path !== node?.path) {
-            this.focusedNode.isFocused = false;
-            this.focusedNode._rev = (this.focusedNode._rev || 0) + 1;
+        // IMPORTANT: bidirectional bind on `focusedNode` can route the value through
+        // the parent's `$state`, which deep-clones the node into a reactive proxy.
+        // That clone shares the path but is a different object from the tree's
+        // canonical node. We MUST mutate the tree's actual node — otherwise
+        // `node.isFocused = false` writes to the clone and the rendered row
+        // (which reads the canonical node's flag) never updates. Same applies to
+        // the incoming `node`: prefer the tree's canonical ref.
+        const prevPath = this.focusedNode?.path;
+        if (prevPath && prevPath !== node?.path) {
+            const prev = this.tree.getNodeByPath(prevPath);
+            if (prev) {
+                prev.isFocused = false;
+                prev._rev = (prev._rev || 0) + 1;
+            }
+        }
+        const canonical = node ? (this.tree.getNodeByPath(node.path) ?? node) : null;
+        if (canonical) {
+            canonical.isFocused = true;
+            canonical._rev = (canonical._rev || 0) + 1;
+        }
+        this.focusedNode = canonical;
+    }
+    /**
+     * Mirror highlightedPaths → selectedPaths when checkboxes are off.
+     * Decision 1 + 10 from selection-highlight-model.md: in no-checkbox mode the
+     * highlight set IS the form selection, so writes to highlightedPaths cascade
+     * to selectedPaths and fire onSelectionChange alongside onHighlightChange.
+     */
+    _mirrorHighlightToSelected() {
+        if (this.showCheckboxes)
+            return;
+        // Take a snapshot to avoid identity-loop on parent rebinding
+        const next = new Set(this.highlightedPaths);
+        // Sync the per-node isSelected flag with the mirrored set.
+        // First clear isSelected on anything currently in selectedPaths but not in next.
+        for (const path of this.selectedPaths) {
+            if (!next.has(path)) {
+                const n = this.tree.getNodeByPath(path);
+                if (n) {
+                    n.isSelected = false;
+                    n._rev = (n._rev || 0) + 1;
+                }
+            }
         }
-        if (node) {
-            node.isFocused = true;
-            node._rev = (node._rev || 0) + 1;
+        // Then set isSelected on the new set.
+        for (const path of next) {
+            const n = this.tree.getNodeByPath(path);
+            if (n && !n.isSelected) {
+                n.isSelected = true;
+                n._rev = (n._rev || 0) + 1;
+            }
         }
-        this.focusedNode = node;
+        this.selectedPaths = next;
+        this._notifySelectionChanged();
     }
     /** Clear isHighlighted flag on all currently highlighted nodes */
     _clearAllHighlightFlags() {
@@ -1648,29 +1778,32 @@ export class TreeController {
         return result;
     }
     // ── Public highlight methods (UI selection) ────────────────────────
-    /** Highlight a node with the given mode */
-    highlightNode(path, mode = 'replace') {
+    /** Highlight a node with the given mode.
+     *  Pass `{ silent: true }` to update state without firing `onNodeClick` / `onHighlightChange`
+     *  (useful when restoring state from URL params or other external sources). */
+    highlightNode(path, mode = 'replace', options) {
         const node = this.tree.getNodeByPath(path);
         if (!node)
             return;
         if (mode === 'toggle') {
-            this._onNodeClicked(node, { ctrl: true, shift: false });
+            this._onNodeClicked(node, { ctrl: true, shift: false }, { ...options, forceMultiSemantics: true });
         }
         else if (mode === 'range') {
-            this._onNodeClicked(node, { ctrl: false, shift: true });
+            this._onNodeClicked(node, { ctrl: false, shift: true }, { ...options, forceMultiSemantics: true });
         }
         else {
-            this._onNodeClicked(node);
+            this._onNodeClicked(node, undefined, options);
         }
     }
-    /** Highlight multiple nodes by paths (replaces current highlights) */
-    highlightNodes(paths) {
+    /** Highlight multiple nodes by paths (replaces current highlights).
+     *  Pass `{ silent: true }` to skip `onHighlightChange`. */
+    highlightNodes(paths, options) {
         this._clearAllHighlightFlags();
         const newPaths = new Set();
         let lastNode = null;
         for (const path of paths) {
             const node = this.tree.getNodeByPath(path);
-            if (node) {
+            if (node && node.isSelectable) {
                 node.isHighlighted = true;
                 node._rev = (node._rev || 0) + 1;
                 newPaths.add(path);
@@ -1680,17 +1813,23 @@ export class TreeController {
         this.highlightedPaths = newPaths;
         if (lastNode) {
             this._setFocusedNode(lastNode);
-            this.lastHighlightedPath = lastNode.path;
+            this._shiftCursor = lastNode.path;
+        }
+        if (!options?.silent) {
+            this._notifyHighlightChanged();
+            this._mirrorHighlightToSelected();
         }
-        this._notifyHighlightChanged();
         this.tree.refresh();
     }
-    /** Clear all highlights */
-    clearHighlight() {
+    /** Clear all highlights. Pass `{ silent: true }` to skip `onHighlightChange`. */
+    clearHighlight(options) {
         this._clearAllHighlightFlags();
         this.highlightedPaths = new Set();
-        this.lastHighlightedPath = null;
-        this._notifyHighlightChanged();
+        this._shiftCursor = null;
+        if (!options?.silent) {
+            this._notifyHighlightChanged();
+            this._mirrorHighlightToSelected();
+        }
         this.tree.refresh();
     }
     /** Get all highlighted nodes */
@@ -1707,6 +1846,15 @@ export class TreeController {
     isNodeHighlighted(path) {
         return this.highlightedPaths.has(path);
     }
+    /** Toggle the focused node in/out of the highlight set. Multi-mode only. */
+    toggleFocusedHighlight() {
+        if (this.selectionMode !== 'multi')
+            return;
+        const node = this.focusedNode;
+        if (!node || !node.isSelectable)
+            return;
+        this._onNodeClicked(node, { ctrl: true, shift: false }, { forceMultiSemantics: true });
+    }
     // ── Public selection methods (checkbox data state) ───────────────
     /** Get all selected (checked) nodes */
     getSelectedNodes() {
@@ -1722,36 +1870,30 @@ export class TreeController {
     isNodeSelected(path) {
         return this.selectedPaths.has(path);
     }
-    /** Clear all checkbox selections */
-    deselectAll() {
+    /** Clear all checkbox selections. Pass `{ silent: true }` to skip `onSelectionChange`. */
+    deselectAll(options) {
         this._clearAllSelectionFlags();
         this.selectedPaths = new Set();
-        this._notifySelectionChanged();
+        if (!options?.silent)
+            this._notifySelectionChanged();
         this.tree.refresh();
     }
     /** @deprecated Use highlightNode() instead */
-    selectNode(path, mode = 'replace') {
-        this.highlightNode(path, mode);
+    selectNode(path, mode = 'replace', options) {
+        this.highlightNode(path, mode, options);
     }
     /** @deprecated Use highlightNodes() instead */
-    selectNodes(paths) {
-        this.highlightNodes(paths);
+    selectNodes(paths, options) {
+        this.highlightNodes(paths, options);
     }
     _onNodeRightClicked(node, event) {
         if (!this.hasContextMenuSnippet && !this.getContextMenuItemsHandler) {
             return;
         }
-        // If right-clicking on an unhighlighted node, clear highlights and highlight only this node
-        if (!this.highlightedPaths.has(node.path)) {
-            this._clearAllHighlightFlags();
-            node.isHighlighted = true;
-            node._rev = (node._rev || 0) + 1;
-            this.highlightedPaths = new Set([node.path]);
-            this._setFocusedNode(node);
-            this.lastHighlightedPath = node.path;
-            this._notifyHighlightChanged();
-            this.tree.refresh();
-        }
+        // Decision 12: right-click does NOT move focus or highlight. It only opens
+        // the context menu at the right-clicked node. If the consumer needs the
+        // menu to act on something other than the highlight set, they can read
+        // the node passed to their getContextMenuItemsCallback.
         uiLogger.debug(`Context menu opened: ${node.path}`);
         event.preventDefault();
         this.openContextMenu(node, event.clientX, event.clientY);
@@ -1786,6 +1928,31 @@ export class TreeController {
         this.draggedNode = node;
         this.isDragInProgress = true;
         this.onNodeDragStartHandler?.(node, event);
+        // OS-convention selection sync: if the user grabs a node that isn't part
+        // of the current highlight set, replace the highlight with just that node.
+        // Mirrors Windows Explorer / macOS Finder where mousedown on an unselected
+        // item selects it. Without this, the prior highlight stayed visible while
+        // the drag silently carried only the single grabbed node — confusing the
+        // user about what's moving. Deferred to rAF (not microtask): microtasks
+        // drain before the browser commits the drag image, so mutating the source
+        // row's DOM there causes `tree.refresh()` to re-create the dragged element
+        // and the browser silently aborts the drag (no dragend fires). rAF runs as
+        // part of the rendering steps, after the drag is committed. Drop handlers
+        // fire well after this rAF, so they read the updated `highlightedPaths`.
+        // Skipped when the node is already in the set (multi-drag) or not
+        // selectable (preserves prior highlight state for unselectable rows).
+        if (node.isSelectable && !this.highlightedPaths.has(node.path)) {
+            requestAnimationFrame(() => {
+                this._clearAllHighlightFlags();
+                node.isHighlighted = true;
+                node._rev = (node._rev || 0) + 1;
+                this.highlightedPaths = new Set([node.path]);
+                this._shiftCursor = node.path;
+                this._notifyHighlightChanged();
+                this._mirrorHighlightToSelected();
+                this.tree.refresh();
+            });
+        }
     }
     _onNodeDragEnd = (event) => {
         dragLogger.debug('Drag ended', {
@@ -1829,6 +1996,50 @@ export class TreeController {
             }
         }
         const isSameTreeDrag = draggedNodeRef.treeId === this.treeId;
+        // Multi-drag (Decision 6 in selection-highlight-model.md):
+        // When the dragged node is part of a multi-highlight, move the whole highlight
+        // set as top-level-selected subtrees. Descendants whose nearest highlighted
+        // ancestor is in the set are absorbed (ride along inside the subtree).
+        const isMultiDrag = isSameTreeDrag &&
+            operation === 'move' &&
+            dropNode &&
+            this.autoHandleMove &&
+            this.highlightedPaths.has(draggedNodeRef.path) &&
+            this.highlightedPaths.size > 1;
+        if (isMultiDrag) {
+            const topLevelPaths = this._getTopLevelHighlightedPaths()
+                // drop target can't be moved onto itself
+                .filter((p) => p !== dropNode.path);
+            dragLogger.info(`Multi-drag: moving ${topLevelPaths.length} top-level subtree(s)`, {
+                topLevelPaths,
+                totalHighlighted: this.highlightedPaths.size,
+                dropTarget: dropNode.path,
+                position
+            });
+            let allOk = true;
+            // First top-level node uses the requested position relative to dropNode.
+            // Subsequent ones chain 'after' the previously moved node so the whole
+            // set lands as siblings in source order: dropping A,B,C 'after D' yields
+            // [D, A, B, C]; 'before D' yields [A, B, C, D]; 'child of D' yields D's
+            // children = [A, B, C]. moveNode mutates the source LTreeNode in place,
+            // so reading the held reference's .path post-move gives the new path.
+            let prevMovedNode = null;
+            for (let i = 0; i < topLevelPaths.length; i++) {
+                const sourcePath = topLevelPaths[i];
+                const targetPath = i === 0 ? dropNode.path : prevMovedNode.path;
+                const pos = i === 0 ? position : 'after';
+                const sourceNode = this.tree.getNodeByPath(sourcePath);
+                const r = this.moveNode(sourcePath, targetPath, pos);
+                if (!r.success) {
+                    allOk = false;
+                }
+                else if (sourceNode) {
+                    prevMovedNode = sourceNode;
+                }
+            }
+            this.onNodeDropHandler?.(dropNode, draggedNodeRef, position, event, operation);
+            return allOk;
+        }
         if (isSameTreeDrag && operation === 'move' && dropNode) {
             if (this.autoHandleMove) {
                 const result = this.moveNode(draggedNodeRef.path, dropNode.path, position);
@@ -2510,14 +2721,17 @@ export class TreeController {
             }
         };
     }
-    /** Extend highlight to target path (Shift+nav) — uses range from anchor, moves focus */
+    /** Extend highlight to target path (Shift+nav) — uses range from the shift cursor
+     *  (or current focus if no cursor yet), moves focus. No-op in single mode. */
     _navHighlightTo(path) {
-        // Set anchor if not set
-        if (!this.lastHighlightedPath && this.focusedNode) {
-            this.lastHighlightedPath = this.focusedNode.path;
-            // Ensure anchor is highlighted
+        if (this.selectionMode !== 'multi')
+            return;
+        // Seed the shift cursor from the focused node on the first Shift+Arrow
+        if (!this._shiftCursor && this.focusedNode) {
             const anchorNode = this.focusedNode;
-            if (!anchorNode.isHighlighted) {
+            this._shiftCursor = anchorNode.path;
+            // Ensure anchor is highlighted so range computation has a starting point visible
+            if (anchorNode.isSelectable && !anchorNode.isHighlighted) {
                 anchorNode.isHighlighted = true;
                 anchorNode._rev = (anchorNode._rev || 0) + 1;
                 this.highlightedPaths = new Set([anchorNode.path]);

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { TreeController } from "./core/TreeController.svelte";
 export type { TreeControllerProps, PasteResult } from "./core/TreeController.svelte";
 export { createTreeController } from "./core/createTreeController.js";
 export type { LTreeNode, NodeId, VisualState } from "./ltree/ltree-node.svelte";
-export type { Ltree, DropPosition, DragDropMode, DropOperation, ToggleIconMode, ClickBehavior, CheckboxMode, ContextMenuItem, ContextMenuDivider, ContextMenuEntry, InsertArrayResult, InsertBranchResult, DeleteBranchResult, TreeChange, ApplyChangesResult } from "./ltree/types.js";
+export type { Ltree, DropPosition, DragDropMode, DropOperation, ToggleIconMode, ClickBehavior, CheckboxMode, SelectionMode, ContextMenuItem, ContextMenuDivider, ContextMenuEntry, InsertArrayResult, InsertBranchResult, DeleteBranchResult, TreeChange, ApplyChangesResult } from "./ltree/types.js";
 export type { ClipboardEntry, TreeClipboard } from "./core/clipboard.js";
 export { setClipboard, getClipboard, clearClipboard, hasClipboard, getClipboardOperation } from "./core/clipboard.js";
 export type { TreeNavigation, TreeNavigationOverrides } from "./core/navigation.js";