@jbrowse/app-core 4.3.0 → 5.0.0-beta.10

package/esm/WorkspaceLayout/tree.js

@@ -0,0 +1,379 @@
+/**
+ * The layout tree, as pure functions over plain snapshots.
+ *
+ * This is the half of an MST-native workspace that carries the risk, so it is
+ * deliberately not MST: no nodes, no parents, no lifecycle, nothing to be alive
+ * or dead. Every operation is `tree in -> tree out`, which means the invariants
+ * below can be tested exhaustively instead of observed to hold.
+ *
+ * The trade being made is worth naming, because it is not "complexity for no
+ * complexity". Reconciling with dockview is replaced by **normalisation**: a
+ * tree that has just had a panel removed, or a branch split, is usually not in
+ * canonical form, and every operation has to put it back. That is real work and
+ * it is where this design's bugs would live. What it is not is timing: there is
+ * no event, no re-entrancy, no window during which the tree is half-updated,
+ * and no second owner to disagree with.
+ */
+export function isBranch(node) {
+    return 'children' in node;
+}
+export function panels(node) {
+    return isBranch(node) ? node.children.flatMap(panels) : [node];
+}
+function findPanel(node, panelId) {
+    return panels(node).find(p => p.id === panelId);
+}
+export function tabs(node) {
+    return panels(node).flatMap(p => p.tabs);
+}
+function homeOf(node, match) {
+    for (const panel of panels(node)) {
+        const tab = panel.tabs.find(match);
+        if (tab) {
+            return { panel, tab };
+        }
+    }
+    return undefined;
+}
+export function findTab(node, tabId) {
+    return homeOf(node, t => t.id === tabId);
+}
+/** The tab a panel is showing: the one it names, or its first. */
+export function activeTabIn(panel) {
+    return panel.tabs.find(t => t.id === panel.activeTabId) ?? panel.tabs[0];
+}
+export function tabContainingView(node, viewId) {
+    return homeOf(node, t => t.viewIds.includes(viewId));
+}
+export function panelContainingView(node, viewId) {
+    return tabContainingView(node, viewId)?.panel;
+}
+/**
+ * Put a tree back in canonical form. Four rules, applied bottom-up:
+ *
+ * 1. a branch with no children is dropped by its parent
+ * 2. a branch with one child is replaced by that child, which inherits the
+ *    branch's size — so the space the branch occupied does not move
+ * 3. a branch directly inside a branch of the same direction is flattened into
+ *    it, its children's sizes scaled to preserve their share of the whole
+ * 4. sizes are renormalised so a node's siblings always sum to 1
+ *
+ * Rule 3 is the one dockview cannot express: it forces orientation to alternate
+ * by depth, so `row` inside `row` is not representable and a nested split gets
+ * silently reparented. Here it is representable AND canonicalised, which is
+ * what makes `size` work at any depth rather than only on the top-level split.
+ *
+ * Empty panels are NOT dropped, and neither are empty tabs. A tab with no views
+ * is exactly what "new empty tab" creates — it shows the view launcher — so
+ * pruning empties wholesale would delete the thing the user just asked for.
+ */
+export function normalize(node) {
+    if (!isBranch(node)) {
+        return node;
+    }
+    const children = node.children
+        .map(normalize)
+        .filter(child => !(isBranch(child) && child.children.length === 0))
+        .flatMap(child => isBranch(child) && child.direction === node.direction
+        ? scaleSizes(child.children, child.size)
+        : [child]);
+    if (children.length === 1) {
+        return { ...children[0], size: node.size };
+    }
+    return { ...node, children: scaleSizes(children) };
+}
+/**
+ * Siblings whose sizes are already right are left ALONE, rather than divided by
+ * a sum of 1 and multiplied by 1.
+ *
+ * That round trip is not the identity in floating point, and normalisation runs
+ * on every action: seven equal panes renormalise to `0.14285714285714285`,
+ * which sums to `0.9999999999999998`, which renormalises to
+ * `0.14285714285714288`, which sums to `1.0000000000000002`, which renormalises
+ * back. So `normalize` had no fixed point — every action rewrote every size,
+ * a settled layout emitted a snapshot for each one, and the undo history filled
+ * with entries in which nothing observable changed. Exactly the failure
+ * dockview's echoing layout event caused, arrived at from the other side.
+ *
+ * The tolerance is what makes it terminate; the drift it admits does not
+ * accumulate, because the sizes stop moving as soon as they are inside it.
+ */
+const SIZE_EPSILON = 1e-9;
+/**
+ * Rescale a set of siblings so their sizes sum to `total`.
+ *
+ * Rule 4 renormalises to 1; rule 3 rescales a flattened branch's children to
+ * the share that branch held, so a child at half of a branch that was a third
+ * of its parent ends up at a sixth. Siblings summing to nothing take equal
+ * shares — the alternative is dividing by zero.
+ */
+function scaleSizes(children, total = 1) {
+    const sum = children.reduce((acc, c) => acc + c.size, 0);
+    if (sum <= 0) {
+        return children.map(c => ({ ...c, size: total / children.length }));
+    }
+    return Math.abs(sum - total) < SIZE_EPSILON
+        ? children
+        : children.map(c => ({ ...c, size: (c.size / sum) * total }));
+}
+/** Rebuild `node` with `replacer` applied to the subtree with id `targetId`. */
+function mapNode(node, targetId, replacer) {
+    if (node.id === targetId) {
+        return replacer(node);
+    }
+    if (!isBranch(node)) {
+        return node;
+    }
+    return {
+        ...node,
+        children: node.children.flatMap(child => {
+            const mapped = mapNode(child, targetId, replacer);
+            return mapped ? [mapped] : [];
+        }),
+    };
+}
+/**
+ * Split `panelId`, putting `newPanel` beside it in `direction`.
+ *
+ * Always builds a branch around the panel and lets `normalize` flatten it into
+ * the parent when the directions agree. Trying to decide up front whether to
+ * nest or to insert as a sibling is the same decision rule twice, and the two
+ * copies drift.
+ */
+export function splitPanel(root, panelId, direction, newPanel, before = false) {
+    // derived rather than minted: this function is pure, and the new panel's id
+    // is already unique in the tree, so a branch named after it is too
+    const branchId = `branch-${newPanel.id}`;
+    const split = mapNode(root, panelId, found => {
+        const pair = before ? [newPanel, found] : [found, newPanel];
+        return {
+            id: branchId,
+            size: found.size,
+            direction,
+            children: pair.map(child => ({ ...child, size: 1 })),
+        };
+    });
+    return normalize(split ?? root);
+}
+/** Drop a panel. Its space goes back to its siblings via renormalisation. */
+export function removePanel(root, panelId) {
+    const removed = mapNode(root, panelId, () => undefined);
+    // Removing the only panel leaves nothing to render, which is not a state the
+    // workspace has: the caller gets an empty panel to put the next tab in.
+    // `activeTabId` has to go with the tabs — it named one of them, and a panel
+    // pointing at a tab it no longer has is the dangling state every other
+    // operation here is careful not to leave (see integrity.test.ts).
+    return removed
+        ? normalize(removed)
+        : { ...root, tabs: [], activeTabId: undefined };
+}
+/** Set the sizes of one branch's children, e.g. from a splitter drag. */
+export function setSizes(root, branchId, sizes) {
+    return (mapNode(root, branchId, found => isBranch(found) && sizes.length === found.children.length
+        ? {
+            ...found,
+            children: scaleSizes(found.children.map((child, i) => ({ ...child, size: sizes[i] }))),
+        }
+        : found) ?? root);
+}
+/** Rebuild `root` with `replacer` applied to the panel with id `panelId`. */
+function mapPanel(root, panelId, replacer) {
+    return (mapNode(root, panelId, found => isBranch(found) ? found : replacer(found)) ?? root);
+}
+/** Rebuild `root` with `replacer` applied to the tab with id `tabId`. */
+function mapTab(root, tabId, replacer) {
+    const home = findTab(root, tabId);
+    return home
+        ? mapPanel(root, home.panel.id, panel => ({
+            ...panel,
+            tabs: panel.tabs.map(t => (t.id === tabId ? replacer(t) : t)),
+        }))
+        : root;
+}
+// --- tabs ------------------------------------------------------------------
+//
+// A tab is the unit the user drags, closes and renames; a view is what lives
+// inside one. Keeping them separate is what dockview models as group/panel, and
+// it is the level the first version of this tree left out entirely.
+export function addTab(root, panelId, tab) {
+    return mapPanel(root, panelId, panel => ({
+        ...panel,
+        tabs: [...panel.tabs, tab],
+        activeTabId: tab.id,
+    }));
+}
+/**
+ * Close a tab. The panel stays — an empty panel shows the view launcher, which
+ * is a state the user can reach deliberately.
+ */
+export function removeTab(root, tabId) {
+    const home = findTab(root, tabId);
+    if (!home) {
+        return root;
+    }
+    return mapPanel(root, home.panel.id, panel => {
+        const at = panel.tabs.findIndex(t => t.id === tabId);
+        const remaining = panel.tabs.filter(t => t.id !== tabId);
+        return {
+            ...panel,
+            tabs: remaining,
+            activeTabId: panel.activeTabId === tabId
+                ? // Fall to the neighbour on the left — which for the leftmost tab is
+                    // the one that slid into its place. A deliberate divergence from
+                    // dockview, which opened `mostRecentlyUsed[0]`: that needs a
+                    // per-panel MRU list in the tree, which is state to persist, keep
+                    // pruned and hold as an invariant, for a difference nobody has
+                    // asked about.
+                    remaining[Math.max(at - 1, 0)]?.id
+                : panel.activeTabId,
+        };
+    });
+}
+/**
+ * Move a tab into another panel, at `index` if given.
+ *
+ * One function returning one tree, so there is no instant at which the tab is
+ * in both panels or neither — the state the imperative bridge had to wrap an
+ * explicit `runInAction` around to hide from its own reconcile autorun.
+ *
+ * **`index` counts the tabs as they are ordered NOW**, before the move. That is
+ * the only reading a caller can supply, because it is the strip the user is
+ * looking at — and it differs from the post-removal ordering exactly when the
+ * tab is moving within its own panel and is currently to the LEFT of the gap it
+ * was dropped in. Dragging A to the gap between B and C in `[A, B, C]` is index
+ * 2 on screen; taking A out first makes that gap index 1, and inserting at 2
+ * lands it after C instead. Adjusting here rather than in the caller keeps the
+ * whole "remove then insert" mechanic inside the one function that does it.
+ *
+ * dockview reaches the same rule from the other end and it is worth knowing
+ * they agree, since this is the fiddliest arithmetic in the file: its tabs
+ * container computes `insertionIndex - (sourceIndex !== -1 && sourceIndex <
+ * insertionIndex ? 1 : 0)`, which is the condition below with the same bounds.
+ */
+export function moveTabToPanel(root, tabId, targetPanelId, index) {
+    const home = findTab(root, tabId);
+    // The target has to be checked BEFORE the removal, not after. This function
+    // takes the tab out and puts it back, so a target that cannot be found and is
+    // not rejected here leaves the tab — and every view in it — nowhere at all.
+    if (!home || !findPanel(root, targetPanelId)) {
+        return root;
+    }
+    const { tab } = home;
+    const from = home.panel.id === targetPanelId
+        ? home.panel.tabs.findIndex(t => t.id === tabId)
+        : -1;
+    return mapPanel(removeTab(root, tabId), targetPanelId, panel => {
+        // No index means append, and it has to keep meaning that within one panel.
+        // The shift below is about reading a STATED index against the strip on
+        // screen; a caller that states nothing is not describing a gap, so shifting
+        // its position lands the tab one place short of the end.
+        const at = index === undefined
+            ? panel.tabs.length
+            : Math.min(Math.max(from >= 0 && from < index ? index - 1 : index, 0), panel.tabs.length);
+        return {
+            ...panel,
+            tabs: [...panel.tabs.slice(0, at), tab, ...panel.tabs.slice(at)],
+            activeTabId: tab.id,
+        };
+    });
+}
+export function setActiveTab(root, panelId, tabId) {
+    return mapPanel(root, panelId, panel => panel.tabs.some(t => t.id === tabId)
+        ? { ...panel, activeTabId: tabId }
+        : panel);
+}
+export function renameTab(root, tabId, title) {
+    return mapTab(root, tabId, tab => ({ ...tab, title }));
+}
+// --- views inside tabs -----------------------------------------------------
+export function addViewToTab(root, tabId, viewId) {
+    return mapTab(root, tabId, tab => tab.viewIds.includes(viewId)
+        ? tab
+        : { ...tab, viewIds: [...tab.viewIds, viewId] });
+}
+/** Take a view out of whatever tab holds it, leaving the tab in place. */
+export function removeView(root, viewId) {
+    const home = tabContainingView(root, viewId);
+    return home
+        ? mapTab(root, home.tab.id, tab => ({
+            ...tab,
+            viewIds: tab.viewIds.filter(id => id !== viewId),
+        }))
+        : root;
+}
+/**
+ * Make the tree's membership agree with the session's list of views.
+ *
+ * The only reconciliation left, and one-directional: `session.views` owns which
+ * views exist, and nothing reads back.
+ *
+ * **`viewIds` is the session's WHOLE set.** A shorter list does not leave the
+ * rest alone — it unhomes them, and the next homing pass sweeps them into one
+ * tab.
+ */
+export function homeViews(root, viewIds, activePanelId, nextTabId) {
+    const all = panels(root);
+    const target = all.find(p => p.id === activePanelId) ?? all[0];
+    if (!target) {
+        return root;
+    }
+    let next = root;
+    let homeTabId = activeTabIn(target)?.id;
+    if (!homeTabId) {
+        // A panel with no tabs is legal, but it cannot be where a view lands — so
+        // this mints one rather than declining, which also means a blank cell built
+        // by `closePanel` on the last panel is repaired by the next homing pass.
+        homeTabId = nextTabId();
+        next = addTab(next, target.id, { id: homeTabId, viewIds: [] });
+    }
+    for (const viewId of viewIds) {
+        if (!tabContainingView(next, viewId)) {
+            next = addViewToTab(next, homeTabId, viewId);
+        }
+    }
+    // read the memberships once, then drop: `removeView` returns a new tree each
+    // call, so a list taken from a tree it has already replaced goes stale
+    const owned = new Set(viewIds);
+    const departed = tabs(next)
+        .flatMap(t => t.viewIds)
+        .filter(id => !owned.has(id));
+    for (const viewId of departed) {
+        next = removeView(next, viewId);
+    }
+    return next;
+}
+/**
+ * Drop a panel that has been left with no tabs, unless it is the only one.
+ *
+ * Deliberately NOT a normalisation rule. A panel with no tabs is reachable on
+ * purpose, so pruning empties wholesale would delete a space the user asked
+ * for. It is a step the *drag* gesture takes about its own source panel,
+ * because dragging the last tab out of a split and leaving a blank half is the
+ * one place an empty panel is clearly not what was meant.
+ */
+export function pruneEmptyPanel(root, panelId) {
+    const found = findPanel(root, panelId);
+    return found && found.tabs.length === 0 && panels(root).length > 1
+        ? removePanel(root, panelId)
+        : root;
+}
+/**
+ * Drop a tab that a move has left with no views, unless it is the panel's last.
+ *
+ * The mirror of `pruneEmptyPanel`, and deliberately as narrow: an empty tab is
+ * legitimate (it shows the view launcher), so this only ever runs on the tab a
+ * move just emptied, never as a rule over the tree.
+ *
+ * Which is why closing a tab's last VIEW leaves the tab standing where a move
+ * out of it does not: the move acted somewhere else and left this behind, and
+ * the close acted here, where an empty tab is a usable place to open the next
+ * thing. A cell's last tab prunes because a blank cell is not usable.
+ */
+export function pruneEmptyTabIn(root, panelId, tabId) {
+    const found = findPanel(root, panelId);
+    if (!found || found.tabs.length <= 1) {
+        return root;
+    }
+    const tab = found.tabs.find(t => t.id === tabId);
+    return tab?.viewIds.length === 0 ? removeTab(root, tabId) : root;
+}

package/esm/WorkspaceLayout/useLayoutDrag.d.ts

@@ -0,0 +1,34 @@
+import type { DropTarget } from './dropZone.ts';
+import type { WorkspaceLayout } from './model.ts';
+export interface DragState extends DropTarget {
+    tabId: string;
+    panelId: string;
+}
+export interface TabDragHandlers {
+    onTabPointerDown: (tabId: string, event: React.PointerEvent<HTMLElement>) => void;
+    onTabPointerMove: (event: React.PointerEvent<HTMLElement>) => void;
+    onTabPointerUp: (event: React.PointerEvent<HTMLElement>) => void;
+    onTabPointerCancel: (event: React.PointerEvent<HTMLElement>) => void;
+}
+/**
+ * Dragging a tab: pointer events, not HTML5 drag-and-drop.
+ *
+ * HTML5 DnD would hand us a drag image we don't want, a `dragover` we can't
+ * read coordinates from reliably across browsers, and no pointer capture — so
+ * releasing outside the window leaves the drag stuck on. Pointer events give
+ * capture for free, which is what makes "let go anywhere" behave.
+ *
+ * The in-flight drag is React state, deliberately NOT in MST. It is transient
+ * UI, and putting it in the session would put every intermediate hover into the
+ * undo history — which is the mistake `dockviewLayout` made in the other
+ * direction, persisting something that was really a view of live state.
+ */
+export declare function useLayoutDrag(layout: WorkspaceLayout): {
+    drag: DragState | undefined;
+    handlers: {
+        onTabPointerDown: (tabId: string, event: React.PointerEvent<HTMLElement>) => void;
+        onTabPointerMove: (event: React.PointerEvent<HTMLElement>) => void;
+        onTabPointerUp: (event: React.PointerEvent<HTMLElement>) => void;
+        onTabPointerCancel: (event: React.PointerEvent<HTMLElement>) => void;
+    };
+};

package/esm/WorkspaceLayout/useLayoutDrag.js

@@ -0,0 +1,232 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { dropZoneAt, splitForZone, stripDropAt } from './dropZone.js';
+/**
+ * Two drags that would paint the same thing.
+ *
+ * The indicator is a function of the cell and the zone — or, on a strip, the gap
+ * — and a pointer produces events far faster than it crosses between any of
+ * them. Publishing a fresh object per move re-rendered the cell under the
+ * pointer at pointer-event rate, and a cell's render rebuilds its `ViewStack`;
+ * `renderTabContent` hands back a new `views` array each time, so nothing
+ * downstream memoises it away. That is the same cost the memoised `handlers`
+ * removed for every OTHER cell, still being paid by the one being dragged over.
+ */
+function samePlace(a, b) {
+    return (a?.tabId === b?.tabId &&
+        a?.panelId === b?.panelId &&
+        a?.zone === b?.zone &&
+        a?.strip?.index === b?.strip?.index &&
+        a?.strip?.left === b?.strip?.left);
+}
+/**
+ * A drop `dropTabInPanel` would decline, so there is nothing to draw for it —
+ * the centre wash promises "be a tab of this cell" to a tab already in it, held
+ * for the whole hover and then dropped on release.
+ *
+ * Declining here rather than at the release makes it one decision: nothing is
+ * published, so `onTabPointerUp` finds an empty `dragRef` and needs no case.
+ * `pendingRef` stays armed, so the drag resumes on crossing back out.
+ */
+function declines(layout, drag) {
+    return (!drag.strip &&
+        drag.zone === 'center' &&
+        layout.findTab(drag.tabId)?.panel.id === drag.panelId);
+}
+/**
+ * Dragging a tab: pointer events, not HTML5 drag-and-drop.
+ *
+ * HTML5 DnD would hand us a drag image we don't want, a `dragover` we can't
+ * read coordinates from reliably across browsers, and no pointer capture — so
+ * releasing outside the window leaves the drag stuck on. Pointer events give
+ * capture for free, which is what makes "let go anywhere" behave.
+ *
+ * The in-flight drag is React state, deliberately NOT in MST. It is transient
+ * UI, and putting it in the session would put every intermediate hover into the
+ * undo history — which is the mistake `dockviewLayout` made in the other
+ * direction, persisting something that was really a view of live state.
+ */
+export function useLayoutDrag(layout) {
+    const [drag, setDrag] = useState(undefined);
+    // the pointer has gone down on a tab but may still turn out to be a click.
+    // `pointerId` is what makes every handler below about ONE pointer: a second
+    // finger elsewhere in the strip otherwise steers the first one's drag, and
+    // its release ends it. dockview tracks the same id for the same reason.
+    const pendingRef = useRef(undefined);
+    /**
+     * The drag, mirrored into a ref so the handlers can read it without depending
+     * on it — which keeps them identity-stable. They go into `PanelChrome`, so
+     * handlers that changed on every pointer move re-rendered every cell in the
+     * workspace, and a cell's render rebuilds its `ViewStack`.
+     */
+    const dragRef = useRef(undefined);
+    const showDrag = useCallback((next) => {
+        if (samePlace(dragRef.current, next)) {
+            return;
+        }
+        dragRef.current = next;
+        setDrag(next);
+    }, []);
+    const resolveTarget = useCallback((x, y) => {
+        const under = document
+            .elementsFromPoint(x, y)
+            .filter(el => el instanceof HTMLElement);
+        const panelEl = under.find(el => el.dataset.panelId);
+        if (!panelEl?.dataset.panelId) {
+            return undefined;
+        }
+        const panelId = panelEl.dataset.panelId;
+        const panelRect = panelEl.getBoundingClientRect();
+        // The strip is a finer answer than `center`, and it has to be tested first:
+        // the strip sits inside the panel's top edge band, so `dropZoneAt` alone
+        // reads a drop between two tabs as "split this cell upwards".
+        const stripEl = under.find(el => 'tabStrip' in el.dataset);
+        if (stripEl) {
+            // panel-relative, so the caret can be drawn inside the panel's own box
+            const rects = [...stripEl.querySelectorAll('[data-tab-id]')].map(el => {
+                const r = el.getBoundingClientRect();
+                return {
+                    left: r.left - panelRect.left,
+                    top: r.top - panelRect.top,
+                    width: r.width,
+                    height: r.height,
+                };
+            });
+            return {
+                panelId,
+                zone: 'center',
+                strip: stripDropAt(rects, x - panelRect.left),
+            };
+        }
+        return { panelId, zone: dropZoneAt(panelRect, x, y) };
+    }, []);
+    /**
+     * A drag starts on the PRIMARY button of the primary pointer, and on nothing
+     * else.
+     *
+     * dockview never had to say this: its tab drags over HTML5 dnd, where the
+     * browser owns the rule, and its pointer source is touch/pen only by default.
+     * Pointer events here are for capture (release outside the window ends the
+     * drag), which means owning the rule too — and without it a right-drag moved
+     * a tab, and a right-press left `pending` armed with no `pointerup` to clear
+     * it, because the native context menu eats that one. The next move of a
+     * button-less pointer then dragged the tab, and the click that dismissed the
+     * menu dropped it.
+     */
+    const onTabPointerDown = useCallback((tabId, event) => {
+        if (event.button !== 0 || !event.isPrimary) {
+            return;
+        }
+        // a fresh press is a fresh gesture: anything left over from a drag that
+        // ended without a drop would otherwise skip the slop below and start on
+        // the first pixel
+        showDrag(undefined);
+        pendingRef.current = {
+            tabId,
+            pointerId: event.pointerId,
+            x: event.clientX,
+            y: event.clientY,
+        };
+        event.currentTarget.setPointerCapture(event.pointerId);
+    }, [showDrag]);
+    const onTabPointerMove = useCallback((event) => {
+        const pending = pendingRef.current;
+        if (pending?.pointerId !== event.pointerId) {
+            return;
+        }
+        // a few pixels of slop, so a tab click is a click and not a zero-distance
+        // drag that lands the tab back where it started
+        const moved = Math.abs(event.clientX - pending.x) +
+            Math.abs(event.clientY - pending.y);
+        if (!dragRef.current && moved < 5) {
+            return;
+        }
+        const target = resolveTarget(event.clientX, event.clientY);
+        const next = target ? { tabId: pending.tabId, ...target } : undefined;
+        showDrag(next && !declines(layout, next) ? next : undefined);
+    }, [layout, resolveTarget, showDrag]);
+    /**
+     * The gesture ended without a drop: the browser took the pointer away.
+     *
+     * A long-press on a touch device does exactly this — the platform opens its
+     * own context menu and cancels the pointer — and there is no `pointerup` to
+     * follow, so the indicator stayed painted over the cell and the drag resumed
+     * from the next move. The same clearing as Escape, and for the same reason:
+     * clearing only what is on screen leaves `pending` to rebuild it.
+     *
+     * Capture is already gone by the time this fires, so there is nothing to
+     * release.
+     */
+    const onTabPointerCancel = useCallback((event) => {
+        const pending = pendingRef.current;
+        if (pending && pending.pointerId !== event.pointerId) {
+            return;
+        }
+        pendingRef.current = undefined;
+        showDrag(undefined);
+    }, [showDrag]);
+    const onTabPointerUp = useCallback((event) => {
+        const pending = pendingRef.current;
+        // No pending at all still releases: Escape cancels the drag and leaves
+        // capture held, so this is the only thing that gives it back.
+        if (pending && pending.pointerId !== event.pointerId) {
+            return;
+        }
+        pendingRef.current = undefined;
+        event.currentTarget.releasePointerCapture(event.pointerId);
+        const current = dragRef.current;
+        showDrag(undefined);
+        if (!pending || !current) {
+            return;
+        }
+        // a drop on the strip says where in the order; anywhere else appends
+        if (current.strip) {
+            layout.dropTabInPanel(current.tabId, current.panelId, current.strip.index);
+            return;
+        }
+        const split = splitForZone(current.zone);
+        if (split) {
+            layout.dropTabInNewSplit(current.tabId, current.panelId, split.direction, split.before);
+        }
+        else {
+            layout.dropTabInPanel(current.tabId, current.panelId);
+        }
+    }, [layout, showDrag]);
+    /**
+     * Escape abandons an in-flight drag.
+     *
+     * On `window`, because pointer capture routes POINTER events to the tab and
+     * does nothing for the keyboard — focus is wherever it was when the drag
+     * started, which is usually not the tab.
+     *
+     * Clearing `pendingRef` as well as the drag state is the part that matters:
+     * the drag is rebuilt from `pending` on every move, so cancelling the visible
+     * state alone would let the next pixel of movement resume it.
+     *
+     * `drag` is the dependency here on purpose, where the handlers avoid it: the
+     * listener should exist only while a drag does.
+     */
+    useEffect(() => {
+        if (!drag) {
+            return;
+        }
+        function onKeyDown(event) {
+            if (event.key === 'Escape') {
+                pendingRef.current = undefined;
+                showDrag(undefined);
+            }
+        }
+        window.addEventListener('keydown', onKeyDown);
+        return () => {
+            window.removeEventListener('keydown', onKeyDown);
+        };
+    }, [drag, showDrag]);
+    // one object, memoised: it goes into `PanelChrome`, which every panel holds,
+    // so a fresh one per render is a re-render of every cell in the workspace
+    const handlers = useMemo(() => ({
+        onTabPointerDown,
+        onTabPointerMove,
+        onTabPointerUp,
+        onTabPointerCancel,
+    }), [onTabPointerDown, onTabPointerMove, onTabPointerUp, onTabPointerCancel]);
+    return { drag, handlers };
+}

package/esm/index.d.ts

@@ -1,9 +1,18 @@
-export * from './ui/index.ts';
-export * from './HistoryManagement/index.ts';
-export * from './AppFocus/index.ts';
-export * from './JBrowseConfig/index.ts';
-export * from './JBrowseModel/index.ts';
-export * from './Assemblies/index.ts';
-export * from './RootMenu/index.ts';
-export * from './DockviewLayout/index.ts';
-export * from './menus.ts';
+export { App, DialogQueue, preloadAppFrame, preloadAppShell, } from './ui/index.ts';
+export { HistoryManagementMixin } from './HistoryManagement/index.ts';
+export { DEFAULT_SHARE_URL, JBrowseConfigF } from './JBrowseConfig/index.ts';
+export { JBrowseModelF } from './JBrowseModel/index.ts';
+export { AssembliesMixin } from './Assemblies/index.ts';
+export { AppSessionMixin } from './AppSession/index.ts';
+export type { AppRootModel } from './AppSession/index.ts';
+export { RootAppMenuMixin } from './RootMenu/index.ts';
+export { WorkspaceLayoutMixin, isSessionWithWorkspaceLayout, } from './WorkspaceLayout/index.ts';
+export type { WorkspaceLayoutMixinType, WorkspaceLayout, LayoutTree, PanelNode, TabNode, LayoutSpecNode, PendingMove, TileMode, TabHome, } from './WorkspaceLayout/index.ts';
+export { addSessionTracks, buildLgvInit, buildLgvInitFromParams, hubConnectionSpec, loadSessionSpec, parseSessionSpecUrl, readHubUrlParam, readNavParam, readTracklistParam, shortHubLabel, splitHighlights, } from './SessionSpec/index.ts';
+export type { LayoutNode, LgvUrlInit, ParsedSessionSpec, ViewSpec, } from './SessionSpec/index.ts';
+export type { SessionModelFactory } from './sessionModelFactory.ts';
+export { deleteQueryParams, readAllQueryParams, readQueryParams, setQueryParams, useQueryParam, } from './queryParams.ts';
+export { processMutableMenuActions, resolveMenus } from './menus.ts';
+export type { Menu, MenuAction } from './menus.ts';
+export { createJbApi, ensureReExports, safeJson, sessionOf, undeliveredNotifications, waitReady, } from './JbApi/index.ts';
+export type { JbApi } from './JbApi/index.ts';