Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

48.7 KB
Raw Blame
import { useState, useRef, useEffect, useLayoutEffect, useMemo, useCallback, memo } from 'react';
import { GripVertical, MoveDiagonal2, GripHorizontal, ChevronsDownUp } from 'lucide-react';
import {
  DndContext,
  KeyboardSensor,
  PointerSensor,
  closestCenter,
  useSensor,
  useSensors,
} from '@dnd-kit/core';
import {
  SortableContext,
  arrayMove,
  sortableKeyboardCoordinates,
  useSortable,
  verticalListSortingStrategy,
} from '@dnd-kit/sortable';
import { GRID_COLS, GRID_DEFAULT_H, WIDTH_TO_COLS, WIDGETS_BY_ID } from './widgetRegistry.jsx';
import useContainerWidth from '../../hooks/useContainerWidth';
import { dndTransformToCss } from '../../lib/dndTransform';

// Free-form 12-column grid with snap-to-column drag, resize, and
// content-sized cells that float up into whatever whitespace is above them.
//
// Items: [{ id, x, w, order, h?, fixedH? }]
//   - x:     0..11 (column origin, integer grid units)
//   - w:     1..12 (column span, integer grid units)
//   - order: 0..n  (reading/packing order — the ONLY vertical coordinate)
//   - h:     1..n  (row span, each row ROW_HEIGHT_PX tall — fallback only)
//   - fixedH: the user dragged a height onto this cell; honor `h` exactly
//
// ONE VERTICAL COORDINATE. Horizontal placement is declared (x/w); vertical
// placement is entirely owned by `packVertically`, which lays cells out in
// PIXELS. `order` says which cell packs first, and nothing else — there is no
// stored row position, no rectangle-collision pass, and no y-compaction. A
// gesture therefore never has to reconcile "where the cell says it is" with
// "where the cell is drawn," because only one of those exists.
//
// HEIGHT IS MEASURED, NOT DECLARED. A widget's card is only as tall as its
// content, so `h` is not the rendered height — it's the pre-measurement
// fallback (first paint, and what an older client reads out of a saved
// layout). Cells the user has explicitly resized carry `fixedH: true` and keep
// their declared height, clipping content the way the whole grid used to.
//
// The pack is what reclaims dead whitespace: each cell drops as high as it can
// go without landing on an already-placed cell that shares a column, so an
// 80px-tall card in a 5-row slot no longer reserves 400px and the cards below
// it float up through the gap.
//
// In edit mode each item exposes a top-right move handle and a bottom-right
// resize handle — plus, on a cell that's already pinned, a bottom-left
// auto-fit handle that hands the height back to the content. Pointer events
// power the two drags so the same handlers work for mouse and touch. Pointer
// capture isn't used because the drag math reads window-level coordinates
// regardless of which element the pointer crosses — the listener lives on
// `window` for the duration of the gesture.
//
// KEYBOARD RUNS THE SAME GESTURE (#7263). Both handles are also grab toggles:
// Enter/Space lifts the cell, the arrows step the ghost, Enter/Space drops it
// and Escape puts it back. There is deliberately no second placement path —
// `beginGesture` freezes the identical snapshot the pointer drag freezes,
// `stepGhost` snaps in the same units the pointer rounds to, and the commit
// goes through the same `applyGhost`. What differs is only where the next
// ghost comes from: a pixel delta, or one arrow press. That is what keeps the
// promise above (one vertical coordinate) intact — a keyboard step never
// introduces a coordinate space the pointer path doesn't already have.
//
// Below MOBILE_BREAKPOINT_PX the grid collapses to a single column, so x/w
// have nowhere to go — but ORDER still does. There, edit mode swaps the two
// grid handles for one reorder handle that sorts the stack via dnd-kit (the
// same PointerSensor/KeyboardSensor pairing as every other sortable list in
// the app); on drop the whole grid is re-flowed so its reading order matches
// the new stack order (`reflowToOrder`). The free-form 2-D drag stays
// hand-rolled — arbitrary grid placement isn't what a sortable list does —
// but the 1-D case is exactly dnd-kit's job, and going through it is what
// buys touch, keyboard, multi-pointer and edge auto-scroll for free.
//
// Drop policy after a move (`insertAtOrder`): the dragged cell is re-inserted
// into the reading sequence at the rank its dropped pixel position implies,
// and every cell is renumbered 0..n-1 from there. The live preview runs the
// same function on the same inputs, so what the drop lands on is exactly what
// was previewed — no compaction pass, no round-trip between coordinate spaces.

const ROW_HEIGHT_PX = 80;
const GAP_PX = 16;
const ROW_STEP_PX = ROW_HEIGHT_PX + GAP_PX;
const MIN_W = 2;
const MIN_H = 2;
// Floor applied to every cell in edit mode only. A widget that renders nothing
// collapses to zero out of view — which is the point — but a zero-height cell
// has nowhere to put the move/resize handles, so Arrange gives it enough room
// to grab.
const EDIT_MIN_HEIGHT_PX = 48;
// Mobile breakpoint: below this width the grid collapses to a single column
// stacked vertically. Free-form move/resize is off there — a phone has no
// room for positional editing — but drag-to-reorder is on (see above).
// Deliberately NOT exported: a caller that needs to know which affordance is
// live gets it from `onLayoutModeChange`, because this threshold is measured
// against the CONTAINER and re-deriving it outside would read the viewport.
const MOBILE_BREAKPOINT_PX = 640;
// Vertical slack, in pixels, within which two cells count as "the same row"
// when a move drag is deciding where the dragged cell lands in the sequence.
// Half a row: past that the cursor has clearly committed to above/below, and
// inside it the column (x) is what orders them — which is what makes dragging
// a card sideways past its row neighbour reorder the two.
//
// Must stay under EDIT_MIN_HEIGHT_PX + GAP_PX (the closest two stacked cells
// can ever be in edit mode, which is the only mode a drag runs in). Above
// that, two cells in the SAME column could read as "same row," and a cell
// whose column ties would then re-rank itself on a zero-distance click.
const SAME_ROW_PX = ROW_HEIGHT_PX / 2;

// One arrow press, in the units the gesture already snaps to: a column on the
// horizontal axis, and on the vertical axis one sequence rank (move) or one
// row step (resize). Signs follow the pointer drag rather than the visual
// metaphor — dragging DOWN grows a cell and pushes it later in the sequence,
// so ArrowDown does both too.
const ARROW_STEPS = {
  ArrowLeft: { axis: 'x', delta: -1 },
  ArrowRight: { axis: 'x', delta: 1 },
  ArrowUp: { axis: 'y', delta: -1 },
  ArrowDown: { axis: 'y', delta: 1 },
};

// Keys that lift and drop a handle. ' ' is what every browser still in scope
// reports; 'Spacebar' is legacy IE/Edge and costs one array entry.
const GRAB_KEYS = ['Enter', ' ', 'Spacebar'];

function clamp(value, min, max) {
  return Math.max(min, Math.min(max, value));
}

function getColWidth(containerWidth) {
  return (containerWidth - GAP_PX * (GRID_COLS - 1)) / GRID_COLS;
}

// Reading order: `order`, then column as a tiebreak. This is the order the
// single-column mobile stack renders in, the order `packVertically` consumes,
// and the order `reflowToOrder` renumbers. The x tiebreak only matters while a
// layout is momentarily sparse/duplicated (a widget appended by
// `reconcileGrid` before the next resequence) — a settled grid is dense.
function byReadingOrder(a, b) {
  return (a.order ?? 0) - (b.order ?? 0) || a.x - b.x;
}

// Renumber `order` densely from the current reading order. Every function that
// hands a grid back to the caller ends here, so the persisted sequence is
// always 0..n-1 with no gaps and no duplicates.
function resequence(items) {
  return [...items].sort(byReadingOrder).map((it, i) => ({ ...it, order: i }));
}

// Grid rows ↔ pixels. A span of `h` rows covers h row boxes plus the gaps
// between them; the inverse rounds so a measured height round-trips to the
// row count that renders closest to it.
export function rowsToPx(h) {
  return h * ROW_HEIGHT_PX + (h - 1) * GAP_PX;
}
export function pxToRows(px) {
  return Math.max(1, Math.round((px + GAP_PX) / ROW_STEP_PX));
}

// Rendered height of one cell. Auto-height cells (the default) are exactly as
// tall as they measured; `fixedH` cells keep the height the user dragged onto
// them. `h` is the fallback until the first measurement lands — which is also
// why every commit refreshes it (see `withMeasuredHeights`).
//
// Keyed on PRESENCE, not truthiness: a widget that renders nothing (several
// self-hide on empty data) measures a legitimate 0, and collapsing that into
// "not measured yet" would hand it back the whole declared slot — the exact
// dead band this grid exists to reclaim, in the one case where the reclaim is
// total.
export function itemHeightPx(item, heights = {}) {
  if (!item.fixedH && item.id in heights) return heights[item.id];
  return rowsToPx(item.h);
}

function shareColumns(a, b) {
  return !(a.x + a.w <= b.x || b.x + b.w <= a.x);
}

// Masonry float. Walk cells in reading order and drop each one as high as it
// will go without landing on an already-placed cell that shares a column.
// Returns Map<id, { top, height }> in pixels.
//
// This is the whole point of the auto-height grid: a card shorter than its
// slot no longer reserves the leftover rows, and whatever sits under it rises
// through the gap instead of leaving a band of dead space across the row.
// Reading order (not grid-array order) is what keeps the result stable — the
// caller must pass items already sorted by `byReadingOrder`.
// `minHeight` floors every cell — passed in edit mode so a widget that
// currently renders nothing still has something to grab the handles on.
export function packVertically(ordered, heights = {}, minHeight = 0) {
  const placed = [];
  const rects = new Map();
  for (const item of ordered) {
    const height = Math.max(minHeight, itemHeightPx(item, heights));
    let top = 0;
    for (const p of placed) {
      if (!shareColumns(item, p)) continue;
      top = Math.max(top, p.top + p.height + GAP_PX);
    }
    placed.push({ x: item.x, w: item.w, top, height });
    rects.set(item.id, { top, height });
  }
  return rects;
}

// Horizontal geometry — the only part still derived straight from grid units.
function columnRect(item, colWidth) {
  return {
    left: item.x * (colWidth + GAP_PX),
    width: item.w * colWidth + (item.w - 1) * GAP_PX,
  };
}

// Refresh each item's `h` from the height the pack actually gave it. `h` is
// only a fallback now (first paint, and what a client too old to know about
// `fixedH` renders), so it would rot without this — every commit goes through
// here to keep the next cold load opening at roughly the right size. It is
// also what makes a resize gesture start where the card is DRAWN: grabbing the
// handle on an auto-height cell would otherwise snap it to a stale row count
// before the pointer had moved.
function withMeasuredHeights(items, rects) {
  return items.map((it) => {
    const rect = rects.get(it.id);
    if (!rect) return { ...it };
    return { ...it, h: pxToRows(rect.height) };
  });
}

// Where a cell dragged to pixel `top` in column `x` lands in the reading
// sequence: the number of other cells that sort before it. Cells clearly above
// or below (more than half a row away) are ordered by pixel position; cells on
// the same row are ordered by column.
function rankAtPixel(items, rects, movedId, top, x) {
  let rank = 0;
  for (const it of items) {
    if (it.id === movedId) continue;
    const otherTop = rects.get(it.id)?.top ?? 0;
    const before = otherTop < top - SAME_ROW_PX
      || (otherTop <= top + SAME_ROW_PX && it.x < x);
    if (before) rank += 1;
  }
  return rank;
}

// Re-insert `movedId` into the reading sequence at `rank`, then renumber.
// Both the live drag preview and the drop commit call this with the same
// inputs, so the preview is the outcome rather than an approximation of it.
function insertAtOrder(items, movedId, rank) {
  const moved = items.find((it) => it.id === movedId);
  if (!moved) return resequence(items);
  const rest = [...items].filter((it) => it.id !== movedId).sort(byReadingOrder);
  const next = [...rest.slice(0, rank), moved, ...rest.slice(rank)];
  return next.map((it, i) => ({ ...it, order: i }));
}

// Has the gesture actually moved the cell? Compares everything a drag can
// change — the column pair, the fallback height, and the sequence position.
function samePlacement(a, b) {
  return a.x === b.x && a.w === b.w && a.h === b.h && a.order === b.order;
}

// Fold the in-flight ghost back into the baseline. A move re-inserts at the
// ghost's rank and renumbers; a resize touches only that cell's w/h, so the
// sequence is left alone. `pin` marks the cell `fixedH` — always true while a
// resize is in flight (the drag, not the content, defines the height for the
// duration of the gesture) but only true on drop if the height really changed.
function applyGhost(baseline, kind, ghost, pin) {
  const swapped = baseline.map((it) => (it.id === ghost.id
    ? { ...it, ...ghost, ...(pin ? { fixedH: true } : {}) }
    : it));
  return kind === 'resize'
    ? resequence(swapped)
    : insertAtOrder(swapped, ghost.id, ghost.order);
}

// Advance a keyboard gesture's ghost by one arrow press. The clamps are the
// SAME ones the pointer path applies to its rounded pixel delta — a move stays
// inside the 12 columns and inside the sequence, a resize keeps MIN_W/MIN_H
// and cannot run off the right edge — so the two gestures can never reach a
// placement the other couldn't.
//
// `count` is how many cells are in the sequence; the last rank is count-1
// because a move re-INSERTS the cell rather than adding one.
//
// A step that would leave the grid comes back as the same values, so the
// caller can compare placements and skip both the re-render and the
// announcement rather than narrating a press that did nothing.
//
// The one deliberate divergence from the drag: a horizontal move step leaves
// `order` alone, where the pointer path re-derives it from `rankAtPixel` on
// every frame (which is what makes dragging a card sideways past its row
// neighbour swap the two). Here ↑/↓ owns the sequence outright, so "change
// columns, keep my place in the reading order" is expressible — and a press
// never has a second, unasked-for effect the user can't see coming.
export function stepGhost(kind, ghost, key, count) {
  const step = ARROW_STEPS[key];
  if (!step) return ghost;
  if (kind === 'move') {
    return step.axis === 'x'
      ? { ...ghost, x: clamp(ghost.x + step.delta, 0, GRID_COLS - ghost.w) }
      : { ...ghost, order: clamp(ghost.order + step.delta, 0, Math.max(0, count - 1)) };
  }
  return step.axis === 'x'
    ? { ...ghost, w: clamp(ghost.w + step.delta, MIN_W, GRID_COLS - ghost.x) }
    // No ceiling, same as the drag: the pack owns vertical space, so a tall
    // cell costs page height and nothing else.
    : { ...ghost, h: Math.max(MIN_H, ghost.h + step.delta) };
}

// What a screen reader hears. The registry label, not the raw id, and 1-based
// numbers because they're read aloud to a human counting columns.
function widgetLabel(item) {
  return WIDGETS_BY_ID[item.id]?.label ?? item.id;
}

function describePlacement(kind, ghost, count) {
  return kind === 'move'
    ? `column ${ghost.x + 1} of ${GRID_COLS}, position ${ghost.order + 1} of ${count}`
    : `${ghost.w} of ${GRID_COLS} columns wide, ${ghost.h} rows tall`;
}

// Everything that differs between the three handles, on one row each. `kind`
// already discriminates them, so icon/size/placement hang off it rather than
// travelling as separate props.
const HANDLE_KINDS = {
  move: { label: 'Move', Icon: GripVertical, size: 14, className: 'top-1.5 right-1.5 p-1 cursor-move' },
  resize: { label: 'Resize', Icon: MoveDiagonal2, size: 14, className: 'bottom-1 right-1 p-1 cursor-se-resize' },
  // Only rendered on a cell whose height the user pinned — clicking it hands
  // the height back to the content so the cell can shrink and let its
  // neighbours float up again.
  'auto-height': {
    label: 'Auto-fit height',
    Icon: ChevronsDownUp,
    size: 14,
    className: 'bottom-1 left-1 p-1 cursor-pointer',
  },
  reorder: {
    label: 'Reorder',
    Icon: GripHorizontal,
    size: 18,
    // Fatter target than the desktop pair: this one is only ever hit by a thumb.
    className: 'top-1.5 right-1.5 p-2.5 cursor-grab active:cursor-grabbing',
  },
};

// Shared drag/resize/reorder handle. `handleProps` is how dnd-kit's sortable
// attributes + listeners reach the reorder variant; the two grid handles pass
// their own onPointerDown instead. `touchAction: 'none'` is what makes any of
// them work under a finger — without it the browser claims the pointer stream
// for scrolling.
//
// The two grid handles additionally pass `onKeyDown`/`grabbed`, which is what
// makes them toggle buttons rather than pointer-only affordances: `aria-pressed`
// is the idle/grabbed state, and the grid's live region narrates each step.
// `grabbed` stays undefined on the handles that are plain buttons (auto-fit) or
// already announce themselves through dnd-kit (reorder), so those keep their
// unpressed semantics.
function DragHandle({ kind, item, onPointerDown, onClick, onKeyDown, onBlur, grabbed, handleProps }) {
  const { label, Icon, size, className } = HANDLE_KINDS[kind];
  // The two states SWAP their surface/border/ink rather than layering a
  // grabbed set on top of the idle one: Tailwind emits utilities in its own
  // order, so `border-port-accent` and `border-port-border` in one class
  // string are decided by the stylesheet, not by which came last here — the
  // same trap `client/src/AGENTS.md` records for `inline-flex`.
  const stateClass = grabbed
    ? 'bg-port-accent/20 border-port-accent text-white ring-1 ring-port-accent'
    : 'bg-port-bg/90 border-port-border text-gray-300 hover:text-white hover:border-port-accent';
  return (
    <button
      type="button"
      onPointerDown={onPointerDown}
      onClick={onClick}
      onKeyDown={onKeyDown}
      onBlur={onBlur}
      aria-pressed={grabbed}
      // The registry label, not the raw id — this is read aloud.
      aria-label={`${label} ${widgetLabel(item)}`}
      className={`absolute z-20 border rounded ${stateClass} ${className}`}
      style={{ touchAction: 'none' }}
      {...handleProps}
    >
      <Icon size={size} aria-hidden="true" />
    </button>
  );
}

// Auto-place a new widget at the end of the reading sequence, left-aligned.
// Used when LayoutEditor adds a widget to a layout without specifying a
// position. The pack decides where "the end" actually renders.
function placeNewWidget(items, widgetId) {
  const meta = WIDGETS_BY_ID[widgetId];
  const w = WIDTH_TO_COLS[meta?.width] ?? 4;
  const h = meta?.defaultH ?? GRID_DEFAULT_H;
  const last = items.reduce((max, it) => Math.max(max, (it.order ?? 0) + 1), 0);
  return [...items, { id: widgetId, x: 0, w, h, order: last }];
}

// Row-flow items into the 12 columns following `orderedIds`, preserving
// each item's w/h and dropping anything not in the order. This is how a mobile
// reorder becomes a grid: the single-column stack has no columns to drop onto,
// so the new stack order is re-flowed into fresh x positions and a fresh
// sequence. Items that already sit in flow order (the common case) come back
// unchanged.
export function reflowToOrder(items, orderedIds = items.map((it) => it.id)) {
  const byId = new Map(items.map((it) => [it.id, it]));
  const flowed = [];
  let cursorX = 0;
  for (const id of orderedIds) {
    const item = byId.get(id);
    if (!item) continue;
    const w = Math.min(item.w, GRID_COLS);
    // Wrap to a fresh row when the widget no longer fits beside its
    // predecessor. There is no row COORDINATE to advance — the pack derives
    // the row from the sequence — only the column cursor to reset.
    if (cursorX + w > GRID_COLS) cursorX = 0;
    flowed.push({ ...item, x: cursorX, w, order: flowed.length });
    cursorX += w;
  }
  return flowed;
}

// Synthesize a row-flow grid from a plain widget id list. Mirrors the
// previous CSS-grid layout so unmigrated layouts open in the same visual
// arrangement they had before the grid feature shipped.
export function synthesizeGrid(widgetIds) {
  return reflowToOrder(widgetIds.flatMap((id) => {
    const meta = WIDGETS_BY_ID[id];
    if (!meta) return [];
    return [{ id, w: WIDTH_TO_COLS[meta.width] ?? 4, h: meta.defaultH ?? GRID_DEFAULT_H }];
  }));
}

// Reconcile a saved grid against the visible widget list. Adds positions for
// any widgets missing from the grid (auto-placed at the bottom) and drops
// grid entries whose widget is no longer in the layout (gated off, deleted,
// etc.). Keeps the renderer's input always coherent with what should display.
//
// `reorder` makes `visibleIds` authoritative for order as well as membership:
// the reconciled grid is re-flowed to that order. Only pass it when the caller
// KNOWS the list order is the edit (LayoutEditor's Move up/down — #4132).
// Inferring it by comparing `visibleIds` against `readingOrderIds(grid)` would
// be wrong: layouts arranged before `saveGridEdit` started syncing `widgets` to
// reading order can already disagree, so a rename or a widget toggle would
// silently re-pack a carefully arranged desktop layout.
export function reconcileGrid(grid, visibleIds, { reorder = false } = {}) {
  const visible = new Set(visibleIds);
  const present = new Set();
  let kept = [];
  for (const item of grid) {
    if (!visible.has(item.id)) continue;
    if (present.has(item.id)) continue;
    present.add(item.id);
    kept.push(item);
  }
  for (const id of visibleIds) {
    if (present.has(id)) continue;
    kept = placeNewWidget(kept, id);
  }
  // Either way the sequence comes back dense — `reflowToOrder` renumbers from
  // the list, and `resequence` closes the gaps that dropping entries leaves
  // (appending can also duplicate the last index) — so callers never have to
  // care.
  return reorder ? reflowToOrder(kept, visibleIds) : resequence(kept);
}

// Reading order of a grid — what the mobile stack shows, and what a layout's
// `widgets` array should agree with so LayoutEditor lists them as displayed.
export function readingOrderIds(grid) {
  return [...grid].sort(byReadingOrder).map((it) => it.id);
}

// One dashboard cell. Split out (and memoized) because every indicator tick of
// a drag re-renders the grid, and without this each tick would re-run
// `renderItem` for all ~12 widgets to move one card.
const GridCell = memo(function GridCell({
  item, isMobile, editable, sortable, left, top, width, height, autoHeight, isGridDragging,
  suppressTransition, onStartGridDrag, onHandleKeyDown, onHandleBlur, grabbedKind,
  onClearFixedHeight, onMeasure, renderItem,
}) {
  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
    id: item.id,
    disabled: !sortable,
  });
  const measureRef = useRef(null);

  // Two sources report this widget's natural height so the parent can pack
  // around it. Both skip the same two cases:
  //  - mobile, where the single-column stack measures at a totally different
  //    width and those numbers would be wrong for the desktop pack;
  //  - pinned, where the measured node is stretched to the declared height, so
  //    all it could publish is that height back — and the pack would then spend
  //    the frame after an unpin laying the cell out at its clipped size.
  //    Skipping leaves the last natural height in place, a far better guess.

  // (1) Post-commit, pre-paint — the AUTHORITATIVE one. It catches whatever
  // React just put in the cell (a lazy chunk resolving out of Suspense, a list
  // arriving) without depending on the observer having noticed. The observer
  // alone was racy: a widget whose content landed without a delivered resize
  // notification kept whatever it measured while it was still a skeleton, so
  // it packed — and clipped — at the wrong height. No dep array, so every
  // render re-measures; `onMeasure` bails on an unchanged value, so a settled
  // cell costs one read and one comparison.
  useLayoutEffect(() => {
    const node = measureRef.current;
    if (node && !isMobile && !item.fixedH) onMeasure(item.id, node.offsetHeight);
  });

  // (2) The observer covers what the commit pass can't see: growth with no
  // render of this cell at all — images and fonts loading, a widget's own
  // async DOM work, or a state change inside the memoized widget subtree.
  //
  // Published straight from the callback, same as `useContainerWidth`. There
  // is no feedback loop to defer around: the measured node's height comes from
  // its content, never from the cell height this publish goes on to set. An
  // rAF here is not just unnecessary, it's harmful — a frame in which the
  // pack is still using the old height is a frame in which this cell is drawn
  // shorter than its content and the one below it sits on top.
  useEffect(() => {
    const node = measureRef.current;
    if (!node || isMobile || item.fixedH) return undefined;
    // 0 is published like any other height — a widget that renders nothing
    // should occupy nothing. `itemHeightPx` keys on presence, so this is what
    // tells it apart from "not measured yet".
    const ro = new ResizeObserver(() => onMeasure(item.id, node.offsetHeight));
    ro.observe(node);
    return () => ro.disconnect();
  }, [isMobile, item.fixedH, item.id, onMeasure]);

  // Memoized so a cell that merely MOVED doesn't re-render its widget: every
  // measurement anywhere in the grid repacks, and without this each repack
  // would re-render the whole subtree of every cell it shifted.
  const content = useMemo(() => renderItem(item), [renderItem, item]);

  // The cell is ALWAYS laid out at exactly the height the pack gave it, even
  // when that height is auto-derived. Letting an auto cell size itself would
  // mean that any moment its content outgrew the last measurement — first
  // paint, a lazy chunk landing, a list arriving — it would overlap whatever
  // was packed beneath it. Clipping for one frame until the observer catches
  // up is the strictly better failure.
  const itemStyle = isMobile
    ? { transform: dndTransformToCss(transform), transition, opacity: isDragging ? 0.4 : undefined }
    : { left, top, width, height };
  const itemClass = isMobile
    ? 'w-full'
    : `absolute ${isGridDragging ? 'opacity-60' : ''} ${suppressTransition ? '' : 'transition-[left,top,width,height] duration-150'}`;
  const innerClass = isMobile
    ? 'relative'
    : `relative w-full h-full overflow-hidden rounded-xl ${editable ? 'ring-1 ring-port-border' : ''}`;

  return (
    <div ref={setNodeRef} data-widget-id={item.id} className={itemClass} style={itemStyle}>
      <div className={innerClass}>
        {/* Free of the cell's height so it reports what the widget WANTS, not
            what it currently gets — that number is the auto height. A pinned
            cell stretches its widget to fill instead (`h-full`), which is the
            one case where the declared height is the answer. `flow-root` keeps
            a widget root's margin from collapsing out of the measurement. */}
        <div ref={measureRef} className={autoHeight ? 'flow-root' : 'h-full flow-root'}>
          {content}
        </div>
        {editable && !isMobile && (
          <>
            <DragHandle
              kind="move"
              item={item}
              onPointerDown={(e) => onStartGridDrag(e, item, 'move')}
              onKeyDown={(e) => onHandleKeyDown(e, item, 'move')}
              onBlur={() => onHandleBlur(item, 'move')}
              grabbed={grabbedKind === 'move'}
            />
            <DragHandle
              kind="resize"
              item={item}
              onPointerDown={(e) => onStartGridDrag(e, item, 'resize')}
              onKeyDown={(e) => onHandleKeyDown(e, item, 'resize')}
              onBlur={() => onHandleBlur(item, 'resize')}
              grabbed={grabbedKind === 'resize'}
            />
            {item.fixedH && (
              <DragHandle kind="auto-height" item={item} onClick={() => onClearFixedHeight(item)} />
            )}
          </>
        )}
        {sortable && (
          <DragHandle kind="reorder" item={item} handleProps={{ ...attributes, ...listeners }} />
        )}
      </div>
    </div>
  );
});

export default function DashboardGrid({ items, editable, onChange, onLayoutModeChange, renderItem }) {
  const [containerRef, containerWidth] = useContainerWidth();
  // Drag state lives outside React when active to avoid a setState on every
  // pointermove (would spam re-renders of every widget). React only learns
  // about the new ghost when we call setDrag, throttled by RAF.
  //
  // `drag` is `{ kind, baseline, baseRects, ghost }`. `baseline` is the layout
  // as it stood when the gesture started with its `h` refreshed from the
  // measurement (see `withMeasuredHeights`), and `baseRects` the pixel rects
  // the pack had produced for it. Everything the drag reasons about — the
  // ghost's rank, the live preview, the committed grid — is relative to that
  // frozen snapshot, never to the live rects, which the preview itself moves.
  // `ghost` stays a plain grid item so the commit can spread it straight on.
  const dragRef = useRef(null);
  const [drag, setDrag] = useState(null);
  // Measured natural heights, px, keyed by widget id.
  const [heights, setHeights] = useState({});
  // What the grid's live region currently says. Only the keyboard gesture
  // writes it: a pointer drag is already visible to the person doing it, and
  // narrating 60 snaps a second would flood the speech queue.
  const [announcement, setAnnouncement] = useState('');

  const onMeasure = useCallback((id, px) => {
    setHeights((prev) => (prev[id] === px ? prev : { ...prev, [id]: px }));
  }, []);

  const isMobile = containerWidth > 0 && containerWidth < MOBILE_BREAKPOINT_PX;
  // The mobile/desktop seam is measured off the CONTAINER, so a caller that
  // wants to describe the active affordance has to be told — a CSS `sm:`
  // breakpoint reads the viewport and disagrees on a padded page.
  useEffect(() => {
    if (containerWidth > 0) onLayoutModeChange?.(isMobile);
  }, [isMobile, containerWidth, onLayoutModeChange]);

  // Render in reading order always, not grid-array order: the mobile stack
  // depends on it, and on desktop it keeps DOM/tab order matching what the
  // eye sees. Keyed children survive reordering, so widget state is safe.
  const ordered = useMemo(() => [...items].sort(byReadingOrder), [items]);
  const orderedIds = useMemo(() => ordered.map((it) => it.id), [ordered]);

  // What the pack actually sees: the drag baseline with the item under the
  // cursor swapped for its snapped ghost, so every OTHER cell reflows live to
  // where it will land instead of waiting for the drop. A resize ghost packs
  // as a pinned cell — the drag is defining a height, so the preview must
  // show that height and not the content's. `applyGhost` is shared with the
  // drop commit, so the preview IS the outcome rather than a lookalike of it.
  const previewItems = useMemo(() => {
    if (!drag) return ordered;
    return applyGhost(drag.baseline, drag.kind, drag.ghost, drag.kind === 'resize');
  }, [ordered, drag]);

  const rects = useMemo(
    () => (isMobile ? new Map() : packVertically(previewItems, heights, editable ? EDIT_MIN_HEIGHT_PX : 0)),
    [isMobile, previewItems, heights, editable]
  );
  // Read by the drag handlers, which must not re-bind every time a widget
  // re-measures (that would churn every memoized cell mid-gesture).
  //
  // Held at the SETTLED pack while a gesture is live: `rects` packs
  // `previewItems`, which folds the ghost in. Both readers below want where the
  // cards really are, not where the preview is drawing them. A keyboard grab is
  // modal and stays open indefinitely, so a pointer drag on a sibling handle
  // (or a pin release) can land mid-gesture and would otherwise compute its
  // rank against displaced tops and commit a card to the wrong slot.
  const rectsRef = useRef(rects);
  if (!drag) rectsRef.current = rects;

  const containerHeight = useMemo(() => {
    let bottom = 0;
    for (const rect of rects.values()) bottom = Math.max(bottom, rect.top + rect.height);
    return bottom;
  }, [rects]);

  // Until every auto cell has reported a height, the pack is still running on
  // declared-row fallbacks — animating the correction would make every page
  // load open with a 150ms shuffle. Cells snap into place instead, and the
  // transition switches on for genuine edits afterwards.
  const settled = useMemo(
    // Presence again, not truthiness — a legitimately 0-tall widget has
    // reported, and gating on `> 0` would latch the transition off forever.
    () => ordered.every((it) => it.fixedH || it.id in heights),
    [ordered, heights]
  );

  // Freeze everything a gesture reasons about, whatever started it. The ghost
  // has to begin exactly where the card is DRAWN (grabbing the resize handle
  // on an auto-height cell would otherwise snap it to a stale row count before
  // the first step), and the rank math has to compare against positions the
  // preview isn't simultaneously shifting.
  const beginGesture = useCallback((item, kind) => {
    const baseRects = rectsRef.current;
    const baseline = withMeasuredHeights(items, baseRects);
    const found = baseline.find((it) => it.id === item.id) ?? item;
    // A resize gesture's floor applies to where it STARTS too. Without it, a
    // cell measuring under MIN_H rows (a widget rendering little or nothing)
    // has its height "changed" by the clamp alone — so a purely horizontal
    // drag would silently pin it.
    //
    // A move's start is expressed as the rank the cell ALREADY reads at, not
    // its stored `order`. The two can differ: the pack places in sequence, but
    // a cell sharing no column with any predecessor lands at the top anyway,
    // so a later `order` can be DRAWN above an earlier one. Comparing a
    // pixel-derived rank against a stored one there would "reorder" a card on
    // a plain click of the handle — a write with nothing behind it.
    const startTop = baseRects.get(item.id)?.top ?? 0;
    const startItem = kind === 'resize'
      ? { ...found, h: Math.max(MIN_H, found.h) }
      : { ...found, order: rankAtPixel(baseline, baseRects, item.id, startTop, found.x) };
    return { id: item.id, kind, baseline, baseRects, startTop, startItem, ghost: { ...startItem } };
  }, [items]);

  // Fold the gesture in `dragRef` back into the layout, then clear it. Shared
  // by the pointer drop and the keyboard commit so "what a gesture writes" has
  // exactly one definition; returns whether anything was actually written.
  const finishGesture = useCallback((commit) => {
    const gesture = dragRef.current;
    dragRef.current = null;
    setDrag(null);
    if (!gesture || !commit) return false;
    // Skip the write entirely when nothing actually changed — avoids a 200 OK
    // on every accidental click of the drag handle.
    if (samePlacement(gesture.startItem, gesture.ghost)) return false;
    // A resize that actually changed the HEIGHT is the user declaring one:
    // pin it. A width-only resize (or a move) leaves the cell auto-sized.
    const pins = gesture.kind === 'resize' && gesture.ghost.h !== gesture.startItem.h;
    onChange(applyGhost(gesture.baseline, gesture.kind, gesture.ghost, pins));
    return true;
  }, [onChange]);

  const startDrag = useCallback((e, item, kind) => {
    if (!editable || isMobile) return;
    // Prevent text selection mid-drag. preventDefault on the handle's
    // pointerdown is enough because the listener lives on window and we
    // never let the pointer leave the gesture.
    e.preventDefault();
    e.stopPropagation();
    const gesture = beginGesture(item, kind);
    dragRef.current = { ...gesture, startPointer: { x: e.clientX, y: e.clientY } };
    setDrag({ kind, baseline: gesture.baseline, baseRects: gesture.baseRects, ghost: { ...gesture.startItem } });
  }, [editable, isMobile, beginGesture]);

  // Enter/Space lifts a handle, the arrows step it, Enter/Space drops it and
  // Escape puts it back — the same state machine dnd-kit gives the mobile
  // reorder handle, so the two gestures feel like one feature.
  const handleKeyDown = useCallback((e, item, kind) => {
    if (!editable || isMobile) return;
    // A chord belongs to the browser or the app, not to this handle — ⌘←
    // navigates back, ⌥↑ jumps a paragraph. Only the bare key is a gesture.
    if (e.metaKey || e.ctrlKey || e.altKey) return;
    const gesture = dragRef.current;
    const grabbed = Boolean(gesture?.keyboard) && gesture.id === item.id && gesture.kind === kind;
    const count = items.length;

    if (GRAB_KEYS.includes(e.key)) {
      // Suppress the button's own activation: Enter/Space on a <button> would
      // otherwise fire a click straight after this, and the grab toggle would
      // cancel itself.
      e.preventDefault();
      e.stopPropagation();
      if (!grabbed) {
        const next = beginGesture(item, kind);
        dragRef.current = { ...next, keyboard: true };
        setDrag({ kind, keyboard: true, baseline: next.baseline, baseRects: next.baseRects, ghost: { ...next.startItem } });
        setAnnouncement(`${widgetLabel(item)} grabbed. ${describePlacement(kind, next.startItem, count)}. Use the arrow keys, then Enter to place or Escape to cancel.`);
        return;
      }
      const placed = finishGesture(true);
      setAnnouncement(`${widgetLabel(item)} ${kind === 'resize' ? 'resized' : 'placed'}. ${placed ? describePlacement(kind, gesture.ghost, count) : 'Unchanged'}.`);
      return;
    }

    if (!grabbed) return;

    if (e.key === 'Escape') {
      // Nothing was written, so dropping the gesture IS the restore — and the
      // stop keeps Escape from also leaving Arrange mode behind our back.
      e.preventDefault();
      e.stopPropagation();
      finishGesture(false);
      setAnnouncement(`${widgetLabel(item)} returned to its original position.`);
      return;
    }

    if (!ARROW_STEPS[e.key]) return;
    // Claim the arrow before the page scrolls under the grabbed cell.
    e.preventDefault();
    e.stopPropagation();
    const next = stepGhost(kind, gesture.ghost, e.key, count);
    // A step clamped at an edge changes nothing — say nothing and re-render
    // nothing rather than repeating the last position back at the user.
    if (samePlacement(gesture.ghost, next)) return;
    gesture.ghost = next;
    setDrag((prev) => (prev ? { ...prev, ghost: { ...next } } : prev));
    setAnnouncement(`${describePlacement(kind, next, count)}.`);
  }, [editable, isMobile, items, beginGesture, finishGesture]);

  // Tabbing (or clicking) away from a grabbed handle abandons the gesture
  // rather than leaving a ghost the user can no longer steer. Scoped to the
  // handle that actually holds the grab, so starting a POINTER drag on a
  // sibling handle — whose pointerdown lands before this blur — isn't undone
  // by it.
  const handleBlur = useCallback((item, kind) => {
    const gesture = dragRef.current;
    if (!gesture?.keyboard || gesture.id !== item.id || gesture.kind !== kind) return;
    finishGesture(false);
    setAnnouncement(`${widgetLabel(item)} returned to its original position.`);
  }, [finishGesture]);

  // A keyboard grab is modal, so it can still be open when the grid leaves the
  // mode that offers it — Save/Cancel on the Arrange toolbar, or a rotation
  // crossing the mobile breakpoint. The handles simply unmount, which fires no
  // blur, so without this the abandoned ghost keeps overriding the preview and
  // the grid goes on drawing a placement the user already cancelled.
  useEffect(() => {
    if (editable && !isMobile) return;
    if (dragRef.current) finishGesture(false);
  }, [editable, isMobile, finishGesture]);

  // The handle keeps focus while the cell travels under it, so the browser has
  // no focus change to scroll to — stepping a widget down a tall dashboard
  // would otherwise walk it past the fold with nothing to look at. `nearest`
  // is a no-op while the cell is already on screen. Keyboard only: a pointer
  // drag is anchored to a cursor the user can already see.
  useEffect(() => {
    if (!drag?.keyboard) return;
    containerRef.current
      ?.querySelector(`[data-widget-id="${drag.ghost.id}"]`)
      ?.scrollIntoView?.({ block: 'nearest' });
  }, [drag, containerRef]);

  useEffect(() => {
    // A keyboard grab drives itself from the handle's own keydown — installing
    // the window pointer listeners for it would let a click anywhere on the
    // page drop the cell.
    if (!drag || drag.keyboard) return undefined;
    const colWidth = getColWidth(containerWidth);
    // Both are fixed for the life of the gesture, and this effect re-installs
    // exactly when one starts — so capturing them here can't go stale, and the
    // per-snap `setDrag` doesn't have to re-bind the window listeners.
    const { kind, baseline, baseRects } = drag;
    let raf = 0;

    const onPointerMove = (e) => {
      const gesture = dragRef.current;
      if (!gesture) return;
      const dx = e.clientX - gesture.startPointer.x;
      const dy = e.clientY - gesture.startPointer.y;
      const colStep = colWidth + GAP_PX;
      const start = gesture.startItem;

      let next;
      if (kind === 'move') {
        const newX = Math.max(0, Math.min(GRID_COLS - start.w, Math.round(start.x + dx / colStep)));
        // Vertical is read straight off the pointer in pixels and turned into
        // a rank — there is no row coordinate to snap to, and the cursor and
        // the card therefore travel at the same speed.
        const top = gesture.startTop + dy;
        const order = rankAtPixel(baseline, baseRects, gesture.id, top, newX);
        next = { ...start, x: newX, order };
      } else {
        const newW = Math.max(MIN_W, Math.min(GRID_COLS - start.x, Math.round(start.w + dx / colStep)));
        const newH = Math.max(MIN_H, Math.round(start.h + dy / ROW_STEP_PX));
        next = { ...start, w: newW, h: newH };
      }
      // Snap dedup: pointermove fires at 200+ Hz, but `next` only changes
      // when the cursor crosses a snap boundary. Skip the React update
      // when we're still inside the same snap cell — saves ~60 widget
      // re-renders per drag and keeps the rAF callback a no-op.
      if (samePlacement(gesture.ghost, next)) return;
      gesture.ghost = next;
      if (!raf) {
        raf = requestAnimationFrame(() => {
          raf = 0;
          const ghost = dragRef.current?.ghost;
          if (ghost) setDrag((prev) => (prev ? { ...prev, ghost: { ...ghost } } : prev));
        });
      }
    };

    const finish = (commit) => {
      if (raf) { cancelAnimationFrame(raf); raf = 0; }
      finishGesture(commit);
    };

    const onPointerUp = () => finish(true);
    const onPointerCancel = () => finish(false);

    // Passive listeners — none of these handlers call preventDefault.
    // preventDefault on the pointerdown (in startDrag) is enough to suppress
    // text selection mid-drag.
    window.addEventListener('pointermove', onPointerMove, { passive: true });
    window.addEventListener('pointerup', onPointerUp, { passive: true });
    window.addEventListener('pointercancel', onPointerCancel, { passive: true });
    return () => {
      window.removeEventListener('pointermove', onPointerMove);
      window.removeEventListener('pointerup', onPointerUp);
      window.removeEventListener('pointercancel', onPointerCancel);
      if (raf) cancelAnimationFrame(raf);
    };
  // The mode key re-installs the listeners only when a POINTER gesture
  // starts/ends, never on a snap — pointermove writes dragRef.current
  // directly, and the `kind`/`baseline` captured above are gesture-constant.
  // A keyboard grab is its own mode, so switching between the two re-runs
  // this instead of leaving the wrong listeners bound.
  }, [drag ? (drag.keyboard ? 'keyboard' : 'pointer') : 'idle', finishGesture, containerWidth]);

  // A short activation distance keeps a tap on the handle from registering as
  // a drag; the keyboard sensor is what makes the handle usable without one.
  const sensors = useSensors(
    useSensor(PointerSensor, { activationConstraint: { distance: 8 } }),
    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
  );

  const onSortEnd = useCallback(({ active, over }) => {
    if (!over || active.id === over.id) return;
    const from = orderedIds.indexOf(active.id);
    const to = orderedIds.indexOf(over.id);
    if (from < 0 || to < 0) return;
    onChange(reflowToOrder(items, arrayMove(orderedIds, from, to)));
  }, [orderedIds, items, onChange]);

  // Hand a pinned cell's height back to its content. The cell re-renders
  // unconstrained, the observer reports its natural height, and the pack
  // closes the gap on the next frame.
  const clearFixedHeight = useCallback((item) => {
    const next = withMeasuredHeights(items, rectsRef.current).map((it) => {
      if (it.id !== item.id) return it;
      // Drop the pin by omission rather than whitelisting the fields to keep,
      // so a field added to the grid item later doesn't get eaten here.
      const { fixedH: _pinned, ...rest } = it;
      return rest;
    });
    onChange(resequence(next));
  }, [items, onChange]);

  const sortable = editable && isMobile;
  const colWidth = isMobile ? 0 : getColWidth(containerWidth);

  return (
    // DndContext/SortableContext render no DOM of their own, so they can wrap
    // unconditionally — which matters, because a conditional wrapper would
    // remount every widget on a breakpoint cross (see the note below).
    <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={onSortEnd}>
      <SortableContext items={orderedIds} strategy={verticalListSortingStrategy}>
        {/* Single render tree across mobile and desktop — only the
            className/style toggle. If we returned a different JSX shape per
            mode (separate mobile branch with shallower wrappers), React would
            unmount every widget on the breakpoint cross, wiping in-progress
            form input. Rotating an iPhone from portrait (~390px) to landscape
            (~844px) crosses MOBILE_BREAKPOINT_PX, so structural divergence
            here = "my Quick Capture text vanished when I rotated." Keep the
            wrapper depth identical and let CSS handle the rest. */}
        <div
          ref={containerRef}
          className={isMobile ? 'space-y-4' : 'relative w-full'}
          style={isMobile ? undefined : { height: containerWidth ? containerHeight : 'auto', minHeight: '4rem' }}
        >
          {ordered.map((item) => {
            const dragged = drag?.ghost.id === item.id;
            const rect = rects.get(item.id);
            const { left, width } = columnRect(dragged ? drag.ghost : item, colWidth);
            // A cell's height comes from its content unless it is pinned OR is
            // the one currently being resized (where the drag, not the content,
            // is defining the height).
            const pinned = item.fixedH || (dragged && drag.kind === 'resize');
            return (
              <GridCell
                key={item.id}
                item={item}
                isMobile={isMobile}
                editable={editable && containerWidth > 0}
                sortable={sortable}
                left={left}
                top={rect?.top ?? 0}
                width={width}
                height={rect?.height ?? rowsToPx(item.h)}
                autoHeight={!pinned}
                isGridDragging={!isMobile && dragged}
                suppressTransition={Boolean(drag) || !settled}
                onStartGridDrag={startDrag}
                onHandleKeyDown={handleKeyDown}
                onHandleBlur={handleBlur}
                grabbedKind={drag?.keyboard && drag.ghost.id === item.id ? drag.kind : null}
                onClearFixedHeight={clearFixedHeight}
                onMeasure={onMeasure}
                renderItem={renderItem}
              />
            );
          })}

          {/* Drop preview during the free-form drag — outline over the packed
              position the item will actually land in. Pointer-events:none so
              it never intercepts the gesture. */}
          {!isMobile && drag && containerWidth > 0 && rects.has(drag.ghost.id) && (
            <div
              className="absolute pointer-events-none border-2 border-dashed border-port-accent rounded-xl bg-port-accent/10 z-30"
              style={{ ...columnRect(drag.ghost, colWidth), ...rects.get(drag.ghost.id) }}
            />
          )}

          {/* Where a keyboard gesture narrates itself. The pointer drag is
              already visible to whoever is doing it; an arrow step is not, so
              this is the only feedback that says a press landed. `polite` so
              a fast run of arrow presses queues behind the current utterance
              instead of cutting it off. */}
          <div role="status" aria-live="polite" className="sr-only">{announcement}</div>
        </div>
      </SortableContext>
    </DndContext>
  );
}