@grafloria/element 0.3.19 → 0.3.21

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

@@ -1,685 +0,0 @@
-"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