flexdesk 0.4.3 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.4.3",
+    "version": "0.4.5",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {

package/src/tiling/tile_tree.js

@@ -690,6 +690,11 @@ export class TileTree {
     split(leafId, dir /* 'h' | 'v' */) {
         const leaf = this.get(leafId);
         if (!leaf || leaf.kind !== 'leaf') return null;
+        // A PANEL IS NEVER SPLIT. The left, right and bottom panels are fixed
+        // chrome around the content area, and a split of one put a second
+        // pane inside the navigator. Refused here, where every split path
+        // meets, so no chord, menu or drop can do it by another route.
+        if (_isPanel(leaf)) return null;
 
         const newLeaf = makeLeaf();
         // Case 1: root split. Wrap root in a new Split.

package/src/tiling/wm.js

@@ -689,7 +689,9 @@ export class WindowManager {
     // ── Split / close / focus / move ────────────────────────────────
     split(dir) {
         const tree = this._tree();
-        const focused = tree.focusedLeafId;
+        // From a panel, the chord means the content area: the same reading
+        // Backspace gives it. A panel itself is never split (TileTree.split).
+        const focused = this._contentLeafId(tree.focusedLeafId);
         if (!focused) return;
         // Chrome split buttons mirror Alt+H / Alt+V. The freshly created
         // pane is SEEDED with the default HOME content (the taxonomy root)
@@ -723,6 +725,7 @@ export class WindowManager {
      *  leaf id, or null if the leaf can't be split. */
     splitLeafWith(leafId, dir, kind, props = {}, title = '') {
         const tree = this._tree();
+        leafId = this._contentLeafId(leafId);
         const src = leafId ? tree.get(leafId) : null;
         if (!src || src.kind !== 'leaf') return null;
         const newId = tree.split(leafId, dir);
@@ -735,6 +738,16 @@ export class WindowManager {
         return newId;
     }
 
+    /** A leaf that can hold content: `leafId` itself, or the primary tile when
+     *  `leafId` is a panel, a window placeholder or gone. */
+    _contentLeafId(leafId) {
+        const tree = this._tree();
+        const leaf = leafId ? tree.get(leafId) : null;
+        const kind = String(leaf?.content?.kind || '');
+        if (leaf && leaf.kind === 'leaf' && !kind.startsWith('panel:') && kind !== PLACEHOLDER_KIND) return leafId;
+        return tree.primaryLeafId();
+    }
+
     /** Resolve the focused tile's active content for the keyboard-driven
      *  "open focused tile elsewhere" chords (Alt+T / Alt+N / Alt+Shift+H /
      *  Alt+Shift+V). Returns null for panels, window placeholders and

package/src/ui/components/column_fit.js

@@ -0,0 +1,170 @@
+/**
+ * column_fit.js — how wide each column of a table should be.
+ *
+ * A pure function over measurements, so the policy can be read and tested
+ * without a DOM. A table measures its columns, hands them here, and applies
+ * the widths it gets back.
+ *
+ * ── The policy ─────────────────────────────────────────────────────────
+ *
+ * Columns are not all alike, and treating them alike is what went wrong
+ * before. An id, a date, a status, a person: SHORT columns, whose values are
+ * all about as wide as each other, and which are useless the moment they are
+ * cut ("2026-09-…", "review-q…"). A summary or a title: TEXT columns, whose
+ * values run as long as people write them, and which are readable cut.
+ *
+ * The old fit spread spare room EVENLY, so a 40px "BUG" chip got 90px while
+ * the summary beside it was clipped in nine rows out of ten, and it shrank the
+ * WIDEST column first, so a narrow tile crushed the title to 85px while every
+ * short column kept its width.
+ *
+ *   1. Short columns get their full content width. Text columns start at a
+ *      readable width.
+ *   2. Room to spare goes to the text columns, in proportion to what each
+ *      still needs, and past their content so the table fills its box. With no
+ *      text column it goes to the last column, so no column in the middle
+ *      opens a gap.
+ *   3. Too little room: shrink in order of harm. Short columns first give up
+ *      only their rare longest values (down to `typical`, what most values
+ *      fit). Then text columns go down to a floor. Then short columns go down
+ *      to theirs, and text columns once more. What still does not fit scrolls
+ *      sideways rather than being crushed further.
+ *
+ * Within each step the widest columns give way first and the narrow ones keep
+ * their width (a water level), so one long column never forces every other
+ * column down with it.
+ *
+ * Columns the user dragged are PINNED: they keep their width and sit out every
+ * step.
+ */
+
+export const COLUMN_FIT = Object.freeze({
+    /** Absolute floor, and the drag-resize minimum. */
+    FLOOR: 40,
+    /** Sub-pixel safety against an ellipsis on content that exactly fits. */
+    PAD: 2,
+    /** A column whose full width reaches this is free text. */
+    TEXT_AT: 240,
+    /** A text column's starting share when room allows it. */
+    TEXT_MIN: 200,
+    /** How far a text column shrinks before short columns go below `typical`. */
+    TEXT_FLOOR: 120,
+    /** How far a short column shrinks before the table scrolls. */
+    SHORT_FLOOR: 56,
+});
+
+/**
+ * @typedef {object} ColumnMeasure
+ * @property {number}  natural   widest cell, padding included (px)
+ * @property {number}  [typical] width most cells fit, e.g. the 95th percentile (px);
+ *                               defaults to `natural`
+ * @property {number}  [header]  the header label's width (px)
+ * @property {number}  [pinned]  a user-dragged width, honoured exactly
+ * @property {boolean} [text]    force (true) or forbid (false) text treatment;
+ *                               omitted, it is decided from the width
+ */
+
+/**
+ * @param {ColumnMeasure[]} columns
+ * @param {number} avail  the width the table has (px); 0 or less means "not laid out"
+ * @returns {number[]} a width per column (px, possibly fractional). The sum
+ *   equals `avail` whenever the floors fit, and exceeds it only when they do
+ *   not, in which case the table should scroll.
+ */
+export function fitColumns(columns, avail) {
+    const { FLOOR, PAD, TEXT_AT, TEXT_MIN, TEXT_FLOOR, SHORT_FLOOR } = COLUMN_FIT;
+    const n = columns.length;
+    const cols = columns.map((c) => {
+        const header = Math.max(0, Number(c.header) || 0);
+        const natural = Math.max(0, Number(c.natural) || 0);
+        const full = Math.max(FLOOR, Math.ceil(Math.max(natural, header) + PAD));
+        const typical = Math.min(full, Math.max(FLOOR, Math.ceil(Math.max(
+            Number.isFinite(c.typical) ? c.typical : natural, header) + PAD)));
+        const pinned = Number.isFinite(c.pinned) ? Math.max(FLOOR, Math.round(c.pinned)) : null;
+        const text = pinned == null && (typeof c.text === 'boolean' ? c.text : full >= TEXT_AT);
+        return { full, typical, pinned, text };
+    });
+
+    const text = [];
+    const short = [];
+    cols.forEach((c, i) => { if (c.pinned == null) (c.text ? text : short).push(i); });
+    if (!(avail > 1)) return cols.map((c) => (c.pinned != null ? c.pinned : c.full));
+
+    // 1. The starting point: short columns at their full content width, text
+    //    columns at a readable width (or their content, if shorter).
+    const widths = cols.map((c) => {
+        if (c.pinned != null) return c.pinned;
+        return c.text ? Math.min(c.full, TEXT_MIN) : c.full;
+    });
+    const total = () => widths.reduce((a, b) => a + b, 0);
+    let slack = avail - total();
+
+    // 2. Room to spare goes to the text columns, in proportion to what each
+    //    still needs, then beyond their content so the table fills its box.
+    //    Widths are not rounded: CSS takes fractional pixels, and rounding is
+    //    what made the total miss the box by a pixel and a column jitter by one
+    //    as its tile was resized.
+    if (slack >= 0) {
+        slack = raise(widths, text, (i) => cols[i].full, slack);
+        if (slack > 0) {
+            if (text.length) text.forEach((i) => { widths[i] += slack / text.length; });
+            else widths[short.length ? short[short.length - 1] : n - 1] += slack;
+        }
+        return widths;
+    }
+
+    // 3. Not enough room: shrink in order of harm until it fits.
+    const steps = [
+        [short, (i) => cols[i].typical],
+        [text, () => TEXT_FLOOR],
+        [short, (i) => Math.min(cols[i].typical, SHORT_FLOOR)],
+        [text, () => FLOOR * 2],
+    ];
+    for (const [idxs, low] of steps) {
+        const over = total() - avail;
+        if (over <= 1e-6) break;
+        lowerTo(widths, idxs, low, over);
+    }
+    return widths;
+}
+
+/**
+ * Give up to `slack` px to the columns in `idxs`, each toward `target(i)`, in
+ * proportion to how far each still is from it. Returns what is left.
+ */
+function raise(widths, idxs, target, slack) {
+    if (!(slack > 0)) return slack;
+    const wants = idxs.map((i) => Math.max(0, target(i) - widths[i]));
+    const need = wants.reduce((a, b) => a + b, 0);
+    if (!(need > 0)) return slack;
+    const give = Math.min(slack, need);
+    idxs.forEach((i, k) => { widths[i] += give * wants[k] / need; });
+    return slack - give;
+}
+
+/**
+ * Take up to `over` px off the columns in `idxs`, widest first, none below
+ * `low(i)`. A water level: every column above the level is cut down to it, and
+ * the level is solved so the total cut is exactly `over`, or everything the
+ * lows allow when that is less. Solved on real numbers: the result is exact,
+ * and a wider box can never make any column narrower.
+ */
+function lowerTo(widths, idxs, low, over) {
+    const floorOf = (i) => Math.min(widths[i], Math.max(0, low(i)));
+    const cand = idxs.filter((i) => widths[i] > floorOf(i));
+    if (!cand.length || over <= 0) return;
+    const floors = new Map(cand.map((i) => [i, floorOf(i)]));
+    const capacity = cand.reduce((a, i) => a + widths[i] - floors.get(i), 0);
+    if (capacity <= over) {
+        for (const i of cand) widths[i] = floors.get(i);
+        return;
+    }
+    const cutAt = (level) => cand.reduce((a, i) => a + Math.max(0, widths[i] - Math.max(floors.get(i), level)), 0);
+    let lo = 0;
+    let hi = Math.max(...cand.map((i) => widths[i]));
+    for (let k = 0; k < 64; k++) {
+        const mid = (lo + hi) / 2;
+        if (cutAt(mid) > over) lo = mid; else hi = mid;
+    }
+    for (const i of cand) widths[i] = Math.min(widths[i], Math.max(floors.get(i), hi));
+}

package/src/ui/components/data_table.js

@@ -411,6 +411,13 @@ export class DataTable {
     render() {
         // Capture active filter input before re-render
         const activeFilterColIdx = this._getActiveFilterColIdx();
+        // KEYBOARD FOCUS SURVIVES A RE-RENDER. Rendering replaces the table
+        // element, and a focused element that is removed hands focus to the
+        // page body, where the arrow keys reach nobody. A data refresh does
+        // exactly that (a record changed on disk, a live reload), so keyboard
+        // navigation silently died the first time the store moved.
+        const doc = this.container.ownerDocument;
+        const hadTableFocus = !!this._tableEl && doc?.activeElement === this._tableEl;
 
         this._cleanup();
         this.container.innerHTML = '';
@@ -581,6 +588,9 @@ export class DataTable {
         if (activeFilterColIdx !== null) {
             this._restoreFilterFocus(activeFilterColIdx);
         }
+        else if (hadTableFocus && this._tableEl) {
+            try { this._tableEl.focus({ preventScroll: true }); } catch (_) { /* detached */ }
+        }
     }
 
     /**
@@ -2267,7 +2277,20 @@ export class DataTable {
         });
     }
 
+    /**
+     * CSS px per screen px. Content inside a zoomed tile reports rects and
+     * pointer coordinates in screen pixels, while `style.width` is CSS pixels;
+     * mixing them widened every column by the zoom factor on a mere click.
+     */
+    _zoomFactor() {
+        const el = this._tableWrapEl || this._tableEl;
+        const css = el?.offsetWidth || 0;
+        const screen = el?.getBoundingClientRect?.().width || 0;
+        return css > 0 && screen > 0 ? screen / css : 1;
+    }
+
     _beginColResize(ev, domIdx) {
+        if (ev.button != null && ev.button !== 0) return;
         ev.preventDefault();
         ev.stopPropagation();
         const headerTable = this._headerTableEl;
@@ -2275,24 +2298,38 @@ export class DataTable {
         const headRow = headerTable && headerTable.querySelector('thead > tr');
         if (!headRow) return;
 
-        // Freeze EVERY column at its current width on BOTH tables and
-        // lock fixed layout up front, so the drag moves only the grabbed
-        // column and a neighbour can never absorb it. Widths come from
-        // the header row (the column source of truth); the body's first
-        // row is pinned to match so the two tables stay in lock-step.
-        const startWidths = [...headRow.children].map(
-            (c) => c.getBoundingClientRect().width);
-        headerTable.style.tableLayout = 'fixed';
-        if (bodyTable) bodyTable.style.tableLayout = 'fixed';
-        startWidths.forEach((w, i) => this._pinColumnWidth(i, w));
-        this._applyTableWidth();
-
+        // NOTHING HAPPENS UNTIL THE POINTER MOVES. Freezing on mousedown pinned
+        // every column on a plain click, and the first click of a double-click,
+        // so a click on a grip was already a resize and switched auto-fit off
+        // for every column for good.
+        //
+        // Once the drag is real: freeze EVERY column at its current width on
+        // BOTH tables and lock fixed layout, so the drag moves only the grabbed
+        // column and a neighbour can never absorb it. Widths come from the
+        // header row (the column source of truth), in CSS pixels.
         const startX = ev.clientX;
+        const THRESHOLD = 3;
         const MIN = 40;
-        document.body.classList.add('twm-dt-col-resizing');
+        let startWidths = null;
+        const begin = () => {
+            const z = this._zoomFactor();
+            startWidths = [...headRow.children].map((c) => {
+                const set = parseFloat(c.style.width);
+                return Number.isFinite(set) ? set : c.getBoundingClientRect().width / z;
+            });
+            headerTable.style.tableLayout = 'fixed';
+            if (bodyTable) bodyTable.style.tableLayout = 'fixed';
+            startWidths.forEach((w, i) => this._pinColumnWidth(i, w));
+            this._applyTableWidth();
+            document.body.classList.add('twm-dt-col-resizing');
+        };
         const onMove = (mv) => {
-            const w = Math.max(
-                MIN, Math.round(startWidths[domIdx] + (mv.clientX - startX)));
+            const dx = mv.clientX - startX;
+            if (!startWidths) {
+                if (Math.abs(dx) < THRESHOLD) return;
+                begin();
+            }
+            const w = Math.max(MIN, Math.round(startWidths[domIdx] + dx / this._zoomFactor()));
             this._pinColumnWidth(domIdx, w);
             // Pass the dragged column so the fill invariant reclaims any
             // freed width into a DIFFERENT (flexible/last) column, never
@@ -2303,6 +2340,7 @@ export class DataTable {
         const onUp = () => {
             document.removeEventListener('mousemove', onMove);
             document.removeEventListener('mouseup', onUp);
+            if (!startWidths) return;               // a click: nothing changed
             document.body.classList.remove('twm-dt-col-resizing');
             this._updateCellTooltips();
             this._savePersisted();

package/src/ui/utils/auto_scrollbars.js

@@ -0,0 +1,270 @@
+/**
+ * auto_scrollbars.js — the overlay scrollbar, on EVERY scrollable element.
+ *
+ * `installOverlayScrollbar` (overlay_scrollbar.js) gives one container a thin
+ * bar that shows on hover and fades away. It is installed container by
+ * container, it puts the bar INSIDE the container, and it holds a resize
+ * observer, a subtree mutation observer and a window listener for each one.
+ * That is fine for a handful of known panes and wrong for "all of them": a
+ * page that redraws with `innerHTML = ''` deletes its bar for good, and a
+ * table body, a dropdown, a textarea and a dialog each want one.
+ *
+ * So this is the same look, done once for a whole subtree:
+ *
+ *   - Native scrollbars are hidden under `root`, so no element reserves
+ *     layout width for one and nothing reflows when a bar appears.
+ *   - Bars live in ONE fixed layer on `document.body`, positioned over the
+ *     element they belong to. Nothing is added to a scroll container, so a
+ *     redraw cannot remove a bar, and a textarea (which cannot hold children)
+ *     gets one too.
+ *   - An element gets its bars when the pointer is over it or it scrolls, if
+ *     it actually overflows. They fade out a moment after the pointer leaves
+ *     or the scrolling stops. Nested scroll areas each show their own.
+ *   - The thumb drags and the track pages, as a native bar does.
+ *
+ * Discovery is lazy: the pointer and scroll events name the elements worth
+ * measuring, so nothing walks the DOM looking for scroll areas.
+ */
+
+const LAYER_ID = 'twm-autoscroll-layer';
+const ROOT_CLASS = 'twm-autoscroll';
+const HIDE_AFTER_MS = 900;
+const MIN_THUMB = 30;
+const BAR = 6;
+
+/**
+ * Where the thumb goes. Pure, so it can be tested without a layout engine.
+ *
+ * @param {number} scrollSize  scrollHeight / scrollWidth
+ * @param {number} clientSize  clientHeight / clientWidth
+ * @param {number} scrollPos   scrollTop / scrollLeft
+ * @param {number} trackLen    the bar's length on screen (px)
+ * @returns {{size:number, pos:number}|null} null when nothing overflows
+ */
+export function thumbGeometry(scrollSize, clientSize, scrollPos, trackLen) {
+    const max = scrollSize - clientSize;
+    if (!(max > 1) || !(trackLen > 0)) return null;
+    const size = Math.min(trackLen, Math.max(MIN_THUMB, trackLen * clientSize / scrollSize));
+    const pos = (trackLen - size) * Math.min(1, Math.max(0, scrollPos / max));
+    return { size, pos };
+}
+
+/** Whether an element scrolls on an axis: its overflow allows it and its
+ *  content is larger than its box. */
+function scrollsOn(el, axis) {
+    if (!(el instanceof Element)) return false;
+    const cs = getComputedStyle(el);
+    const overflow = axis === 'y' ? cs.overflowY : cs.overflowX;
+    if (overflow !== 'auto' && overflow !== 'scroll' && !(el.tagName === 'TEXTAREA' && overflow !== 'hidden')) return false;
+    return axis === 'y' ? el.scrollHeight - el.clientHeight > 1 : el.scrollWidth - el.clientWidth > 1;
+}
+
+/**
+ * Give every scrollable element under `root` an auto-hiding overlay scrollbar.
+ *
+ * @param {HTMLElement} [root=document.body]
+ * @param {{exclude?: (el: Element) => boolean}} [opts]  elements to leave to
+ *   their own scrollbar. Containers that already carry an
+ *   `installOverlayScrollbar` bar are always left alone.
+ * @returns {{dispose: () => void}}
+ */
+export function installAutoScrollbars(root = document.body, { exclude = null } = {}) {
+    const doc = root.ownerDocument || document;
+    const win = doc.defaultView || window;
+    root.classList.add(ROOT_CLASS);
+
+    let layer = doc.getElementById(LAYER_ID);
+    if (!layer) {
+        layer = doc.createElement('div');
+        layer.id = LAYER_ID;
+        layer.className = 'twm-autoscroll-layer';
+        doc.body.appendChild(layer);
+    }
+
+    /** element -> { v, h, timer, hovered } */
+    const managed = new Map();
+    let hoverChain = new Set();
+
+    const eligible = (el) => el instanceof Element
+        && root.contains(el)
+        && !el.__overlayScrollbarInstalled
+        && !el.closest?.('.twm-autoscroll-layer')
+        && !(exclude && exclude(el));
+
+    const makeBar = (el, axis) => {
+        const bar = doc.createElement('div');
+        bar.className = `twm-autoscroll-bar twm-autoscroll-bar--${axis}`;
+        const thumb = doc.createElement('div');
+        thumb.className = 'twm-autoscroll-thumb';
+        bar.appendChild(thumb);
+        layer.appendChild(bar);
+
+        // The track pages, like a native bar's.
+        bar.addEventListener('mousedown', (e) => {
+            if (e.target !== bar) return;
+            e.preventDefault();
+            const r = thumb.getBoundingClientRect();
+            const before = axis === 'y' ? e.clientY < r.top : e.clientX < r.left;
+            const page = (axis === 'y' ? el.clientHeight : el.clientWidth) * 0.9;
+            if (axis === 'y') el.scrollTop += before ? -page : page;
+            else el.scrollLeft += before ? -page : page;
+        });
+        // The thumb drags.
+        thumb.addEventListener('mousedown', (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            const rec = managed.get(el);
+            if (rec) rec.dragging = true;
+            const start = axis === 'y' ? e.clientY : e.clientX;
+            const startScroll = axis === 'y' ? el.scrollTop : el.scrollLeft;
+            const trackLen = axis === 'y' ? bar.getBoundingClientRect().height : bar.getBoundingClientRect().width;
+            const thumbLen = axis === 'y' ? thumb.getBoundingClientRect().height : thumb.getBoundingClientRect().width;
+            const max = axis === 'y' ? el.scrollHeight - el.clientHeight : el.scrollWidth - el.clientWidth;
+            const perPx = trackLen > thumbLen ? max / (trackLen - thumbLen) : 0;
+            bar.classList.add('twm-autoscroll-bar--active');
+            const move = (mv) => {
+                const d = (axis === 'y' ? mv.clientY : mv.clientX) - start;
+                if (axis === 'y') el.scrollTop = startScroll + d * perPx;
+                else el.scrollLeft = startScroll + d * perPx;
+            };
+            const up = () => {
+                doc.removeEventListener('mousemove', move);
+                doc.removeEventListener('mouseup', up);
+                bar.classList.remove('twm-autoscroll-bar--active');
+                if (rec) rec.dragging = false;
+                hideLater(el);
+            };
+            doc.addEventListener('mousemove', move);
+            doc.addEventListener('mouseup', up);
+        });
+        bar.addEventListener('mouseenter', () => { const rec = managed.get(el); if (rec) { rec.onBar = true; show(el); } });
+        bar.addEventListener('mouseleave', () => { const rec = managed.get(el); if (rec) { rec.onBar = false; hideLater(el); } });
+        return { bar, thumb };
+    };
+
+    const record = (el) => {
+        let rec = managed.get(el);
+        if (!rec) {
+            rec = { v: null, h: null, timer: 0, dragging: false, onBar: false };
+            managed.set(el, rec);
+        }
+        return rec;
+    };
+
+    /** Place and size an element's bars; drop the element when it is gone. */
+    const place = (el) => {
+        const rec = managed.get(el);
+        if (!rec) return;
+        if (!el.isConnected) { drop(el); return; }
+        const r = el.getBoundingClientRect();
+        const vw = win.innerWidth;
+        const vh = win.innerHeight;
+        const top = Math.max(0, r.top);
+        const left = Math.max(0, r.left);
+        const bottom = Math.min(vh, r.bottom);
+        const right = Math.min(vw, r.right);
+        // Screen px per CSS px, for content inside a zoomed tile.
+        const z = el.offsetHeight ? r.height / el.offsetHeight : 1;
+        for (const axis of ['y', 'x']) {
+            const key = axis === 'y' ? 'v' : 'h';
+            const overflows = scrollsOn(el, axis);
+            if (!overflows) { if (rec[key]) rec[key].bar.style.display = 'none'; continue; }
+            if (!rec[key]) rec[key] = makeBar(el, axis);
+            const { bar, thumb } = rec[key];
+            bar.style.display = '';
+            if (axis === 'y') {
+                const len = bottom - top;
+                Object.assign(bar.style, { top: `${top}px`, left: `${right - BAR - 1}px`, height: `${len}px`, width: `${BAR}px` });
+                const g = thumbGeometry(el.scrollHeight * z, el.clientHeight * z, el.scrollTop * z, len);
+                if (!g) { bar.style.display = 'none'; continue; }
+                Object.assign(thumb.style, { top: `${g.pos}px`, height: `${g.size}px`, left: '0', width: '100%' });
+            } else {
+                const len = right - left;
+                Object.assign(bar.style, { left: `${left}px`, top: `${bottom - BAR - 1}px`, width: `${len}px`, height: `${BAR}px` });
+                const g = thumbGeometry(el.scrollWidth * z, el.clientWidth * z, el.scrollLeft * z, len);
+                if (!g) { bar.style.display = 'none'; continue; }
+                Object.assign(thumb.style, { left: `${g.pos}px`, width: `${g.size}px`, top: '0', height: '100%' });
+            }
+        }
+    };
+
+    const setVisible = (el, on) => {
+        const rec = managed.get(el);
+        if (!rec) return;
+        for (const b of [rec.v, rec.h]) if (b) b.bar.classList.toggle('twm-autoscroll-bar--on', on);
+    };
+    const show = (el) => {
+        const rec = record(el);
+        clearTimeout(rec.timer);
+        place(el);
+        setVisible(el, true);
+    };
+    const hideLater = (el) => {
+        const rec = managed.get(el);
+        if (!rec) return;
+        clearTimeout(rec.timer);
+        rec.timer = setTimeout(() => {
+            if (rec.dragging || rec.onBar || hoverChain.has(el)) return;
+            setVisible(el, false);
+        }, HIDE_AFTER_MS);
+    };
+    const drop = (el) => {
+        const rec = managed.get(el);
+        if (!rec) return;
+        clearTimeout(rec.timer);
+        rec.v?.bar.remove();
+        rec.h?.bar.remove();
+        managed.delete(el);
+    };
+
+    /** The scrollable elements from `target` up to `root`. */
+    const scrollChain = (target) => {
+        const out = new Set();
+        for (let el = target instanceof Element ? target : target?.parentElement; el && el !== doc.documentElement; el = el.parentElement) {
+            if (el.closest?.('.twm-autoscroll-layer')) return out;
+            if (eligible(el) && (scrollsOn(el, 'y') || scrollsOn(el, 'x'))) out.add(el);
+            if (el === root) break;
+        }
+        return out;
+    };
+
+    const onOver = (e) => {
+        if (e.target?.closest?.('.twm-autoscroll-layer')) return;
+        const next = scrollChain(e.target);
+        for (const el of hoverChain) if (!next.has(el)) hideLater(el);
+        for (const el of next) show(el);
+        hoverChain = next;
+    };
+    const onLeaveWindow = (e) => {
+        if (e.relatedTarget) return;
+        for (const el of hoverChain) hideLater(el);
+        hoverChain = new Set();
+    };
+    const onScroll = (e) => {
+        const el = e.target === doc ? null : e.target;
+        if (el && eligible(el)) { show(el); hideLater(el); }
+        // A scrolling ancestor moves every bar inside it.
+        for (const other of managed.keys()) if (other !== el) place(other);
+    };
+    let raf = 0;
+    const onResize = () => {
+        cancelAnimationFrame(raf);
+        raf = requestAnimationFrame(() => { for (const el of managed.keys()) place(el); });
+    };
+
+    doc.addEventListener('mouseover', onOver, true);
+    doc.addEventListener('mouseout', onLeaveWindow, true);
+    doc.addEventListener('scroll', onScroll, true);
+    win.addEventListener('resize', onResize);
+
+    return {
+        dispose() {
+            doc.removeEventListener('mouseover', onOver, true);
+            doc.removeEventListener('mouseout', onLeaveWindow, true);
+            doc.removeEventListener('scroll', onScroll, true);
+            win.removeEventListener('resize', onResize);
+            for (const el of [...managed.keys()]) drop(el);
+            root.classList.remove(ROOT_CLASS);
+        },
+    };
+}