@jarenjs/collection 0.85.0 → 0.87.0

package/dist/types/component/index.d.ts

@@ -562,6 +562,15 @@ export declare function mountCollection(host: HTMLElement, options: any): {
     element: HTMLDivElement;
     refresh: () => void;
     measureVisible: () => void;
+    /** Observe layout/disposal without placing resources in application state.
+     * @param {(event:any)=>void} fn */
+    subscribe(fn: (event: any) => void): () => void;
+    /** Add transient pins inside the existing shared row/column budgets.
+     * @param {()=>{rows:number[],columns:number[]}} read */
+    retain(read: () => {
+        rows: number[];
+        columns: number[];
+    }): () => void;
     update(next: any): void;
     scrollToOffset(offset: any): any;
     /** @param {number} index @param {number} [column] */
@@ -596,9 +605,16 @@ export declare function mountCollection(host: HTMLElement, options: any): {
         listeners: number;
         observers: number;
         frames: number;
+        subscribers: number;
+        retainers: number;
     };
     dispose: () => void;
 };
+export { mountCollectionDrag, createDraggableCollectionWidget } from './drag.js';
+export type DragContainer = import('./drag.js').DragContainer;
+export type CollectionDragOptions = import('./drag.js').CollectionDragOptions;
+/** @typedef {import('./drag.js').DragContainer} DragContainer */
+/** @typedef {import('./drag.js').CollectionDragOptions} CollectionDragOptions */
 /** Adapt controller disposal to the existing WidgetDef unmount lifecycle.
  * @param {any | ((props:any, emit:any)=>any)} options */
 export declare function createCollectionWidget(options: any | ((props: any, emit: any) => any)): {
@@ -1162,6 +1178,15 @@ export declare function createCollectionWidget(options: any | ((props: any, emit
             element: HTMLDivElement;
             refresh: () => void;
             measureVisible: () => void;
+            /** Observe layout/disposal without placing resources in application state.
+             * @param {(event:any)=>void} fn */
+            subscribe(fn: (event: any) => void): () => void;
+            /** Add transient pins inside the existing shared row/column budgets.
+             * @param {()=>{rows:number[],columns:number[]}} read */
+            retain(read: () => {
+                rows: number[];
+                columns: number[];
+            }): () => void;
             update(next: any): void;
             scrollToOffset(offset: any): any;
             /** @param {number} index @param {number} [column] */
@@ -1196,6 +1221,8 @@ export declare function createCollectionWidget(options: any | ((props: any, emit
                 listeners: number;
                 observers: number;
                 frames: number;
+                subscribers: number;
+                retainers: number;
             };
             dispose: () => void;
         };
@@ -1766,6 +1793,15 @@ export declare function mountProviderCollection(host: HTMLElement, coordinator:
         element: HTMLDivElement;
         refresh: () => void;
         measureVisible: () => void;
+        /** Observe layout/disposal without placing resources in application state.
+         * @param {(event:any)=>void} fn */
+        subscribe(fn: (event: any) => void): () => void;
+        /** Add transient pins inside the existing shared row/column budgets.
+         * @param {()=>{rows:number[],columns:number[]}} read */
+        retain(read: () => {
+            rows: number[];
+            columns: number[];
+        }): () => void;
         update(next: any): void;
         scrollToOffset(offset: any): any;
         /** @param {number} index @param {number} [column] */
@@ -1800,6 +1836,8 @@ export declare function mountProviderCollection(host: HTMLElement, coordinator:
             listeners: number;
             observers: number;
             frames: number;
+            subscribers: number;
+            retainers: number;
         };
         dispose: () => void;
     };

package/dist/types/drag.d.ts

@@ -0,0 +1,91 @@
+export type DragSource = {
+    key: string;
+    revision: string | number;
+};
+export type DragTarget = {
+    container: string;
+    key: string;
+    column: string;
+};
+export type DragIntent = {
+    source: DragSource;
+    target: DragTarget;
+    mode: 'move' | 'copy';
+};
+export type DragState = {
+    phase: 'idle' | 'armed' | 'dragging' | 'validating' | 'committing' | 'settled' | 'cancelled' | 'disposed';
+    source: DragSource | null;
+    target: DragTarget | null;
+    mode: 'move' | 'copy';
+    input: 'pointer' | 'touch' | 'keyboard' | null;
+    point: {
+        x: number;
+        y: number;
+    } | null;
+    reason: string | null;
+    generation: number;
+    pending: boolean;
+};
+export type DragOptions = {
+    resolveSource: (key: string) => DragSource | null | undefined;
+    validTarget: (target: DragTarget) => boolean;
+    validate?: (intent: DragIntent, context: {
+        signal: AbortSignal;
+    }) => boolean | Promise<boolean>;
+    commit: (intent: DragIntent, context: {
+        signal: AbortSignal;
+    }) => unknown | Promise<unknown>;
+    onChange?: (state: DragState) => void;
+    activationDistance?: number;
+};
+/** @typedef {{key:string, revision:string|number}} DragSource */
+/** @typedef {{container:string, key:string, column:string}} DragTarget */
+/** @typedef {{source:DragSource, target:DragTarget, mode:'move'|'copy'}} DragIntent */
+/** @typedef {{phase:'idle'|'armed'|'dragging'|'validating'|'committing'|'settled'|'cancelled'|'disposed',
+ * source:DragSource|null, target:DragTarget|null, mode:'move'|'copy', input:'pointer'|'touch'|'keyboard'|null,
+ * point:{x:number,y:number}|null, reason:string|null, generation:number, pending:boolean}} DragState */
+/** @typedef {{resolveSource:(key:string)=>DragSource|null|undefined,
+ * validTarget:(target:DragTarget)=>boolean,
+ * validate?:(intent:DragIntent, context:{signal:AbortSignal})=>boolean|Promise<boolean>,
+ * commit:(intent:DragIntent, context:{signal:AbortSignal})=>unknown|Promise<unknown>,
+ * onChange?:(state:DragState)=>void, activationDistance?:number}} DragOptions */
+/** Stable intent and one pending authority call; this engine never moves source data.
+ * @param {DragOptions} options */
+export declare function createDragInteraction(options: DragOptions): {
+    state: () => DragState;
+    cancel: (reason?: string) => DragState;
+    revalidate: () => DragState;
+    /** @param {string} key @param {{input?:'pointer'|'touch'|'keyboard', point?:{x:number,y:number}, copy?:boolean}} [request] */
+    begin(key: string, request?: {
+        input?: 'pointer' | 'touch' | 'keyboard';
+        point?: {
+            x: number;
+            y: number;
+        };
+        copy?: boolean;
+    }): DragState | {
+        phase: string;
+        reason: string;
+    };
+    /** @param {{x:number,y:number}} point @param {DragTarget|null} target @param {boolean} [copy] */
+    move(point: {
+        x: number;
+        y: number;
+    }, target: DragTarget | null, copy?: boolean): DragState;
+    drop(): Promise<DragState | {
+        phase: 'idle' | 'armed' | 'dragging' | 'validating' | 'committing' | 'settled' | 'cancelled' | 'disposed';
+        source: DragSource | null;
+        target: DragTarget | null;
+        mode: 'move' | 'copy';
+        input: 'pointer' | 'touch' | 'keyboard' | null;
+        point: {
+            x: number;
+            y: number;
+        } | null;
+        reason: string | null;
+        generation: number;
+        pending: boolean;
+        error: unknown;
+    }>;
+    dispose(): void;
+};

package/dist/types/index.d.ts

@@ -1,3 +1,14 @@
 /** Public headless collection geometry and vnode projection. */
 export { createCollection } from './collection.js';
 export { createCollectionInteraction } from './interaction.js';
+export { createDragInteraction } from './drag.js';
+export type DragState = import('./drag.js').DragState;
+export type DragSource = import('./drag.js').DragSource;
+export type DragTarget = import('./drag.js').DragTarget;
+export type DragIntent = import('./drag.js').DragIntent;
+export type DragOptions = import('./drag.js').DragOptions;
+/** @typedef {import('./drag.js').DragState} DragState */
+/** @typedef {import('./drag.js').DragSource} DragSource */
+/** @typedef {import('./drag.js').DragTarget} DragTarget */
+/** @typedef {import('./drag.js').DragIntent} DragIntent */
+/** @typedef {import('./drag.js').DragOptions} DragOptions */

package/docs/COLLECTION.md

@@ -108,3 +108,105 @@ reads mounted DOM. The source must advertise `completeExport`. See the normative
 
 Actual assistive technology, physical touch and native OS IME qualification remain
 separate from automated browser evidence; see [measurements](MEASUREMENTS.md).
+
+## Drag intent and authoritative commands
+
+`createDragInteraction` from `@jarenjs/collection` owns a single drag with a stable
+`source:{key,revision}`, `target:{container,key,column}` and `mode:'move'|'copy'`.
+Source revisions are finite numbers or strings; every target identity is a string.
+Indices and DOM objects never enter this intent. The engine requires
+`resolveSource(key)`, `validTarget(target)` and `commit(intent,{signal})`; an optional
+`validate(intent,{signal})` can check asynchronous permission before dispatch.
+
+`begin(key,{input,point,copy})` arms pointer/touch input and immediately activates
+keyboard input. Pointer movement must meet `activationDistance` before dragging.
+`move(point,target,copy)` changes only transient intent. `revalidate()` resolves
+current source revision and target availability; source changes or invalid targets
+cancel. `drop()` validates and then dispatches one command. Repeated drops do not
+dispatch again. Permission denial, a false command result or a rejected promise
+cancels without any optimistic source mutation. The authoritative host owns all
+policy, revision checks and actual movement.
+
+`state()` returns a detached serializable snapshot with phase, identity, point,
+generation and pending status. `cancel(reason)` and idempotent `dispose()` fence
+late replies and abort their signals. A cancelled asynchronous callback retains
+the single pending credit until it settles, so repeated cancellation cannot
+accumulate new authority calls on that engine. Cancellation after dispatch does
+not undo a server command: the host must honour the signal or reconcile its
+authoritative result. The engine never applies a late reply to source data.
+
+## Owned collection drag adapter
+
+`mountCollectionDrag(containers,options)` from `@jarenjs/collection/component`
+attaches to already-mounted collections. Each container supplies a unique `id`,
+its `mounted` handle, `columnKey(index)` and `indexOfColumn(key)`. Options supply
+the engine policy above and `locateSource(key) => {container,key,column}` for its
+current cell. `disabled(target)` may additionally reject a cell. Resolvers are
+synchronous and must be bounded; unloaded or unmounted targets are unavailable.
+
+```js
+import { mountCollectionDrag } from '@jarenjs/collection/component';
+
+const drag = mountCollectionDrag([{
+  id: 'catalog', mounted: grid,
+  columnKey: (index) => columns[index].id,
+  indexOfColumn: (key) => columnIndex.get(key) ?? -1
+}], {
+  resolveSource: (key) => records.get(key), // { key, revision }
+  locateSource: (key) => positions.get(key), // stable container/row/column keys
+  validTarget: (target) => permittedCells.has(target.key),
+  commit: (intent, { signal }) => commands.moveOrCopy(intent, { signal })
+});
+// A cell renderer supplies a dedicated, focusable handle:
+const handle = ['button', {
+  'data-jc-drag': record.key, style: { touchAction: 'none' }
+}, 'Move item'];
+// The owning widget or route disposes the adapter with its collections.
+drag.dispose();
+```
+
+Pointer input uses capture and client-coordinate hit testing. Touch activation
+requires a dedicated `data-jc-drag` handle whose computed `touch-action` is `none`;
+the remainder of the collection keeps ordinary browser scrolling. No global
+touch-scroll suppression or long-press heuristic is installed. Pointer coordinates
+come from actual cell rectangles, so nested scrolling, pinned headers, transforms
+and CSS zoom do not require storing logical indices as positions. A keyed DOM move
+can reacquire capture for the same connected source; actual capture loss cancels.
+
+Space or Enter on a focused handle starts keyboard dragging. Arrows resolve the
+next current row/column key; horizontal motion follows the collection direction.
+Tab switches containers, Alt selects copy, and Enter/Space drops. Escape cancels.
+Text controls and composition retain their native editing keys; Escape can cancel
+an active pointer drag when a text control still has focus, while composing input
+remains untouched. A polite status region announces target, result and cancellation.
+Focus returns to the original connected element, or a surviving collection if it
+was removed. Native OS IME and assistive-technology behaviour still need manual
+qualification; synthetic events do not establish those results.
+
+The overlay is text in an owned portal, outside the grid's clipped containers.
+It uses the browser top layer when popovers are available and otherwise a fixed
+positioned portal. A custom `portal` owns its own CSS coordinate context. Only
+one overlay and one animation frame belong to an adapter. Auto-scroll visits a
+bounded chain of scrollable ancestors, stops at limits and on cancellation, and
+re-resolves targets after movement. Existing row/column pin budgets include the
+drag source and focus together. A pin or DOM-credit refusal cancels the drag.
+
+`mounted.subscribe(listener)` observes layout, reset and disposal;
+`mounted.retain(() => ({rows,columns}))` contributes transient indices resolved
+from stable keys inside the same pin budget. Both return idempotent unsubscribe
+functions. These host resources stay outside app state. Their own finite admission
+limits refuse excess rather than silently keeping more listeners or pins.
+
+The drag handle exposes `interaction`, `cancel`, `update`, `stats` and idempotent
+`dispose`. `update` replaces authority callbacks; geometry, portal and scheduling
+ownership are fixed for a mount. Window blur, pointer cancellation, lost capture,
+source reset, removed source and collection disposal clear the gesture. Disposal
+attempts every acquired cleanup even if an observer throws. Stats count owned
+listeners, subscriptions, frames, overlays, status nodes and pending authority.
+
+`createDraggableCollectionWidget(options)` combines one collection and its drag
+adapter with the existing WidgetDef lifetime. Supply `id`, `collection`,
+`columnKey`, `indexOfColumn` and `drag`; a factory may derive them from props and
+the host emit callback. Updating props refreshes policy and collection state.
+A changed container identity requires a new widget key. Multi-container widgets
+own one `mountCollectionDrag` handle and dispose it before their mounted collections.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/collection",
   "private": false,
-  "version": "0.85.0",
+  "version": "0.87.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -52,8 +52,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.85.0",
-    "@jarenjs/view": "^0.85.0",
-    "@jarenjs/app": "^0.85.0"
+    "@jarenjs/core": "^0.87.0",
+    "@jarenjs/view": "^0.87.0",
+    "@jarenjs/app": "^0.87.0"
   }
 }

package/src/component/drag.js

@@ -0,0 +1,317 @@
+//@ts-check
+import { createDragInteraction } from '../drag.js';
+import { mountCollection } from './index.js';
+
+/** @typedef {import('../drag.js').DragTarget} DragTarget */
+/** @typedef {{id:string, mounted:ReturnType<typeof mountCollection>,
+ * columnKey:(index:number)=>string, indexOfColumn:(key:string)=>number}} DragContainer */
+/** @typedef {import('../drag.js').DragOptions & {
+ * locateSource:(key:string)=>DragTarget|null, disabled?:(target:DragTarget)=>boolean,
+ * label?:(key:string)=>string, portal?:HTMLElement, maxContainers?:number,
+ * edgeSize?:number, maxScrollPerFrame?:number,
+ * requestFrame?:(fn:FrameRequestCallback)=>number, cancelFrame?:(id:number)=>void
+ * }} CollectionDragOptions */
+
+/** Own sensors and an overlay across bounded, already-mounted collections.
+ * Touch starts only on handles marked data-jc-drag and styled touch-action:none.
+ * @param {DragContainer[]} containers @param {CollectionDragOptions} options */
+export function mountCollectionDrag(containers, options) {
+  const maxContainers = options.maxContainers ?? 8;
+  const edge = options.edgeSize ?? 32, speed = options.maxScrollPerFrame ?? 16;
+  if (!Number.isSafeInteger(maxContainers) || maxContainers < 1 || !containers.length || containers.length > maxContainers
+    || !Number.isFinite(edge) || edge <= 0 || !Number.isFinite(speed) || speed <= 0)
+    throw new RangeError('Invalid drag container or scroll credits');
+  const byId = new Map(containers.map((container) => [container.id, container]));
+  if (byId.size !== containers.length || containers.some((c) => typeof c.id !== 'string'
+    || typeof c.columnKey !== 'function' || typeof c.indexOfColumn !== 'function')) throw new TypeError('Drag containers need unique stable identities and column lookups');
+  const document = containers[0].mounted.element.ownerDocument, window = document.defaultView;
+  if (containers.some((c) => c.mounted.element.ownerDocument !== document)) throw new TypeError('Drag containers must share a document');
+  const portal = options.portal ?? document.documentElement;
+  const requestFrame = options.requestFrame ?? ((fn) => window.requestAnimationFrame(fn));
+  const cancelFrame = options.cancelFrame ?? ((id) => window.cancelAnimationFrame(id));
+  let disposed = false, frame = null, overlay = null, pointer = null, retained = null, focusBefore = null;
+  let lastPoint = null, copy = false, suppressedClick = null, announcement = '';
+  const stops = [];
+  const status = document.createElement('div');
+  status.setAttribute('role', 'status'); status.setAttribute('aria-live', 'polite'); status.setAttribute('aria-atomic', 'true');
+  Object.assign(status.style, { position: 'fixed', width: '1px', height: '1px', overflow: 'hidden', clipPath: 'inset(50%)' });
+  function location(target) {
+    const container = byId.get(target?.container);
+    if (!container || !container.mounted.element.isConnected) return null;
+    const config = container.mounted.controller.options();
+    const row = config.indexOf?.(target.key) ?? container.mounted.controller.layout().rows.find((r) => r.key === target.key)?.index;
+    const column = container.indexOfColumn(target.column);
+    if (!Number.isSafeInteger(row) || row < 0 || config.keyAt(row) !== target.key
+      || !Number.isSafeInteger(column) || column < 0 || column >= config.columnCount || container.columnKey(column) !== target.column) return null;
+    const cell = container.mounted.element.querySelector(`[data-row="${row}"] [data-column="${column}"]`);
+    return { container, row, column, cell };
+  }
+  const available = (target) => {
+    const found = location(target);
+    return !!found?.cell && !options.disabled?.(target) && (options.validTarget?.(target) ?? true);
+  };
+  const editing = (target) => !!target?.closest?.('input,textarea,select,[contenteditable]:not([contenteditable="false"])');
+  function cleanGesture() {
+    let failure;
+    const clean = (fn) => { try { fn(); } catch (error) { failure ??= error; } };
+    if (frame !== null) clean(() => cancelFrame(frame));
+    frame = null;
+    const capture = pointer; pointer = null;
+    clean(() => { if (capture?.element.hasPointerCapture?.(capture.id)) capture.element.releasePointerCapture(capture.id); });
+    const release = retained; retained = null; if (release) clean(release);
+    const priorOverlay = overlay; overlay = null; clean(() => priorOverlay?.remove());
+    if (focusBefore) {
+      const target = focusBefore; focusBefore = null;
+      clean(() => {
+        if (target.isConnected) target.focus({ preventScroll: true });
+        else containers.find((c) => c.mounted.element.isConnected)?.mounted.element.focus({ preventScroll: true });
+      });
+    }
+    if (failure) throw failure;
+  }
+  function changed(state) {
+    const active = ['dragging', 'validating', 'committing'].includes(state.phase);
+    if (active) {
+      if (!overlay) {
+        overlay = document.createElement('div'); overlay.setAttribute('data-jc-overlay', '');
+        overlay.setAttribute('aria-hidden', 'true');
+        Object.assign(overlay.style, { position: 'fixed', margin: '0', inset: 'auto', pointerEvents: 'none',
+          zIndex: '2147483647', padding: '8px', background: 'Canvas', color: 'CanvasText', border: '1px solid currentColor' });
+        portal.appendChild(overlay);
+        if (typeof overlay.showPopover === 'function') { overlay.setAttribute('popover', 'manual'); overlay.showPopover(); }
+      }
+      overlay.textContent = `${state.mode === 'copy' ? 'Copy' : 'Move'} ${options.label?.(state.source.key) ?? state.source.key}`;
+      overlay.style.left = `${state.point.x + 12}px`; overlay.style.top = `${state.point.y + 12}px`;
+    }
+    if (!['armed', 'dragging', 'validating', 'committing'].includes(state.phase)) cleanGesture();
+    if (!['armed', 'dragging'].includes(state.phase) && frame !== null) { cancelFrame(frame); frame = null; }
+    const message = state.phase === 'dragging' ? `${state.mode === 'copy' ? 'Copying' : 'Moving'} ${state.source.key}${state.target ? ` to ${state.target.key}, ${state.target.column}` : ''}. Enter to drop, Escape to cancel.`
+      : state.phase === 'settled' ? 'Drop accepted.' : state.phase === 'cancelled' ? `Drag cancelled: ${state.reason}.`
+        : state.phase === 'validating' || state.phase === 'committing' ? 'Checking drop.' : '';
+    if (message !== announcement) { announcement = message; status.textContent = message; }
+    options.onChange?.(state);
+  }
+  const interaction = createDragInteraction({ activationDistance: options.activationDistance,
+    resolveSource: (key) => options.resolveSource(key), validTarget: available,
+    validate: (intent, context) => options.validate?.(intent, context) ?? true,
+    commit: (intent, context) => options.commit(intent, context), onChange: changed });
+  function hit(point) {
+    const elements = document.elementsFromPoint(point.x, point.y).slice(0, 64);
+    for (const element of elements) {
+      const cell = element.closest?.('.jc-cell'), row = cell?.closest('.jc-row');
+      if (!cell || !row) continue;
+      const container = containers.find((c) => c.mounted.element.contains(cell));
+      if (!container) continue;
+      const key = row.getAttribute('data-key'), column = container.columnKey(Number(cell.getAttribute('data-column')));
+      if (typeof key !== 'string' || typeof column !== 'string') continue;
+      const target = { container: container.id, key, column };
+      return available(target) ? target : null;
+    }
+    return null;
+  }
+  function scroll(point) {
+    const container = containers.find((c) => {
+      const r = c.mounted.element.getBoundingClientRect();
+      return point.x >= r.left && point.x <= r.right && point.y >= r.top && point.y <= r.bottom;
+    });
+    let node = container?.mounted.element, xDone = false, yDone = false, moved = false;
+    for (let i = 0; node && i < 8; i++, node = node.parentElement) {
+      const r = node.getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) continue;
+      const delta = (v, low, high) => v < low + edge ? -speed : v > high - edge ? speed : 0;
+      const left = node.scrollLeft, top = node.scrollTop;
+      const maxX = Math.max(0, node.scrollWidth - node.clientWidth), maxY = Math.max(0, node.scrollHeight - node.clientHeight);
+      const style = window.getComputedStyle(node), rtl = style.direction === 'rtl';
+      const root = node === document.scrollingElement;
+      if (!xDone && maxX && (root || /auto|scroll/.test(style.overflowX))) node.scrollLeft = Math.max(rtl ? -maxX : 0, Math.min(rtl ? 0 : maxX,
+        left + delta(point.x, r.left, r.right) / Math.max(0.01, r.width / node.offsetWidth)));
+      if (!yDone && maxY && (root || /auto|scroll/.test(style.overflowY))) node.scrollTop = Math.max(0, Math.min(maxY,
+        top + delta(point.y, r.top, r.bottom) / Math.max(0.01, r.height / node.offsetHeight)));
+      xDone ||= node.scrollLeft !== left; yDone ||= node.scrollTop !== top;
+      moved ||= xDone || yDone;
+    }
+    if (moved) container?.mounted.refresh();
+  }
+  function tick() {
+    frame = null;
+    if (disposed || !['armed', 'dragging'].includes(interaction.revalidate().phase)) return;
+    if (!location(options.locateSource(interaction.state().source.key))?.cell) { interaction.cancel('source-unavailable'); return; }
+    if (lastPoint && interaction.state().input !== 'keyboard') {
+      if (interaction.state().phase === 'dragging') {
+        interaction.move(lastPoint, null, copy);
+        scroll(lastPoint);
+      }
+      interaction.move(lastPoint, hit(lastPoint), copy);
+    }
+    if (['armed', 'dragging'].includes(interaction.state().phase)) frame = requestFrame(tick);
+  }
+  function start(key, input, point, copyMode) {
+    const current = interaction.state();
+    if (current.pending || ['armed', 'dragging'].includes(current.phase)) return false;
+    const origin = options.locateSource(key), place = location(origin);
+    if (!place?.cell) return false;
+    focusBefore = document.activeElement; lastPoint = point; copy = copyMode;
+    try {
+      const started = interaction.begin(key, { input, point, copy: copyMode });
+      if (!['armed', 'dragging'].includes(started.phase)) { focusBefore = null; return false; }
+      retained = place.container.mounted.retain(() => {
+        const current = location(options.locateSource(key));
+        return current ? { rows: [current.row], columns: [current.column] } : { rows: [], columns: [] };
+      });
+      place.container.mounted.refresh();
+      if (!['armed', 'dragging'].includes(interaction.state().phase)) return false;
+      if (input === 'keyboard') interaction.move(point, origin, copyMode);
+      frame = requestFrame(tick); return true;
+    }
+    catch (error) {
+      try { interaction.cancel('activation-failed'); } finally { cleanGesture(); }
+      throw error;
+    }
+  }
+  function pointerdown(event) {
+    suppressedClick = null;
+    if (disposed || pointer || event.button !== 0 || !event.isPrimary || editing(event.target)) return;
+    const handle = event.target.closest?.('[data-jc-drag]');
+    if (!handle || !containers.some((c) => c.mounted.element.contains(handle))) return;
+    if (event.pointerType === 'touch' && window.getComputedStyle(handle).touchAction !== 'none') return;
+    if (start(handle.getAttribute('data-jc-drag'), event.pointerType === 'touch' ? 'touch' : 'pointer', { x: event.clientX, y: event.clientY }, event.altKey)) {
+      pointer = { id: event.pointerId, element: handle };
+      try { handle.setPointerCapture(event.pointerId); }
+      catch (error) { interaction.cancel('capture-failed'); throw error; }
+      if (event.pointerType === 'touch') event.preventDefault();
+    }
+  }
+  function pointermove(event) {
+    if (!pointer || pointer.id !== event.pointerId) return;
+    lastPoint = { x: event.clientX, y: event.clientY }; copy = event.altKey;
+    const next = interaction.move(lastPoint, hit(lastPoint), copy);
+    if (next.phase === 'dragging') event.preventDefault();
+  }
+  function pointerup(event) {
+    if (!pointer || pointer.id !== event.pointerId) return;
+    if (interaction.state().phase === 'dragging') {
+      event.preventDefault(); suppressedClick = { id: pointer.id, until: Date.now() + 300 };
+      const held = pointer; pointer = null;
+      if (held.element.hasPointerCapture(held.id)) held.element.releasePointerCapture(held.id);
+      void interaction.drop();
+    }
+    else interaction.cancel('not-activated');
+  }
+  function keydown(event) {
+    if (event.isComposing) return;
+    const current = interaction.state();
+    if (['armed', 'dragging', 'validating', 'committing'].includes(current.phase) && event.key === 'Escape') {
+      event.preventDefault(); event.stopImmediatePropagation(); interaction.cancel('escape'); return;
+    }
+    if (editing(event.target)) return;
+    if (['armed', 'dragging', 'validating', 'committing'].includes(current.phase)) {
+      if (event.key === 'Alt' && current.phase === 'dragging') {
+        copy = event.altKey; interaction.move(current.point, current.target, copy); return;
+      }
+      if (current.input !== 'keyboard' || current.phase !== 'dragging') return;
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault(); event.stopImmediatePropagation(); void interaction.drop(); return;
+      }
+      const place = location(current.target ?? options.locateSource(current.source.key));
+      if (!place || !['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Tab', 'Alt'].includes(event.key)) return;
+      event.preventDefault(); event.stopImmediatePropagation();
+      let container = place.container, row = place.row, column = place.column;
+      if (event.key === 'ArrowUp') row--;
+      if (event.key === 'ArrowDown') row++;
+      const direction = container.mounted.controller.options().direction === 'rtl' ? -1 : 1;
+      if (event.key === 'ArrowLeft') column -= direction;
+      if (event.key === 'ArrowRight') column += direction;
+      if (event.key === 'Tab') container = containers[(containers.indexOf(container) + (event.shiftKey ? containers.length - 1 : 1)) % containers.length];
+      const config = container.mounted.controller.options();
+      row = Math.max(0, Math.min(config.count - 1, row)); column = Math.max(0, Math.min(config.columnCount - 1, column));
+      container.mounted.scrollToIndex(row, column);
+      const target = { container: container.id, key: config.keyAt(row), column: container.columnKey(column) };
+      const rect = location(target)?.cell?.getBoundingClientRect();
+      if (rect) interaction.move({ x: rect.left, y: rect.top }, target, event.altKey);
+      return;
+    }
+    if (![' ', 'Enter'].includes(event.key)) return;
+    const handle = event.target.closest?.('[data-jc-drag]');
+    if (!handle || !containers.some((c) => c.mounted.element.contains(handle))) return;
+    const rect = handle.getBoundingClientRect();
+    if (start(handle.getAttribute('data-jc-drag'), 'keyboard', { x: rect.left, y: rect.top }, event.altKey)) {
+      event.preventDefault(); event.stopImmediatePropagation();
+    }
+  }
+  const listen = (node, name, fn, config = true) => {
+    node.addEventListener(name, fn, config); stops.push(() => node.removeEventListener(name, fn, config));
+  };
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    let failure;
+    const clean = (fn) => { try { fn(); } catch (error) { failure ??= error; } };
+    clean(() => interaction.dispose()); clean(cleanGesture);
+    for (const stop of stops.splice(0)) clean(stop);
+    clean(() => status.remove());
+    if (failure) throw failure;
+  }
+  try {
+    portal.appendChild(status);
+    listen(window, 'pointerdown', pointerdown);
+    listen(window, 'pointermove', pointermove, { capture: true, passive: false });
+    listen(window, 'pointerup', pointerup);
+    listen(window, 'pointercancel', (event) => { if (pointer?.id === event.pointerId) interaction.cancel('pointer-cancel'); });
+    listen(window, 'lostpointercapture', (event) => {
+      if (pointer?.id === event.pointerId && !pointer.element.hasPointerCapture(pointer.id)) interaction.cancel('capture-lost');
+    });
+    listen(window, 'blur', (event) => { if (event.target === window) interaction.cancel('blur'); });
+    listen(window, 'keydown', keydown);
+    listen(window, 'keyup', (event) => { if (event.key === 'Alt' && interaction.state().phase === 'dragging') {
+      const current = interaction.state(); copy = false; interaction.move(current.point, current.target, false);
+    } });
+    listen(window, 'click', (event) => {
+      if (suppressedClick && event.pointerId === suppressedClick.id && Date.now() < suppressedClick.until) {
+        suppressedClick = null; event.preventDefault(); event.stopImmediatePropagation();
+      }
+    });
+    for (const container of containers) stops.push(container.mounted.subscribe((event) => {
+      if (event.kind === 'dispose') { dispose(); return; }
+      if (event.kind === 'reset') interaction.cancel('source-reset');
+      else if (event.state !== 'ready') interaction.cancel(event.reason ?? 'collection-unavailable');
+      else if (interaction.state().phase !== 'committing') {
+        interaction.revalidate();
+        // A keyed DOM move can release capture while preserving the source.
+        // Reacquire only for the same connected handle and live pointer.
+        if (pointer?.element.isConnected && !pointer.element.hasPointerCapture(pointer.id)) pointer.element.setPointerCapture(pointer.id);
+      }
+    }));
+  }
+  catch (error) { dispose(); throw error; }
+  return { interaction, dispose, cancel: (reason = 'cancelled') => interaction.cancel(reason),
+    /** Update authority callbacks; geometry and resource owners belong to this mount.
+     * @param {Partial<CollectionDragOptions>} next */
+    update(next) { options = { ...options, ...next }; return interaction.revalidate(); },
+    stats: () => ({ listeners: disposed ? 0 : 9, subscriptions: disposed ? 0 : containers.length,
+      frames: frame === null ? 0 : 1, overlays: overlay ? 1 : 0, statusNodes: disposed ? 0 : 1,
+      pending: interaction.state().pending ? 1 : 0 }) };
+}
+
+/** One collection and its interaction share the existing WidgetDef lifetime.
+ * @param {any|((props:any,emit:any)=>any)} options */
+export function createDraggableCollectionWidget(options) {
+  const config = (props, emit) => typeof options === 'function' ? options(props, emit) : { ...options, ...props };
+  return {
+    mount(host, props, emit) {
+      const settings = config(props, emit), mounted = mountCollection(host, settings.collection);
+      try {
+        const container = { id: settings.id, mounted, columnKey: settings.columnKey, indexOfColumn: settings.indexOfColumn };
+        const drag = mountCollectionDrag([container], settings.drag);
+        return { mounted, drag, container, emit };
+      }
+      catch (error) { mounted.dispose(); throw error; }
+    },
+    update(handle, props) {
+      const settings = config(props, handle.emit);
+      if (settings.id !== handle.container.id) throw new TypeError('A different drag container requires a new widget key');
+      handle.container.columnKey = settings.columnKey; handle.container.indexOfColumn = settings.indexOfColumn;
+      handle.drag.update(settings.drag); handle.mounted.update(settings.collection);
+    },
+    unmount(handle) { try { handle.drag.dispose(); } finally { handle.mounted.dispose(); } },
+  };
+}