@agent-native/toolkit 0.0.0-beta-20260819143124

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,96 @@
+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,
+  filterSlashCommandItems,
+  focusEditorInInsertedBlock,
+  type SlashCommandItem,
+  type SlashCommandMenuProps,
+  type SlashCommandFeatureFlags,
+} 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();
+  });
+});