@dash-builder/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @dash-builder/core
+
+## 0.1.0
+
+### Minor Changes
+
+- 37f3acf: First public release: a dashboard grid where widgets flow into a fixed number of columns and can be dragged and resized, with four drop modes (insert, block, shrink, swap), drag handles, locked widgets, a row limit and a narrow (stacked) view. `@dash-builder/core` works on its own; `@dash-builder/angular` and `@dash-builder/react` wrap it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dash-builder contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @dash-builder/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A framework-free TypeScript dashboard grid. Widgets flow left to right into a fixed number of columns, wrap into rows, and can be dragged and resized. There are no free x/y coordinates: the layout is an ordered list, and the grid positions the widgets from it.
+
+## Install
+
+```sh
+pnpm add @dash-builder/core
+# or: npm install @dash-builder/core
+```
+
+The package is ESM-only (`"type": "module"`, no CommonJS build): use `import`, not `require`.
+
+## Usage
+
+The grid reads widgets from the DOM. Each direct child of the container that has a `data-grid-id` attribute is a widget, and its id must match an entry in `layout`.
+
+```html
+<div id="grid">
+  <div data-grid-id="a">Widget A</div>
+  <div data-grid-id="b"><span data-grid-handle>drag here</span> Widget B</div>
+  <div data-grid-id="c">Widget C</div>
+</div>
+```
+
+```ts
+import { createGrid } from '@dash-builder/core';
+import '@dash-builder/core/grid.css';
+import type { LayoutItem } from '@dash-builder/core';
+
+const save = (layout: LayoutItem[]) => localStorage.setItem('dashboard-layout', JSON.stringify(layout));
+
+const grid = createGrid(document.getElementById('grid')!, {
+  columns: 4,
+  layout: [
+    { id: 'a', w: 2, h: 2 },
+    { id: 'b', w: 1, h: 1 },
+    { id: 'c', w: 1, h: 1, locked: true },
+  ],
+  dropMode: 'insert',
+  onLayoutChange: (layout) => save(layout),
+});
+```
+
+### DOM contract
+
+- Widgets are direct children of the container with a `data-grid-id` attribute. The first element with a given id wins; later duplicates are hidden. Widgets without a layout entry are hidden.
+- A widget containing a `[data-grid-handle]` element can only be dragged by that element. Without one, the whole widget is the drag surface.
+- The controller scans the container on every render. After you add or remove widget elements yourself, call `grid.refresh()` so it binds new elements and releases removed ones.
+- The container gets the `dash-grid` class and `display: grid`; widgets get `dash-item`. Both are removed again by `destroy()`.
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `columns` | required | Number of columns. |
+| `layout` | required | Ordered list of `LayoutItem`s. |
+| `dropMode` | `'insert'` | `'insert'`, `'block'`, `'shrink'` or `'swap'`. |
+| `maxRows` | none | Refuse a drop, resize or `addItem` whose result needs more rows than both `maxRows` and the current layout (see below). |
+| `rowHeight` | `80` | Row height in px. |
+| `gap` | `8` | Gap between widgets in px. |
+| `breakpoint` | `640` | Container width in px below which the narrow view is used. |
+| `onLayoutChange` | none | Called with a copy of the layout after a drop, a resize, `addItem`, `removeItem`, or when `setOptions({ columns })` changes widths. |
+| `onReject` | none | Called with a `RejectReason` when `addItem` is refused. |
+| `ghost` | sanitized clone | `(el: HTMLElement) => HTMLElement`: builds the element that follows the pointer during a drag. The grid adds the `dash-ghost` class, sizes and positions it, appends it to `body` and removes it on drop. |
+
+The default ghost is a deep clone of the widget with every `id` attribute removed, `name` removed from radio inputs (so the clone can't steal the original's checked state), each `iframe`, `video` and `audio` replaced by an empty box of the same rendered size (no reload, no second playback), and each `canvas` given a copy of the original's pixels (left blank if the canvas can't be read, for example when it is tainted). Pass `ghost` when you want something lighter, such as a plain box with a title.
+
+### Controller
+
+```ts
+grid.setLayout(layout);           // replace the layout (no onLayoutChange); a no-op if it equals the current one
+grid.setOptions({ dropMode: 'swap' }); // change options at runtime (any option except layout, including callbacks and ghost)
+grid.addItem({ id: 'd', w: 1, h: 1 }, index?); // returns { ok: true, layout } or { ok: false, reason }
+grid.removeItem('d');
+grid.getLayout();                 // a copy of the current layout
+grid.refresh();                   // re-scan the DOM and re-render
+grid.destroy();                   // remove listeners, classes and inline styles
+```
+
+Notes:
+
+- `addItem` only inserts into the layout. Create the element with its `data-grid-id` and append it to the container before calling `addItem`; remove it again if the result is not `ok`. For `removeItem`, call it first, then remove the element and call `refresh()`.
+- `addItem` and `removeItem` cancel an active drag or resize. So does `setLayout`, but only when the new layout differs from the current one after normalizing (an equal layout changes nothing, and a temporary narrow-view order is kept). `setOptions` cancels only when `columns`, `dropMode`, `maxRows`, `breakpoint`, `rowHeight` or `gap` actually changes value; changing callbacks or `ghost`, or passing equal values, never interrupts the user.
+- `addItem(item, index)` may shift a locked widget's index. Locks constrain the user's drags, not your own calls; the same goes for `removeItem` and `setLayout`.
+- `setLayout` (and `createGrid`) normalize the layout silently: widths are clamped to `[minW, columns]`, heights to at least `minH`, sizes are truncated to integers, non-finite values become their minimum, and `minW` and `minH` below 1 are raised to 1. The normalized layout is not emitted; you see it in `getLayout()` and in the next `onLayoutChange`.
+- `setOptions({ columns })` re-normalizes widths to the new column count and calls `onLayoutChange` if that changed any width.
+- After `destroy()`, `setLayout`, `setOptions`, `addItem` (returns `{ ok: false, reason: 'invalid' }`), `removeItem` and `refresh` do nothing; `getLayout()` still returns a copy of the last layout and `destroy()` can be called again safely.
+- `onLayoutChange` is the only notification of change. Treat it as the source of truth for saving state.
+
+## Layout JSON
+
+```ts
+interface LayoutItem {
+  id: string;       // matches data-grid-id
+  w: number;        // width in columns, clamped to [minW ?? 1, columns]
+  h: number;        // height in rows, at least minH ?? 1
+  minW?: number;
+  minH?: number;
+  locked?: boolean; // cannot be dragged or resized, and stays pinned to its index in the order
+}
+```
+
+```json
+[
+  { "id": "a", "w": 2, "h": 2 },
+  { "id": "b", "w": 1, "h": 1, "minW": 1 },
+  { "id": "c", "w": 1, "h": 1, "locked": true }
+]
+```
+
+The array order is the flow order: items fill each row left to right and wrap when the next one does not fit.
+
+## Drop modes
+
+- `insert`: the dragged widget is inserted at the target position and everything after it moves on.
+- `block`: the drop is refused if it would change which widgets share a row. The rows are compared two ways, and either one is enough: as you see them now (the dragged widget still in place), and as they would be with the dragged widget's old spot closed up. So moving a widget within its own row is always allowed, and so is a move whose gap the following widgets refill without changing rows.
+- `shrink`: the widgets of the row the marker is on are narrowed (nearest first, down to their `minW`) to make room. The drop is refused if they cannot fit, or if shrinking would move any widget into a different row (for example a narrowed neighbour jumping onto the row above). Rows are judged the same two ways as in block, the rows as you see them first, so moving a widget within its own row never narrows anything when it fits. Dropping a widget that starts a row onto the end of the previous row narrows that row to take it. Resizing in this mode: narrowing a widget behaves like insert (later widgets may move up); only a resize that narrows neighbours checks that the other rows keep their members.
+- `swap`: the dragged widget trades places with the widget it is dropped on.
+
+Locked widgets are pinned to their index in the list; unlocked widgets reorder freely around them. In insert, block and shrink mode you can drop a widget on the other side of a locked one: the dragged widget takes its place among the unlocked widgets, and the unlocked widgets fill the slots the locked ones leave free. For example, with `[a, L, b]` and `L` locked, dragging `a` to the end gives `[b, L, a]`. Marker: next to a locked widget it shows where the dragged widget will actually land (right after the widget that ends up before it), not where the pointer is. Pointing between a locked widget and the widget being dragged can map back to the dragged widget's own slot; that drop changes nothing. Block and shrink still apply their row rules to the result (block: every other widget stays in its row, though it may change sides of a locked widget within the row; shrink: the widget must land in the marker's row). In shrink mode this means a drop next to a locked widget can be refused: when pinning the locked widget pushes the dragged one onto the next row, it no longer lands in the marker's row. A locked widget can't be dragged, and in swap mode it can't be swapped with. With `maxRows`, a drop, resize or `addItem` is refused when the result needs more rows than both `maxRows` and the current layout. A layout that is already taller than `maxRows` (for example after lowering it) can still be rearranged as long as it doesn't grow. Refused drops show the marker in the blocked colour and change nothing. Nothing else moves during a drag: only a marker (or, in swap mode, an outline on the target) shows where the widget will land, and `onLayoutChange` fires once on drop.
+
+The engine is also exported for use without the DOM: `planDrop`, `planResize`, `addItem`, `removeItem`, `normalizeLayout`, `layoutsEqual`, `computeFlow`, `rowsOf`, `totalRows`, `stackForNarrow`, and the types `LayoutItem`, `PlacedItem`, `DropMode`, `EngineConfig`, `DropTarget`, `RejectReason` and `DropResult`.
+
+`planDrop` takes a `DropTarget`: `{ swapWith: id }` in swap mode, otherwise `{ index, after? }`, where `index` is the position in the list without the dragged widget. Set `after: true` when the marker is drawn after a widget (its right half, the empty space beside it, or the end of the list): shrink mode then makes room in the row of the widget before `index` rather than the one at `index`. Insert and block ignore `after`.
+
+## Interaction
+
+- Mouse: press on the widget (or its handle) and move to drag. Resize with the corner handle (`.dash-resize-handle`) at the bottom right of unlocked widgets.
+- Touch: a widget with a `[data-grid-handle]` drags immediately from the handle. A widget without one needs a 400 ms long-press before it drags, so normal scrolling still works. Resize handles start at once.
+- Form controls (`input`, `textarea`, `select`, `button`, `label`, links with `href`, editable text) inside a widget without a `[data-grid-handle]` never start a drag, so they stay usable. Add `data-grid-no-drag` to any other element to opt it out the same way. A `[data-grid-handle]` that is itself a `button` still drags. The widget root itself being a link, `label` or `button` doesn't count (it still drags; put `data-grid-no-drag` on the root to opt the whole widget out). For a widget whose body is a form control or a label, add a `[data-grid-handle]`: that is the way to drag it.
+- Dragging or resizing near the top or bottom edge of the scrolling area scrolls it.
+- Escape cancels an active drag or resize.
+
+## Narrow view
+
+When the container is narrower than `breakpoint` (default 640 px) the grid switches to a single column: widgets are stacked, one per row, and resizing is disabled (the resize handles are hidden). Dragging still works, but reordering in the narrow view is temporary. It is a temporary display order that is cleared by `addItem`, `removeItem` or a `setLayout` that changes the layout; it never calls `onLayoutChange` or changes `getLayout()`, so the saved layout is untouched.
+
+## Styling
+
+Import `@dash-builder/core/grid.css` and override these CSS custom properties on the container. The exception is `--dash-ghost-opacity`: the ghost is appended to `body`, outside the container, so set that one on `:root` or `body`.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `--dash-marker-color` | `#3b82f6` | Drop marker, swap outline and resize preview. |
+| `--dash-marker-blocked-color` | `#ef4444` | Same, when the drop or resize is refused. |
+| `--dash-placeholder-border` | `2px dashed #94a3b8` | Border of the placeholder left at the origin during a drag. |
+| `--dash-ghost-opacity` | `0.85` | Opacity of the widget following the pointer. Set on `:root` or `body`. |
+
+The controller sets `--dash-columns`, `--dash-row-height` and `--dash-gap` on the container from its options; do not set these yourself.
+
+## Development
+
+```sh
+pnpm build        # tsc + copy grid.css into dist/
+pnpm test         # unit tests
+pnpm test:smoke   # builds, then imports the built package in Node and checks its exports
+```
+
+`examples/vanilla.html` is a manual smoke page. Serve the repository root (for example `npx serve .`) and open `/packages/core/examples/vanilla.html` after building.
+
+## License
+
+MIT

package/dist/dom/autoscroll.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Px to scroll per frame for a pointer at `pointerY` in a scroll area spanning
+ * `top`..`bottom`: negative near the top, positive near the bottom, 0 elsewhere,
+ * growing linearly to ±max at the edge or beyond it.
+ */
+export declare function scrollStep(pointerY: number, top: number, bottom: number, zone?: number, max?: number): number;
+export interface AutoScroll {
+    /** Pointer position changed: start, retarget or end the scroll loop. */
+    move(clientY: number): void;
+    stop(): void;
+}
+/**
+ * While the pointer is within the edge zone of the scroll target, scrolls it once
+ * per animation frame and reports each step that actually moved (`onScroll(delta)`).
+ */
+export declare function createAutoScroll(container: HTMLElement, onScroll: (dy: number) => void): AutoScroll;

package/dist/dom/autoscroll.js

@@ -0,0 +1,83 @@
+// Edge autoscroll shared by the drag and resize interactions.
+const ZONE = 48; // px from the scroll area's top/bottom edge in which scrolling starts
+const MAX_STEP = 16; // px per frame at (or beyond) the edge
+/**
+ * Px to scroll per frame for a pointer at `pointerY` in a scroll area spanning
+ * `top`..`bottom`: negative near the top, positive near the bottom, 0 elsewhere,
+ * growing linearly to ±max at the edge or beyond it.
+ */
+export function scrollStep(pointerY, top, bottom, zone = ZONE, max = MAX_STEP) {
+    if (pointerY < top + zone)
+        return -max * Math.min(1, (top + zone - pointerY) / zone);
+    if (pointerY > bottom - zone)
+        return max * Math.min(1, (pointerY - (bottom - zone)) / zone);
+    return 0;
+}
+/** Nearest ancestor that scrolls vertically, else the document's scrolling element. */
+function findScroller(container) {
+    const view = container.ownerDocument.defaultView;
+    for (let node = container.parentElement; node; node = node.parentElement) {
+        const overflow = view?.getComputedStyle(node).overflowY;
+        if ((overflow === 'auto' || overflow === 'scroll') && node.scrollHeight > node.clientHeight)
+            return node;
+    }
+    return container.ownerDocument.scrollingElement;
+}
+/**
+ * While the pointer is within the edge zone of the scroll target, scrolls it once
+ * per animation frame and reports each step that actually moved (`onScroll(delta)`).
+ */
+export function createAutoScroll(container, onScroll) {
+    const doc = container.ownerDocument;
+    const target = findScroller(container);
+    let y = 0;
+    let frame = null;
+    function edges() {
+        if (!target || target === doc.scrollingElement)
+            return [0, doc.defaultView?.innerHeight ?? 0];
+        const r = target.getBoundingClientRect();
+        return [r.top, r.bottom];
+    }
+    /** The step for the current pointer, 0 when outside the zone or already at that end of the range. */
+    function pending() {
+        if (!target)
+            return 0;
+        const [top, bottom] = edges();
+        const step = scrollStep(y, top, bottom);
+        const max = Math.max(0, target.scrollHeight - target.clientHeight);
+        return (step < 0 && target.scrollTop <= 0) || (step > 0 && target.scrollTop >= max) ? 0 : step;
+    }
+    function tick() {
+        frame = null;
+        const step = pending();
+        if (!target || step === 0)
+            return; // the next move() restarts the loop
+        const before = target.scrollTop;
+        const max = Math.max(0, target.scrollHeight - target.clientHeight);
+        target.scrollTop = Math.min(max, Math.max(0, before + step));
+        const delta = target.scrollTop - before;
+        if (delta === 0)
+            return;
+        onScroll(delta);
+        request();
+    }
+    function request() {
+        const raf = globalThis.requestAnimationFrame;
+        if (frame === null && typeof raf === 'function')
+            frame = raf(tick);
+    }
+    function move(clientY) {
+        y = clientY;
+        if (pending() !== 0)
+            request();
+    }
+    function stop() {
+        if (frame === null)
+            return;
+        const caf = globalThis.cancelAnimationFrame;
+        if (typeof caf === 'function')
+            caf(frame);
+        frame = null;
+    }
+    return { move, stop };
+}

package/dist/dom/controller.d.ts

@@ -0,0 +1,28 @@
+import type { DropMode, DropResult, LayoutItem, RejectReason } from '../engine/types.js';
+export interface GridOptions {
+    columns: number;
+    layout: LayoutItem[];
+    dropMode?: DropMode;
+    maxRows?: number;
+    rowHeight?: number;
+    gap?: number;
+    breakpoint?: number;
+    onLayoutChange?: (layout: LayoutItem[]) => void;
+    onReject?: (reason: RejectReason) => void;
+    /**
+     * Builds the drag ghost from the widget element. The grid adds `dash-ghost`,
+     * positions and sizes it, appends it to body and removes it on drop. Default:
+     * a sanitized deep clone (see README).
+     */
+    ghost?: (el: HTMLElement) => HTMLElement;
+}
+export interface GridController {
+    setLayout(layout: LayoutItem[]): void;
+    setOptions(opts: Partial<Omit<GridOptions, 'layout'>>): void;
+    addItem(item: LayoutItem, index?: number): DropResult;
+    removeItem(id: string): void;
+    getLayout(): LayoutItem[];
+    refresh(): void;
+    destroy(): void;
+}
+export declare function createGrid(container: HTMLElement, options: GridOptions): GridController;

package/dist/dom/controller.js

@@ -0,0 +1,308 @@
+import { computeFlow, stackForNarrow } from '../engine/flow.js';
+import { addItem as engineAddItem, removeItem as engineRemoveItem } from '../engine/mutate.js';
+import { layoutsEqual, normalizeLayout } from '../engine/normalize.js';
+import { createDrag } from './drag.js';
+import { createResize } from './resize.js';
+const ID_ATTR = 'data-grid-id';
+/** Options the geometry or the drop rules depend on; changing one cancels an interaction. */
+const GEOMETRY_KEYS = ['columns', 'dropMode', 'maxRows', 'breakpoint', 'rowHeight', 'gap'];
+const DEFAULTS = { dropMode: 'insert', rowHeight: 80, gap: 8, breakpoint: 640 };
+const effective = (o, k) => o[k] ?? DEFAULTS[k];
+export function createGrid(container, options) {
+    const opts = { ...options };
+    let layout = normalizeLayout(opts.layout, opts.columns);
+    let narrow = false;
+    // Temporary narrow-view order (ids) from a narrow drag; never emitted, cleared by a setLayout that changes the layout.
+    let narrowOrder = null;
+    let destroyed = false;
+    const items = new Map(); // widgets currently managed, by id
+    const bound = new Map(); // element -> id it is bound under
+    const hiddenByUs = new Set();
+    const prevInline = {
+        display: container.style.display,
+    };
+    const marker = document.createElement('div');
+    marker.className = 'dash-marker';
+    marker.hidden = true;
+    container.classList.add('dash-grid');
+    container.style.display = 'grid';
+    container.appendChild(marker);
+    const config = () => ({ columns: opts.columns, maxRows: opts.maxRows, mode: opts.dropMode ?? 'insert' });
+    const emit = () => opts.onLayoutChange?.(layout.map((i) => ({ ...i })));
+    /** The layout in narrow-view order: the temporary order first, then items it doesn't know. */
+    function narrowList() {
+        if (!narrowOrder)
+            return layout;
+        const byId = new Map(layout.map((i) => [i.id, i]));
+        const ordered = narrowOrder.flatMap((id) => byId.get(id) ?? []);
+        const seen = new Set(ordered.map((i) => i.id));
+        return [...ordered, ...layout.filter((i) => !seen.has(i.id))];
+    }
+    // ---- interactions --------------------------------------------------------
+    function commit(next) {
+        layout = next;
+        render();
+        emit();
+    }
+    // Only one interaction at a time: each refuses to start while the other is active.
+    const drag = createDrag({
+        container,
+        marker,
+        items,
+        isNarrow: () => narrow,
+        getList: () => (narrow ? narrowList() : layout),
+        config,
+        commit,
+        setNarrowOrder(ids) {
+            narrowOrder = ids;
+            render();
+        },
+        isBusy: () => resize.isActive(),
+        ghost: () => opts.ghost,
+    });
+    const resize = createResize({
+        container,
+        items,
+        isNarrow: () => narrow,
+        getLayout: () => layout,
+        config,
+        metrics: () => ({ rowHeight: opts.rowHeight ?? 80, gap: opts.gap ?? 8 }),
+        commit,
+        isBusy: () => drag.isActive(),
+    });
+    // Cancel any active drag or resize. Called from setLayout (when the layout changes),
+    // setOptions (when a geometry option changes), addItem, removeItem and from render when the view flips between wide and narrow
+    // (destroy uses drag.destroy() / resize.destroy(), which also drop any pending click blocker).
+    function cancelInteraction() {
+        drag.cancel();
+        resize.cancel();
+    }
+    // Called once per element when it becomes managed (or is rebound under a new id).
+    function bindItem(el, id) {
+        drag.bind(el, id);
+    }
+    // Called when an element leaves the managed set or before it is rebound.
+    function unbindItem(el) {
+        drag.unbind(el);
+        resize.unbind(el);
+    }
+    // ---------------------------------------------------------------------------
+    function scan() {
+        const winners = new Map();
+        const dupes = [];
+        for (const child of Array.from(container.children)) {
+            const id = child.getAttribute(ID_ATTR);
+            if (id === null || !(child instanceof HTMLElement))
+                continue;
+            if (winners.has(id))
+                dupes.push(child); // first in DOM order wins
+            else
+                winners.set(id, child);
+        }
+        const winnerEls = new Set(winners.values());
+        // release elements no longer managed (removed, now a duplicate, or id attribute dropped)
+        for (const [node, id] of Array.from(bound)) {
+            if (!winnerEls.has(node)) {
+                unbindItem(node);
+                bound.delete(node);
+                clearItem(node);
+            }
+            else if (winners.get(id) !== node) {
+                unbindItem(node); // id attribute changed: rebound below under the new id
+                bound.delete(node);
+            }
+        }
+        for (const [id, node] of winners) {
+            if (bound.get(node) !== id) {
+                bound.set(node, id);
+                node.classList.add('dash-item');
+                bindItem(node, id);
+            }
+        }
+        items.clear();
+        for (const [id, node] of winners)
+            items.set(id, node);
+        for (const node of dupes)
+            hide(node);
+        // forget hidden-by-us elements that left the container
+        for (const node of Array.from(hiddenByUs))
+            if (node.parentElement !== container)
+                unhide(node);
+    }
+    function hide(node) {
+        if (!node.hidden) {
+            node.hidden = true;
+            hiddenByUs.add(node);
+        }
+    }
+    // Only un-hides what the controller hid; consumer-hidden elements stay hidden.
+    function unhide(node) {
+        if (hiddenByUs.delete(node))
+            node.hidden = false;
+    }
+    function clearItem(node) {
+        node.classList.remove('dash-item');
+        node.style.removeProperty('--dash-col');
+        node.style.removeProperty('--dash-row');
+        node.querySelector(':scope > .dash-resize-handle')?.remove();
+        unhide(node);
+    }
+    function measureNarrow() {
+        return container.clientWidth < (opts.breakpoint ?? 640);
+    }
+    function render() {
+        scan();
+        const nextNarrow = measureNarrow();
+        if (nextNarrow !== narrow)
+            cancelInteraction(); // axis and drop config differ between views
+        narrow = nextNarrow;
+        container.classList.toggle('dash-grid--narrow', narrow);
+        container.style.setProperty('--dash-columns', String(narrow ? 1 : opts.columns));
+        container.style.setProperty('--dash-row-height', `${opts.rowHeight ?? 80}px`);
+        container.style.setProperty('--dash-gap', `${opts.gap ?? 8}px`);
+        const placed = narrow ? stackForNarrow(narrowList()) : computeFlow(layout, opts.columns);
+        const byId = new Map(placed.map((p) => [p.id, p]));
+        for (const [id, node] of items) {
+            const p = byId.get(id);
+            if (!p) {
+                hide(node);
+                node.style.removeProperty('--dash-col');
+                node.style.removeProperty('--dash-row');
+                node.querySelector(':scope > .dash-resize-handle')?.remove();
+                continue;
+            }
+            unhide(node);
+            node.style.setProperty('--dash-col', `${p.x + 1} / span ${p.w}`);
+            node.style.setProperty('--dash-row', `${p.y + 1} / span ${p.h}`);
+            const handle = node.querySelector(':scope > .dash-resize-handle');
+            if (p.locked) {
+                handle?.remove();
+            }
+            else if (!handle) {
+                const h = document.createElement('div');
+                h.className = 'dash-resize-handle';
+                h.style.touchAction = 'none'; // touch resize starts at once; no long-press, no page scroll
+                node.appendChild(h);
+            }
+        }
+        drag.sync(); // touch-action follows handles and lock state
+        // keep the marker last so it never interleaves with widgets
+        if (container.lastElementChild !== marker)
+            container.appendChild(marker);
+    }
+    let observer;
+    let frame = null; // pending narrow re-check
+    if (typeof ResizeObserver !== 'undefined') {
+        observer = new ResizeObserver(() => {
+            if (destroyed)
+                return;
+            // Rendering here changes the container size inside the observer callback, which the
+            // browser reports as "ResizeObserver loop completed with undelivered notifications".
+            // Defer to a frame instead (one at a time); render at once only without rAF.
+            if (typeof requestAnimationFrame === 'undefined') {
+                if (measureNarrow() !== narrow)
+                    render();
+                return;
+            }
+            if (frame !== null)
+                return;
+            frame = requestAnimationFrame(() => {
+                frame = null;
+                if (!destroyed && measureNarrow() !== narrow)
+                    render();
+            });
+        });
+        observer.observe(container);
+    }
+    render();
+    return {
+        setLayout(next) {
+            if (destroyed)
+                return;
+            const normalized = normalizeLayout(next, opts.columns);
+            if (layoutsEqual(normalized, layout))
+                return; // nothing changes: keep any interaction and the narrow order
+            cancelInteraction();
+            narrowOrder = null;
+            layout = normalized;
+            render();
+        },
+        setOptions(patch) {
+            if (destroyed)
+                return;
+            // Only a change to something the geometry or an in-flight plan depends on cancels.
+            const changed = GEOMETRY_KEYS.some((k) => k in patch && effective(patch, k) !== effective(opts, k));
+            Object.assign(opts, patch);
+            if (!changed)
+                return; // callbacks / equal values: nothing to re-render
+            cancelInteraction();
+            let layoutChanged = false;
+            if (patch.columns !== undefined) {
+                const next = normalizeLayout(layout, opts.columns);
+                layoutChanged = !layoutsEqual(layout, next);
+                layout = next;
+            }
+            render();
+            if (layoutChanged)
+                emit();
+        },
+        addItem(item, index) {
+            if (destroyed)
+                return { ok: false, reason: 'invalid' };
+            const result = engineAddItem(layout, config(), item, index);
+            if (result.ok) {
+                cancelInteraction(); // an in-flight plan was computed against the old list
+                narrowOrder = null;
+                layout = result.layout;
+                render();
+                emit();
+            }
+            else {
+                opts.onReject?.(result.reason);
+            }
+            return result;
+        },
+        removeItem(id) {
+            if (destroyed)
+                return;
+            const next = engineRemoveItem(layout, id);
+            if (next === layout)
+                return;
+            cancelInteraction(); // an in-flight plan was computed against the old list
+            narrowOrder = null;
+            layout = next;
+            render();
+            emit();
+        },
+        getLayout: () => layout.map((i) => ({ ...i })),
+        refresh() {
+            if (!destroyed)
+                render();
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            drag.destroy(); // like cancelInteraction, but leaves no click blocker behind
+            resize.destroy(); // also removes the delegated pointerdown listener
+            observer?.disconnect();
+            if (frame !== null) {
+                cancelAnimationFrame(frame);
+                frame = null;
+            }
+            for (const node of Array.from(bound.keys())) {
+                unbindItem(node);
+                clearItem(node);
+            }
+            for (const node of Array.from(hiddenByUs))
+                unhide(node);
+            bound.clear();
+            items.clear();
+            marker.remove();
+            container.classList.remove('dash-grid', 'dash-grid--narrow');
+            container.style.display = prevInline.display;
+            for (const p of ['--dash-columns', '--dash-row-height', '--dash-gap'])
+                container.style.removeProperty(p);
+        },
+    };
+}