backpack-viewer 0.5.1 → 0.7.0

package/dist/extensions/types.d.ts

@@ -0,0 +1,182 @@
+import type { LearningGraphData } from "backpack-ontology";
+/**
+ * Versioned extension API contract.
+ *
+ * Bumping the major version means breaking changes for installed
+ * extensions — extensions declare which version they target in their
+ * manifest and the loader rejects mismatches.
+ */
+export declare const VIEWER_API_VERSION: "1";
+export type ViewerApiVersion = "1";
+/**
+ * Events an extension can subscribe to via `viewer.on(event, cb)`.
+ *
+ * - `graph-changed`: the active graph data was mutated (any source)
+ * - `graph-switched`: the user switched to a different active graph
+ * - `selection-changed`: the set of selected node ids changed
+ * - `focus-changed`: focus mode was entered, exited, or modified
+ */
+export type ViewerEvent = "graph-changed" | "graph-switched" | "selection-changed" | "focus-changed";
+/** Snapshot of the viewer's current focus state. */
+export interface ViewerFocusSnapshot {
+    seedNodeIds: string[];
+    hops: number;
+    totalNodes: number;
+}
+/** Public extension API surface. */
+export interface ViewerExtensionAPI {
+    readonly name: string;
+    readonly viewerApiVersion: ViewerApiVersion;
+    getGraph(): LearningGraphData | null;
+    getGraphName(): string;
+    getSelection(): string[];
+    getFocus(): ViewerFocusSnapshot | null;
+    on(event: ViewerEvent, callback: () => void): () => void;
+    addNode(type: string, properties: Record<string, unknown>): Promise<string>;
+    updateNode(nodeId: string, properties: Record<string, unknown>): Promise<void>;
+    removeNode(nodeId: string): Promise<void>;
+    addEdge(sourceId: string, targetId: string, type: string): Promise<string>;
+    removeEdge(edgeId: string): Promise<void>;
+    panToNode(nodeId: string): void;
+    focusNodes(nodeIds: string[], hops: number): void;
+    exitFocus(): void;
+    registerTaskbarIcon(opts: TaskbarIconOptions): () => void;
+    mountPanel(element: HTMLElement, opts?: MountPanelOptions): MountedPanel;
+    settings: ExtensionSettingsAPI;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+}
+export type TaskbarPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+export interface TaskbarIconOptions {
+    /** Visible button text and accessible label */
+    label: string;
+    /** Optional leading symbol shown before the label (no SVG in v1) */
+    iconText?: string;
+    /**
+     * Where to place the icon. Top slots nest into the viewer's existing
+     * top bar (alongside zoom/theme controls); bottom slots float in the
+     * canvas corners. Default: "bottom-right".
+     *
+     * The bottom-center area is reserved for the viewer's path bar — no
+     * slot lives there to avoid overlap.
+     */
+    position?: TaskbarPosition;
+    /** Click handler — usually toggles a panel */
+    onClick: () => void;
+}
+/**
+ * A custom button rendered in a panel's header, to the left of the
+ * built-in fullscreen + close controls. Each button shares the same
+ * visual style as the built-ins so extension chrome reads as one row
+ * of controls.
+ */
+export interface PanelHeaderButton {
+    label: string;
+    /** Optional short text shown as the button content (defaults to label). */
+    iconText?: string;
+    onClick: () => void;
+    disabled?: boolean;
+}
+export interface MountPanelOptions {
+    /** Panel header title */
+    title?: string;
+    /**
+     * Initial position relative to the canvas container (CSS pixels).
+     * Defaults to a sensible right-side spot. If a persisted position
+     * exists for this panel's persistence key, that wins over this
+     * default. The user can drag the panel by its title bar from there.
+     */
+    defaultPosition?: {
+        left: number;
+        top: number;
+    };
+    /** Custom buttons rendered before the built-in fullscreen + close. */
+    headerButtons?: PanelHeaderButton[];
+    /** Show the built-in fullscreen toggle button (default true). */
+    showFullscreenButton?: boolean;
+    /** Show the built-in close X button (default true). */
+    showCloseButton?: boolean;
+    /**
+     * If true, clicking the X button hides the panel via setVisible(false)
+     * instead of removing it from the DOM. Used by long-lived built-in
+     * panels (like info-panel) which are mounted once and reused for
+     * the lifetime of the viewer. Extensions typically leave this unset.
+     */
+    hideOnClose?: boolean;
+    /**
+     * Persistence key suffix. Position + fullscreen state are stored in
+     * localStorage under `backpack-viewer:panel:<key>`. Defaults to the
+     * extension/panel name passed to mount(). Set this if you need
+     * multiple panels for the same name.
+     */
+    persistKey?: string;
+    /**
+     * Called once after the panel is closed for any reason — user
+     * clicked the X button, the extension called `close()` itself, or
+     * the panel was destroyed because the viewer is reloading. For
+     * `hideOnClose` panels, this fires when the X is clicked too. The
+     * callback fires at most once per close.
+     */
+    onClose?: () => void;
+    /** Called whenever fullscreen state changes (button or programmatic). */
+    onFullscreenChange?: (fullscreen: boolean) => void;
+}
+export interface MountedPanel {
+    /** Remove the panel from the DOM (ignores hideOnClose). */
+    close(): void;
+    /** Toggle fullscreen state. */
+    setFullscreen(fullscreen: boolean): void;
+    /** Whether the panel is currently fullscreen. */
+    isFullscreen(): boolean;
+    /** Update the title shown in the header. */
+    setTitle(title: string): void;
+    /** Replace the custom header buttons. */
+    setHeaderButtons(buttons: PanelHeaderButton[]): void;
+    /** Show or hide the panel (without destroying it). */
+    setVisible(visible: boolean): void;
+    /** Whether the panel is currently visible. */
+    isVisible(): boolean;
+    /** Bring the panel to the front of the panel z-tier. */
+    bringToFront(): void;
+    /** The body element the extension owns (not the chrome). */
+    element: HTMLElement;
+}
+export interface ExtensionSettingsAPI {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/**
+ * Internal interface — what the extension API factory needs from main.ts
+ * to construct a per-extension API instance. main.ts creates a single
+ * "host" object and passes it to the API factory for each loaded
+ * extension. The host is the abstraction barrier between extension code
+ * and viewer internals.
+ */
+export interface ViewerHost {
+    getGraph(): LearningGraphData | null;
+    getGraphName(): string;
+    getSelection(): string[];
+    getFocus(): ViewerFocusSnapshot | null;
+    /** Save current graph state. Caller is expected to mutate getGraph() in place first. */
+    saveCurrentGraph(): Promise<void>;
+    /** Push current graph onto undo stack. */
+    snapshotForUndo(): void;
+    /** Drive the canvas. */
+    panToNode(nodeId: string): void;
+    focusNodes(nodeIds: string[], hops: number): void;
+    exitFocus(): void;
+    /**
+     * Taskbar slot containers (one per supported position). The host
+     * creates these in main.ts; the extension API factory routes
+     * `registerTaskbarIcon` calls into the right one based on the
+     * extension's chosen position.
+     */
+    taskbarSlots: {
+        topLeft: HTMLElement;
+        topRight: HTMLElement;
+        bottomLeft: HTMLElement;
+        bottomRight: HTMLElement;
+    };
+    /** Subscribe to events emitted by the host. */
+    subscribe(event: ViewerEvent, cb: () => void): () => void;
+}

package/dist/extensions/types.js

@@ -0,0 +1,8 @@
+/**
+ * Versioned extension API contract.
+ *
+ * Bumping the major version means breaking changes for installed
+ * extensions — extensions declare which version they target in their
+ * manifest and the loader rejects mismatches.
+ */
+export const VIEWER_API_VERSION = "1";

package/dist/info-panel.d.ts

@@ -1,4 +1,5 @@
 import type { LearningGraphData } from "backpack-ontology";
+import type { PanelMount } from "./extensions/panel-mount";
 export interface EditCallbacks {
     onUpdateNode(nodeId: string, properties: Record<string, unknown>): void;
     onChangeNodeType(nodeId: string, newType: string): void;
@@ -6,7 +7,7 @@ export interface EditCallbacks {
     onDeleteEdge(edgeId: string): void;
     onAddProperty(nodeId: string, key: string, value: string): void;
 }
-export declare function initInfoPanel(container: HTMLElement, callbacks?: EditCallbacks, onNavigateToNode?: (nodeId: string) => void, onFocus?: (nodeIds: string[]) => void): {
+export declare function initInfoPanel(container: HTMLElement, panelMount: PanelMount, callbacks?: EditCallbacks, onNavigateToNode?: (nodeId: string) => void, onFocus?: (nodeIds: string[]) => void): {
     show(nodeIds: string[], data: LearningGraphData): void;
     hide: () => void;
     goBack: () => void;

package/dist/info-panel.js

@@ -8,13 +8,17 @@ function nodeLabel(node) {
     return node.id;
 }
 const EDIT_ICON = '\u270E'; // pencil
-export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
-    const panel = document.createElement("div");
-    panel.id = "info-panel";
-    panel.className = "info-panel hidden";
-    container.appendChild(panel);
+export function initInfoPanel(container, panelMount, callbacks, onNavigateToNode, onFocus) {
+    // The body element is owned by info-panel and refilled on every
+    // show. Panel-mount wraps it with the standard chrome (title +
+    // header buttons + fullscreen + close). info-panel never destroys
+    // the panel — it uses setVisible(true/false) instead.
+    const bodyEl = document.createElement("div");
+    bodyEl.className = "info-panel-content";
+    container; // unused — kept in signature for backwards compat
+    // (the canvas container is no longer the direct parent; panel-mount
+    // handles DOM placement.)
     // --- State ---
-    let maximized = false;
     let history = [];
     let historyIndex = -1;
     let navigatingHistory = false;
@@ -23,11 +27,23 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
     let focusDisabled = false;
     let connectionNodeIds = []; // other-end node IDs for each connection
     let activeConnectionIndex = -1;
+    // Mount the panel once with placeholder chrome. show*() updates the
+    // title + header buttons each time a node is selected.
+    const handle = panelMount.mount("info", bodyEl, {
+        title: "Node info",
+        persistKey: "info-panel",
+        hideOnClose: true,
+        onClose: () => {
+            // Reset history when the user explicitly closes — re-opening on
+            // a fresh node selection should start a new history chain.
+            history = [];
+            historyIndex = -1;
+        },
+    });
+    // Start hidden — info-panel only appears when a node is selected.
+    handle.setVisible(false);
     function hide() {
-        panel.classList.add("hidden");
-        panel.classList.remove("info-panel-maximized");
-        panel.innerHTML = "";
-        maximized = false;
+        handle.setVisible(false);
         history = [];
         historyIndex = -1;
     }
@@ -65,60 +81,38 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
         showSingle(nodeId, lastData);
         navigatingHistory = false;
     }
-    function createToolbar() {
-        const toolbar = document.createElement("div");
-        toolbar.className = "info-panel-toolbar";
-        // Back
-        const backBtn = document.createElement("button");
-        backBtn.className = "info-toolbar-btn";
-        backBtn.textContent = "\u2190";
-        backBtn.title = "Back";
-        backBtn.disabled = historyIndex <= 0;
-        backBtn.addEventListener("click", goBack);
-        toolbar.appendChild(backBtn);
-        // Forward
-        const fwdBtn = document.createElement("button");
-        fwdBtn.className = "info-toolbar-btn";
-        fwdBtn.textContent = "\u2192";
-        fwdBtn.title = "Forward";
-        fwdBtn.disabled = historyIndex >= history.length - 1;
-        fwdBtn.addEventListener("click", goForward);
-        toolbar.appendChild(fwdBtn);
-        // Focus
+    /**
+     * Build the header-button list reflecting current state. Called
+     * after every show() so the back/forward/focus enabled state stays
+     * in sync.
+     */
+    function refreshHeaderButtons() {
+        const buttons = [
+            {
+                label: "Back",
+                iconText: "\u2190",
+                onClick: goBack,
+                disabled: historyIndex <= 0,
+            },
+            {
+                label: "Forward",
+                iconText: "\u2192",
+                onClick: goForward,
+                disabled: historyIndex >= history.length - 1,
+            },
+        ];
         if (onFocus && currentNodeIds.length > 0) {
-            const focusBtn = document.createElement("button");
-            focusBtn.className = "info-toolbar-btn info-focus-btn";
-            focusBtn.textContent = "\u25CE"; // bullseye
-            focusBtn.title = "Focus on neighborhood (F)";
-            focusBtn.disabled = focusDisabled;
-            if (focusDisabled)
-                focusBtn.style.opacity = "0.3";
-            focusBtn.addEventListener("click", () => {
-                if (!focusDisabled)
-                    onFocus(currentNodeIds);
+            buttons.push({
+                label: "Focus",
+                iconText: "\u25CE",
+                onClick: () => {
+                    if (!focusDisabled)
+                        onFocus(currentNodeIds);
+                },
+                disabled: focusDisabled,
             });
-            toolbar.appendChild(focusBtn);
         }
-        // Maximize/restore
-        const maxBtn = document.createElement("button");
-        maxBtn.className = "info-toolbar-btn";
-        maxBtn.textContent = maximized ? "\u2398" : "\u26F6";
-        maxBtn.title = maximized ? "Restore" : "Maximize";
-        maxBtn.addEventListener("click", () => {
-            maximized = !maximized;
-            panel.classList.toggle("info-panel-maximized", maximized);
-            maxBtn.textContent = maximized ? "\u2398" : "\u26F6";
-            maxBtn.title = maximized ? "Restore" : "Maximize";
-        });
-        toolbar.appendChild(maxBtn);
-        // Close
-        const closeBtn = document.createElement("button");
-        closeBtn.className = "info-toolbar-btn info-close-btn";
-        closeBtn.textContent = "\u00d7";
-        closeBtn.title = "Close";
-        closeBtn.addEventListener("click", hide);
-        toolbar.appendChild(closeBtn);
-        return toolbar;
+        handle.setHeaderButtons(buttons);
     }
     function showSingle(nodeId, data) {
         const node = data.nodes.find((n) => n.id === nodeId);
@@ -128,15 +122,15 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
         // Store connection targets for keyboard cycling
         connectionNodeIds = connectedEdges.map((e) => e.sourceId === nodeId ? e.targetId : e.sourceId);
         activeConnectionIndex = -1;
-        panel.innerHTML = "";
-        panel.classList.remove("hidden");
-        if (maximized)
-            panel.classList.add("info-panel-maximized");
-        // Pinned header area (toolbar + node identity)
+        bodyEl.replaceChildren();
+        // Update chrome with the node label as title + refresh header buttons
+        handle.setTitle(nodeLabel(node));
+        refreshHeaderButtons();
+        handle.setVisible(true);
+        // Pinned header area (type badge + node identity); the toolbar
+        // moved out of here into the panel chrome.
         const pinnedHeader = document.createElement("div");
         pinnedHeader.className = "info-panel-header";
-        // Toolbar (back, forward, maximize, close)
-        pinnedHeader.appendChild(createToolbar());
         // Header: type badge + label
         const header = document.createElement("div");
         header.className = "info-header";
@@ -191,7 +185,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
         header.appendChild(label);
         header.appendChild(nodeIdEl);
         pinnedHeader.appendChild(header);
-        panel.appendChild(pinnedHeader);
+        bodyEl.appendChild(pinnedHeader);
         // Scrollable body for properties, connections, timestamps
         const body = document.createElement("div");
         body.className = "info-panel-body";
@@ -382,7 +376,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
             deleteSection.appendChild(deleteBtn);
             body.appendChild(deleteSection);
         }
-        panel.appendChild(body);
+        bodyEl.appendChild(body);
     }
     function showMulti(nodeIds, data) {
         const selectedSet = new Set(nodeIds);
@@ -390,12 +384,11 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
         if (nodes.length === 0)
             return;
         const sharedEdges = data.edges.filter((e) => selectedSet.has(e.sourceId) && selectedSet.has(e.targetId));
-        panel.innerHTML = "";
-        panel.classList.remove("hidden");
-        if (maximized)
-            panel.classList.add("info-panel-maximized");
-        // Toolbar
-        panel.appendChild(createToolbar());
+        bodyEl.replaceChildren();
+        // Update chrome with multi-selection title + refresh header buttons
+        handle.setTitle(`${nodes.length} nodes selected`);
+        refreshHeaderButtons();
+        handle.setVisible(true);
         const header = document.createElement("div");
         header.className = "info-header";
         const label = document.createElement("h3");
@@ -416,7 +409,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
             badgeRow.appendChild(badge);
         }
         header.appendChild(badgeRow);
-        panel.appendChild(header);
+        bodyEl.appendChild(header);
         const nodesSection = createSection("Selected Nodes");
         const nodesList = document.createElement("ul");
         nodesList.className = "info-connections";
@@ -445,7 +438,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
             nodesList.appendChild(li);
         }
         nodesSection.appendChild(nodesList);
-        panel.appendChild(nodesSection);
+        bodyEl.appendChild(nodesSection);
         const connSection = createSection(sharedEdges.length > 0
             ? `Connections Between Selected (${sharedEdges.length})`
             : "Connections Between Selected");
@@ -517,7 +510,7 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
             }
             connSection.appendChild(list);
         }
-        panel.appendChild(connSection);
+        bodyEl.appendChild(connSection);
     }
     return {
         show(nodeIds, data) {
@@ -558,8 +551,8 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
                 if (activeConnectionIndex < 0)
                     activeConnectionIndex = connectionNodeIds.length - 1;
             }
-            // Highlight active row in the panel
-            const items = panel.querySelectorAll(".info-connection");
+            // Highlight active row in the panel body
+            const items = bodyEl.querySelectorAll(".info-connection");
             items.forEach((el, i) => {
                 el.classList.toggle("info-connection-active", i === activeConnectionIndex);
             });
@@ -570,14 +563,12 @@ export function initInfoPanel(container, callbacks, onNavigateToNode, onFocus) {
         },
         setFocusDisabled(disabled) {
             focusDisabled = disabled;
-            const btn = panel.querySelector(".info-focus-btn");
-            if (btn) {
-                btn.disabled = disabled;
-                btn.style.opacity = disabled ? "0.3" : "";
-            }
+            // Refresh the chrome's header buttons to pick up the new
+            // disabled state on the focus button (if currently shown).
+            refreshHeaderButtons();
         },
         get visible() {
-            return !panel.classList.contains("hidden");
+            return handle.isVisible();
         },
     };
 }

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);