@agent-native/toolkit 0.5.1 → 0.7.0

package/src/editor/gfmDoc.spec.ts

@@ -0,0 +1,230 @@
+// @vitest-environment happy-dom
+
+import type { JSONContent } from "@tiptap/core";
+import { describe, expect, it } from "vitest";
+
+import { gfmToProseJSON, proseJSONToGfm } from "./gfmDoc.js";
+
+/**
+ * GFM ↔ ProseMirror primitive for the plan single-doc editor.
+ *
+ * `gfmToProseJSON` / `proseJSONToGfm` go through ONE memoized headless Tiptap
+ * editor built from the SAME `createSharedEditorExtensions({ dialect: "gfm",
+ * features: { image: true } })` config the live plan editor uses, plus the
+ * `RunId` extension. These tests assert two things:
+ *
+ *   1. `proseJSONToGfm(gfmToProseJSON(md))` normalizes STABLY — once a corpus
+ *      entry has been through the converter, running it through again is a
+ *      fixed point (the live editor re-serializes the whole doc on every edit,
+ *      so a non-stable round-trip would churn untouched prose on first edit).
+ *   2. `gfmToProseJSON` produces the EXPECTED top-level node types for a known
+ *      corpus, so the bridge can rely on the shapes it walks.
+ *
+ * The headless editor needs a DOM (ProseMirror's EditorView); this file runs
+ * under `happy-dom` (the same env the other editor specs use), proving the
+ * primitive works in jsdom-style test runners as well as the browser.
+ */
+
+/** First pass: md → prose → md. */
+function once(markdown: string): string {
+  return proseJSONToGfm(gfmToProseJSON(markdown));
+}
+
+/** Asserts the converter reaches a fixed point (re-running is a no-op). */
+function expectStableRoundTrip(markdown: string): void {
+  const first = once(markdown);
+  const second = once(first);
+  expect(second).toBe(first);
+}
+
+/** Top-level node types produced for a markdown string. */
+function topLevelTypes(markdown: string): string[] {
+  return gfmToProseJSON(markdown).map((node) => node.type ?? "");
+}
+
+/**
+ * Top-level node types with any trailing empty paragraph(s) dropped.
+ *
+ * The markdown parser appends a trailing empty `paragraph` whenever the doc
+ * would otherwise end in a non-paragraph block (heading / list / code / table /
+ * blockquote). This is a genuine ProseMirror parse artifact — the GFM
+ * serializer drops it again, so the round-trip stays byte-stable — and the
+ * plan's doc→blocks bridge skips whitespace-only runs, so it is not meaningful
+ * content. These assertions focus on the meaningful leading block types.
+ */
+function meaningfulTypes(markdown: string): string[] {
+  const types = topLevelTypes(markdown);
+  while (
+    types.length > 1 &&
+    types[types.length - 1] === "paragraph" &&
+    isEmptyParagraph(gfmToProseJSON(markdown)[types.length - 1])
+  ) {
+    types.pop();
+  }
+  return types;
+}
+
+/** True when a paragraph node has no inline content (the trailing filler). */
+function isEmptyParagraph(node: JSONContent | undefined): boolean {
+  return node?.type === "paragraph" && (node.content ?? []).length === 0;
+}
+
+const PROSE_CORPUS: Record<string, string> = {
+  "heading 1": "# Heading 1",
+  "heading 2": "## Heading 2",
+  "heading 3": "### Heading 3",
+  paragraph: "A plain paragraph of prose.",
+  "bulleted list": "- One\n- Two\n- Three",
+  "numbered list": "1. One\n2. Two\n3. Three",
+  "task list": "- [ ] Todo item\n- [x] Done item",
+  blockquote: "> A quoted line.",
+  "fenced code block": "```ts\nconst x: number = 1;\n```",
+  "inline marks": "Text with **bold**, *italic*, `code`, and a word.",
+  link: "See [the docs](https://example.com/docs) for details.",
+  table: [
+    "| Name | Status |",
+    "| --- | --- |",
+    "| Alpha | Done |",
+    "| Beta | Open |",
+    "",
+    "Trailing paragraph so the table is not the last block.",
+  ].join("\n"),
+  "mixed body": [
+    "# Project Plan",
+    "",
+    "## Overview",
+    "",
+    "This plan covers the **rollout** of the new flow.",
+    "",
+    "- Step one",
+    "- Step two",
+    "",
+    "> A note to remember.",
+    "",
+    "```ts",
+    "const ready = true;",
+    "```",
+  ].join("\n"),
+};
+
+describe("gfmDoc GFM ↔ ProseMirror primitive", () => {
+  describe("round-trip is stable (fixed point)", () => {
+    for (const [name, markdown] of Object.entries(PROSE_CORPUS)) {
+      it(`stabilizes: ${name}`, () => {
+        expectStableRoundTrip(markdown);
+      });
+    }
+  });
+
+  describe("gfmToProseJSON produces expected node types", () => {
+    it("headings carry their level", () => {
+      expect(meaningfulTypes("# A\n\n## B\n\n### C")).toEqual([
+        "heading",
+        "heading",
+        "heading",
+      ]);
+      const levels = gfmToProseJSON("# A\n\n## B\n\n### C")
+        .filter((n) => n.type === "heading")
+        .map((n) => n.attrs?.level);
+      expect(levels).toEqual([1, 2, 3]);
+    });
+
+    it("paragraph", () => {
+      expect(meaningfulTypes("Just text.")).toEqual(["paragraph"]);
+    });
+
+    it("bulleted list", () => {
+      expect(meaningfulTypes("- a\n- b")).toEqual(["bulletList"]);
+    });
+
+    it("numbered list", () => {
+      expect(meaningfulTypes("1. a\n2. b")).toEqual(["orderedList"]);
+    });
+
+    it("task list", () => {
+      expect(meaningfulTypes("- [ ] a\n- [x] b")).toEqual(["taskList"]);
+    });
+
+    it("blockquote", () => {
+      expect(meaningfulTypes("> quoted")).toEqual(["blockquote"]);
+    });
+
+    it("fenced code block keeps language", () => {
+      const nodes = gfmToProseJSON("```ts\nconst x = 1;\n```");
+      const code = nodes.find((n) => n.type === "codeBlock");
+      expect(meaningfulTypes("```ts\nconst x = 1;\n```")).toEqual([
+        "codeBlock",
+      ]);
+      expect(code?.attrs?.language).toBe("ts");
+    });
+
+    it("GFM pipe table", () => {
+      expect(meaningfulTypes(["| H |", "| --- |", "| v |"].join("\n"))).toEqual(
+        ["table"],
+      );
+    });
+
+    it("inline marks land on the paragraph's text", () => {
+      const nodes = gfmToProseJSON("Has **bold**, *italic*, `code`.");
+      expect(nodes).toHaveLength(1);
+      const para = nodes[0] as JSONContent;
+      expect(para.type).toBe("paragraph");
+      const markTypes = new Set(
+        (para.content ?? []).flatMap((child) =>
+          (child.marks ?? []).map((m) => m.type),
+        ),
+      );
+      expect(markTypes.has("bold")).toBe(true);
+      expect(markTypes.has("italic")).toBe(true);
+      expect(markTypes.has("code")).toBe(true);
+    });
+
+    it("link mark carries the href", () => {
+      const nodes = gfmToProseJSON("See [docs](https://example.com).");
+      const para = nodes[0] as JSONContent;
+      const linkMark = (para.content ?? [])
+        .flatMap((child) => child.marks ?? [])
+        .find((m) => m.type === "link");
+      expect(linkMark?.attrs?.href).toBe("https://example.com");
+    });
+  });
+
+  describe("runId attribute", () => {
+    it("is omitted from serialized GFM markdown", () => {
+      const nodes = gfmToProseJSON("A paragraph.");
+      const stamped = nodes.map((n, i) =>
+        i === 0
+          ? { ...n, attrs: { ...(n.attrs ?? {}), runId: "block-123" } }
+          : n,
+      );
+      const markdown = proseJSONToGfm(stamped);
+      expect(markdown).toBe("A paragraph.");
+      expect(markdown).not.toContain("block-123");
+      expect(markdown).not.toContain("run-id");
+    });
+
+    it("survives a prose → JSON → prose round-trip when set", () => {
+      const nodes = gfmToProseJSON("A paragraph.");
+      const stamped = nodes.map((n, i) =>
+        i === 0 ? { ...n, attrs: { ...(n.attrs ?? {}), runId: "block-9" } } : n,
+      );
+      // Serializing drops runId (GFM), but the attribute is a valid schema
+      // attribute on the node JSON — re-parsing markdown yields runId: null.
+      const reparsed = gfmToProseJSON(proseJSONToGfm(stamped));
+      expect(reparsed[0]?.type).toBe("paragraph");
+      expect(reparsed[0]?.attrs?.runId ?? null).toBeNull();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("empty string yields a single empty paragraph", () => {
+      const nodes = gfmToProseJSON("");
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]?.type).toBe("paragraph");
+    });
+
+    it("empty node array serializes to empty markdown", () => {
+      expect(proseJSONToGfm([])).toBe("");
+    });
+  });
+});

package/src/editor/gfmDoc.ts

@@ -0,0 +1,92 @@
+import { Editor, type JSONContent } from "@tiptap/core";
+
+import { createSharedEditorExtensions } from "./extensions.js";
+import { RunId } from "./RunId.js";
+
+/**
+ * The GFM ↔ ProseMirror primitive for the plan single-doc editor.
+ *
+ * Plans keep `PlanContent.blocks[]` as the source of truth, but the editor is
+ * ONE ProseMirror/Tiptap document. The `doc ↔ blocks[]` serializer
+ * (`templates/plan/shared/plan-doc.ts`) needs to turn a `rich-text` block's GFM
+ * markdown into prose nodes and back. This module is that primitive.
+ *
+ * Both directions go through a SINGLE headless Tiptap {@link Editor} built from
+ * the exact same `createSharedEditorExtensions` config the live plan editor
+ * uses (`dialect: "gfm"`, `features.image: true`) plus the {@link RunId}
+ * extension, so the schema and the GFM serializer can never drift from the live
+ * editor. The instance is created lazily on first use and reused across calls.
+ *
+ * The headless editor needs a DOM (ProseMirror's `EditorView`). It works under
+ * `happy-dom` in vitest (see `gfmDoc.spec.ts`) and under the real browser DOM
+ * in production. `createElement` is used rather than mounting into the page so
+ * nothing is ever attached to the document.
+ */
+
+let sharedEditor: Editor | null = null;
+
+/**
+ * Lazily build (and memoize) the single headless editor. Throws if no DOM is
+ * available — this primitive is for the client / jsdom-style test envs only.
+ */
+function getSharedEditor(): Editor {
+  if (sharedEditor) return sharedEditor;
+  if (typeof document === "undefined") {
+    throw new Error(
+      "gfmDoc requires a DOM (document). It runs in the browser and in jsdom/happy-dom tests, not in a bare Node server context.",
+    );
+  }
+  sharedEditor = new Editor({
+    element: document.createElement("div"),
+    extensions: createSharedEditorExtensions({
+      dialect: "gfm",
+      features: { image: true },
+      extraExtensions: [RunId],
+    }),
+    content: "",
+  });
+  return sharedEditor;
+}
+
+/** Reads the GFM markdown out of the tiptap-markdown storage. */
+function getMarkdown(editor: Editor): string {
+  const storage = editor.storage as unknown as {
+    markdown?: { getMarkdown?: () => string };
+  };
+  return storage.markdown?.getMarkdown?.() ?? "";
+}
+
+/**
+ * Parse a GFM markdown string into an array of top-level ProseMirror node JSON
+ * (paragraph / heading / list / table / code block / etc.), matching the live
+ * plan editor schema (`createSharedEditorExtensions({ dialect: "gfm",
+ * features: { image: true } })`) plus the {@link RunId} attribute.
+ *
+ * `tiptap-markdown` registers the markdown parser, so handing the raw markdown
+ * string to `setContent` deserializes it (the same path the live editor uses
+ * when it seeds `content: markdown`). Returns the doc's child nodes; an empty
+ * string yields a single empty paragraph.
+ */
+export function gfmToProseJSON(markdown: string): JSONContent[] {
+  const editor = getSharedEditor();
+  // `emitUpdate: false` keeps this a pure transform with no side effects on any
+  // (non-existent) consumers of the headless editor's update stream.
+  editor.commands.setContent(markdown, { emitUpdate: false });
+  return editor.getJSON().content ?? [];
+}
+
+/**
+ * Serialize an array of top-level ProseMirror node JSON into GFM markdown. The
+ * `runId` attribute is omitted by GFM (the {@link RunId} extension registers no
+ * markdown serializer), so it never leaks into the saved markdown.
+ *
+ * The nodes are wrapped in a `doc` and set on the shared editor, then the GFM
+ * markdown is read from the tiptap-markdown storage — the exact serializer the
+ * live editor persists with, so output is byte-stable with the live save path.
+ */
+export function proseJSONToGfm(nodes: JSONContent[]): string {
+  const editor = getSharedEditor();
+  const content = nodes.length > 0 ? nodes : [{ type: "paragraph" }];
+  editor.commands.setContent({ type: "doc", content }, { emitUpdate: false });
+  return getMarkdown(editor);
+}

package/src/editor/index.ts

@@ -0,0 +1,93 @@
+export {
+  createSharedEditorExtensions,
+  MARKDOWN_DIALECT_CONFIG,
+  type RichMarkdownDialect,
+  type RichMarkdownEditorPreset,
+  type RichMarkdownCollabUser,
+  type SharedEditorCollab,
+  type SharedEditorFeatures,
+  type CreateSharedEditorExtensionsOptions,
+} from "./extensions.js";
+export {
+  useCollabReconcile,
+  getEditorMarkdown,
+  RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION,
+  type UseCollabReconcileOptions,
+  type UseCollabReconcileResult,
+} from "./useCollabReconcile.js";
+export {
+  applyDocSurgically,
+  defaultParseValue,
+  diffTopLevel,
+  type TopLevelDiff,
+} from "./surgical-apply.js";
+export {
+  SlashCommandMenu,
+  DEFAULT_SLASH_COMMANDS,
+  createImageSlashCommand,
+  type SlashCommandItem,
+  type SlashCommandMenuProps,
+} from "./SlashCommandMenu.js";
+export {
+  SharedImage,
+  createImageExtension,
+  pickAndInsertImage,
+  type ImageUploadFn,
+  type SharedImageOptions,
+} from "./ImageExtension.js";
+export {
+  BubbleToolbar,
+  buildDefaultBubbleItems,
+  type BubbleToolbarItem,
+  type BubbleToolbarProps,
+} from "./BubbleToolbar.js";
+export {
+  SharedRichEditor,
+  type SharedRichEditorProps,
+} from "./SharedRichEditor.js";
+export {
+  createCodeBlockNode,
+  DEFAULT_CODE_LANGUAGES,
+  type CodeLanguageOption,
+  type CodeBlockClassNames,
+  type CreateCodeBlockNodeOptions,
+} from "./CodeBlockNode.js";
+export {
+  RichMarkdownEditor,
+  createRichMarkdownExtensions,
+  type RichMarkdownEditorProps,
+  type CreateRichMarkdownExtensionsOptions,
+} from "./RichMarkdownEditor.js";
+export { RunId, RUN_ID_NODE_TYPES } from "./RunId.js";
+export { gfmToProseJSON, proseJSONToGfm } from "./gfmDoc.js";
+export {
+  DragHandle,
+  DEFAULT_DRAG_HANDLE_WRAPPER_SELECTOR,
+  type DragHandleDropContext,
+  type DragHandleDropPlacement,
+  type DragHandleOptions,
+} from "./DragHandle.js";
+export {
+  createRegistryBlockNode,
+  LegacyJsonEditSurface,
+  RegistryBlockDataProvider,
+  RegistryBlockNodeView,
+  useRegistryBlockData,
+  type CreateRegistryBlockNodeOptions,
+  type RegistryBlockDataChangeMeta,
+  type RegistryBlockDataValue,
+  type RegistryBlockEditSurfaceOptions,
+  type RegistryBlockNestedBlock,
+  type RegistryBlockRenderOptions,
+  type RegistryBlockRenderResult,
+  type RegistryBlockSideMapBlock,
+} from "./RegistryBlockNode.js";
+export {
+  buildRegistryBlockSlashItems,
+  getRegistryBlockSlashDescription,
+  getRegistryBlockSlashSearchText,
+  type BuildRegistryBlockSlashItemsOptions,
+  type RegistrySlashBlockRegistry,
+  type RegistrySlashBlockSpec,
+} from "./registrySlashCommands.js";
+export type { JSONContent } from "@tiptap/core";

package/src/editor/registrySlashCommands.ts

@@ -0,0 +1,131 @@
+export interface RegistrySlashBlockSpec {
+  type: string;
+  label: string;
+  description: string;
+  notionCompatible?: boolean;
+}
+
+export interface RegistrySlashBlockRegistry<
+  TSpec extends RegistrySlashBlockSpec = RegistrySlashBlockSpec,
+> {
+  list: (placement: "block") => TSpec[];
+}
+
+const COMPACT_REGISTRY_BLOCK_DESCRIPTIONS: Record<string, string> = {
+  callout: "Emphasized note",
+  diagram: "Inline diagram",
+  wireframe: "Screen mockup",
+  "question-form": "Interactive questions",
+  checklist: "Checklist items",
+  table: "Editable grid",
+  "table-block": "Editable grid",
+  "code-tabs": "Tabbed code snippets",
+  "custom-html": "Sandboxed HTML",
+  tabs: "Tabbed block group",
+  columns: "Side-by-side columns",
+  mermaid: "Mermaid diagram",
+  "api-endpoint": "API reference",
+  "openapi-spec": "OpenAPI document",
+  "data-model": "ERD schema",
+  diff: "Code diff",
+  "file-tree": "File/change tree",
+  "json-explorer": "JSON tree",
+  "annotated-code": "Code walkthrough",
+};
+
+/**
+ * Compact, user-facing slash-menu copy for structured registry blocks. The full
+ * registry description remains available through search text, but the visible
+ * row should scan like a command palette, not a block reference page.
+ */
+export function getRegistryBlockSlashDescription(
+  spec: Pick<RegistrySlashBlockSpec, "type" | "description">,
+): string {
+  return (
+    COMPACT_REGISTRY_BLOCK_DESCRIPTIONS[spec.type] ??
+    spec.description.trim().replace(/\s+/g, " ")
+  );
+}
+
+/** Searchable text for registry block slash items, including raw type keywords. */
+export function getRegistryBlockSlashSearchText(
+  spec: Pick<RegistrySlashBlockSpec, "type" | "label" | "description">,
+): string {
+  return [spec.label, spec.description, spec.type]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+/**
+ * Shared builder for the registry-derived block slash commands both the plan and
+ * content editors offer. Both apps take every `BlockSpec` whose `placement`
+ * includes `"block"`, gate it by Notion-compatibility when the open document is
+ * linked to a Notion page, and emit one slash item per surviving spec that
+ * inserts that block's atom node. The only legitimate per-app differences are:
+ *
+ *  - the ITEM SHAPE (plan uses a text-glyph `icon`, content a React component),
+ *  - the Notion-compat PREDICATE (plan unions in prose-only NFM analogs, content
+ *    reads the registry `notionCompatible` flag directly), and
+ *  - the INSERT behavior (plan inserts a `planBlock` node, content a
+ *    `registryBlock` node seeded with inline `__raw`).
+ *
+ * Those three are injected; everything else (the `list("block")` source, the
+ * Notion filter wiring, the one-item-per-spec mapping) lives here so adding a
+ * new library block only touches the registry, never the slash builders.
+ */
+export interface BuildRegistryBlockSlashItemsOptions<
+  TItem,
+  TEditor,
+  TSpec extends RegistrySlashBlockSpec = RegistrySlashBlockSpec,
+> {
+  /**
+   * When `true`, only specs the predicate accepts are offered (the open document
+   * is linked to a Notion page, so blocks that can't round-trip to NFM are
+   * hidden). When unset/false, every block-placed spec is offered.
+   */
+  notionCompatibleOnly?: boolean;
+  /**
+   * Decide whether a spec round-trips to Notion. Defaults to the spec's own
+   * `notionCompatible` flag (content's rule). Plan passes a predicate that unions
+   * in prose-only NFM analogs not carried as registry flags.
+   */
+  isNotionCompatible?: (spec: TSpec) => boolean;
+  /** Build one app-shaped slash item from a surviving block spec. */
+  toItem: (spec: TSpec, insert: (editor: TEditor) => void) => TItem;
+  /**
+   * Optional app-level capability gate. Use this for blocks whose schema is
+   * registered for parse/render compatibility but whose authoring experience is
+   * not available in this editor yet.
+   */
+  includeSpec?: (spec: TSpec) => boolean;
+  /**
+   * Insert this spec's block atom into the editor. Plan inserts a `planBlock`
+   * node; content inserts a `registryBlock` node seeded with inline `__raw`.
+   */
+  insertBlock: (editor: TEditor, spec: TSpec) => void;
+}
+
+/**
+ * Build the registry-derived block slash items, shared by plan and content. Each
+ * app prepends its own prose/base commands and wraps the result in its own item
+ * type via {@link BuildRegistryBlockSlashItemsOptions.toItem}.
+ */
+export function buildRegistryBlockSlashItems<
+  TItem,
+  TEditor,
+  TSpec extends RegistrySlashBlockSpec = RegistrySlashBlockSpec,
+>(
+  registry: RegistrySlashBlockRegistry<TSpec>,
+  options: BuildRegistryBlockSlashItemsOptions<TItem, TEditor, TSpec>,
+): TItem[] {
+  const isCompatible =
+    options.isNotionCompatible ?? ((spec) => Boolean(spec.notionCompatible));
+  return registry
+    .list("block")
+    .filter((spec) => options.includeSpec?.(spec) ?? true)
+    .filter((spec) => !options.notionCompatibleOnly || isCompatible(spec))
+    .map((spec) =>
+      options.toItem(spec, (editor) => options.insertBlock(editor, spec)),
+    );
+}

package/src/editor/structuralReorderUndo.spec.ts

@@ -0,0 +1,144 @@
+// @vitest-environment happy-dom
+
+import { Editor, Node } from "@tiptap/core";
+import { describe, expect, it } from "vitest";
+
+import { createRichMarkdownExtensions } from "./RichMarkdownEditor.js";
+
+/**
+ * Structural block reorder must be undoable with cmd+z (Notion parity).
+ *
+ * The plan editor renders the whole document as ONE ProseMirror doc; structured
+ * blocks are atomic `planBlock` nodes. Dragging a block to reorder it repaints
+ * the doc via a whole-document `replaceWith` (the plan editor's
+ * `replaceEditorViewBlocks`). That repaint used to be dispatched with
+ * `addToHistory: false`, so the editor's (already working) undo keymap had
+ * nothing to revert — cmd+z after a drag did nothing. The fix makes a
+ * single-editor drag repaint a HISTORICAL transaction, so the existing undo
+ * stack captures the reorder and interleaves it with text edits, exactly like
+ * Notion.
+ *
+ * This reproduces that exact mechanism headlessly: a minimal block-level ATOM
+ * (the analog of `planBlock`, but with a plain-DOM render so no React NodeView
+ * is needed) reordered by a whole-document `replaceWith`, dispatched the two
+ * ways — and asserts cmd+z reverts ONLY the historical one.
+ */
+
+// Minimal stand-in for the plan's atomic `planBlock` node.
+const BlockAtom = Node.create({
+  name: "blockAtom",
+  group: "block",
+  atom: true,
+  selectable: true,
+  draggable: true,
+  addAttributes() {
+    return { blockId: { default: null } };
+  },
+  parseHTML() {
+    return [{ tag: "div[data-block-atom]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { ...HTMLAttributes, "data-block-atom": "" }];
+  },
+});
+
+function docOf(ids: string[]) {
+  return {
+    type: "doc",
+    content: ids.map((id) => ({ type: "blockAtom", attrs: { blockId: id } })),
+  };
+}
+
+// Initial content goes through the constructor, NOT setContent, so the seed is
+// the baseline doc and is NOT itself an undoable history entry — the first
+// undoable step is whatever the test dispatches next.
+function makeEditor(ids: string[]) {
+  const element = document.createElement("div");
+  document.body.appendChild(element);
+  return new Editor({
+    element,
+    extensions: [...createRichMarkdownExtensions(), BlockAtom],
+    content: docOf(ids),
+  });
+}
+
+function atomOrder(editor: Editor): string[] {
+  const ids: string[] = [];
+  editor.state.doc.forEach((node) => {
+    if (node.type.name === "blockAtom") ids.push(node.attrs.blockId as string);
+  });
+  return ids;
+}
+
+/** Reorder by replacing the whole doc — the shape of `replaceEditorViewBlocks`. */
+function reorderViaReplace(
+  editor: Editor,
+  ids: string[],
+  addToHistory: boolean,
+) {
+  const view = editor.view;
+  const next = view.state.schema.nodeFromJSON(docOf(ids));
+  const tr = view.state.tr.replaceWith(
+    0,
+    view.state.doc.content.size,
+    next.content,
+  );
+  if (!addToHistory) tr.setMeta("addToHistory", false);
+  view.dispatch(tr);
+}
+
+/** Fire a real Mod-z (or Shift-Mod-z) through the ProseMirror undo keymap. */
+function pressModZ(editor: Editor, opts: { shift?: boolean } = {}): boolean {
+  const isMac =
+    typeof navigator !== "undefined" &&
+    /Mac|iP(hone|ad|od)/.test(navigator.platform || "");
+  const event = new KeyboardEvent("keydown", {
+    key: opts.shift ? "Z" : "z",
+    code: "KeyZ",
+    // prosemirror-keymap resolves a shifted letter (Shift-Mod-Z → redo) through
+    // the physical key via `event.keyCode`; a real browser sends it, so the
+    // synthetic event must too or the redo binding never matches.
+    keyCode: 90,
+    which: 90,
+    metaKey: isMac,
+    ctrlKey: !isMac,
+    shiftKey: !!opts.shift,
+    bubbles: true,
+    cancelable: true,
+  } as KeyboardEventInit);
+  return (
+    editor.view.someProp("handleKeyDown", (f) => f(editor.view, event)) ?? false
+  );
+}
+
+describe("structural block reorder undo", () => {
+  it("OLD behavior: a non-historical reorder repaint is NOT undoable", () => {
+    const editor = makeEditor(["a", "b", "c"]);
+    expect(atomOrder(editor)).toEqual(["a", "b", "c"]);
+
+    reorderViaReplace(editor, ["c", "a", "b"], /* addToHistory */ false);
+    expect(atomOrder(editor)).toEqual(["c", "a", "b"]);
+
+    pressModZ(editor);
+    // Nothing to undo — the reorder was deliberately excluded from history.
+    expect(atomOrder(editor)).toEqual(["c", "a", "b"]);
+    editor.destroy();
+  });
+
+  it("FIX: a historical reorder repaint is reverted by cmd+z and redone by cmd+shift+z", () => {
+    const editor = makeEditor(["a", "b", "c"]);
+    expect(atomOrder(editor)).toEqual(["a", "b", "c"]);
+
+    reorderViaReplace(editor, ["c", "a", "b"], /* addToHistory */ true);
+    expect(atomOrder(editor)).toEqual(["c", "a", "b"]);
+
+    const undid = pressModZ(editor);
+    expect(undid).toBe(true);
+    expect(atomOrder(editor)).toEqual(["a", "b", "c"]);
+
+    const redid = pressModZ(editor, { shift: true });
+    expect(redid).toBe(true);
+    expect(atomOrder(editor)).toEqual(["c", "a", "b"]);
+    editor.destroy();
+  });
+});