@anchrd/intel-ui 0.36.0 → 0.38.0

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/flows/flows.tsx

@@ -675,6 +675,7 @@ function FlowsEditor() {
           saving={save.isPending}
           canMutate={canMutate}
           incomplete={stepsMissingServer.map((node) => ({ label: node.data.node.label }))}
+          scrollingView={selection.view === "runs"}
           onSave={() => save.mutate()}
           onPublish={() => setPublishing(true)}
         />
@@ -943,6 +944,7 @@ function FlowTitle({
   saving,
   canMutate,
   incomplete,
+  scrollingView,
   onSave,
   onPublish,
 }: {
@@ -950,6 +952,9 @@ function FlowTitle({
   dirty: boolean;
   saving: boolean;
   canMutate: boolean;
+  // Whether what stands below this line can scroll under it. The runs list can and earns its edge
+  // the usual way; the canvas and the graph pan instead, and would never get one (#634).
+  scrollingView: boolean;
   // Tool steps that name no server yet. They cannot be saved, so the refusal is shown here rather
   // than fetched from the server as a message that names no step.
   incomplete: Array<{ label: string }>;
@@ -974,7 +979,12 @@ function FlowTitle({
     // loudest thing in this line and used to hold the edge; the menu takes it, because a menu one can
     // hit without looking is worth more than the primary button being outermost. `TitleRow` is what
     // enforces that — nothing passed in here can get past the menu.
-    <TitleRow title={flow.title} description={flow.description} target={{ type: "flow", flow }}>
+    <TitleRow
+      title={flow.title}
+      description={flow.description}
+      target={{ type: "flow", flow }}
+      separated={!scrollingView}
+    >
       {/* ⚠️ #454: the toggle used to stand in the global header, beside the search — where what
           applies EVERYWHERE stands. But it says how THIS flow is shown, and so belongs in the line
           that names this flow. A flow is the only level with runs, and therefore the only one with

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}`;
+}

package/src/frontmatter/frontmatter.tsx

@@ -0,0 +1,184 @@
+import { createReactBlockSpec } from "@blocknote/react";
+import { ChevronRight } from "lucide-react";
+import { createContext, Fragment, useContext, useState } from "react";
+
+/**
+ * The head of a knowledge node, as one block (#657).
+ *
+ * ⚠️ The type lives here rather than in the contract, unlike `documentLink`. The server reads
+ * document links out of the stored blocks and therefore has to know that word; nothing on the
+ * server side ever looks at this one. What the server reads of a head is the `markdown` field
+ * beside the blocks — which is exactly why the export half of this module matters more than the
+ * block does.
+ */
+export const FrontmatterBlockType = "frontmatter";
+
+/**
+ * The head, exactly as it stood between the two fences.
+ *
+ * ⚠️ Stored raw, never as parsed pairs, and this is the whole reason the roundtrip cannot lose
+ * anything. A head that is not valid YAML — a typo, a half-written list, a value somebody is in the
+ * middle of writing — travels through unchanged and comes back out as it went in. Parsing happens
+ * for the DISPLAY only, in `frontmatterEntries`, and a line that will not split is shown as it
+ * stands rather than dropped. The alternative, parsing on the way in and re-emitting on the way
+ * out, turns every gap in the parser into silent data loss at the next save.
+ */
+const FRONTMATTER_PROPS = { raw: { default: "" } } as const;
+
+/**
+ * A head at the very start of the document, and only there.
+ *
+ * ⚠️ No `m` flag, and the `^` is doing real work — though not on the documents one first reaches
+ * for. `exec` without `g` finds a head at position 0 with or without the anchor; what the anchor
+ * decides is a document that has NO head and two rules further down. Unanchored, the first rule and
+ * the text after it are swallowed into an invented head. That is the case its test uses.
+ *
+ * ⚠️ `(?![ \t]*\r?\n)` — a head begins on the line after the fence, never with a blank one. This
+ * is what keeps `---\n\nErster Teil\n\n---` from reading as a head: nothing is lost from
+ * `markdown` when it does, but the rule, the text and the second rule all vanish behind a folded
+ * "Metadata" strip, and the reader has no way to know where their paragraph went.
+ *
+ * `[\s\S]+?` rather than `*?` says the same thing the falsy check in `splitFrontmatter` already
+ * says — an empty capture is no head — and is kept for saying it here rather than two lines later.
+ * It is not what makes `---\n---` two thematic breaks; that check is.
+ *
+ * The blank lines after the closing fence belong to the fence, not to the body. Leaving them on
+ * would make `body` start with an empty line that the head had put there — and the join in
+ * `blocksToMarkdown` writes exactly one back, so taking them here is what keeps a document from
+ * growing a blank line per save.
+ */
+const LEADING_FRONTMATTER =
+  /^---\r?\n(?![ \t]*\r?\n)([\s\S]+?)\r?\n---[ \t]*(?:\r?\n|$)(?:[ \t]*\r?\n)*/;
+
+/**
+ * A document's markdown, cut into its head and the rest.
+ *
+ * `raw` is `null` when there is no head, and then `body` is the whole input — the caller has one
+ * branch, not two shapes to tell apart.
+ */
+export function splitFrontmatter(markdown: string): { raw: string | null; body: string } {
+  const match = LEADING_FRONTMATTER.exec(markdown);
+  if (!match?.[1]) return { raw: null, body: markdown };
+  return { raw: match[1], body: markdown.slice(match[0].length) };
+}
+
+/**
+ * The head split into what a reader sees, for display only.
+ *
+ * ⚠️ It is never the source of the stored value — `raw` is. A line without a colon is not a broken
+ * pair but a normal part of YAML (a list item under the key above it, a folded value's second
+ * line), and it is shown whole rather than split at nothing.
+ */
+export function frontmatterEntries(raw: string): { key: string; value: string }[] {
+  return raw
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const colon = line.indexOf(":");
+      const continues = /^[\s-]/.test(line);
+      if (colon < 0 || continues) return { key: "", value: line.trim() };
+      return { key: line.slice(0, colon).trim(), value: line.slice(colon + 1).trim() };
+    });
+}
+
+/**
+ * The two words the block says. They travel in a context for the same reason the document link's
+ * one word does: a block is rendered by the editor, not by a view that could reach the catalog.
+ */
+export interface FrontmatterLabels {
+  summary: string;
+  expand: string;
+}
+
+const FrontmatterContext = createContext<FrontmatterLabels>({
+  summary: "Metadata",
+  expand: "Show metadata",
+});
+
+export const FrontmatterProvider = FrontmatterContext.Provider;
+
+export function FrontmatterHead({ raw }: { raw: string }) {
+  const labels = useContext(FrontmatterContext);
+  // ⚠️ Local state, deliberately NOT a block prop. The fold is how the head is being looked at, not
+  // what it says — and a prop would put it into the stored document, which means opening the head
+  // to read it would mark the document unsaved and offer to write a "change" nobody made.
+  const [open, setOpen] = useState(false);
+  const entries = frontmatterEntries(raw);
+
+  return (
+    <div
+      // The editor owns the text around this; the head itself is not typed into.
+      contentEditable={false}
+      data-frontmatter={open ? "open" : "closed"}
+      className="my-2 w-full rounded-md border border-border bg-muted/40"
+    >
+      <button
+        type="button"
+        aria-expanded={open}
+        aria-label={labels.expand}
+        onClick={() => setOpen(!open)}
+        className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <ChevronRight
+          aria-hidden="true"
+          className={
+            open ? "size-3.5 rotate-90 transition-transform" : "size-3.5 transition-transform"
+          }
+        />
+        {/* ⚠️ Closed, it says THAT there is a head, never what is in it. A preview of `title` or
+            `status` here would be the H2 from #657 again, one size smaller. */}
+        {labels.summary}
+      </button>
+      {open ? (
+        <dl className="grid grid-cols-[max-content_1fr] gap-x-4 gap-y-1 px-3 pb-3 font-mono text-xs">
+          {entries.map((entry, index) =>
+            entry.key ? (
+              // Nothing in a head is unique — two `- Q-04` lines under `quellen` are the ordinary
+              // case — so the position is the only honest key. It is also a safe one here: the list
+              // is derived from an immutable `raw` and is never sorted, inserted into or filtered.
+              // biome-ignore lint/suspicious/noArrayIndexKey: a head's lines have no other key
+              <Fragment key={index}>
+                <dt className="text-muted-foreground">{entry.key}</dt>
+                <dd className="break-words text-foreground">{entry.value}</dd>
+              </Fragment>
+            ) : (
+              // A line that is not a pair — a list item, a folded value's second line — spans both
+              // columns rather than being squeezed into the value one, and is indented so it still
+              // reads as belonging to the key above it.
+              // biome-ignore lint/suspicious/noArrayIndexKey: a head's lines have no other key
+              <dd key={index} className="col-span-2 break-words pl-4 text-foreground">
+                {entry.value}
+              </dd>
+            ),
+          )}
+        </dl>
+      ) : null}
+    </div>
+  );
+}
+
+export const frontmatterSpec = createReactBlockSpec(
+  {
+    type: FrontmatterBlockType,
+    propSchema: FRONTMATTER_PROPS,
+    // The head is not editable text. It is written by whoever writes the document's markdown, and a
+    // caret inside it would let a reader break `type:` without it looking like anything happened.
+    content: "none",
+  },
+  {
+    render: (props) => <FrontmatterHead raw={String(props.block.props.raw)} />,
+    // ⚠️ The net under `blocksToMarkdown`, for every path that does not go through it. Without a
+    // serialiser BlockNote falls back to the RENDERED DOM, so a head would leave the editor as the
+    // word "Metadata" — its own label, in place of the metadata. A fenced block is not a head, but
+    // it is visible and it is lossless, which is what a fallback owes.
+    //
+    // ⚠️ `<pre><code>`, not `<pre>` alone. Measured: a bare `<pre>` survives the HTML export and is
+    // then dropped by the HTML-to-markdown step, which returns `"\n"` — a net that looks like one
+    // in the HTML and catches nothing where it matters.
+    toExternalHTML: (props) => (
+      <pre>
+        <code>{String(props.block.props.raw)}</code>
+      </pre>
+    ),
+  },
+);