@heycys/gallery 0.1.0 → 0.1.2

package/browser/shared/block-packs.mjs

@@ -0,0 +1,404 @@
+import fs from "node:fs";
+import path from "node:path";
+import { componentSettings, problemIn, writeComponentSettings } from "./component-catalog.mjs";
+import { refusal, said } from "./i18n/index.mjs";
+import { PACK_FILE, PACK_ID, readPackManifest } from "./pack-manifest.mjs";
+import { packsDirectory } from "./paths.mjs";
+import { filesIn, fingerprintOf, fingerprintOfFiles, isSystemFile, recordOf, shippedBlocks, shippedPackIds, versionAfter, writeRecord, writingOrder } from "./shipped-blocks.mjs";
+import { DEVICE_NAMES, PACKAGE_MANIFEST, layoutOf, markerOf, packageFolders } from "./workspace.mjs";
+
+// Block packs (自定义块包: notes/plans/block-packs-plan-2026-11-09.md; docs/render.md "Block packs"). A pack
+// is a scope of the workspace's custom blocks, components/<id>/, with its pack.json (./pack-manifest.mjs)
+// and a folder of each of its blocks, <id>/<name>/, the blocks' ids <id>/<name> as ever, so that nothing
+// written of a block changes; a scope with no pack.json (local/, the Agent's own) is a pack of its own,
+// named by its scope. A pack is shared as its folder, or a zip of it (the folder itself, or what it
+// holds, at the zip's top), and installed into a workspace by gallery block pack install (src/cli/component.mjs)
+// or 设置 › 组件列表's 导入 (src/server/component-settings.mjs), which both read it (src/transfer/pack-source.mjs)
+// and hand its files here, checked alike:
+//
+//   installPack  its files copied in, as gallery block add copies one of Gallery's own: each block's
+//                manifest last; .gallery/blocks.json records each block's version and fingerprint, and
+//                under `packs` the pack's version, the fingerprint of its own files (pack.json, and what
+//                else stands at its top) and its blocks. Installed again (a newer version), a block as it
+//                was installed is replaced, one changed since kept as it is (someone's work), a block
+//                the new version has not taken out where it is as installed; pack.json the same way.
+//                Refused, with why (said()'s, a \`code\`): a file that points out of the pack ("path"),
+//                one too large ("size"), a pack.json missing or that does not read ("manifest"), a block
+//                folder of no component.json naming it <id>/<name> ("block"), the id of one of Gallery's
+//                own packs ("official"), an id a scope of the workspace has that no install put there
+//                ("taken": another pack, or blocks someone wrote).
+//   removePack   a pack installed taken out, its folder and records; never one of Gallery's own (its
+//                switch turns it off), nor a scope no install put there ("own": someone's work).
+//   workspacePacks  the workspace's packs as 设置 › 组件列表 and gallery block pack list say them.
+//
+// Gallery's own packs (src/packs/<id>/: gallery, Gallery 风格; gallery-soft, 柔光风格) are installed the
+// same way as a workspace's server starts and by gallery init (installOfficialPacks): once each, a pack
+// switched off at first where OFF_AT_FIRST says so (gallery.json's components.packs), and again at each
+// start with the same rule, so that a block as it was installed follows Gallery, a block Gallery's pack
+// has come to hold is added, and one taken away by hand stays away (its record says it was there).
+// A pack's switch (components.packs, { "<id>": { "enabled": false } }, none written on) keeps all its
+// blocks out of every menu and library, as each one's master switch does (shared/components/installed.mjs
+// inDocumentMenus); what is written of them shows as ever.
+
+/** Gallery's own packs that a workspace has switched off when they are first installed. */
+export const OFF_AT_FIRST = Object.freeze(["gallery-soft"]);
+
+/** The environment variable that keeps a start (and gallery init) from installing Gallery's own packs: the tests' workspaces. */
+export const NO_PACKS = "GALLERY_NO_PACKS";
+
+/** Whether `env` says to install none of Gallery's own packs (NO_PACKS set, not to "", "0" or "false"). */
+export const packsSkipped = (env = process.env) => !["", "0", "false", undefined].includes(env[NO_PACKS]);
+
+const MOST_FILES = 2000;
+const MOST_BYTES = 64 * 1024 * 1024;
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const isTable = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const fail = (code, message) => {
+  throw refusal(message, { code });
+};
+
+/** The files of `folder`, [{ name (its path in it, with "/"), data }]: a link is none of them. */
+export function folderFiles(folder) {
+  const files = [];
+  for (const entry of fs.readdirSync(folder, { recursive: true, withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    if (files.length >= MOST_FILES) fail("size", said("块包太大：最多 {0} 个文件、{1} MB", MOST_FILES, MOST_BYTES / 1024 / 1024));
+    const name = path.relative(folder, path.join(entry.parentPath, entry.name)).split(path.sep).join("/");
+    files.push({ name, data: fs.readFileSync(path.join(folder, ...name.split("/"))) });
+  }
+  return files;
+}
+
+/**
+ * A pack's files ([{ name, data }], as a folder or a zip gives them) read as one: { manifest, blocks: Map
+ * of each block's folder name to its files, own: the files at its top, pack.json among them }. A pack
+ * zipped with its folder (one folder at the top, pack.json in it) is read from that folder; what a
+ * system wrote (.DS_Store, __MACOSX/…) is passed over. Refused as installPack says; `refuse(manifest)`, run
+ * once its pack.json reads, before its blocks are looked at, refuses what it will.
+ */
+export function readPack(given, { refuse = () => {} } = {}) {
+  const files = [];
+  let bytes = 0;
+  for (const { name: written, data } of given) {
+    const name = String(written).replace(/\\/g, "/");
+    if (name.endsWith("/")) continue; // a folder of a zip
+    const parts = name.split("/");
+    if (name.startsWith("/") || /^[A-Za-z]:/.test(name) || name.includes("\u0000") || parts.some((part) => part === "" || part === "." || part === "..")) fail("path", said("{0} 指向块包外面，不能装", String(written)));
+    if (parts[0] === "__MACOSX" || isSystemFile(parts.at(-1))) continue;
+    bytes += data.length;
+    files.push({ name, data });
+  }
+  if (files.length > MOST_FILES || bytes > MOST_BYTES) fail("size", said("块包太大：最多 {0} 个文件、{1} MB", MOST_FILES, MOST_BYTES / 1024 / 1024));
+  let inner = files;
+  if (!files.some(({ name }) => name === PACK_FILE)) {
+    const tops = new Set(files.map(({ name }) => name.split("/")[0]));
+    const [top] = tops;
+    if (tops.size !== 1 || !files.some(({ name }) => name === `${top}/${PACK_FILE}`)) fail("manifest", said("最上一层没有 pack.json：块包是一个文件夹，最上一层放 pack.json，每个块一个文件夹"));
+    inner = files.map(({ name, data }) => ({ name: name.slice(top.length + 1), data }));
+  }
+  const manifest = readPackManifest(inner.find(({ name }) => name === PACK_FILE).data.toString("utf8"));
+  refuse(manifest);
+  const blocks = new Map();
+  const own = [];
+  for (const file of inner) {
+    const [first, ...rest] = file.name.split("/");
+    if (rest.length === 0) {
+      own.push(file);
+      continue;
+    }
+    if (!blocks.has(first)) blocks.set(first, []);
+    blocks.get(first).push({ name: rest.join("/"), data: file.data });
+  }
+  for (const [name, list] of blocks) {
+    if (!NAME.test(name) || DEVICE_NAMES.has(name)) fail("block", said("{0} 不是块的文件夹名：只用小写字母、数字和连字符", name));
+    const file = list.find((each) => each.name === PACKAGE_MANIFEST);
+    if (!file) fail("block", said("{0}/ 里没有 component.json", name));
+    let id;
+    try {
+      id = JSON.parse(file.data.toString("utf8").replace(/^/, "")).id;
+    } catch {
+      fail("block", said("{0}/component.json 不是 JSON", name));
+    }
+    if (id !== `${manifest.id}/${name}`) fail("block", said("{0}/component.json 的 id 要写成 {1}", name, `${manifest.id}/${name}`));
+  }
+  return { manifest, blocks, own };
+}
+
+// A block's version, as its manifest says it, or null.
+function versionIn(list) {
+  try {
+    const version = JSON.parse(list.find(({ name }) => name === PACKAGE_MANIFEST).data.toString("utf8").replace(/^/, "")).version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+// The files right at the top of a pack's folder (pack.json and what else stands beside the blocks).
+function topFiles(folder) {
+  try {
+    return fs.readdirSync(folder, { withFileTypes: true }).filter((entry) => entry.isFile() && !isSystemFile(entry.name)).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+// What the top of a pack's folder holds, as a fingerprint, or null for nothing there.
+function ownFingerprint(folder) {
+  const names = topFiles(folder);
+  return names.length ? fingerprintOfFiles(names.map((name) => ({ name, data: fs.readFileSync(path.join(folder, name)) }))) : null;
+}
+
+// Whether a folder holds anything a system did not write there.
+function holds(folder) {
+  try {
+    return fs.readdirSync(folder).some((name) => !isSystemFile(name));
+  } catch {
+    return false;
+  }
+}
+
+// `files` written into `folder`, the files of what was there that they have not taken out first
+// (`replacing`), the manifest last: what makes a folder a block to a running server's watcher.
+function writeFiles(folder, files, { replacing = false, last = PACKAGE_MANIFEST } = {}) {
+  const names = files.map(({ name }) => name);
+  if (replacing) for (const old of filesIn(folder)) if (!names.includes(old)) fs.rmSync(path.join(folder, ...old.split("/")), { force: true });
+  const byName = new Map(files.map((file) => [file.name, file.data]));
+  const order = last === PACKAGE_MANIFEST ? writingOrder(names) : [...names.filter((name) => name !== last), ...(names.includes(last) ? [last] : [])];
+  for (const name of order) {
+    const target = path.join(folder, ...name.split("/"));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, byName.get(name));
+  }
+}
+
+/**
+ * The pack `given` holds ([{ name, data }]: src/transfer/pack-source.mjs reads a folder or a zip into
+ * them) installed into the workspace at `root` (above): { id, name, version, from (the version installed
+ * before, or null), did ("installed", "updated" or "same"), folder, added, updated, same, kept (blocks
+ * changed since they were installed, left as they are), removed (blocks the new version has not), skipped
+ * (blocks of Gallery's own taken away by hand, which stay away), ownKept (its pack.json changed since,
+ * left) }, each list of block ids. `official`: one of Gallery's own packs (installOfficialPacks), whose
+ * id is its own and whose scope may hold its blocks already, as gallery block add put them there.
+ */
+export function installPack(root, given, { official = false, shippedIds = shippedPackIds() } = {}) {
+  const { manifest, blocks, own } = readPack(given, {
+    refuse: ({ id }) => {
+      if (!official && shippedIds.includes(id)) fail("official", said("{0} 是 Gallery 自带的块包用的 id：换一个 id 再装", id));
+    },
+  });
+  const { id } = manifest;
+  const folder = path.join(layoutOf(root).components, id);
+  const record = recordOf(root);
+  const packs = isTable(record.packs) ? record.packs : {};
+  const was = isTable(packs[id]) ? packs[id] : null;
+  if (!official && !was && holds(folder)) fail("taken", said("工作区里已经有 components/{0}：这个名字被别的块包或别人写的块用着，换一个 id，或先把那个文件夹挪走", id));
+  const done = { id, name: manifest.name, version: manifest.version, from: was?.version ?? null, folder, added: [], updated: [], same: [], kept: [], removed: [], skipped: [], ownKept: false };
+  const names = [...blocks.keys()].sort();
+  for (const name of names) {
+    const block = `${id}/${name}`;
+    const list = blocks.get(name);
+    const target = path.join(folder, name);
+    const next = fingerprintOfFiles(list);
+    const now = fingerprintOf(target);
+    const kept = isTable(record[block]) ? record[block] : null;
+    if (now === null) {
+      if (official && kept) {
+        done.skipped.push(block);
+        continue;
+      }
+      writeFiles(target, list);
+      done.added.push(block);
+    } else if (now === next) done.same.push(block);
+    else if (kept && now === kept.fingerprint) {
+      writeFiles(target, list, { replacing: true });
+      done.updated.push(block);
+    } else {
+      done.kept.push(block);
+      continue;
+    }
+    record[block] = { version: versionIn(list), fingerprint: next };
+  }
+  // The blocks of the pack as it was installed that this version has not: out, where they are as installed.
+  for (const block of Array.isArray(was?.blocks) ? was.blocks : []) {
+    const name = String(block).split("/")[1];
+    if (!name || blocks.has(name) || !NAME.test(name)) continue;
+    const target = path.join(folder, name);
+    const now = fingerprintOf(target);
+    if (now !== null && now !== record[block]?.fingerprint) {
+      done.kept.push(block);
+      continue;
+    }
+    if (now !== null) {
+      fs.rmSync(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+      done.removed.push(block);
+    }
+    delete record[block];
+  }
+  // Its own files, pack.json last, the same way.
+  const ownNow = ownFingerprint(folder);
+  const ownNext = fingerprintOfFiles(own);
+  if (ownNow !== ownNext) {
+    if (ownNow === null || ownNow === was?.fingerprint) {
+      const names = own.map(({ name }) => name);
+      for (const old of topFiles(folder)) if (!names.includes(old)) fs.rmSync(path.join(folder, old), { force: true });
+      fs.mkdirSync(folder, { recursive: true });
+      writeFiles(folder, own, { last: PACK_FILE });
+    } else done.ownKept = true;
+  }
+  const changed = done.added.length + done.updated.length + done.removed.length > 0 || (ownNow !== ownNext && !done.ownKept);
+  done.did = !was ? "installed" : changed ? "updated" : "same";
+  record.packs = { ...packs, [id]: { version: manifest.version, fingerprint: done.ownKept ? was.fingerprint : ownNext, blocks: names.map((name) => `${id}/${name}`), ...(official ? { official: true } : {}) } };
+  writeRecord(root, record);
+  return done;
+}
+
+/**
+ * The pack `id` taken out of the workspace at `root`: its folder and what .gallery/blocks.json records of
+ * it ({ id, version, blocks }). What documents and pages hold of its blocks stays, shown as blocks that
+ * are not there. Refused: one of Gallery's own ("official": its switch in 设置 › 组件列表 turns it off), none
+ * there ("missing"), a scope no install put there ("own": blocks someone wrote, theirs to delete).
+ */
+export function removePack(root, id, { shippedIds = shippedPackIds() } = {}) {
+  if (shippedIds.includes(id)) fail("official", said("{0} 是 Gallery 自带的块包，不能删除：在 设置 › 组件列表 里把它关掉", id));
+  const folder = path.join(layoutOf(root).components, id);
+  if (!PACK_ID.test(id) || !fs.existsSync(folder)) fail("missing", said("工作区里没有块包 {0}", id));
+  const record = recordOf(root);
+  const was = isTable(record.packs) && isTable(record.packs[id]) ? record.packs[id] : null;
+  if (!was) fail("own", said("components/{0} 不是装进来的块包，里面的块是有人在这个工作区写的：要删就自己删掉这个文件夹", id));
+  fs.rmSync(folder, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  for (const key of Object.keys(record)) if (key.startsWith(`${id}/`)) delete record[key];
+  const { [id]: _gone, ...rest } = record.packs;
+  writeRecord(root, { ...record, packs: rest });
+  return { id, version: was.version ?? null, blocks: Array.isArray(was.blocks) ? was.blocks : [] };
+}
+
+// Why, in both languages.
+const both = (problem) => ({ zh: problemIn("zh", problem), en: problemIn("en", problem) });
+
+/**
+ * The workspace's packs, as 设置 › 组件列表's cards and gallery block pack list say them: each scope of
+ * components/ that holds a block or a pack.json, [{ id, name: { zh, en } (its scope's for one with no
+ * pack.json), description, version, author, homepage, icon (null where it says none), kind ("official":
+ * one of Gallery's own; "installed": put there by an install; "own": a scope of blocks someone wrote
+ * here), problem ({ zh, en }: why its pack.json does not read, or null), blocks (how many), enabled (its
+ * switch, gallery.json's components.packs), changed (of what was installed, the blocks changed since, and
+ * pack.json where it was), newer (of one of Gallery's own that was changed since, Gallery's version of it
+ * when that comes after the one installed, which is not put over it; else null) }]: Gallery's own first,
+ * then those installed, then the workspace's own, each by id.
+ */
+export function workspacePacks(root, { settings = null, shippedIds = shippedPackIds(), directory = packsDirectory } = {}) {
+  const { components } = layoutOf(root);
+  const record = recordOf(root);
+  const installed = isTable(record.packs) ? record.packs : {};
+  const blocks = packageFolders(root);
+  const scopes = new Set(blocks.map(({ id }) => id.split("/")[0]));
+  try {
+    for (const name of fs.readdirSync(components)) if (PACK_ID.test(name) && fs.existsSync(path.join(components, name, PACK_FILE))) scopes.add(name);
+  } catch {}
+  const switches = (settings ?? componentSettings(root)).packs ?? {};
+  const listed = [...scopes].map((id) => {
+    const folder = path.join(components, id);
+    let manifest = null;
+    let problem = null;
+    if (fs.existsSync(path.join(folder, PACK_FILE))) {
+      try {
+        manifest = readPackManifest(fs.readFileSync(path.join(folder, PACK_FILE), "utf8"));
+        if (manifest.id !== id) {
+          problem = said("pack.json 的 id 是 {0}，它的文件夹却是 components/{1}", manifest.id, id);
+          manifest = null;
+        }
+      } catch (error) {
+        problem = error;
+      }
+    }
+    const was = isTable(installed[id]) ? installed[id] : null;
+    const ids = blocks.filter((block) => block.id.startsWith(`${id}/`));
+    const changed = was ? ids.filter((block) => isTable(record[block.id]) && fingerprintOf(block.folder) !== record[block.id].fingerprint).map((block) => block.id) : [];
+    if (was && ownFingerprint(folder) !== was.fingerprint) changed.push(`${id}/${PACK_FILE}`);
+    const official = shippedIds.includes(id);
+    // One of Gallery's own: what Gallery's pack.json says of it, where the workspace's has none (its blocks
+    // put there one by one, gallery block add's, before a start installed the pack).
+    let shipped = null;
+    if (official) {
+      try {
+        shipped = readPackManifest(fs.readFileSync(path.join(directory, id, PACK_FILE), "utf8"));
+      } catch {}
+    }
+    // Gallery's newer version, not put over a change: a changed block of it whose version Gallery's comes after, or a changed pack.json.
+    const versionAt = (block) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(components, ...block.split("/"), PACKAGE_MANIFEST), "utf8")).version ?? null;
+      } catch {
+        return null;
+      }
+    };
+    const ownBlocks = official ? shippedBlocks(directory) : [];
+    const behind = official && shipped && changed.some((block) => (block.endsWith(`/${PACK_FILE}`) ? versionAfter(shipped.version, manifest?.version ?? null) : (ownBlocks.some((one) => one.id === block) && versionAfter(ownBlocks.find((one) => one.id === block).version, versionAt(block)))));
+    const newer = behind ? shipped.version : null;
+    const told = manifest ?? (problem ? null : shipped);
+    return {
+      id,
+      name: told?.name ?? { zh: id, en: id },
+      description: told?.description ?? null,
+      version: manifest?.version ?? null,
+      author: told?.author ?? null,
+      homepage: told?.homepage ?? null,
+      icon: told?.icon ?? null,
+      kind: official ? "official" : was ? "installed" : "own",
+      problem: problem ? both(problem) : null,
+      blocks: ids.length,
+      enabled: switches[id] !== false,
+      changed,
+      newer,
+    };
+  });
+  const rank = ({ id, kind }) => (kind === "official" ? shippedIds.indexOf(id) : kind === "installed" ? 1000 : 2000);
+  return listed.sort((a, b) => rank(a) - rank(b) || (a.id < b.id ? -1 : 1));
+}
+
+// What installOfficialPacks tells the log of one pack, a line each.
+function installedLines(root, made, first) {
+  const lines = [];
+  const where = path.resolve(root);
+  if (first) lines.push(`Gallery's pack ${made.id} ${made.version} installed in ${where} (${made.added.length + made.same.length + made.updated.length} blocks)${OFF_AT_FIRST.includes(made.id) ? ", switched off: 设置 › 组件列表 turns it on" : ""}`);
+  else {
+    if (made.added.length) lines.push(`Gallery's pack ${made.id} in ${where} has new blocks: ${made.added.join(", ")}`);
+    if (made.updated.length) lines.push(`Gallery's pack ${made.id} in ${where}, its blocks as they were installed, updated to this Gallery's: ${made.updated.join(", ")}`);
+    if (made.removed.length) lines.push(`Gallery's pack ${made.id} in ${where}: ${made.removed.join(", ")} no longer in it, taken out`);
+  }
+  return lines;
+}
+
+/**
+ * Gallery's own packs (in `directory`, the package's) installed into the workspace at `root`, as
+ * installPack installs any, whenever its server starts and by gallery init: one not installed yet is
+ * (one of OFF_AT_FIRST switched off first in gallery.json, where it says nothing of it: a gallery.json that
+ * cannot be written leaves that pack for the next start), one installed is brought up to Gallery's.
+ * `env`: whose NO_PACKS is read; `log`: told what was done, a line each. Never rejects: { did: "off"
+ * (NO_PACKS), "unread" (gallery.json does not read as Gallery's) or "done", packs: [installPack's answer
+ * with `first`, or { id, failed }] }.
+ */
+export async function installOfficialPacks(root, { directory = packsDirectory, env = process.env, log = () => {} } = {}) {
+  if (packsSkipped(env)) return { did: "off", packs: [] };
+  let marker = { ours: false };
+  try {
+    marker = markerOf(fs.readFileSync(layoutOf(root).marker, "utf8"));
+  } catch {}
+  if (!marker.ours) return { did: "unread", packs: [] };
+  const ids = shippedPackIds(directory);
+  const packs = [];
+  for (const id of ids) {
+    try {
+      const first = !isTable(recordOf(root).packs?.[id]);
+      if (first && OFF_AT_FIRST.includes(id) && componentSettings(root).packs[id] === undefined) await writeComponentSettings(root, { pack: id, enabled: false });
+      const made = installPack(root, folderFiles(path.join(directory, id)), { official: true, shippedIds: ids });
+      packs.push({ ...made, first });
+      for (const line of installedLines(root, made, first)) log(line);
+    } catch (error) {
+      log(`Gallery's pack ${id} could not be installed in ${path.resolve(root)}: ${error?.message ?? error}`);
+      packs.push({ id, failed: error?.message ?? String(error) });
+    }
+  }
+  return { did: "done", packs };
+}

package/browser/shared/board-places.mjs

@@ -0,0 +1,224 @@
+// Where the cards of a custom page's board go (notes/plans/custom-blocks-spec-2026-11-07.md §6, §8;
+// docs/render.md "A custom page"): the one set of rules every side places a card by, so that what the
+// page shows while a card is dragged, what the page service writes and what gallery page add writes
+// are the same. The page service (src/editor/page-service.mjs) and gallery page add place and push
+// cards in the file by them; the kit's board script (src/render/kit/board/) draws a board by them,
+// cards of `fit: "content"` as high as what they hold, those under them pushed down; the page's board
+// editing (src/editor/page/board/) shows a drag's spot and the cards it pushes by them before it asks
+// the service. Pure: no DOM, no Node.
+//
+// A card is { id, x, y, w, h } in whole cells of a board 12 columns wide, at most 24 cells high: what the
+// file says, wherever it is drawn. A cell's side is fixed (CELL), as a document's reading width is, so a
+// board is as wide whatever the window (the workbench's sidebar open or folded); where the room holds
+// fewer than twelve of them the board is drawn in as many as it holds (gridFor), 4 at the least, its
+// cards one after another in their order (flow), as wide as they are, which nothing writes: nothing is
+// placed there. Nothing here ever moves a card up: a card pushed down stays where it was pushed, the room
+// it left a room on the board, as on a board things are pinned to.
+
+/** The cells of a board's row, and the most a card is high (the manifest's own range, spec §1). */
+export const GRID = Object.freeze({ columns: 12, rows: 24 });
+
+/** The pixels between two cells. */
+export const GAP = 16;
+
+/**
+ * A cell's side in pixels, the same however wide the window (the user's word of 2026-11-09: the cards no
+ * larger with the sidebar folded, only further in): twelve of them and their gaps are 944px, which the
+ * workbench's content holds on a 1280px laptop with the sidebar open at its default width.
+ */
+export const CELL = 64;
+
+/** The fewest columns a board is drawn in: where not even these fit their cells are drawn smaller (a phone). */
+export const LEAST = 4;
+
+/** The pixels `n` cells take on a board whose cell is `cell` pixels (n cells and the n - 1 gaps between them). */
+export const spanOf = (n, cell, gap = GAP) => n * cell + Math.max(0, n - 1) * gap;
+
+/**
+ * A board drawn in `room` pixels: { columns, cell, width }, as many whole cells of CELL, GAP apart, as
+ * the room holds, from LEAST to 12; where not even LEAST fit, LEAST cells as large as the room lets
+ * them be. `width` is what its columns take (the board stands them in its middle).
+ */
+export function gridFor(room) {
+  const fit = Math.floor((Math.max(0, room) + GAP) / (CELL + GAP));
+  const columns = Math.max(LEAST, Math.min(GRID.columns, fit));
+  const cell = fit >= LEAST ? CELL : Math.max(0, (room - (LEAST - 1) * GAP) / LEAST);
+  return { columns, cell, width: spanOf(columns, cell) };
+}
+
+const whole = (value, fallback) => (Number.isInteger(value) ? value : fallback);
+
+/** Whether cards `a` and `b` share a cell. */
+export const overlaps = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+
+/**
+ * Cells `{ x, y, w, h }` held to a board of `columns`: 1 <= w <= columns, 1 <= h <= 24, 0 <= x <=
+ * columns - w, 0 <= y; what is no whole number the default, a 4 x 2 card at 0, 0.
+ */
+export function onBoard({ x, y, w, h }, columns = GRID.columns) {
+  const width = Math.min(columns, Math.max(1, whole(w, 4)));
+  const height = Math.min(GRID.rows, Math.max(1, whole(h, 2)));
+  return { x: Math.min(columns - width, Math.max(0, whole(x, 0))), y: Math.max(0, whole(y, 0)), w: width, h: height };
+}
+
+/**
+ * The cards of a board with none sharing a cell, none moved up: `fixed` (ids) stay where they are,
+ * and every other card, in the order of its place (top to bottom, left to right, then as given), goes
+ * down until it shares no cell with one placed before it, right under the one it met. What the file
+ * says of a board that shares no cell is what this gives back. Returns new cards, in the order given.
+ * @template {{ id: string, x: number, y: number, w: number, h: number }} Card
+ * @param {Card[]} cards
+ * @param {Iterable<string>} fixed
+ * @returns {Card[]}
+ */
+export function settle(cards, fixed = []) {
+  const kept = new Set(fixed);
+  const placed = cards.filter((card) => kept.has(card.id)).map((card) => ({ ...card }));
+  const rest = cards.map((card, index) => ({ card, index })).filter(({ card }) => !kept.has(card.id))
+    .sort((a, b) => a.card.y - b.card.y || a.card.x - b.card.x || a.index - b.index);
+  for (const { card } of rest) {
+    const going = { ...card };
+    for (let met = placed.filter((other) => overlaps(going, other)); met.length > 0; met = placed.filter((other) => overlaps(going, other))) {
+      going.y = Math.max(...met.map((other) => other.y + other.h));
+    }
+    placed.push(going);
+  }
+  const at = new Map(placed.map((card) => [card.id, card]));
+  return cards.map((card) => at.get(card.id));
+}
+
+/**
+ * The cards with card `moved.id` at `moved`'s cells (held to the board), and those it now shares a cell
+ * with pushed down under it, and so on (settle): what a drop, a resize and a card put on a board at a
+ * place of its own do. A card of no id there joins them (a card added).
+ */
+export function pushDown(cards, moved, columns = GRID.columns) {
+  const cells = onBoard(moved, columns);
+  const next = cards.some((card) => card.id === moved.id)
+    ? cards.map((card) => (card.id === moved.id ? { ...card, ...cells } : card))
+    : [...cards, { ...moved, ...cells }];
+  return settle(next, [moved.id]);
+}
+
+/**
+ * The first place a card of `w` x `h` cells takes on a board holding `cards`, reading the board as a
+ * page is read: the topmost row it fits in, and there the leftmost column, sharing a cell with none.
+ * @returns {{ x: number, y: number }}
+ */
+export function freeSpot(cards, { w, h }, columns = GRID.columns) {
+  const { w: width, h: height } = onBoard({ x: 0, y: 0, w, h }, columns);
+  const bottom = cards.reduce((most, card) => Math.max(most, card.y + card.h), 0);
+  for (let y = 0; y <= bottom; y++) {
+    for (let x = 0; x + width <= columns; x++) {
+      if (!cards.some((card) => overlaps({ x, y, w: width, h: height }, card))) return { x, y };
+    }
+  }
+  return { x: 0, y: bottom };
+}
+
+/**
+ * The size a card of a block takes when it is put on a board (the manifest's `card`, as the catalog
+ * reads it: component-catalog.mjs cardOf): the first of its `sizes`, else its `w` and `h`; `h` null
+ * where the manifest says none, the fewest whole cells its content takes, which only the page measures
+ * (`measured`: 2 until then).
+ * @param {{ sizes?: number[][] | null, w?: number, h?: number | null } | null | undefined} card
+ * @returns {{ w: number, h: number, measured: boolean }}
+ */
+export function defaultSize(card) {
+  if (card?.sizes?.length) return { w: card.sizes[0][0], h: card.sizes[0][1], measured: false };
+  return { w: card?.w ?? 4, h: card?.h ?? 2, measured: card?.h === null || card?.h === undefined };
+}
+
+/** Of `sizes` ([w, h] each), the nearest to `w` x `h` (by the distance of their corners; the first of two as near). */
+export function nearestSize(sizes, { w, h }) {
+  let best = sizes[0];
+  let far = Infinity;
+  for (const size of sizes) {
+    const distance = (size[0] - w) ** 2 + (size[1] - h) ** 2;
+    if (distance < far) {
+      far = distance;
+      best = size;
+    }
+  }
+  return { w: best[0], h: best[1] };
+}
+
+/**
+ * What a card of a block may be resized to, for `w` x `h` asked: the nearest of the manifest's `sizes`
+ * where it lists them (unless `any`: a manifest that wrote a min or a max beside them frees the card,
+ * its sizes only the common ones its menu lists), else whole cells between its `min` and `max`
+ * (1 x 1 and 12 x 24 where it says none), never past the board.
+ */
+export function sizeFor(card, { w, h }, columns = GRID.columns) {
+  if (card?.sizes?.length && !card.any) {
+    const near = nearestSize(card.sizes, { w, h });
+    return { w: Math.min(columns, near.w), h: near.h };
+  }
+  const min = { w: card?.min?.w ?? 1, h: card?.min?.h ?? 1 };
+  const max = { w: Math.min(columns, card?.max?.w ?? GRID.columns), h: Math.min(GRID.rows, card?.max?.h ?? GRID.rows) };
+  return { w: Math.min(max.w, Math.max(min.w, Math.round(w))), h: Math.min(max.h, Math.max(min.h, Math.round(h))) };
+}
+
+/**
+ * The cells high a card of `fit: "content"` is drawn, for its content `height` in pixels (what it
+ * needs, its frame and padding with it) on a board whose cell is `cell` pixels: the spec's
+ * ceil((height + 16) / (cell + 16)), 1 at least and 24 at most.
+ */
+export function fitHeight(height, cell, gap = GAP) {
+  if (!(cell > 0)) return 1;
+  return Math.min(GRID.rows, Math.max(1, Math.ceil((height + gap) / (cell + gap) - 1e-6)));
+}
+
+/**
+ * The cards of a board drawn in `columns` fewer than twelve (a narrow room: gridFor): one after another
+ * in the order of their places (top to bottom, left to right, then as given), each as wide as it is but
+ * never wider than the row (`w` held to `columns`) and as high, each at the first spot at or after where
+ * the one before it ends, row by row, that shares no cell with those before it (as a grid flows its items
+ * with no place of their own: no card goes before one it came after, so a room may be left beside a tall
+ * one). What is drawn only, never written: the file's twelve-column places stay as they are, and the
+ * board is drawn by them again once the room holds twelve. Returns new cards, in the order given.
+ * @template {{ id: string, x: number, y: number, w: number, h: number }} Card
+ * @param {Card[]} cards
+ * @param {number} columns
+ * @returns {Card[]}
+ */
+export function flow(cards, columns) {
+  const order = cards.map((card, index) => ({ card, index })).sort((a, b) => a.card.y - b.card.y || a.card.x - b.card.x || a.index - b.index);
+  const placed = [];
+  const at = new Map();
+  let row = 0;
+  let column = 0;
+  for (const { card, index } of order) {
+    const w = Math.max(1, Math.min(card.w, columns));
+    let x = column;
+    let y = row;
+    for (;;) {
+      if (x + w > columns) {
+        x = 0;
+        y += 1;
+        continue;
+      }
+      const spot = { x, y, w, h: card.h };
+      if (!placed.some((other) => overlaps(spot, other))) break;
+      x += 1;
+    }
+    const going = { ...card, x, y, w };
+    placed.push(going);
+    at.set(index, going);
+    row = y;
+    column = x + w;
+  }
+  return cards.map((_, index) => at.get(index));
+}
+
+/** The whole cells `pixels` are nearest to, from a board's edge: what a drag snaps to. */
+export const cellAt = (pixels, cell, gap = GAP) => (cell > 0 ? Math.round(pixels / (cell + gap)) : 0);
+
+/** The cards whose cells changed from `before` to `after` (lists of cards), by id: [{ id, x, y, w, h }] as `after` has them. */
+export function moved(before, after) {
+  const was = new Map(before.map((card) => [card.id, card]));
+  return after.filter((card) => {
+    const old = was.get(card.id);
+    return !old || old.x !== card.x || old.y !== card.y || old.w !== card.w || old.h !== card.h;
+  });
+}