@anchrd/intel-ui 0.37.0 → 0.38.0

package/src/board/board-panel/board-panel.tsx

@@ -0,0 +1,74 @@
+import type { BoardTaskFilter } from "@anchrd/intel-contract/board";
+import type { Node } from "@anchrd/intel-contract/node";
+import { useState } from "react";
+import { useBoard } from "@/board/board-data/board-data.ts";
+import { BoardKanban } from "@/board/board-kanban/board-kanban.tsx";
+import type { GroupKey, Sort } from "@/board/board-table/board-table.ts";
+import { BoardTable } from "@/board/board-table/board-table.tsx";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+
+type View = "kanban" | "table";
+
+/**
+ * A board on the node screen, beside the folder, the table and the editor (D66, #376).
+ *
+ * ⚠️ The whole board is ONE answer. `board_get` returns the columns and every card in them, and the
+ * views below read that one object — no view fetches per card, per column, or on scroll. A board
+ * that loaded its cards one by one would look exactly the same on screen and be a different thing
+ * over the wire, which is why `board-panel.unit.tsx` counts the calls rather than the cards.
+ */
+export function BoardPanel({ node }: { node: Node }) {
+  const i18n = useI18n();
+  const [view, setView] = useState<View>("kanban");
+  return (
+    <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+      {/* No wrapper role: the house switch (`view-toggle.tsx`) carries none either, and a `group`
+          on a plain `div` is the shape a linter rightly asks to be a `fieldset`. What names the
+          control is each button — its own text, plus `aria-pressed` for which view is showing. */}
+      <div className="flex shrink-0 items-center gap-1 border-b px-4 py-2">
+        {(["kanban", "table"] as const).map((name) => (
+          <button
+            key={name}
+            type="button"
+            aria-pressed={view === name}
+            onClick={() => setView(name)}
+            className="rounded-md px-3 py-1 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring aria-pressed:bg-muted aria-pressed:font-medium"
+          >
+            {i18n.t(`board.view.${name}`)}
+          </button>
+        ))}
+      </div>
+      {view === "kanban" ? <KanbanView nodeId={node.id} /> : <TableView nodeId={node.id} />}
+    </div>
+  );
+}
+
+function KanbanView({ nodeId }: { nodeId: string }) {
+  const board = useBoard(nodeId);
+  return <BoardKanban board={board} />;
+}
+
+/**
+ * ⚠️ **The filter lives HERE, inside the table's own branch, not beside both views.** Held one
+ * level up it would survive a switch to the kanban board — which draws whatever the query answered
+ * and would then show a column full and the rest empty, with nothing on screen saying why. That is
+ * the quiet failure: cards that look deleted. Unmounting the table takes its filter with it, and
+ * the kanban asks for the whole board every time.
+ */
+function TableView({ nodeId }: { nodeId: string }) {
+  const [filter, setFilter] = useState<Partial<BoardTaskFilter>>({});
+  const [sort, setSort] = useState<Sort | null>(null);
+  const [group, setGroup] = useState<GroupKey>("none");
+  const board = useBoard(nodeId, filter);
+  return (
+    <BoardTable
+      board={board}
+      filter={filter}
+      onFilter={setFilter}
+      sort={sort}
+      onSort={setSort}
+      group={group}
+      onGroup={setGroup}
+    />
+  );
+}

package/src/board/board-table/board-table.ts

@@ -0,0 +1,135 @@
+import type { BoardTask } from "@anchrd/intel-contract/board";
+import type { ColumnWithCards } from "@/board/board-data/board-data.types.ts";
+
+export type SortKey = "title" | "status" | "assignee" | "due" | "dependsOn";
+export type GroupKey = "none" | "status" | "assignee";
+
+export interface Sort {
+  key: SortKey;
+  direction: "asc" | "desc";
+}
+
+/**
+ * One line of the table: the card, plus the two things the card cannot answer about itself.
+ *
+ * `columnTitle` is its status resolved against the board's configuration, and `blocking` is what
+ * `dependsOn` points at — the blocking card's title when it is on this board, its bare id when it
+ * is not. ⚠️ **The id is shown rather than hidden**: a dependency on something outside this board
+ * is exactly the case somebody needs to see, and an empty cell claims there is no dependency.
+ */
+export interface Row {
+  task: BoardTask;
+  columnTitle: string;
+  blocking: string | null;
+}
+
+export function rowsOf(columns: ColumnWithCards[]): Row[] {
+  const titles = new Map<string, string>();
+  for (const entry of columns) {
+    for (const card of entry.cards) titles.set(card.id, card.title);
+  }
+  return columns.flatMap((entry) =>
+    entry.cards.map((task) => ({
+      task,
+      columnTitle: entry.column.title,
+      blocking: task.dependsOn === null ? null : (titles.get(task.dependsOn) ?? task.dependsOn),
+    })),
+  );
+}
+
+function cellOf(row: Row, key: SortKey): string | null {
+  switch (key) {
+    case "title":
+      return row.task.title;
+    case "status":
+      return row.columnTitle;
+    case "assignee":
+      return row.task.assigneeId;
+    case "due":
+      return row.task.dueDate;
+    case "dependsOn":
+      return row.blocking;
+  }
+}
+
+/**
+ * The table in one order.
+ *
+ * ⚠️ **An empty cell sorts last in BOTH directions, and that is not a preference.** A card without
+ * a due date is not the earliest one — it is one whose date nobody knows, and putting it first is a
+ * table that answers "what is due next" with the rows that have no answer. Comparing `null` with a
+ * string instead is worse than wrong: `null < "2026-08-19"` and `null > "2026-08-19"` are BOTH
+ * false, so the comparator claims equality between rows that are not equal, and the order then
+ * depends on where the dateless rows happened to sit.
+ *
+ * ⚠️ **The sort is stable and the incoming order is the tiebreaker.** Rows arrive in the board's
+ * own order — configured columns first, cards by position — so two cards with the same due date
+ * keep the order the board gives them rather than swapping on every render.
+ */
+export function sortRows(rows: Row[], sort: Sort | null): Row[] {
+  if (sort === null) return rows;
+  const factor = sort.direction === "asc" ? 1 : -1;
+  return [...rows].sort((left, right) => {
+    const a = cellOf(left, sort.key);
+    const b = cellOf(right, sort.key);
+    if (a === null && b === null) return 0;
+    if (a === null) return 1;
+    if (b === null) return -1;
+    // An ISO timestamp compares correctly as a string, so one comparison serves every column.
+    return factor * a.localeCompare(b, undefined, { numeric: true, sensitivity: "base" });
+  });
+}
+
+export interface Group {
+  /**
+   * The VALUE the rows were grouped by, not the text to draw.
+   *
+   * ⚠️ The difference matters for the assignee: the value is a Gate principal id, and an id must
+   * never reach the screen (`user-name.ts`, #258). The view resolves it to a name or to the word
+   * for somebody it cannot name; this module has no business deciding that, and returning a
+   * ready-made label would have made the id the obvious thing to put there.
+   *
+   * `null` is the group the key does not answer for — unassigned, mostly.
+   */
+  key: string | null;
+  rows: Row[];
+}
+
+/**
+ * The rows in groups, in the order the rows themselves arrive.
+ *
+ * ⚠️ **Not alphabetically.** Grouped by status, the groups are the board's columns, and their order
+ * carries meaning the alphabet destroys: `todo, doing, done` would be drawn `doing, done, todo`.
+ * Walking the rows and appending each new group as it first appears keeps the board's order for
+ * free — and keeps whatever `sortRows` decided when the grouping key is something else.
+ */
+export function groupRows(rows: Row[], key: GroupKey): Group[] {
+  if (key === "none") return [{ key: null, rows }];
+  const groups: Group[] = [];
+  for (const row of rows) {
+    const value = key === "status" ? row.columnTitle : row.task.assigneeId;
+    const existing = groups.find((group) => group.key === value);
+    if (existing === undefined) groups.push({ key: value, rows: [row] });
+    else existing.rows.push(row);
+  }
+  return groups;
+}
+
+/** What the header of a sortable column has to say for a reader who cannot see the arrow. */
+export function ariaSortOf(sort: Sort | null, key: SortKey): "ascending" | "descending" | "none" {
+  if (sort === null || sort.key !== key) return "none";
+  return sort.direction === "asc" ? "ascending" : "descending";
+}
+
+/**
+ * What a click on a header means.
+ *
+ * ⚠️ Three states, not two: ascending, descending, and back to the board's own order. Without the
+ * third there is no way back — once a table is sorted it stays sorted, and the order the board was
+ * arranged in by hand is unreachable for the rest of the session.
+ */
+export function nextSort(sort: Sort | null, key: SortKey): Sort | null {
+  if (sort === null || sort.key !== key) return { key, direction: "asc" };
+  if (sort.direction === "asc") return { key, direction: "desc" };
+  return null;
+}

package/src/board/board-table/board-table.tsx

@@ -0,0 +1,199 @@
+import type { BoardColumn, BoardTaskFilter } from "@anchrd/intel-contract/board";
+import { isFiltering } from "@/board/board-data/board-data.ts";
+import type { BoardHandle } from "@/board/board-data/board-data.types.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { useUserName } from "@/user-name/user-name.ts";
+import {
+  ariaSortOf,
+  type GroupKey,
+  groupRows,
+  nextSort,
+  type Row,
+  rowsOf,
+  type Sort,
+  type SortKey,
+  sortRows,
+} from "./board-table.ts";
+
+const headers: { key: SortKey; labelKey: string }[] = [
+  { key: "title", labelKey: "board.column.title" },
+  { key: "status", labelKey: "board.column.status" },
+  { key: "assignee", labelKey: "board.column.assignee" },
+  { key: "due", labelKey: "board.column.due" },
+  // ⚠️ `dependsOn` is a column of its own, and that is the condition under which the board graph
+  // stays parked (#651, #653). Stored but undrawn, a dependency is a card that waits for a reason
+  // nobody can see.
+  { key: "dependsOn", labelKey: "board.column.dependsOn" },
+];
+
+export function BoardTable({
+  board,
+  filter,
+  onFilter,
+  sort,
+  onSort,
+  group,
+  onGroup,
+}: {
+  board: BoardHandle;
+  filter: Partial<BoardTaskFilter>;
+  onFilter(next: Partial<BoardTaskFilter>): void;
+  sort: Sort | null;
+  onSort(next: Sort | null): void;
+  group: GroupKey;
+  onGroup(next: GroupKey): void;
+}) {
+  const i18n = useI18n();
+
+  if (board.isPending) {
+    return <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
+  }
+  if (board.isError) {
+    return (
+      <p role="alert" className="p-6 text-sm text-destructive">
+        {i18n.t("board.failed")}
+      </p>
+    );
+  }
+
+  const groups = groupRows(sortRows(rowsOf(board.columns), sort), group);
+  const configured: BoardColumn[] = board.columns
+    .filter((entry) => entry.unknown !== true)
+    .map((entry) => entry.column);
+  // ⚠️ The answer this is measured against is the FILTERED one. A board full of cards, narrowed to
+  // a column that happens to be empty, would otherwise be told it has no cards at all — and the
+  // reader would go looking for the cards they just watched disappear.
+  const empty = board.columns.every((entry) => entry.cards.length === 0);
+  const emptyMessage = isFiltering(filter) ? "board.filterEmpty" : "board.tableEmpty";
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col gap-3 p-4" aria-busy={board.isWriting}>
+      <div className="flex flex-wrap items-center gap-4 text-sm">
+        <label className="flex items-center gap-2">
+          {i18n.t("board.filter.status")}
+          {/* ⚠️ This one TRAVELS. `useBoard` carries the filter in the query key and sends it, so
+              the server answers with the cards that match. A view that fetched everything and hid
+              rows in the browser would look identical on screen and be a different thing over the
+              wire — which is why the test asserts the argument of the second request. */}
+          <select
+            className="rounded-md border bg-background px-2 py-1"
+            value={filter.status ?? ""}
+            onChange={(event) =>
+              onFilter(
+                event.target.value === ""
+                  ? { ...filter, status: undefined }
+                  : { ...filter, status: event.target.value },
+              )
+            }
+          >
+            <option value="">{i18n.t("board.filter.all")}</option>
+            {configured.map((column) => (
+              <option key={column.id} value={column.id}>
+                {column.title}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="flex items-center gap-2">
+          {i18n.t("board.groupBy")}
+          <select
+            className="rounded-md border bg-background px-2 py-1"
+            value={group}
+            onChange={(event) => onGroup(event.target.value as GroupKey)}
+          >
+            <option value="none">{i18n.t("board.group.none")}</option>
+            <option value="status">{i18n.t("board.group.status")}</option>
+            <option value="assignee">{i18n.t("board.group.assignee")}</option>
+          </select>
+        </label>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-auto">
+        <table className="w-full border-collapse text-left text-sm">
+          <thead>
+            <tr className="border-b">
+              {headers.map((header) => (
+                <th
+                  key={header.key}
+                  scope="col"
+                  aria-sort={ariaSortOf(sort, header.key)}
+                  className="p-2 font-medium"
+                >
+                  <button
+                    type="button"
+                    onClick={() => onSort(nextSort(sort, header.key))}
+                    className="inline-flex items-center gap-1 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {i18n.t(header.labelKey)}
+                    <span aria-hidden="true" className="text-xs text-muted-foreground">
+                      {sort?.key === header.key ? (sort.direction === "asc" ? "▲" : "▼") : ""}
+                    </span>
+                  </button>
+                </th>
+              ))}
+              <th scope="col" className="p-2 font-medium">
+                {i18n.t("board.column.labels")}
+              </th>
+            </tr>
+          </thead>
+          {groups.map((entry) => (
+            <tbody key={entry.key ?? "-none-"}>
+              {group === "none" ? null : (
+                <tr className="border-b bg-muted/40">
+                  <th scope="rowgroup" colSpan={headers.length + 1} className="p-2 text-left">
+                    {group === "assignee" ? (
+                      <Assignee id={entry.key} />
+                    ) : (
+                      (entry.key ?? i18n.t("board.unassigned"))
+                    )}
+                    <span className="ml-2 text-xs font-normal text-muted-foreground tabular-nums">
+                      {entry.rows.length}
+                    </span>
+                  </th>
+                </tr>
+              )}
+              {entry.rows.map((row) => (
+                <Line key={row.task.id} row={row} />
+              ))}
+            </tbody>
+          ))}
+        </table>
+        {empty ? <p className="p-6 text-sm text-muted-foreground">{i18n.t(emptyMessage)}</p> : null}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Who a card belongs to, by the one rule this application has for saying so.
+ *
+ * ⚠️ **Never the raw id.** Intel has no user directory — `useUserName` can resolve exactly one id,
+ * the signed-in person's — and an id under the heading "assigned to" is not an answer to "who", it
+ * is the question again in smaller type. It would also put a Gate principal identifier on a screen
+ * that has no reason to carry one (`user-name.ts`, #258). Somebody this browser cannot name is
+ * drawn as somebody, which is true, and the word changes in exactly one place when Intel gains a
+ * lookup (#261).
+ */
+function Assignee({ id }: { id: string | null }) {
+  const i18n = useI18n();
+  const name = useUserName(id);
+  if (id === null) return <>{i18n.t("board.unassigned")}</>;
+  return <>{name ?? i18n.t("node.someUser")}</>;
+}
+
+function Line({ row }: { row: Row }) {
+  return (
+    <tr className="border-b last:border-0">
+      <td className="p-2">{row.task.title}</td>
+      <td className="p-2">{row.columnTitle}</td>
+      <td className="p-2 text-muted-foreground">
+        <Assignee id={row.task.assigneeId} />
+      </td>
+      {/* The date, not the time: a board deals in days, and a timestamp in a cell is noise that
+          pushes the columns beside it off the screen. */}
+      <td className="p-2 tabular-nums">{row.task.dueDate?.slice(0, 10) ?? ""}</td>
+      <td className="p-2">{row.blocking ?? ""}</td>
+      <td className="p-2 text-muted-foreground">{row.task.labels.join(", ")}</td>
+    </tr>
+  );
+}

package/src/data/intel-data-provider/intel-data-provider.ts

@@ -1,4 +1,11 @@
 import { type NamedOrCounted, ProblemDetails, SessionUser } from "@anchrd/intel-contract";
+import {
+  BoardGetInput,
+  BoardTaskCreateInput,
+  BoardTaskUpdateInput,
+  BoardUpdateInput,
+  BoardView,
+} from "@anchrd/intel-contract/board";
 import { BundleImportResult } from "@anchrd/intel-contract/bundle";
 import {
   ArchiveFlowInput,
@@ -344,6 +351,49 @@ export function createIntelDataProvider(
     async listNodeVersions(nodeId) {
       return await request(`/nodes/${encodeURIComponent(nodeId)}/versions`, NodeVersionList);
     },
+    async getBoard(input) {
+      const parsed = BoardGetInput.parse(input);
+      // ⚠️ Only the filters the caller actually named travel. Sending an empty `status` would ask
+      // the server for the column called "" rather than for every column — the same rule the flow
+      // list follows above, and for the same reason.
+      const params = new URLSearchParams();
+      if (parsed.status !== undefined) params.set("status", parsed.status);
+      if (parsed.assigneeId !== undefined) params.set("assigneeId", parsed.assigneeId);
+      if (parsed.dueBefore !== undefined) params.set("dueBefore", parsed.dueBefore);
+      if (parsed.dependsOn !== undefined) params.set("dependsOn", parsed.dependsOn);
+      if (parsed.includeArchived) params.set("includeArchived", "true");
+      const query = params.toString();
+      return await request(
+        `/boards/${encodeURIComponent(parsed.boardId)}${query === "" ? "" : `?${query}`}`,
+        BoardView,
+      );
+    },
+    async updateBoard(input) {
+      const parsed = BoardUpdateInput.parse(input);
+      return await request(`/boards/${encodeURIComponent(parsed.boardId)}`, BoardView, {
+        method: "PATCH",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async createBoardTask(input) {
+      const parsed = BoardTaskCreateInput.parse(input);
+      return await request(`/boards/${encodeURIComponent(parsed.boardId)}/tasks`, BoardView, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    // ⚠️ The board id is in the path although the call identifies the card by its own id: the route
+    // mirrors the tool name segment for segment (`board_task_update`), and a card that could be
+    // addressed without its board would invite a caller to move one between boards — which the
+    // service refuses on purpose (#377).
+    async updateBoardTask(boardId, input) {
+      const parsed = BoardTaskUpdateInput.parse(input);
+      return await request(
+        `/boards/${encodeURIComponent(boardId)}/tasks/${encodeURIComponent(parsed.taskId)}`,
+        BoardView,
+        { method: "PATCH", body: JSON.stringify(parsed) },
+      );
+    },
     async updateNode(input) {
       const parsed = UpdateNodeInput.parse(input);
       return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}`, Node, {

package/src/data/intel-data-provider/intel-data-provider.types.ts

@@ -1,4 +1,11 @@
 import type { SessionUser } from "@anchrd/intel-contract";
+import type {
+  BoardGetInput,
+  BoardTaskCreateInput,
+  BoardTaskUpdateInput,
+  BoardUpdateInput,
+  BoardView,
+} from "@anchrd/intel-contract/board";
 import type { BundleImportResult } from "@anchrd/intel-contract/bundle";
 import type {
   ArchiveFlowInput,
@@ -95,6 +102,21 @@ export interface IntelDataProvider {
    * would be reporting the wrong thing.
    */
   reindexNodes(): Promise<ReindexResult>;
+  /**
+   * One board, in one answer: its columns and every card the caller may see, without the card
+   * bodies (#648).
+   *
+   * ⚠️ **One call, not one per card.** A screen that fetched each card separately would look
+   * identical and is the reason this endpoint exists — the test that guards it counts requests
+   * rather than pixels.
+   */
+  getBoard(input: BoardGetInput): Promise<BoardView>;
+  updateBoard(input: BoardUpdateInput): Promise<BoardView>;
+  createBoardTask(input: BoardTaskCreateInput): Promise<BoardView>;
+  // Every write answers with the WHOLE board rather than the row it changed: a drag moves one card
+  // and shifts nothing else, but a column's contents are what the screen draws, and re-deriving
+  // them from a single row is where a second, quietly different truth would start.
+  updateBoardTask(boardId: string, input: BoardTaskUpdateInput): Promise<BoardView>;
   listNodes(input?: Partial<ListNodesInput>): Promise<NodeList>;
   // One level of the shared tree: the documents and the flows filed in the same folder, in one
   // sorted list. Per level rather than recursive, so opening a folder is what costs a request.

package/src/document-link/document-link.tsx

@@ -1,5 +1,4 @@
 import { DocumentLinkInlineType } from "@anchrd/intel-contract/node";
-import { BlockNoteSchema } from "@blocknote/core";
 import { createReactInlineContentSpec } from "@blocknote/react";
 import { FileText, Link2Off } from "lucide-react";
 import { createContext, useContext } from "react";
@@ -87,23 +86,6 @@ export const documentLinkSpec = createReactInlineContentSpec(
   },
 );
 
-// One schema for the editor and for everything that reads its documents back: BlockNote's defaults
-// plus the one inline element #41 adds.
-//
-// ⚠️ `extend` rather than `create({ inlineContentSpecs: { ...defaults, documentLink } })`. Both
-// build the same schema at run time, but only `extend` keeps the added type in the schema's own
-// generics under this repo's `exactOptionalPropertyTypes` — with the spread form the editor infers
-// BlockNote's default schema, typechecks, and then refuses to insert a document link.
-export const intelEditorSchema = BlockNoteSchema.create().extend({
-  inlineContentSpecs: { documentLink: documentLinkSpec },
-});
-
-// The schema carries its own editor and block types as declaration-only properties, which is the
-// only way to name them here: writing `BlockNoteEditor<typeof schema.blockSchema, ...>` by hand
-// fails BlockNote's own constraint under `exactOptionalPropertyTypes`.
-export type IntelEditor = (typeof intelEditorSchema)["BlockNoteEditor"];
-export type IntelEditorPartialBlock = (typeof intelEditorSchema)["PartialBlock"];
-
 /**
  * The IDs a stored BlockNote document links to.
  *

package/src/editor-schema/editor-schema.ts

@@ -0,0 +1,21 @@
+import { BlockNoteSchema } from "@blocknote/core";
+import { documentLinkSpec } from "@/document-link/document-link.tsx";
+import { frontmatterSpec } from "@/frontmatter/frontmatter.tsx";
+
+// One schema for the editor and for everything that reads its documents back: BlockNote's defaults
+// plus what Intel adds — the inline element of #41 and the head block of #657.
+//
+// ⚠️ `extend` rather than `create({ inlineContentSpecs: { ...defaults, documentLink } })`. Both
+// build the same schema at run time, but only `extend` keeps the added types in the schema's own
+// generics under this repo's `exactOptionalPropertyTypes` — with the spread form the editor infers
+// BlockNote's default schema, typechecks, and then refuses to insert a document link.
+export const intelEditorSchema = BlockNoteSchema.create().extend({
+  inlineContentSpecs: { documentLink: documentLinkSpec },
+  blockSpecs: { frontmatter: frontmatterSpec() },
+});
+
+// The schema carries its own editor and block types as declaration-only properties, which is the
+// only way to name them here: writing `BlockNoteEditor<typeof schema.blockSchema, ...>` by hand
+// fails BlockNote's own constraint under `exactOptionalPropertyTypes`.
+export type IntelEditor = (typeof intelEditorSchema)["BlockNoteEditor"];
+export type IntelEditorPartialBlock = (typeof intelEditorSchema)["PartialBlock"];

package/src/frontmatter/frontmatter-markdown.ts

@@ -0,0 +1,63 @@
+import type { IntelEditor, IntelEditorPartialBlock } from "@/editor-schema/editor-schema.ts";
+import { FrontmatterBlockType, splitFrontmatter } from "@/frontmatter/frontmatter.tsx";
+
+/**
+ * The two halves of #657, and they only work as a pair.
+ *
+ * Before them the editor had no idea what a head was, and remark had no reason to invent one: it
+ * read `---` as a thematic break, the keys as a paragraph, and the LAST key plus the closing `---`
+ * as a setext heading — so `## autor: Jack` stood above the document's own title. That was the
+ * visible half.
+ *
+ * ⚠️ The invisible half is the one that cost data. `blocksToMarkdownLossy` is what the editor
+ * writes into `payload.markdown`, and that field is not decoration: `indexing.ts` pulls it — and
+ * nothing else — into full text and vectors, so it is the whole of what a search can match.
+ * Serialising those blocks back gave `***`, `\`-hard-breaks and `## autor: Jack`, which is no
+ * longer a head at all. Opening a document and saving it left its metadata unfindable, and nothing
+ * anywhere went red.
+ *
+ * Therefore: whatever is parsed out here is what is written back out there, byte for byte. The two
+ * functions are each other's inverse over the head, and the test that matters asserts exactly that.
+ */
+
+/**
+ * Markdown to blocks, with the head lifted out of remark's way.
+ *
+ * ⚠️ Synchronous, because `tryParseMarkdownToBlocks` is. Making it `async` would put the load path
+ * behind a tick, and the effect in `node-editor.tsx` moves `savedSnapshot` immediately after it —
+ * a gap there is a document that reports itself unsaved the moment it opens (#115).
+ */
+export function markdownToBlocks(editor: IntelEditor, markdown: string): IntelEditorPartialBlock[] {
+  const { raw, body } = splitFrontmatter(markdown);
+  const blocks = editor.tryParseMarkdownToBlocks(body) as IntelEditorPartialBlock[];
+  if (raw === null) return blocks;
+  return [{ type: FrontmatterBlockType, props: { raw } } as IntelEditorPartialBlock, ...blocks];
+}
+
+/**
+ * Blocks to markdown, with the head written back as a head.
+ *
+ * ⚠️ The head is emitted from `raw`, never re-serialised from anything parsed. A head that is not
+ * valid YAML comes back exactly as it went in, and the roundtrip has no gap for a parser to fall
+ * into.
+ */
+export async function blocksToMarkdown(editor: IntelEditor, blocks: unknown[]): Promise<string> {
+  const all = blocks as { type?: string; props?: { raw?: unknown } }[];
+  // ⚠️ Found by type, NOT taken from position 0. The head is a block like any other: BlockNote's
+  // drag handle moves it, and typing above the first block pushes it down. A positional guard falls
+  // through to `blocksToMarkdownLossy` for exactly those documents, and that path has no head in it
+  // — it serialises the block's rendered DOM, so `payload.markdown` would carry the word "Metadata"
+  // where the metadata used to be. That is the same silent loss #657 is about, one gesture away.
+  const at = all.findIndex((block) => block?.type === FrontmatterBlockType);
+  if (at < 0) return editor.blocksToMarkdownLossy(blocks as never);
+  const head = all[at];
+  const raw = typeof head?.props?.raw === "string" ? head.props.raw : "";
+  // A document has ONE head, and it belongs at the top wherever the block ended up. Any further
+  // head block stays in the body and is serialised by the spec's own `toExternalHTML` — as a code
+  // block, which is visible and lossless without claiming to be a second head.
+  const body = await editor.blocksToMarkdownLossy(all.filter((_, index) => index !== at) as never);
+  // ⚠️ The blank line after the closing fence is part of the contract, not tidiness: without it the
+  // first line of the body sits against the fence, and a `# Title` there would be read back as part
+  // of nothing in particular the next time round.
+  return `---\n${raw}\n---\n\n${body}`;
+}