@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/layout/grid-pack/grid-pack-engine.js

@@ -0,0 +1,685 @@
+"use strict";
+/**
+ * GridPackEngine — the dashboard-grid interaction engine (Phase 1 of the
+ * dashboard-grid plan; `documentation/api-architecture/dashboard-grid-plan.html`).
+ *
+ * A DOM-free, deterministic INTEGER-CELL engine implementing the gridstack
+ * interaction model, with semantics EMPIRICALLY RECORDED from the real
+ * gridstackjs.com demos (web1 + web2 driven with Playwright; gs-x/gs-y read at
+ * every stage), then hand-tested four rounds on the interactive prototype the
+ * plan page embeds. The recordings — not the gridstack source, which we found
+ * misleading on E4b — are this engine's contract:
+ *
+ *   E1  resize grow→shrink in ONE gesture: pushed tiles RETURN when the space
+ *       frees (emergent from re-settling after every step).
+ *   E2  tiles below CLIMB into vacated space live during a drag; after the
+ *       gesture ends there is NO memory (a later gesture re-resolves fresh).
+ *   E3  same-size side-by-side tiles SWAP cleanly, no oscillation.
+ *   E4b a move ONTO a locked tile is REFUSED outright — the placeholder never
+ *       enters it. (The source reads as "skip below"; the live demo refuses.)
+ *   E4c grow→shrink taller: full restore — same mechanism as E1.
+ *
+ * Plus three user-review rules the prototype rounds added:
+ *   S1  a swap exchanges CELLS exactly — never "the probe cell" (that left a
+ *       one-column overlap when the probe straddled the neighbour's edge).
+ *   S2  displaced tiles remember their gesture-start cell and TELEPORT home
+ *       when it frees — even from below a pinned row, which gravity alone can
+ *       never climb back through. This is a deliberate improvement over
+ *       gridstack itself. Memory clears at gesture end (E2).
+ *   S3  gridstack's swap() has THREE shapes, not one: same size; same ROW +
+ *       equal height (different widths — exchange horizontal order, union
+ *       span preserved); same COLUMN + equal width. And the >50% anti-jitter
+ *       gate must measure swap-eligible pairs against the SMALLER tile, or a
+ *       4-wide can never displace an 8-wide and swapping is one-directional.
+ *
+ * The engine mutates ONLY the {x,y,w,h} cells of the items it is given. Pixel
+ * mapping (row height, margins, the fit/grow sizing modes), placeholders,
+ * ghosts and commands belong to the binder built on top (Phase 2) — this
+ * class must stay pure enough to drive from a table-driven spec.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GridPackEngine = void 0;
+class GridPackEngine {
+    /** Live column count. Change it only through {@link setColumns}. */
+    get columns() {
+        return this._columns;
+    }
+    constructor(items = [], options = {}) {
+        var _a, _b;
+        this.items = [];
+        /** Per-gesture displaced-tile memory (S2/E2). Item id → gesture-start cell. */
+        this.memory = new Map();
+        /** Gesture-start snapshot of EVERY item, for cancel/Escape restore. */
+        this.snapshot = null;
+        /**
+         * S4 — swap hysteresis. An accepted swap LOCKS the pair for the rest of the
+         * gesture: the same two tiles may swap again only on a DELIBERATE return —
+         * the mover's probe centre reaching the partner's centre. Without this, a
+         * slow sweep of a small tile across a big one ping-pongs: the row swap
+         * drops the mover at the row edge, far from the cursor, so the very next
+         * cell crossing still covers the partner and instantly swaps back (found
+         * by driving the REAL demo board with a real mouse — synthetic step sizes
+         * jumped past it). Same-size pairs land ON the probe cell, which is why
+         * the recorded E3 never showed the defect; the lock's inclusive-midpoint
+         * return keeps the S1 wiggle (swap, retreat, swap again) intact.
+         */
+        this.swapLock = null;
+        /**
+         * THE PER-COLUMN LAYOUT CACHE (gridstack's `_layouts`). Column count → the
+         * layout the board had at that count. Written on the way OUT of a column
+         * count, read on the way BACK IN, so 12 → 1 → 12 round-trips losslessly
+         * instead of re-deriving a squashed 12 from the phone stack.
+         */
+        this.layouts = new Map();
+        /**
+         * What the last column change ASSIGNED each item. It is the only way to
+         * tell a user edit made at the narrow count from a value the column change
+         * itself derived — an edit propagates into the wider cached layouts, a
+         * derived value must not (or every visit to 1 column would flatten the
+         * desktop layout to full-width tiles).
+         */
+        this.assigned = new Map();
+        /** Re-entrancy guard: the column change's own writes never propagate. */
+        this.inColumnChange = false;
+        this._columns = (_a = options.columns) !== null && _a !== void 0 ? _a : 12;
+        this.float = (_b = options.float) !== null && _b !== void 0 ? _b : false;
+        this.maxRows = options.maxRows;
+        for (const it of items)
+            this.add(it);
+    }
+    /** Bound check + wholesale rollback — the maxRows enforcement primitive. */
+    cellsSnapshot() {
+        return new Map(this.items.map((i) => [i.id, { x: i.x, y: i.y, w: i.w, h: i.h }]));
+    }
+    restoreCells(snap) {
+        for (const it of this.items) {
+            const s = snap.get(it.id);
+            if (s) {
+                it.x = s.x;
+                it.y = s.y;
+                it.w = s.w;
+                it.h = s.h;
+            }
+        }
+    }
+    /**
+     * Accept the op that just mutated the board — unless the settled result
+     * exceeds `maxRows`, in which case the whole op rolls back and is refused.
+     * (Trial-run-then-commit, the same shape gridstack uses for maxRow grids.)
+     */
+    acceptWithinBound(pre) {
+        if (this.maxRows !== undefined && this.rows() > this.maxRows) {
+            this.restoreCells(pre);
+            return { changed: false };
+        }
+        this.propagateToCaches();
+        return { changed: true };
+    }
+    // -- introspection ---------------------------------------------------------
+    getItems() {
+        return this.items;
+    }
+    getItem(id) {
+        return this.items.find((i) => i.id === id);
+    }
+    /** Content height in rows: max(y+h) over all items (0 when empty). */
+    rows() {
+        return this.items.reduce((m, i) => Math.max(m, i.y + i.h), 0);
+    }
+    /** True when any two items overlap — the invariant every op must preserve. */
+    hasOverlaps() {
+        for (let i = 0; i < this.items.length; i++) {
+            for (let j = i + 1; j < this.items.length; j++) {
+                if (GridPackEngine.hit(this.items[i], this.items[j]))
+                    return true;
+            }
+        }
+        return false;
+    }
+    // -- membership ------------------------------------------------------------
+    /**
+     * Add an item. An explicit legal position is honoured verbatim. When the
+     * position collides — or the item asks for `autoPosition` — the tile
+     * AUTO-POSITIONS: a row-major scan for the first
+     * hole it fits, which is gridstack's `autoPosition` and NOT the same thing
+     * as gravity (gravity climbs one column; a hole at (3,0) under an occupied
+     * column is only reachable by the scan — the spec's first red proved it).
+     */
+    add(item) {
+        const it = Object.assign({}, item);
+        it.w = Math.max(1, Math.min(this._columns, it.w));
+        it.x = Math.max(0, Math.min(this._columns - it.w, it.x));
+        it.y = Math.max(0, it.y);
+        it.h = Math.max(1, it.h);
+        // A bounded board refuses an item that cannot fit at all.
+        if (this.maxRows !== undefined && it.h > this.maxRows)
+            return null;
+        const outOfBound = this.maxRows !== undefined && it.y + it.h > this.maxRows;
+        const auto = it.autoPosition === true || outOfBound || !!this.collide(it, it);
+        delete it.autoPosition;
+        if (auto) {
+            const yMax = this.maxRows !== undefined ? this.maxRows - it.h : Infinity;
+            let placed = false;
+            scan: for (let y = 0; y <= yMax; y++) {
+                for (let x = 0; x <= this._columns - it.w; x++) {
+                    const probe = Object.assign(Object.assign({}, it), { x, y });
+                    if (!this.collide(probe, it)) {
+                        it.x = x;
+                        it.y = y;
+                        placed = true;
+                        break scan;
+                    }
+                }
+                if (this.maxRows === undefined && y > this.rows() + it.h + 1)
+                    break; // safety net
+            }
+            if (!placed) {
+                // Unbounded boards always fit at the bottom; bounded ones refuse.
+                if (this.maxRows !== undefined)
+                    return null;
+                it.x = 0;
+                it.y = this.rows();
+            }
+        }
+        this.items.push(it);
+        this.settle(null);
+        this.propagateToCaches();
+        return it;
+    }
+    remove(id) {
+        const idx = this.items.findIndex((i) => i.id === id);
+        if (idx < 0)
+            return;
+        this.items.splice(idx, 1);
+        this.memory.delete(id);
+        this.settle(null);
+        this.propagateToCaches();
+    }
+    // -- gestures --------------------------------------------------------------
+    /**
+     * Begin a drag/resize gesture: fresh displaced-tile memory, and a full
+     * snapshot so `cancelGesture` (Escape) can restore every tile (gridstack
+     * `saveInitial` / `restoreInitial`).
+     */
+    beginGesture() {
+        this.memory.clear();
+        this.swapLock = null;
+        this.snapshot = new Map(this.items.map((i) => [i.id, { x: i.x, y: i.y }]));
+    }
+    /** End a gesture: memory does NOT outlive it (E2, and the S4 swap lock). */
+    endGesture() {
+        this.memory.clear();
+        this.swapLock = null;
+        this.snapshot = null;
+    }
+    /** Escape: restore every tile to its gesture-start cell. */
+    cancelGesture() {
+        if (this.snapshot) {
+            for (const it of this.items) {
+                const s = this.snapshot.get(it.id);
+                if (s) {
+                    it.x = s.x;
+                    it.y = s.y;
+                }
+            }
+        }
+        this.endGesture();
+    }
+    // -- the core: move --------------------------------------------------------
+    /**
+     * Try to put `id` at cell (x,y). Applies the full pipeline on acceptance:
+     * swap (three shapes) | push-down (+skip below locked) → settle (teleport
+     * memory + gravity). Refuses: out-of-gesture no-ops, cells intersecting a
+     * locked tile (E4b), and collisions under the anti-jitter coverage gate.
+     * `{ gate: false }` (see {@link MoveCheckOptions}) is first-placement mode:
+     * gate and swaps are skipped, push-down still applies, E4b still refuses.
+     */
+    moveCheck(id, x, y, options = {}) {
+        const n = this.getItem(id);
+        if (!n || n.locked)
+            return { changed: false };
+        x = Math.max(0, Math.min(this._columns - n.w, Math.round(x)));
+        y = Math.max(0, Math.round(y));
+        if (n.x === x && n.y === y)
+            return { changed: false };
+        const probe = Object.assign(Object.assign({}, n), { x, y });
+        if (this.collideLocked(probe, n))
+            return { changed: false }; // E4b: refuse
+        // maxRows: trial-run the whole op, roll back if the settled result spills.
+        const pre = this.cellsSnapshot();
+        const c = options.gate === false ? undefined : this.collide(probe, n);
+        if (c) {
+            // S3 — the three swap shapes.
+            const sameSize = !this.float && c.w === n.w && c.h === n.h;
+            const rowSwap = !this.float && !sameSize && c.h === n.h && c.y === n.y;
+            const colSwap = !this.float && !sameSize && c.w === n.w && c.x === n.x;
+            // Anti-jitter gate — gridstack's `directionCollideCoverage`: per axis,
+            // and ONLY along the side you approached from, how deep the mover has
+            // penetrated the STATIC tile as a fraction of that tile's extent; the
+            // tighter axis wins and must exceed 50%.
+            //
+            // This replaced an OVERLAP-AREA gate that was a mis-port: a 3x1 tile
+            // covers at most 3/16 of an 8x2 tile's area, so a small widget could
+            // never displace a big one however far you dragged it (live report:
+            // "Total Revenue can't be switched with Revenue vs Target"). Area also
+            // needed a min-area special case to let swaps fire in both directions;
+            // penetration is naturally symmetric and needs none.
+            if (GridPackEngine.penetration(n, probe, c) <= 0.5)
+                return { changed: false };
+            // S4: a just-swapped pair re-swaps only on a deliberate return.
+            if ((sameSize || rowSwap || colSwap) &&
+                this.swapLock &&
+                ((this.swapLock.a === n.id && this.swapLock.b === c.id) ||
+                    (this.swapLock.a === c.id && this.swapLock.b === n.id)) &&
+                !GridPackEngine.deliberateReturn(probe, n, c)) {
+                return { changed: false };
+            }
+            if (sameSize || rowSwap || colSwap)
+                this.remember(c);
+            if (sameSize) {
+                // S1: exchange CELLS exactly, never the probe cell.
+                const ox = n.x;
+                const oy = n.y;
+                n.x = c.x;
+                n.y = c.y;
+                c.x = ox;
+                c.y = oy;
+                this.swapLock = { a: n.id, b: c.id };
+                this.settle(n);
+                return this.acceptWithinBound(pre);
+            }
+            if (rowSwap) {
+                // Exchange horizontal ORDER, union span preserved:
+                // left(0..8)+right(8..12) → right-at-0(0..4)+left-at-4(4..12).
+                const leftX = Math.min(n.x, c.x);
+                if (n.x < c.x) {
+                    c.x = leftX;
+                    n.x = leftX + c.w;
+                }
+                else {
+                    n.x = leftX;
+                    c.x = leftX + n.w;
+                }
+                n.y = c.y;
+                this.swapLock = { a: n.id, b: c.id };
+                this.settle(n);
+                return this.acceptWithinBound(pre);
+            }
+            if (colSwap) {
+                const topY = Math.min(n.y, c.y);
+                if (n.y < c.y) {
+                    c.y = topY;
+                    n.y = topY + c.h;
+                }
+                else {
+                    n.y = topY;
+                    c.y = topY + n.h;
+                }
+                n.x = c.x;
+                this.swapLock = { a: n.id, b: c.id };
+                this.settle(n);
+                return this.acceptWithinBound(pre);
+            }
+        }
+        n.x = x;
+        n.y = y;
+        this.pushDown(n);
+        this.settle(n);
+        return this.acceptWithinBound(pre);
+    }
+    // -- the core: resize ------------------------------------------------------
+    /**
+     * Resize `id` to w×h cells. Growth is CLAMPED so the tile never covers a
+     * locked tile (E4b applied to size); displaced neighbours push + settle,
+     * and return when the size shrinks back (E1/S2).
+     */
+    resizeCheck(id, w, h) {
+        const n = this.getItem(id);
+        if (!n)
+            return { changed: false };
+        w = Math.max(1, Math.min(this._columns - n.x, Math.round(w)));
+        h = Math.max(1, Math.round(h));
+        // A bounded board clamps the tile's own height outright…
+        if (this.maxRows !== undefined)
+            h = Math.min(h, Math.max(1, this.maxRows - n.y));
+        while (w > n.w && this.collideLocked(Object.assign(Object.assign({}, n), { w }), n))
+            w--;
+        while (h > n.h && this.collideLocked(Object.assign(Object.assign({}, n), { h }), n))
+            h--;
+        if (w === n.w && h === n.h)
+            return { changed: false };
+        // …and rolls back wholesale when the PUSH spills a sibling past the bound.
+        const pre = this.cellsSnapshot();
+        n.w = w;
+        n.h = h;
+        this.pushDown(n);
+        this.settle(n);
+        return this.acceptWithinBound(pre);
+    }
+    // -- the core: responsive column count -------------------------------------
+    /**
+     * Change the board's COLUMN COUNT — gridstack's `column(n, layout)`, and the
+     * whole of responsive behaviour in one operation.
+     *
+     * Three things happen, in this order:
+     *
+     *  1. THE LAYOUT WE ARE LEAVING IS CACHED under its own column count. This
+     *     is the load-bearing step: without it, 12 → 1 → 12 would have to
+     *     re-derive twelve columns from a one-column stack and every tile would
+     *     come back full width.
+     *  2. GROWING RESTORES FROM THE CACHE, per item. Items the cache knows come
+     *     back at exactly the cells they had the last time the board was this
+     *     wide; items it does not know (added while narrow) fall through to the
+     *     scale rules below. Shrinking never restores — a narrower layout is
+     *     always derived from where the board is NOW, which is what makes a
+     *     gradual squeeze look natural.
+     *  3. THE REMAINDER IS SCALED by `layout` (see {@link GridColumnLayout}),
+     *     `columns === 1` forcing a single stack, and everything is re-placed in
+     *     reading order so the result cannot overlap.
+     *
+     * Returns true when the count actually changed.
+     */
+    setColumns(next, layout = 'moveScale') {
+        const n = Math.max(1, Math.round(next));
+        const prev = this._columns;
+        if (n === prev)
+            return false;
+        this.inColumnChange = true;
+        try {
+            // 1. cache the layout we are leaving, keyed by the count it belongs to.
+            this.cacheLayout(prev);
+            // 2. growing back: restore per item from the cache for the NEW count.
+            const restored = new Set();
+            const cached = n > prev ? this.layouts.get(n) : undefined;
+            if (cached) {
+                for (const it of this.items) {
+                    const c = cached.get(it.id);
+                    if (!c)
+                        continue;
+                    it.x = c.x;
+                    it.y = c.y;
+                    it.w = c.w;
+                    restored.add(it.id);
+                }
+            }
+            // 3. everything else follows the layout mode.
+            const ratio = n / prev;
+            const move = layout === 'move' || layout === 'moveScale';
+            const scale = layout === 'scale' || layout === 'moveScale';
+            // NOTE ON `columns === 1`: the phone layout (every tile x=0, w=1, one per
+            // row) needs no special case — the two clamps below already produce it in
+            // EVERY mode, since `min(1, w)` is 1 and `min(1 - 1, x)` is 0. An
+            // explicit `if (n === 1)` branch was written here first and no test could
+            // kill it (mutation-proved: deleting it changed nothing), so it is gone.
+            // The spec asserts the stack for all four modes instead.
+            for (const it of this.items) {
+                if (restored.has(it.id))
+                    continue;
+                const w = scale ? Math.max(1, Math.round(it.w * ratio)) : it.w;
+                it.w = Math.max(1, Math.min(n, w));
+                const x = move ? Math.round(it.x * ratio) : it.x;
+                it.x = Math.max(0, Math.min(n - it.w, x));
+            }
+            this._columns = n;
+            this.rePlace();
+            // Remember what THIS change assigned, so a later edit at the new count
+            // is distinguishable from a value the change itself derived.
+            this.assigned = new Map(this.items.map((i) => [i.id, { x: i.x, y: i.y, w: i.w }]));
+        }
+        finally {
+            this.inColumnChange = false;
+        }
+        return true;
+    }
+    /**
+     * The layout to PERSIST — gridstack's `save()`, which serialises from the
+     * LARGEST cached column count rather than the live one. Saving while the
+     * board is narrow (a phone) therefore saves the DESKTOP layout: the cells a
+     * user authored at full width are the document, and the narrow arrangement
+     * is a projection of it.
+     *
+     * `h` is never cached because it does not depend on the column count, so it
+     * always comes from the live item; items the widest cache does not know
+     * (added while narrow) contribute their live cells, which are legal at any
+     * count at least as wide.
+     */
+    saveLayout() {
+        let widest = this._columns;
+        for (const col of this.layouts.keys())
+            if (col > widest)
+                widest = col;
+        const cached = widest === this._columns ? undefined : this.layouts.get(widest);
+        return {
+            columns: widest,
+            items: this.items.map((it) => {
+                const c = cached === null || cached === void 0 ? void 0 : cached.get(it.id);
+                return c ? Object.assign(Object.assign({}, it), { x: c.x, y: c.y, w: c.w }) : Object.assign({}, it);
+            }),
+        };
+    }
+    /** The column counts the cache currently holds a layout for (ascending). */
+    cachedColumns() {
+        return [...this.layouts.keys()].sort((a, b) => a - b);
+    }
+    /** The cache as plain data — hand it to a rebuilt engine via {@link setLayouts}. */
+    getLayouts() {
+        const out = {};
+        for (const [col, entries] of this.layouts) {
+            const o = {};
+            for (const [id, c] of entries)
+                o[id] = Object.assign({}, c);
+            out[col] = o;
+        }
+        return out;
+    }
+    /**
+     * Adopt a cache exported by {@link getLayouts}. The kit calls this after
+     * rebuilding its engine from the model (`sync()`), which would otherwise
+     * throw the wider layouts away on every undo, add or refresh.
+     */
+    setLayouts(cache) {
+        var _a;
+        this.layouts = new Map();
+        for (const key of Object.keys(cache)) {
+            const col = Number(key);
+            if (!Number.isFinite(col) || col < 1)
+                continue;
+            const entries = new Map();
+            for (const [id, c] of Object.entries((_a = cache[col]) !== null && _a !== void 0 ? _a : {}))
+                entries.set(id, Object.assign({}, c));
+            this.layouts.set(col, entries);
+        }
+    }
+    /** Snapshot every item's x/y/w under `columns`. */
+    cacheLayout(columns) {
+        const entries = new Map();
+        for (const it of this.items)
+            entries.set(it.id, { x: it.x, y: it.y, w: it.w });
+        this.layouts.set(columns, entries);
+    }
+    /**
+     * Push an edit made at the LIVE column count into every WIDER (and narrower)
+     * cached layout, proportionally — so a widget re-arranged on a phone is
+     * still re-arranged when the desktop layout comes back.
+     *
+     *  - `y` always propagates verbatim: vertical order is column-independent,
+     *    and reordering is exactly what a user does on a narrow board.
+     *  - `x` and `w` propagate SCALED by cachedColumns/liveColumns, but only
+     *    when they differ from what the last column change assigned. That test
+     *    is what keeps a mere reorder at 1 column from rewriting every cached
+     *    width to full width (x=0,w=1 scaled by 12 would be x=0,w=12).
+     */
+    propagateToCaches() {
+        if (this.inColumnChange || this.layouts.size === 0)
+            return;
+        const cur = this._columns;
+        for (const [col, entries] of this.layouts) {
+            if (col === cur)
+                continue;
+            const ratio = col / cur;
+            for (const it of this.items) {
+                const e = entries.get(it.id);
+                if (!e)
+                    continue;
+                const a = this.assigned.get(it.id);
+                e.y = it.y;
+                if (!a || a.w !== it.w)
+                    e.w = Math.max(1, Math.min(col, Math.round(it.w * ratio)));
+                if (!a || a.x !== it.x)
+                    e.x = Math.round(it.x * ratio);
+                e.x = Math.max(0, Math.min(col - e.w, e.x));
+            }
+        }
+    }
+    /**
+     * Re-place every item in READING ORDER after a column change: clamp it to
+     * the new width, then let `add()` resolve collisions exactly as it does for
+     * any other placement (row-major first-hole scan, then gravity).
+     *
+     * Reading order — not gridstack's reverse order — is what keeps the visible
+     * sequence intact: at 12 → 6 four 3-wide tiles on one row must become two
+     * rows of two IN ORDER, and placing bottom-right-first scrambles them.
+     */
+    rePlace() {
+        const ordered = [...this.items].sort((a, b) => a.y - b.y || a.x - b.x);
+        this.items = [];
+        for (const it of ordered) {
+            if (this.add(it))
+                continue;
+            // A bounded board can refuse (maxRows). Never LOSE a tile to a column
+            // change: park it on a fresh row at the bottom instead.
+            this.items.push(Object.assign(Object.assign({}, it), { x: 0, y: this.rows() }));
+        }
+    }
+    // -- internals -------------------------------------------------------------
+    static hit(a, b) {
+        return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+    }
+    /**
+     * S4's return condition: on every axis where the pair's centres differ, the
+     * mover's PROBE centre must have reached (inclusive) the partner's centre
+     * from the mover's current side. Inclusive, so a same-size retreat onto the
+     * partner's exact cell (S1 wiggle) passes.
+     */
+    static deliberateReturn(probe, n, c) {
+        const probeCx = probe.x + n.w / 2;
+        const probeCy = probe.y + n.h / 2;
+        const curCx = n.x + n.w / 2;
+        const curCy = n.y + n.h / 2;
+        const cCx = c.x + c.w / 2;
+        const cCy = c.y + c.h / 2;
+        if (curCx !== cCx && !(curCx < cCx ? probeCx >= cCx : probeCx <= cCx))
+            return false;
+        if (curCy !== cCy && !(curCy < cCy ? probeCy >= cCy : probeCy <= cCy))
+            return false;
+        return true;
+    }
+    /**
+     * Directional penetration of `probe` into the static tile `c`, given the
+     * mover's pre-step cell `from` (which encodes the direction of travel).
+     * Returns the tighter of the two axes; an axis the move does not approach
+     * from is unconstrained (Infinity) and never decides.
+     */
+    static penetration(from, probe, c) {
+        let yOver = Infinity;
+        let xOver = Infinity;
+        if (from.y < c.y)
+            yOver = (probe.y + probe.h - c.y) / c.h; // entering from above
+        else if (from.y + from.h > c.y + c.h)
+            yOver = (c.y + c.h - probe.y) / c.h; // from below
+        if (from.x < c.x)
+            xOver = (probe.x + probe.w - c.x) / c.w; // from the left
+        else if (from.x + from.w > c.x + c.w)
+            xOver = (c.x + c.w - probe.x) / c.w; // from the right
+        return Math.min(xOver, yOver);
+    }
+    static overlapArea(a, b) {
+        const w = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x);
+        const h = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+        return Math.max(0, w) * Math.max(0, h);
+    }
+    collide(probe, self) {
+        return this.items.find((o) => o !== self && o.id !== self.id && GridPackEngine.hit(probe, o));
+    }
+    collideLocked(probe, self) {
+        return this.items.find((o) => o !== self && o.id !== self.id && !!o.locked && GridPackEngine.hit(probe, o));
+    }
+    remember(o) {
+        if (!this.memory.has(o.id))
+            this.memory.set(o.id, { x: o.x, y: o.y });
+    }
+    /** Sorted reading order — the deterministic iteration every rule uses. */
+    ordered() {
+        return [...this.items].sort((a, b) => a.y - b.y || a.x - b.x);
+    }
+    /**
+     * Displace whatever `placed` now covers: below the placed tile, then past
+     * any locked tile it lands on (gridstack `_skipDown` — without it a push
+     * cascade can bury the pinned row), recursively.
+     */
+    pushDown(placed) {
+        for (const o of this.ordered()) {
+            if (o === placed)
+                continue;
+            if (o.locked)
+                continue; // locked: never pushed
+            if (!GridPackEngine.hit(placed, o))
+                continue;
+            this.remember(o);
+            // A BOUNDED board displaces along the ROW first: in a one-row strip
+            // (the KPI section) "below" always spills the bound, while shifting the
+            // sibling rightward into free columns is the legal arrangement — and
+            // the teleport-home memory undoes the shift when the space frees again.
+            if (this.maxRows !== undefined) {
+                const rightX = placed.x + placed.w;
+                const right = Object.assign(Object.assign({}, o), { x: rightX });
+                if (rightX + o.w <= this._columns && !this.collideLocked(right, o)) {
+                    o.x = rightX;
+                    this.pushDown(o);
+                    continue;
+                }
+            }
+            o.y = placed.y + placed.h;
+            let lk;
+            while ((lk = this.collideLocked(o, o)))
+                o.y = lk.y + lk.h;
+            this.pushDown(o);
+        }
+    }
+    /**
+     * The settle loop, run after EVERY accepted change: displaced tiles first
+     * try to TELEPORT back to their remembered gesture-start cell (works across
+     * a pinned row — S2), then gravity packs (each tile climbs while free).
+     * Loops until stable so one restore can cascade further restores; this is
+     * exactly why gridstack's E1 restore is emergent rather than special-cased.
+     */
+    settle(active) {
+        for (let guard = 0; guard < 4 * this.items.length + 8; guard++) {
+            let changed = false;
+            for (const n of this.ordered()) {
+                if (n.locked || n === active)
+                    continue;
+                const mem = this.memory.get(n.id);
+                if (mem && (n.x !== mem.x || n.y !== mem.y)) {
+                    const home = Object.assign(Object.assign({}, n), { x: mem.x, y: mem.y });
+                    if (!this.collide(home, n)) {
+                        n.x = mem.x;
+                        n.y = mem.y;
+                        changed = true;
+                        continue;
+                    }
+                }
+                if (!this.float) {
+                    while (n.y > 0 && !this.collide(Object.assign(Object.assign({}, n), { y: n.y - 1 }), n)) {
+                        n.y--;
+                        changed = true;
+                    }
+                }
+            }
+            if (!changed)
+                break;
+        }
+    }
+}
+exports.GridPackEngine = GridPackEngine;
+//# sourceMappingURL=grid-pack-engine.js.map