backpack-viewer 0.5.0 → 0.6.0

package/dist/canvas.js

@@ -34,6 +34,22 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
     let showEdgeLabels = true;
     let showTypeHulls = true;
     let showMinimap = true;
+    let dragMode = "idle";
+    // Node(s) being dragged, with their starting world positions so the
+    // mouse delta can translate a whole selection as a rigid body.
+    let dragNodes = [];
+    // World coords of the cursor when the drag started — used to compute
+    // how far the dragged group should move each mousemove.
+    let dragStartWorldX = 0;
+    let dragStartWorldY = 0;
+    // Rubber-band rectangle in world coords during shift-drag on empty canvas.
+    let rubberBand = null;
+    // IDs of nodes that currently have `pinned: true`. Tracked here for
+    // rendering the pin indicator without scanning the full nodes array.
+    let pinnedNodeIds = new Set();
+    // Pixels the cursor must move between mousedown and mousemove before
+    // the gesture is promoted from "click" to "drag". Matches pan threshold.
+    const CLICK_DRAG_THRESHOLD = 5;
     // Focus mode state
     let lastLoadedData = null;
     let focusSeedIds = null;
@@ -143,6 +159,31 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
     }
     // --- Rendering ---
     /** Draw only walk pulse effects (edges + node glows) + minimap on top of cached scene. */
+    /**
+     * Draw the rubber-band selection rectangle in world coords, if active.
+     * Intended to be called AFTER the main scene has been drawn and
+     * AFTER the camera transform has been applied (so the rect is in
+     * world space). Idempotent when no rubber-band is active.
+     */
+    function drawRubberBandIfActive() {
+        if (!rubberBand)
+            return;
+        ctx.save();
+        const minX = Math.min(rubberBand.x1, rubberBand.x2);
+        const maxX = Math.max(rubberBand.x1, rubberBand.x2);
+        const minY = Math.min(rubberBand.y1, rubberBand.y2);
+        const maxY = Math.max(rubberBand.y1, rubberBand.y2);
+        ctx.strokeStyle = cssVar("--accent") || "#d4a27f";
+        ctx.fillStyle = cssVar("--accent") || "#d4a27f";
+        ctx.globalAlpha = 0.12;
+        ctx.fillRect(minX, minY, maxX - minX, maxY - minY);
+        ctx.globalAlpha = 0.8;
+        ctx.lineWidth = 1 / Math.max(camera.scale, 0.5);
+        ctx.setLineDash([6 / Math.max(camera.scale, 0.5), 4 / Math.max(camera.scale, 0.5)]);
+        ctx.strokeRect(minX, minY, maxX - minX, maxY - minY);
+        ctx.setLineDash([]);
+        ctx.restore();
+    }
     function renderWalkOverlay() {
         if (!state)
             return;
@@ -203,6 +244,8 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             ctx.stroke();
         }
         ctx.globalAlpha = 1;
+        // Rubber-band overlay (still inside the world-transform save/restore)
+        drawRubberBandIfActive();
         ctx.restore();
         // Minimap
         if (showMinimap && state.nodes.length > 1) {
@@ -468,6 +511,22 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
                 ctx.lineWidth = isSelected ? 3 : 1.5;
                 ctx.stroke();
                 ctx.globalAlpha = 1;
+                // Pin indicator — subtle dashed outer ring on pinned nodes so the
+                // user can see which positions are being manually held. Rendered
+                // after the main circle but before the label so the label stays
+                // on top.
+                if (node.pinned) {
+                    ctx.save();
+                    ctx.strokeStyle = nodeBorder;
+                    ctx.globalAlpha = 0.55;
+                    ctx.lineWidth = 1;
+                    ctx.setLineDash([3, 3]);
+                    ctx.beginPath();
+                    ctx.arc(node.x, node.y, r + 4, 0, Math.PI * 2);
+                    ctx.stroke();
+                    ctx.setLineDash([]);
+                    ctx.restore();
+                }
                 // Highlighted path glow
                 if (highlightedPath && highlightedPath.nodeIds.has(node.id) && !isSelected) {
                     ctx.save();
@@ -528,6 +587,16 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         if (showMinimap && state.nodes.length > 1) {
             drawMinimap();
         }
+        // Rubber-band overlay — drawn AFTER the cache snapshot so it never
+        // gets baked into the cached scene. Uses its own camera transform.
+        if (rubberBand) {
+            ctx.save();
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+            ctx.translate(-camera.x * camera.scale, -camera.y * camera.scale);
+            ctx.scale(camera.scale, camera.scale);
+            drawRubberBandIfActive();
+            ctx.restore();
+        }
     }
     function drawMinimap() {
         if (!state)
@@ -689,6 +758,11 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
     }
     function simulate() {
         if (!state || alpha < ALPHA_MIN) {
+            // Clear animFrame so callers using the `if (!animFrame) simulate()`
+            // idiom can kick the sim back on after releasing pins or bumping
+            // alpha. Without this reset, animFrame stays truthy from the last
+            // RAF handle and subsequent restart attempts silently no-op.
+            animFrame = 0;
             // Start walk animation loop if simulation stopped but walk mode is active
             if (walkMode && walkTrail.length > 0 && !walkAnimFrame) {
                 walkAnimFrame = requestAnimationFrame(walkAnimate);
@@ -700,32 +774,185 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         render();
         animFrame = requestAnimationFrame(simulate);
     }
-    // --- Interaction: Pan + Click ---
-    let dragging = false;
+    // --- Interaction: Pan + Click + Node drag + Rubber-band select ---
+    //
+    // Gesture dispatch on mousedown:
+    //   1. mousedown on a node (no modifier) + cursor moves > threshold →
+    //      NODE DRAG. If the node is part of the current selection, drag
+    //      the whole selection as a rigid body. Otherwise drag just this
+    //      node. On drop, pin all dragged nodes.
+    //   2. mousedown on a node (no movement) → CLICK (existing selection
+    //      and walk-mode behavior).
+    //   3. mousedown on empty canvas with Shift → RUBBER-BAND select.
+    //   4. mousedown on empty canvas without modifier → PAN (existing).
+    //
+    // Node drag is disabled during walk mode — in walk mode, clicking a
+    // node advances the path, and drag gestures would fight the animation.
     let didDrag = false;
     let lastX = 0;
     let lastY = 0;
+    let mouseDownStartX = 0;
+    let mouseDownStartY = 0;
     canvas.addEventListener("mousedown", (e) => {
-        dragging = true;
+        dragMode = "pending";
         didDrag = false;
         lastX = e.clientX;
         lastY = e.clientY;
+        mouseDownStartX = e.clientX;
+        mouseDownStartY = e.clientY;
+        // Decide the potential gesture now — committed on first movement
+        // past the threshold. We still track "pending" so mouseup without
+        // movement falls through to the click path below.
+        const rect = canvas.getBoundingClientRect();
+        const mx = e.clientX - rect.left;
+        const my = e.clientY - rect.top;
+        const hit = nodeAtScreen(mx, my);
+        if (hit && !walkMode) {
+            // Set up the pending node drag. On first movement past the
+            // threshold we commit to "nodeDrag" mode.
+            dragNodes = [];
+            if (selectedNodeIds.has(hit.id) && selectedNodeIds.size > 1) {
+                // Drag the whole selection as a group
+                for (const id of selectedNodeIds) {
+                    const n = state?.nodeMap.get(id);
+                    if (n)
+                        dragNodes.push({ node: n, startX: n.x, startY: n.y });
+                }
+            }
+            else {
+                dragNodes.push({ node: hit, startX: hit.x, startY: hit.y });
+            }
+            const [wx, wy] = screenToWorld(mx, my);
+            dragStartWorldX = wx;
+            dragStartWorldY = wy;
+        }
+        else if (!hit && e.shiftKey) {
+            // Pending rubber-band (commits on first movement)
+            const [wx, wy] = screenToWorld(mx, my);
+            rubberBand = { x1: wx, y1: wy, x2: wx, y2: wy };
+        }
+        // Otherwise (empty canvas, no shift): will become pan on first move
     });
     canvas.addEventListener("mousemove", (e) => {
-        if (!dragging)
+        if (dragMode === "idle")
             return;
         const dx = e.clientX - lastX;
         const dy = e.clientY - lastY;
-        if (Math.abs(dx) > 5 || Math.abs(dy) > 5)
+        const totalDx = Math.abs(e.clientX - mouseDownStartX);
+        const totalDy = Math.abs(e.clientY - mouseDownStartY);
+        // Commit to a gesture once the cursor crosses the threshold
+        if (dragMode === "pending" &&
+            (totalDx > CLICK_DRAG_THRESHOLD || totalDy > CLICK_DRAG_THRESHOLD)) {
             didDrag = true;
-        camera.x -= dx / camera.scale;
-        camera.y -= dy / camera.scale;
+            if (dragNodes.length > 0) {
+                dragMode = "nodeDrag";
+                // Freeze the worker while the user is actively dragging so its
+                // incoming tick messages don't fight our local x/y updates
+                if (useWorker && layoutWorker) {
+                    layoutWorker.postMessage({ type: "stop" });
+                }
+            }
+            else if (rubberBand) {
+                dragMode = "rubberBand";
+            }
+            else {
+                dragMode = "pan";
+            }
+        }
+        if (dragMode === "nodeDrag") {
+            // Translate the dragged group by the cursor delta in world coords
+            const rect = canvas.getBoundingClientRect();
+            const mx = e.clientX - rect.left;
+            const my = e.clientY - rect.top;
+            const [wx, wy] = screenToWorld(mx, my);
+            const worldDx = wx - dragStartWorldX;
+            const worldDy = wy - dragStartWorldY;
+            for (const d of dragNodes) {
+                d.node.x = d.startX + worldDx;
+                d.node.y = d.startY + worldDy;
+                d.node.vx = 0;
+                d.node.vy = 0;
+                d.node.pinned = true;
+                pinnedNodeIds.add(d.node.id);
+            }
+            nodeHash.rebuild(state?.nodes ?? []);
+            requestRedraw();
+        }
+        else if (dragMode === "rubberBand" && rubberBand) {
+            const rect = canvas.getBoundingClientRect();
+            const mx = e.clientX - rect.left;
+            const my = e.clientY - rect.top;
+            const [wx, wy] = screenToWorld(mx, my);
+            rubberBand.x2 = wx;
+            rubberBand.y2 = wy;
+            requestRedraw();
+        }
+        else if (dragMode === "pan") {
+            camera.x -= dx / camera.scale;
+            camera.y -= dy / camera.scale;
+            requestRedraw();
+        }
         lastX = e.clientX;
         lastY = e.clientY;
-        requestRedraw();
     });
     canvas.addEventListener("mouseup", (e) => {
-        dragging = false;
+        const wasNodeDrag = dragMode === "nodeDrag";
+        const wasRubberBand = dragMode === "rubberBand";
+        const draggedNodeIdsSnapshot = dragNodes.map((d) => d.node.id);
+        if (wasNodeDrag) {
+            // Commit pins to the worker's copy so its simulation respects them
+            if (useWorker && layoutWorker && state) {
+                const updates = dragNodes.map((d) => ({
+                    id: d.node.id,
+                    x: d.node.x,
+                    y: d.node.y,
+                }));
+                layoutWorker.postMessage({ type: "pin", updates });
+                layoutWorker.postMessage({ type: "resume", alpha: 0.5 });
+            }
+            else {
+                // Main-thread simulation — just bump alpha so neighbors reflow
+                alpha = Math.max(alpha, 0.5);
+                if (!animFrame)
+                    simulate();
+            }
+            dragMode = "idle";
+            dragNodes = [];
+            requestRedraw();
+            return;
+        }
+        if (wasRubberBand && rubberBand && state) {
+            // Compute which nodes are inside the rectangle (world coords)
+            const minX = Math.min(rubberBand.x1, rubberBand.x2);
+            const maxX = Math.max(rubberBand.x1, rubberBand.x2);
+            const minY = Math.min(rubberBand.y1, rubberBand.y2);
+            const maxY = Math.max(rubberBand.y1, rubberBand.y2);
+            // Shift extends the existing selection; rubber-band without shift
+            // is currently impossible (we only enter this mode on shift+drag),
+            // but if that changes later we handle both cases here.
+            if (!e.shiftKey)
+                selectedNodeIds.clear();
+            for (const node of state.nodes) {
+                if (node.x >= minX && node.x <= maxX && node.y >= minY && node.y <= maxY) {
+                    selectedNodeIds.add(node.id);
+                }
+            }
+            const ids = [...selectedNodeIds];
+            onNodeClick?.(ids.length > 0 ? ids : null);
+            rubberBand = null;
+            dragMode = "idle";
+            requestRedraw();
+            return;
+        }
+        // Pan finishing → nothing to do, state cleanup below
+        if (dragMode === "pan") {
+            dragMode = "idle";
+            return;
+        }
+        // Fall through: this was a click (pending → no drag). Treat as the
+        // existing click-to-select / walk-mode-path behavior.
+        dragMode = "idle";
+        rubberBand = null;
         if (didDrag)
             return;
         // Click — hit test for node selection
@@ -733,7 +960,8 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         const mx = e.clientX - rect.left;
         const my = e.clientY - rect.top;
         const hit = nodeAtScreen(mx, my);
-        const multiSelect = e.ctrlKey || e.metaKey;
+        const multiSelect = e.ctrlKey || e.metaKey || e.shiftKey;
+        void draggedNodeIdsSnapshot;
         if (walkMode && focusSeedIds && hit && state) {
             // Walk mode: find path from current position to clicked node
             const currentId = walkTrail.length > 0 ? walkTrail[walkTrail.length - 1] : focusSeedIds[0];
@@ -829,7 +1057,32 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         requestRedraw();
     });
     canvas.addEventListener("mouseleave", () => {
-        dragging = false;
+        // Cancel any in-progress drag. Node drags keep the pins they already
+        // applied (the dragged nodes stay where the cursor last was). Rubber-
+        // band selects are abandoned without committing the selection.
+        if (dragMode === "nodeDrag") {
+            // Sync the final pin positions to the worker so simulation resumes
+            if (useWorker && layoutWorker && dragNodes.length > 0) {
+                const updates = dragNodes.map((d) => ({
+                    id: d.node.id,
+                    x: d.node.x,
+                    y: d.node.y,
+                }));
+                layoutWorker.postMessage({ type: "pin", updates });
+                layoutWorker.postMessage({ type: "resume", alpha: 0.5 });
+            }
+            else {
+                alpha = Math.max(alpha, 0.5);
+                if (!animFrame)
+                    simulate();
+            }
+        }
+        if (dragMode === "rubberBand") {
+            rubberBand = null;
+            requestRedraw();
+        }
+        dragMode = "idle";
+        dragNodes = [];
     });
     // --- Interaction: Zoom (wheel + pinch) ---
     canvas.addEventListener("wheel", (e) => {
@@ -996,7 +1249,8 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
     let hoverNodeId = null;
     let hoverTimeout = null;
     canvas.addEventListener("mousemove", (e) => {
-        if (dragging) {
+        // Suppress hover tooltip while any drag gesture is active
+        if (dragMode !== "idle" && dragMode !== "pending") {
             if (tooltip.style.display !== "none") {
                 tooltip.style.display = "none";
                 hoverNodeId = null;
@@ -1056,6 +1310,11 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             alpha = 1;
             selectedNodeIds = new Set();
             filteredNodeIds = null;
+            // Reset any lingering drag/pin state from the previous graph
+            pinnedNodeIds.clear();
+            dragMode = "idle";
+            dragNodes = [];
+            rubberBand = null;
             // Center camera on the graph
             camera = { x: 0, y: 0, scale: 1 };
             if (state.nodes.length > 0) {
@@ -1092,6 +1351,66 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             filteredNodeIds = ids;
             requestRedraw();
         },
+        /**
+         * Release every manually-pinned node so the force simulation
+         * reclaims them. Called by main.ts when a data event (node/edge
+         * add/remove, graph switch, backpack switch, focus/walk mode
+         * enter/exit, live reload) invalidates the user's temporary
+         * layout tweaks.
+         *
+         * Returns `true` if any pins were released, so the caller can
+         * show a toast only when the user actually loses work.
+         */
+        releaseAllPins() {
+            if (!state)
+                return false;
+            let hadPins = false;
+            for (const node of state.nodes) {
+                if (node.pinned) {
+                    hadPins = true;
+                    node.pinned = false;
+                }
+            }
+            pinnedNodeIds.clear();
+            // Clear any in-progress drag state too — a data change mid-drag
+            // should abort the drag cleanly
+            dragMode = "idle";
+            dragNodes = [];
+            rubberBand = null;
+            if (hadPins) {
+                // Nudge the simulation so the freed nodes start moving
+                if (useWorker && layoutWorker) {
+                    layoutWorker.postMessage({ type: "unpin", ids: "all" });
+                }
+                else {
+                    alpha = Math.max(alpha, 0.5);
+                    if (!animFrame)
+                        simulate();
+                }
+                requestRedraw();
+            }
+            return hadPins;
+        },
+        hasPinnedNodes() {
+            if (!state)
+                return false;
+            for (const node of state.nodes) {
+                if (node.pinned)
+                    return true;
+            }
+            return false;
+        },
+        /** Clear the multi-selection (used by ESC keyboard shortcut). */
+        clearSelection() {
+            if (selectedNodeIds.size === 0)
+                return;
+            selectedNodeIds.clear();
+            onNodeClick?.(null);
+            requestRedraw();
+        },
+        getSelectedNodeIds() {
+            return [...selectedNodeIds];
+        },
         panToNode(nodeId) {
             this.panToNodes([nodeId]);
         },
@@ -1215,6 +1534,14 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         enterFocus(seedNodeIds, hops) {
             if (!lastLoadedData || !state)
                 return;
+            // Release any user-pinned nodes — focus has its own layout and
+            // shouldn't inherit manual tweaks from the full-graph view.
+            for (const n of state.nodes)
+                n.pinned = false;
+            pinnedNodeIds.clear();
+            dragMode = "idle";
+            dragNodes = [];
+            rubberBand = null;
             // Save current full-graph state
             if (!focusSeedIds) {
                 savedFullState = state;
@@ -1261,6 +1588,15 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
             if (layoutWorker)
                 layoutWorker.postMessage({ type: "stop" });
             state = savedFullState;
+            // The saved full-graph state may have stale pinned flags from
+            // before the focus transition; scrub them so the user starts
+            // fresh on exit (pins are temporary view tweaks, not persistent).
+            for (const n of state.nodes)
+                n.pinned = false;
+            pinnedNodeIds.clear();
+            dragMode = "idle";
+            dragNodes = [];
+            rubberBand = null;
             nodeHash.rebuild(state.nodes);
             camera = savedFullCamera ?? { x: 0, y: 0, scale: 1 };
             focusSeedIds = null;
@@ -1329,6 +1665,10 @@ export function initCanvas(container, onNodeClick, onFocusChange, config) {
         },
         setWalkMode(enabled) {
             walkMode = enabled;
+            // Walk mode has its own layout choreography and must not fight
+            // with user-pinned positions. Releasing pins on mode transitions
+            // (either direction) keeps the two subsystems independent.
+            this.releaseAllPins();
             if (enabled) {
                 walkTrail = focusSeedIds ? [...focusSeedIds] : [...selectedNodeIds];
                 if (!walkAnimFrame)

package/dist/default-config.json

@@ -31,7 +31,8 @@
         "clusteringIncrease": "}",
         "toggleSidebar": "Tab",
         "walkMode": "w",
-        "walkIsolate": "i"
+        "walkIsolate": "i",
+        "resetPins": "r"
     },
     "server": {
         "host": "127.0.0.1",

package/dist/keybindings.d.ts

@@ -1,4 +1,4 @@
-export type KeybindingAction = "search" | "searchAlt" | "undo" | "redo" | "help" | "escape" | "focus" | "toggleEdges" | "center" | "nextNode" | "prevNode" | "nextConnection" | "prevConnection" | "historyBack" | "historyForward" | "hopsIncrease" | "hopsDecrease" | "panLeft" | "panDown" | "panUp" | "panRight" | "panFastLeft" | "zoomOut" | "zoomIn" | "panFastRight" | "spacingDecrease" | "spacingIncrease" | "clusteringDecrease" | "clusteringIncrease" | "toggleSidebar" | "walkMode" | "walkIsolate";
+export type KeybindingAction = "search" | "searchAlt" | "undo" | "redo" | "help" | "escape" | "focus" | "toggleEdges" | "center" | "nextNode" | "prevNode" | "nextConnection" | "prevConnection" | "historyBack" | "historyForward" | "hopsIncrease" | "hopsDecrease" | "panLeft" | "panDown" | "panUp" | "panRight" | "panFastLeft" | "zoomOut" | "zoomIn" | "panFastRight" | "spacingDecrease" | "spacingIncrease" | "clusteringDecrease" | "clusteringIncrease" | "toggleSidebar" | "walkMode" | "walkIsolate" | "resetPins";
 export type KeybindingMap = Record<KeybindingAction, string>;
 /** Parse a binding string like "ctrl+shift+z" and check if it matches a KeyboardEvent. */
 export declare function matchKey(e: KeyboardEvent, binding: string): boolean;

package/dist/keybindings.js

@@ -65,5 +65,6 @@ export function actionDescriptions() {
         toggleSidebar: "Toggle sidebar",
         walkMode: "Toggle walk mode (in focus)",
         walkIsolate: "Isolate walk trail nodes",
+        resetPins: "Release all pinned nodes (reset manual layout)",
     };
 }

package/dist/layout-worker.d.ts

@@ -7,8 +7,11 @@
  * Protocol:
  *   Main → Worker:
  *     { type: 'start', nodes, edges, params }  — begin simulation
- *     { type: 'stop' }                          — halt simulation
+ *     { type: 'stop' }                          — halt simulation (pauses)
+ *     { type: 'resume', alpha? }                — resume after a stop
  *     { type: 'params', params }                — update layout params + reheat
+ *     { type: 'pin', updates: [{id, x, y}] }    — mark node(s) as pinned at given pos
+ *     { type: 'unpin', ids: string[] | 'all' }  — release pins; 'all' clears every pin
  *
  *   Worker → Main:
  *     { type: 'tick', positions: Float64Array, alpha }  — position update per tick

package/dist/layout-worker.js

@@ -7,8 +7,11 @@
  * Protocol:
  *   Main → Worker:
  *     { type: 'start', nodes, edges, params }  — begin simulation
- *     { type: 'stop' }                          — halt simulation
+ *     { type: 'stop' }                          — halt simulation (pauses)
+ *     { type: 'resume', alpha? }                — resume after a stop
  *     { type: 'params', params }                — update layout params + reheat
+ *     { type: 'pin', updates: [{id, x, y}] }    — mark node(s) as pinned at given pos
+ *     { type: 'unpin', ids: string[] | 'all' }  — release pins; 'all' clears every pin
  *
  *   Worker → Main:
  *     { type: 'tick', positions: Float64Array, alpha }  — position update per tick
@@ -66,6 +69,53 @@ self.onmessage = (e) => {
     if (msg.type === "stop") {
         running = false;
     }
+    if (msg.type === "resume") {
+        if (!running && state) {
+            alpha = Math.max(alpha, typeof msg.alpha === "number" ? msg.alpha : 0.5);
+            running = true;
+            runLoop();
+        }
+    }
+    if (msg.type === "pin" && state) {
+        // updates: [{ id, x, y }] — apply to the worker's state copy. Pinned
+        // nodes are treated as fixed points by tick() in layout.ts.
+        const updates = msg.updates;
+        for (const u of updates) {
+            const node = state.nodeMap.get(u.id);
+            if (node) {
+                node.x = u.x;
+                node.y = u.y;
+                node.vx = 0;
+                node.vy = 0;
+                node.pinned = true;
+            }
+        }
+        // Nudge simulation so neighbors react to the new pin location
+        alpha = Math.max(alpha, 0.3);
+        if (!running) {
+            running = true;
+            runLoop();
+        }
+    }
+    if (msg.type === "unpin" && state) {
+        const ids = msg.ids;
+        if (ids === "all") {
+            for (const node of state.nodes)
+                node.pinned = false;
+        }
+        else if (Array.isArray(ids)) {
+            for (const id of ids) {
+                const node = state.nodeMap.get(id);
+                if (node)
+                    node.pinned = false;
+            }
+        }
+        alpha = Math.max(alpha, 0.5);
+        if (!running) {
+            running = true;
+            runLoop();
+        }
+    }
     if (msg.type === "params") {
         setLayoutParams(msg.params);
         // Reheat simulation

package/dist/layout.d.ts

@@ -7,6 +7,14 @@ export interface LayoutNode {
     vy: number;
     label: string;
     type: string;
+    /**
+     * When true, the simulation treats this node as a fixed point:
+     * it still contributes forces to neighbors (its x/y is read for
+     * repulsion and attraction calculations) but its own position is
+     * not updated by the integration step. Set by the viewer's drag
+     * handler to temporarily pin a node at a user-chosen location.
+     */
+    pinned?: boolean;
 }
 export interface LayoutEdge {
     sourceId: string;

package/dist/layout.js

@@ -229,8 +229,15 @@ export function tick(state, alpha) {
         node.vx += (c.x - node.x) * params.clusterStrength * alpha;
         node.vy += (c.y - node.y) * params.clusterStrength * alpha;
     }
-    // Integrate — update positions, apply damping, clamp velocity
+    // Integrate — update positions, apply damping, clamp velocity.
+    // Pinned nodes keep their x/y and have velocity zeroed so they
+    // don't drift when released later with pending momentum.
     for (const node of nodes) {
+        if (node.pinned) {
+            node.vx = 0;
+            node.vy = 0;
+            continue;
+        }
         node.vx *= DAMPING;
         node.vy *= DAMPING;
         const speed = Math.sqrt(node.vx * node.vx + node.vy * node.vy);