@nativedesktop/panes 0.1.2 → 0.2.0

package/src/tiles.test.ts

@@ -0,0 +1,262 @@
+import { describe, expect, test } from "bun:test";
+import {
+  applyTileDrop,
+  deserializeTiles,
+  emptyTiles,
+  findTile,
+  moveTile,
+  parseTileDrag,
+  placeTile,
+  raiseTile,
+  removeTile,
+  resizeTile,
+  seedTiles,
+  serializeTiles,
+  tileCellAt,
+  tileDragPayload,
+  tileRows,
+  updateTile,
+} from "./tiles.ts";
+import type { TileModel } from "./tiles.ts";
+
+const isString = (d: unknown): d is string => typeof d === "string";
+
+/** Two 2x2 tiles side by side on a 4-column grid, plus one below them. */
+function base(): TileModel<string> {
+  return seedTiles(
+    [
+      { x: 0, y: 0, w: 2, h: 2, data: "a" },
+      { x: 2, y: 0, w: 2, h: 2, data: "b" },
+      { x: 0, y: 2, w: 4, h: 1, data: "c" },
+    ],
+    4,
+  );
+}
+
+function boxes(m: TileModel<string>): string[] {
+  return m.tiles.map((t) => `${t.id}@${t.x},${t.y} ${t.w}x${t.h}`);
+}
+
+describe("placeTile", () => {
+  test("mints sequential ids and keeps what fits where it was asked for", () => {
+    expect(boxes(base())).toEqual(["1@0,0 2x2", "2@2,0 2x2", "3@0,2 4x1"]);
+    expect(base().nextId).toBe(4);
+  });
+
+  test("the new tile keeps its cells and pushes the occupant down", () => {
+    const m = placeTile(base(), { x: 0, y: 0, w: 4, h: 1, data: "d" });
+    expect(boxes(m)).toEqual(["1@0,1 2x2", "2@2,1 2x2", "3@0,3 4x1", "4@0,0 4x1"]);
+  });
+
+  test("cells are clamped to the grid and to whole rows and columns", () => {
+    const m = placeTile(emptyTiles<string>(4), { x: 9, y: -3, w: 99, h: 0.4, data: "a" });
+    expect(boxes(m)).toEqual(["1@0,0 4x1"]);
+    expect(boxes(placeTile(emptyTiles<string>(4), { x: 3, y: 0, w: 2, h: 1, data: "a" }))).toEqual(["1@2,0 2x1"]);
+    expect(boxes(placeTile(emptyTiles<string>(4), { x: NaN, y: NaN, w: NaN, h: NaN, data: "a" }))).toEqual([
+      "1@0,0 1x1",
+    ]);
+  });
+
+  test("an explicit id advances nextId past it; a duplicate id is a no-op", () => {
+    const m = placeTile(emptyTiles<string>(4), { id: "7", x: 0, y: 0, w: 1, h: 1, data: "a" });
+    expect(m.nextId).toBe(8);
+    expect(placeTile(m, { id: "7", x: 2, y: 0, w: 1, h: 1, data: "b" })).toBe(m);
+  });
+});
+
+describe("moveTile", () => {
+  test("pushes the tiles it lands on down, cascading", () => {
+    // "1" onto "2"'s cells: 2 goes below it, and c below that.
+    const m = moveTile(base(), "1", 2, 0);
+    expect(boxes(m)).toEqual(["1@2,0 2x2", "2@2,2 2x2", "3@0,4 4x1"]);
+  });
+
+  test("tiles that did not move keep their object identity", () => {
+    const m = base();
+    const moved = moveTile(m, "3", 0, 3);
+    expect(moved.tiles[0]).toBe(m.tiles[0]);
+    expect(moved.tiles[1]).toBe(m.tiles[1]);
+    expect(moved.tiles[2]).not.toBe(m.tiles[2]);
+  });
+
+  test("no upward compaction: a hole stays a hole", () => {
+    const m = removeTile(base(), "1");
+    expect(boxes(m)).toEqual(["2@2,0 2x2", "3@0,2 4x1"]);
+    expect(boxes(moveTile(m, "3", 0, 6))).toEqual(["2@2,0 2x2", "3@0,6 4x1"]);
+  });
+
+  test("same cells, unknown id and an out-of-range move that clamps back are same-reference", () => {
+    const m = base();
+    expect(moveTile(m, "1", 0, 0)).toBe(m);
+    expect(moveTile(m, "1", -5, -5)).toBe(m);
+    expect(moveTile(m, "zzz", 1, 1)).toBe(m);
+  });
+});
+
+describe("resizeTile", () => {
+  test("growing over a neighbour pushes it down", () => {
+    const m = resizeTile(base(), "1", 4, 2);
+    expect(boxes(m)).toEqual(["1@0,0 4x2", "2@2,2 2x2", "3@0,4 4x1"]);
+  });
+
+  test("a width past the grid edge pulls the tile back inside", () => {
+    expect(boxes(resizeTile(base(), "2", 4, 2))).toEqual(["1@0,2 2x2", "2@0,0 4x2", "3@0,4 4x1"]);
+  });
+
+  test("same size and unknown id are same-reference", () => {
+    const m = base();
+    expect(resizeTile(m, "1", 2, 2)).toBe(m);
+    expect(resizeTile(m, "1", 0.2, -4)).not.toBe(m); // clamps to 1x1, which is a change
+    expect(resizeTile(m, "zzz", 1, 1)).toBe(m);
+  });
+});
+
+describe("raiseTile", () => {
+  test("moves the tile last in layout order without moving any cells", () => {
+    const m = raiseTile(base(), "1");
+    expect(m.tiles.map((t) => t.id)).toEqual(["2", "3", "1"]);
+    expect(boxes(m).sort()).toEqual(boxes(base()).sort());
+  });
+
+  test("already last, or unknown, is same-reference", () => {
+    const m = base();
+    expect(raiseTile(m, "3")).toBe(m);
+    expect(raiseTile(m, "zzz")).toBe(m);
+  });
+});
+
+describe("removeTile / updateTile", () => {
+  test("removeTile drops the tile; unknown id is same-reference", () => {
+    const m = base();
+    expect(removeTile(m, "2").tiles.map((t) => t.id)).toEqual(["1", "3"]);
+    expect(removeTile(m, "zzz")).toBe(m);
+  });
+
+  test("updateTile replaces data; identical data is same-reference", () => {
+    const m = base();
+    const updated = updateTile(m, "1", (d) => `${d}!`);
+    expect(findTile(updated, "1")!.data).toBe("a!");
+    expect(updateTile(updated, "1", (d) => d)).toBe(updated);
+    expect(updateTile(updated, "zzz", (d) => d)).toBe(updated);
+  });
+});
+
+describe("serializeTiles / deserializeTiles", () => {
+  test("round-trips a layout through JSON", () => {
+    const m = raiseTile(moveTile(base(), "1", 2, 0), "3");
+    const back = deserializeTiles<string>(JSON.parse(JSON.stringify(serializeTiles(m))), 4, isString);
+    expect(back).toEqual(m);
+  });
+
+  test("serializeTiles is a deep copy, not a view of the live model", () => {
+    const m = base();
+    const snapshot = serializeTiles(m);
+    expect(boxes(moveTile(m, "1", 2, 0))[0]).toBe("1@2,0 2x2");
+    expect(findTile(snapshot, "1")).toEqual({ id: "1", x: 0, y: 0, w: 2, h: 2, data: "a" });
+  });
+
+  test("malformed input falls back to the empty layout on the given columns", () => {
+    const empty = emptyTiles<string>(6);
+    expect(deserializeTiles<string>(null, 6, isString)).toEqual(empty);
+    expect(deserializeTiles<string>({ tiles: "nope" }, 6, isString)).toEqual(empty);
+    expect(deserializeTiles<string>({ tiles: [{ x: 0, y: 0, w: 1, h: 1, data: "a" }] }, 6, isString)).toEqual(empty);
+    expect(deserializeTiles<string>({ tiles: [{ id: "1", x: "0", y: 0, w: 1, h: 1, data: "a" }] }, 6, isString)).toEqual(
+      empty,
+    );
+    expect(deserializeTiles<string>({ tiles: [{ id: "1", x: 0, y: 0, w: 1, h: 1, data: 42 }] }, 6, isString)).toEqual(
+      empty,
+    );
+  });
+
+  test("a duplicate id rejects the layout", () => {
+    const raw = {
+      columns: 4,
+      tiles: [
+        { id: "1", x: 0, y: 0, w: 1, h: 1, data: "a" },
+        { id: "1", x: 1, y: 0, w: 1, h: 1, data: "b" },
+      ],
+      nextId: 2,
+    };
+    expect(deserializeTiles<string>(raw, 4, isString)).toEqual(emptyTiles<string>(4));
+  });
+
+  test("a hand-edited overlapping layout is pushed apart on load, and nextId lands past every id", () => {
+    const raw = {
+      columns: 4,
+      tiles: [
+        { id: "1", x: 0, y: 0, w: 2, h: 2, data: "a" },
+        { id: "9", x: 0, y: 0, w: 2, h: 2, data: "b" },
+      ],
+      nextId: 1,
+    };
+    const m = deserializeTiles<string>(raw, 4, isString);
+    expect(boxes(m)).toEqual(["1@0,0 2x2", "9@0,2 2x2"]);
+    expect(m.nextId).toBe(10);
+  });
+});
+
+describe("tile drag payloads", () => {
+  test("round-trip, and anything foreign is not a tile drag", () => {
+    expect(parseTileDrag(tileDragPayload("3"))).toBe("3");
+    for (const foreign of ["", "3", "nd-tiles:tile:", "nd-dock:tab:3"]) {
+      expect(parseTileDrag(foreign)).toBeUndefined();
+    }
+  });
+});
+
+describe("tileCellAt", () => {
+  // base() occupies 4 columns and 3 rows, so a 400x300 grid is 100px cells.
+  const size = { width: 400, height: 300 };
+
+  test("a point maps to the cell it lands in", () => {
+    const m = base();
+    expect(tileRows(m)).toBe(3);
+    expect(tileCellAt(m, size, 0, 0)).toEqual({ column: 0, row: 0 });
+    expect(tileCellAt(m, size, 250, 150)).toEqual({ column: 2, row: 1 });
+    expect(tileCellAt(m, size, 399, 299)).toEqual({ column: 3, row: 2 });
+  });
+
+  test("cell boundaries belong to the cell they open", () => {
+    const m = base();
+    expect(tileCellAt(m, size, 99, 99)).toEqual({ column: 0, row: 0 });
+    expect(tileCellAt(m, size, 100, 100)).toEqual({ column: 1, row: 1 });
+  });
+
+  test("a point outside the grid clamps to its edge column, and a degenerate size is cell 0", () => {
+    const m = base();
+    expect(tileCellAt(m, size, -20, -20)).toEqual({ column: 0, row: 0 });
+    expect(tileCellAt(m, size, 900, 150)).toEqual({ column: 3, row: 1 });
+    expect(tileCellAt(m, { width: 0, height: 0 }, 40, 40)).toEqual({ column: 0, row: 0 });
+    expect(tileCellAt(m, { width: Number.NaN, height: 300 }, 40, 40)).toEqual({ column: 0, row: 0 });
+  });
+});
+
+describe("applyTileDrop", () => {
+  const size = { width: 400, height: 300 };
+
+  test("the cell under the pointer becomes the tile's top-left", () => {
+    // Tile 3 (row 2, full width) dropped on column 2 of row 0: it takes those
+    // cells and pushes tiles 1 and 2 down past it.
+    const m = applyTileDrop(base(), tileDragPayload("3"), size, 250, 40);
+    expect(boxes(m)).toEqual(["1@0,1 2x2", "2@2,1 2x2", "3@0,0 4x1"]);
+  });
+
+  test("a tile dropped inside a neighbour lands on that neighbour's origin cell", () => {
+    const m = applyTileDrop(base(), tileDragPayload("1"), size, 250, 40);
+    expect(findTile(m, "1")).toMatchObject({ x: 2, y: 0 });
+  });
+
+  test("a tile dropped back on the cell it already occupies is the same model", () => {
+    const m = base();
+    // Anywhere inside tile 2's own 2x2 block resolves to a cell it already
+    // covers, and clamping lands it back on its own origin.
+    expect(applyTileDrop(m, tileDragPayload("2"), size, 250, 40)).toBe(m);
+    expect(applyTileDrop(m, tileDragPayload("2"), size, 210, 10)).toBe(m);
+  });
+
+  test("a foreign drag and an unknown tile are ignored", () => {
+    const m = base();
+    expect(applyTileDrop(m, "https://example.com", size, 250, 40)).toBe(m);
+    expect(applyTileDrop(m, tileDragPayload("gone"), size, 250, 40)).toBe(m);
+  });
+});

package/src/tiles.ts

@@ -0,0 +1,285 @@
+// Tiles model: freeform panels on a column grid, rendered through the
+// existing <grid> widget (x/y/w/h map straight onto the gridColumn/gridRow/
+// gridColumnSpan/gridRowSpan attached props). No schema change, no ABI change.
+//
+// Collision handling is the standard grid-layout one: the tile you just
+// touched keeps the cells it asked for and every tile it overlaps is pushed
+// down until it clears, cascading. There is no upward compaction, so a tile
+// left at row 8 stays at row 8 and the layout is exactly what the caller
+// placed.
+//
+// Same invariant as model.ts: an op that changes nothing returns the SAME
+// reference, and every tile the op did not move keeps its object identity so
+// a re-render diffs down to the tiles that actually moved.
+
+export interface Tile<T> {
+  id: string;
+  /** Column of the tile's leading edge, 0-based. */
+  x: number;
+  /** Row of the tile's top edge, 0-based. */
+  y: number;
+  /** Width in columns, at least 1. */
+  w: number;
+  /** Height in rows, at least 1. */
+  h: number;
+  data: T;
+}
+
+export interface TileModel<T> {
+  /** Column count the model clamps against. The native grid still sizes its
+   * columns from the children, so this bounds placement, not pixels. */
+  columns: number;
+  /** Layout order, which is also paint order: later tiles draw over earlier
+   * ones where the platform lets cells overlap. `raiseTile` moves one last. */
+  tiles: Tile<T>[];
+  nextId: number;
+}
+
+export interface TilePlacement<T> {
+  id?: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  data: T;
+}
+
+/** Grid geometry is integer cells, and a non-finite span would panic a
+ * Debug/ReleaseSafe host on the attached-prop write, so this is a safety
+ * boundary like clampPaneRatio: everything rounds to an integer, spans floor
+ * at 1, and a tile is kept inside the column count. */
+function clampColumns(columns: number): number {
+  if (!Number.isFinite(columns)) return 1;
+  return Math.max(1, Math.trunc(columns));
+}
+
+function cell(value: number, fallback: number): number {
+  return Number.isFinite(value) ? Math.round(value) : fallback;
+}
+
+function clampTile<T>(tile: Tile<T>, columns: number): Tile<T> {
+  const w = Math.min(columns, Math.max(1, cell(tile.w, 1)));
+  const h = Math.max(1, cell(tile.h, 1));
+  const x = Math.min(columns - w, Math.max(0, cell(tile.x, 0)));
+  const y = Math.max(0, cell(tile.y, 0));
+  if (x === tile.x && y === tile.y && w === tile.w && h === tile.h) return tile;
+  return { ...tile, x, y, w, h };
+}
+
+function overlaps<T>(a: Tile<T>, b: Tile<T>): boolean {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+
+/** Pushes every tile that collides with an already-placed one down past it.
+ * `anchorId` is placed first, so the tile the caller just moved or resized is
+ * the one that wins its cells. Terminates because each push strictly
+ * increases a tile's y and heights are at least 1. */
+function resolveOverlaps<T>(tiles: readonly Tile<T>[], anchorId: string): Tile<T>[] {
+  const order = tiles.map((tile, index) => ({ tile, index }));
+  order.sort((a, b) => a.tile.y - b.tile.y || a.tile.x - b.tile.x || a.index - b.index);
+  const anchor = order.findIndex((entry) => entry.tile.id === anchorId);
+  if (anchor > 0) order.unshift(order.splice(anchor, 1)[0]!);
+
+  const placed: Tile<T>[] = [];
+  const out = tiles.slice();
+  for (const entry of order) {
+    let current = entry.tile;
+    for (;;) {
+      const hit = placed.find((p) => overlaps(p, current));
+      if (!hit) break;
+      current = { ...current, y: hit.y + hit.h };
+    }
+    placed.push(current);
+    out[entry.index] = current;
+  }
+  return out;
+}
+
+/** The model, or the one it was given when resolution moved nothing. */
+function commit<T>(m: TileModel<T>, tiles: Tile<T>[], nextId = m.nextId): TileModel<T> {
+  const changed = tiles.length !== m.tiles.length || tiles.some((tile, i) => tile !== m.tiles[i]);
+  if (!changed && nextId === m.nextId) return m;
+  return { columns: m.columns, tiles, nextId };
+}
+
+function numericId(id: string): number {
+  const match = /^(\d+)$/.exec(id);
+  return match ? Number(match[1]) : 0;
+}
+
+export function emptyTiles<T>(columns: number): TileModel<T> {
+  return { columns: clampColumns(columns), tiles: [], nextId: 1 };
+}
+
+/** Places `items` in order, each one dropped at its requested cell and pushed
+ * clear of what is already down. Ids default to "1".."n". */
+export function seedTiles<T>(items: readonly TilePlacement<T>[], columns: number): TileModel<T> {
+  let model = emptyTiles<T>(columns);
+  for (const item of items) model = placeTile(model, item);
+  return model;
+}
+
+export function findTile<T>(m: TileModel<T>, id: string): Tile<T> | undefined {
+  return m.tiles.find((tile) => tile.id === id);
+}
+
+/** Adds a tile at the cells it asks for, pushing whatever was there down. An
+ * id already in the model is rejected (same reference), the way addTab
+ * rejects a duplicate tab id. */
+export function placeTile<T>(m: TileModel<T>, placement: TilePlacement<T>): TileModel<T> {
+  const id = placement.id ?? String(m.nextId);
+  if (findTile(m, id)) return m;
+  const tile = clampTile({ id, x: placement.x, y: placement.y, w: placement.w, h: placement.h, data: placement.data }, m.columns);
+  const tiles = resolveOverlaps([...m.tiles, tile], id);
+  return commit(m, tiles, Math.max(m.nextId + (placement.id === undefined ? 1 : 0), numericId(id) + 1));
+}
+
+export function removeTile<T>(m: TileModel<T>, id: string): TileModel<T> {
+  if (!findTile(m, id)) return m;
+  return commit(m, m.tiles.filter((tile) => tile.id !== id));
+}
+
+export function moveTile<T>(m: TileModel<T>, id: string, x: number, y: number): TileModel<T> {
+  const tile = findTile(m, id);
+  if (!tile) return m;
+  const moved = clampTile({ ...tile, x, y }, m.columns);
+  if (moved.x === tile.x && moved.y === tile.y) return m;
+  return commit(m, resolveOverlaps(m.tiles.map((t) => (t.id === id ? moved : t)), id));
+}
+
+export function resizeTile<T>(m: TileModel<T>, id: string, w: number, h: number): TileModel<T> {
+  const tile = findTile(m, id);
+  if (!tile) return m;
+  const sized = clampTile({ ...tile, w, h }, m.columns);
+  if (sized.w === tile.w && sized.h === tile.h && sized.x === tile.x) return m;
+  return commit(m, resolveOverlaps(m.tiles.map((t) => (t.id === id ? sized : t)), id));
+}
+
+/** Moves a tile last in layout order, which is the top of the paint order. */
+export function raiseTile<T>(m: TileModel<T>, id: string): TileModel<T> {
+  const index = m.tiles.findIndex((tile) => tile.id === id);
+  if (index < 0 || index === m.tiles.length - 1) return m;
+  const tiles = m.tiles.slice();
+  tiles.push(tiles.splice(index, 1)[0]!);
+  return { columns: m.columns, tiles, nextId: m.nextId };
+}
+
+export function updateTile<T>(m: TileModel<T>, id: string, fn: (data: T) => T): TileModel<T> {
+  const tile = findTile(m, id);
+  if (!tile) return m;
+  const data = fn(tile.data);
+  if (Object.is(data, tile.data)) return m;
+  return commit(m, m.tiles.map((t) => (t.id === id ? { ...t, data } : t)));
+}
+
+// ============================================================================
+// Drag and drop
+// ============================================================================
+
+/** Pixel extent of the grid the tiles are laid out in. A drop reports a point
+ * in the grid's own coordinate space and the native grid never reports its
+ * geometry, so this is what turns that point back into a cell. Feed it from
+ * whatever sizes the grid. Without it a drop is ignored. */
+export interface TileSize {
+  width: number;
+  height: number;
+}
+
+export interface TileCell {
+  column: number;
+  row: number;
+}
+
+const DRAG_PREFIX = "nd-tiles:tile:";
+
+/** The `dragPayload` a tile carries, namespaced for the same reason
+ * dockDragPayload is: text dragged in from another application arrives on the
+ * same drop handler and must not be read as a tile id. */
+export function tileDragPayload(id: string): string {
+  return `${DRAG_PREFIX}${id}`;
+}
+
+export function parseTileDrag(payload: string): string | undefined {
+  if (!payload.startsWith(DRAG_PREFIX)) return undefined;
+  const id = payload.slice(DRAG_PREFIX.length);
+  return id.length > 0 ? id : undefined;
+}
+
+/** Row count the layout currently occupies, at least 1. The native grid sizes
+ * its rows from their children, so this is what a uniform-cell mapping has to
+ * divide by. */
+export function tileRows<T>(m: TileModel<T>): number {
+  let rows = 1;
+  for (const tile of m.tiles) rows = Math.max(rows, tile.y + tile.h);
+  return rows;
+}
+
+/** Cell under a point in the grid's coordinate space. Cells are taken as
+ * uniform, which is what the grid draws when every tile expands; a layout of
+ * mixed intrinsic heights drifts from this by whatever the row heights
+ * differ. Points outside the grid clamp to its edge cells. */
+export function tileCellAt<T>(m: TileModel<T>, size: TileSize, x: number, y: number): TileCell {
+  const columns = Math.max(1, m.columns);
+  const rows = tileRows(m);
+  const width = Number.isFinite(size.width) ? size.width : 0;
+  const height = Number.isFinite(size.height) ? size.height : 0;
+  const px = Number.isFinite(x) ? x : 0;
+  const py = Number.isFinite(y) ? y : 0;
+  const column = width > 0 ? Math.floor((px / width) * columns) : 0;
+  const row = height > 0 ? Math.floor((py / height) * rows) : 0;
+  return {
+    column: Math.min(columns - 1, Math.max(0, column)),
+    row: Math.max(0, row),
+  };
+}
+
+/** Turns one drop into one model op: the cell under the pointer becomes the
+ * dragged tile's top-left, and `moveTile` pushes whatever it lands on clear.
+ * A tile dropped back on the cell it already occupies returns the SAME
+ * reference, as does a payload from anything but a tile. */
+export function applyTileDrop<T>(m: TileModel<T>, payload: string, size: TileSize, x: number, y: number): TileModel<T> {
+  const id = parseTileDrag(payload);
+  if (id === undefined || !findTile(m, id)) return m;
+  const cell = tileCellAt(m, size, x, y);
+  return moveTile(m, id, cell.column, cell.row);
+}
+
+/** JSON-safe deep copy, same contract as serializeDock. */
+export function serializeTiles<T>(m: TileModel<T>): TileModel<T> {
+  return { columns: m.columns, tiles: m.tiles.map((tile) => ({ ...tile })), nextId: m.nextId };
+}
+
+/** Rebuilds a tile layout from persisted unknown data. Anything malformed (a
+ * missing id, a non-numeric cell, a duplicate id, data failing `isData`)
+ * rejects the whole layout back to emptyTiles(columns); `columns` is also the
+ * fallback when the persisted column count is unusable. Loaded tiles are
+ * clamped and pushed clear of each other, so a hand-edited file cannot land
+ * an overlapping layout. */
+export function deserializeTiles<T>(raw: unknown, columns: number, isData?: (d: unknown) => d is T): TileModel<T> {
+  const fallback = emptyTiles<T>(columns);
+  if (typeof raw !== "object" || raw === null) return fallback;
+  const candidate = raw as { columns?: unknown; tiles?: unknown; nextId?: unknown };
+  if (!Array.isArray(candidate.tiles)) return fallback;
+  const width = typeof candidate.columns === "number" ? clampColumns(candidate.columns) : fallback.columns;
+  const seen = new Set<string>();
+  const tiles: Tile<T>[] = [];
+  let maxNumericId = 0;
+  for (const entry of candidate.tiles) {
+    if (typeof entry !== "object" || entry === null) return fallback;
+    const t = entry as { id?: unknown; x?: unknown; y?: unknown; w?: unknown; h?: unknown; data?: unknown };
+    if (typeof t.id !== "string" || t.id.length === 0 || seen.has(t.id)) return fallback;
+    if (typeof t.x !== "number" || typeof t.y !== "number" || typeof t.w !== "number" || typeof t.h !== "number") {
+      return fallback;
+    }
+    if (isData && !isData(t.data)) return fallback;
+    seen.add(t.id);
+    maxNumericId = Math.max(maxNumericId, numericId(t.id));
+    tiles.push(clampTile({ id: t.id, x: t.x, y: t.y, w: t.w, h: t.h, data: t.data as T }, width));
+  }
+  const rawNextId = typeof candidate.nextId === "number" && Number.isInteger(candidate.nextId) ? candidate.nextId : 1;
+  return {
+    columns: width,
+    tiles: tiles.length > 0 ? resolveOverlaps(tiles, tiles[0]!.id) : tiles,
+    nextId: Math.max(rawNextId, maxNumericId + 1, 1),
+  };
+}