@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/editor/RichMarkdownEditor.collab.spec.ts

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { Awareness } from "y-protocols/awareness";
+import * as Y from "yjs";
+
+import { createRichMarkdownExtensions } from "./RichMarkdownEditor.js";
+
+/**
+ * The optional collaboration wiring on the shared rich-markdown editor must be
+ * strictly additive: with no `ydoc`, the editor behaves exactly as the existing
+ * controlled single-user editor (no Collaboration extensions, undo/redo on);
+ * with a `ydoc`, it binds Collaboration (+ a CollaborationCaret when awareness
+ * is present) and disables StarterKit's undo/redo so Yjs owns history.
+ */
+function extensionNames(
+  opts?: Parameters<typeof createRichMarkdownExtensions>[0],
+): string[] {
+  return createRichMarkdownExtensions(opts).map((ext) => ext.name);
+}
+
+describe("createRichMarkdownExtensions collaboration wiring", () => {
+  it("adds no collaboration extensions when ydoc is absent", () => {
+    const names = extensionNames();
+    expect(names).not.toContain("collaboration");
+    expect(names).not.toContain("collaborationCaret");
+  });
+
+  it("adds Collaboration only when a ydoc is provided", () => {
+    const ydoc = new Y.Doc();
+    try {
+      const names = extensionNames({ ydoc });
+      expect(names).toContain("collaboration");
+      // No awareness → no caret extension, but core collab still binds.
+      expect(names).not.toContain("collaborationCaret");
+    } finally {
+      ydoc.destroy();
+    }
+  });
+
+  it("adds CollaborationCaret when ydoc and awareness are both provided", () => {
+    const ydoc = new Y.Doc();
+    const awareness = new Awareness(ydoc);
+    try {
+      const names = extensionNames({
+        ydoc,
+        awareness,
+        user: { name: "Ada", color: "#60a5fa", email: "ada@example.com" },
+      });
+      expect(names).toContain("collaboration");
+      expect(names).toContain("collaborationCaret");
+    } finally {
+      awareness.destroy();
+      ydoc.destroy();
+    }
+  });
+
+  it("disables StarterKit undo/redo only in collab mode", () => {
+    const findStarterKit = (
+      opts?: Parameters<typeof createRichMarkdownExtensions>[0],
+    ) =>
+      createRichMarkdownExtensions(opts).find(
+        (ext) => ext.name === "starterKit",
+      );
+
+    const standalone = findStarterKit();
+    expect((standalone?.options as { undoRedo?: unknown })?.undoRedo).toBe(
+      undefined,
+    );
+
+    const ydoc = new Y.Doc();
+    try {
+      const collab = findStarterKit({ ydoc });
+      expect((collab?.options as { undoRedo?: unknown })?.undoRedo).toBe(false);
+    } finally {
+      ydoc.destroy();
+    }
+  });
+});

package/src/editor/RichMarkdownEditor.roundtrip.spec.ts

@@ -0,0 +1,226 @@
+// @vitest-environment happy-dom
+
+import { Editor } from "@tiptap/core";
+import { describe, expect, it } from "vitest";
+
+import { createRichMarkdownExtensions } from "./RichMarkdownEditor.js";
+
+/**
+ * Round-trip fidelity for the Plan rich-text editor.
+ *
+ * tiptap-markdown re-serializes the ENTIRE document on every edit. If
+ * `serialize(parse(markdown)) !== markdown` for the markdown that plans
+ * actually contain, then the FIRST edit of an existing block emits a fully
+ * normalized version of text the user never touched — a noisy one-time git
+ * diff plus an update-rich-text write that rewrites untouched prose.
+ *
+ * This suite mounts an `Editor` from the SAME extension factory the component
+ * uses ({@link createRichMarkdownExtensions}) so the test and the component can
+ * never disagree about the dialect, then pins the round-trip output for a
+ * representative plan corpus. Cases fall into two buckets:
+ *
+ *   - byte-stable: `roundTrip(x) === x`. Asserted via `expectStable`.
+ *   - pinned-lossy: tiptap-markdown 0.9.0 normalizes the input in a way that
+ *     CANNOT be removed through the public `Markdown.configure` surface
+ *     (the relevant internals — prosemirror-markdown's `em` serializer and the
+ *     non-exported `MarkdownTightLists` extension — are not configurable). We
+ *     are forbidden from reformatting/post-processing stored markdown to chase
+ *     stability, so these are pinned to their ACTUAL normalized output via
+ *     `expectNormalizesTo`. That keeps each normalization visible and
+ *     regression-guarded instead of silently churning.
+ *
+ * The only lever we are allowed to pull is the tiptap-markdown
+ * `Markdown.configure` options in the shared factory. The current config
+ * (`bulletListMarker: "-"`, `tightLists: true`, `linkify: false`,
+ * `breaks: false`) already minimizes normalization for everything below; the
+ * remaining lossy cases are inherent to the library at this version.
+ */
+
+function roundTrip(markdown: string): string {
+  const editor = new Editor({
+    element: document.createElement("div"),
+    extensions: createRichMarkdownExtensions({ dialect: "gfm" }),
+    content: markdown,
+  });
+  try {
+    const storage = editor.storage as unknown as {
+      markdown?: { getMarkdown?: () => string };
+    };
+    return storage.markdown?.getMarkdown?.() ?? "";
+  } finally {
+    editor.destroy();
+  }
+}
+
+/** Asserts the markdown survives parse→serialize unchanged (byte-stable). */
+function expectStable(markdown: string): void {
+  expect(roundTrip(markdown)).toBe(markdown);
+}
+
+/**
+ * Asserts an inherently-lossy case serializes to a KNOWN normalized form.
+ * Pins the normalization so it stays visible and regression-guarded; also
+ * guards that the case is genuinely lossy (otherwise it belongs in the
+ * byte-stable bucket).
+ */
+function expectNormalizesTo(input: string, normalized: string): void {
+  expect(roundTrip(input)).toBe(normalized);
+  expect(normalized).not.toBe(input);
+}
+
+describe("RichMarkdownEditor markdown round-trip", () => {
+  describe("byte-stable cases", () => {
+    it("headings H1-H4 (ATX)", () => {
+      expectStable("# Heading 1");
+      expectStable("## Heading 2");
+      expectStable("### Heading 3");
+      expectStable("#### Heading 4");
+    });
+
+    it("paragraphs", () => {
+      expectStable("A single plain paragraph.");
+      expectStable("First paragraph.\n\nSecond paragraph.");
+    });
+
+    it("bold and inline code marks", () => {
+      expectStable("Text with **bold** words.");
+      expectStable("Text with `inline code` words.");
+      expectStable("Mixed **bold** and `code` together.");
+    });
+
+    it("bulleted list (tight)", () => {
+      expectStable("- One\n- Two\n- Three");
+    });
+
+    it("numbered list (tight)", () => {
+      expectStable("1. One\n2. Two\n3. Three");
+    });
+
+    it("nested bulleted list", () => {
+      expectStable("- One\n  - Nested A\n  - Nested B\n- Two");
+    });
+
+    it("a single task item", () => {
+      expectStable("- [ ] Todo item");
+      expectStable("- [x] Done item");
+    });
+
+    it("blockquote", () => {
+      expectStable("> A quoted line.");
+    });
+
+    it("fenced code block with a language", () => {
+      expectStable("```ts\nconst x: number = 1;\n```");
+    });
+
+    it("links", () => {
+      expectStable("See [the docs](https://example.com/docs) for details.");
+    });
+
+    it("horizontal rule", () => {
+      expectStable("Above.\n\n---\n\nBelow.");
+    });
+
+    it("GFM pipe table when followed by more content", () => {
+      // A table in the middle of a body (the common case in a plan) is stable.
+      // The trailing-newline normalization only happens when a table is the
+      // very last block — see pinned-lossy cases below.
+      expectStable(
+        [
+          "Intro paragraph.",
+          "",
+          "| Name | Status |",
+          "| --- | --- |",
+          "| Alpha | Done |",
+          "| Beta | Open |",
+          "",
+          "Closing paragraph.",
+        ].join("\n"),
+      );
+    });
+
+    it("a representative mixed plan body (no italics, table not last)", () => {
+      expectStable(
+        [
+          "# Project Plan",
+          "",
+          "## Overview",
+          "",
+          "This plan covers the **rollout** of the new flow.",
+          "",
+          "## Notes",
+          "",
+          "See [the brief](https://example.com/brief) and run `pnpm test`.",
+          "",
+          "```ts",
+          "const ready = true;",
+          "```",
+        ].join("\n"),
+      );
+    });
+  });
+
+  describe("pinned-lossy cases (inherent to tiptap-markdown 0.9.0)", () => {
+    it("italic: underscore markers normalize to asterisks", () => {
+      // tiptap-markdown serializes the italic mark via prosemirror-markdown's
+      // `defaultMarkdownSerializer.marks.em`, which hardcodes `*` open/close.
+      // There is NO `Markdown.configure` option for the emphasis marker
+      // (`bulletListMarker` only controls bullet lists), so `_x_` always
+      // re-emits as `*x*`. Asterisk-delimited italics are already stable.
+      expectNormalizesTo(
+        "Text with _italic_ words.",
+        "Text with *italic* words.",
+      );
+      expectStable("Text with *italic* words.");
+    });
+
+    it("multi-item task lists serialize loose (blank line between items)", () => {
+      // tiptap-markdown's tight-list support (MarkdownTightLists) only
+      // registers the `tight` attribute for `bulletList`/`orderedList`, never
+      // `taskList`, and that extension is not exported for reconfiguration.
+      // So task lists with 2+ items always gain a blank line between items.
+      // A single task item (above) stays stable.
+      expectNormalizesTo(
+        "- [ ] Todo item\n- [x] Done item",
+        "- [ ] Todo item\n\n- [x] Done item",
+      );
+    });
+
+    it("nested task list also serializes loose", () => {
+      expectNormalizesTo(
+        "- [ ] parent\n  - [x] child",
+        "- [ ] parent\n\n  - [x] child",
+      );
+    });
+
+    it("a table as the LAST block gains a trailing newline", () => {
+      // When a pipe table is the final block in the document the serializer
+      // appends a trailing "\n". (Mid-body tables — see byte-stable cases —
+      // do not.) Not removable via public config.
+      expectNormalizesTo(
+        [
+          "| Name | Status |",
+          "| --- | --- |",
+          "| Alpha | Done |",
+          "| Beta | Open |",
+        ].join("\n"),
+        [
+          "| Name | Status |",
+          "| --- | --- |",
+          "| Alpha | Done |",
+          "| Beta | Open |",
+          "",
+        ].join("\n"),
+      );
+    });
+  });
+
+  describe("intentional normalizations (desired, GFM-canonical)", () => {
+    it("`*` bullet markers normalize to `-` per bulletListMarker config", () => {
+      // We deliberately keep bulletListMarker: "-" so all bullets converge on
+      // the GFM-canonical dash. `*`/`+` bullets becoming `-` is intended.
+      expectNormalizesTo("* One\n* Two", "- One\n- Two");
+      expectNormalizesTo("+ One\n+ Two", "- One\n- Two");
+    });
+  });
+});

package/src/editor/RichMarkdownEditor.tsx

@@ -0,0 +1,81 @@
+import type { Awareness } from "y-protocols/awareness";
+import type { Doc as YDoc } from "yjs";
+
+/**
+ * Back-compat surface for the shared rich markdown editor.
+ *
+ * The editor core now lives in dedicated modules:
+ *   - {@link createSharedEditorExtensions} — the ONE extension factory.
+ *   - {@link useCollabReconcile} — seed / reconcile / lead-client logic.
+ *   - {@link SlashCommandMenu} / {@link BubbleToolbar} — shared menus.
+ *   - {@link SharedRichEditor} — the editor component.
+ *
+ * This file keeps the historical `RichMarkdownEditor` component name (aliased to
+ * {@link SharedRichEditor}) and the `createRichMarkdownExtensions` factory so
+ * existing embedders and the round-trip / collab specs keep working unchanged.
+ */
+import {
+  createSharedEditorExtensions,
+  type RichMarkdownDialect,
+  type RichMarkdownEditorPreset,
+  type RichMarkdownCollabUser,
+} from "./extensions.js";
+import {
+  SharedRichEditor,
+  type SharedRichEditorProps,
+} from "./SharedRichEditor.js";
+
+export type {
+  RichMarkdownDialect,
+  RichMarkdownEditorPreset,
+  RichMarkdownCollabUser,
+};
+
+/** @deprecated Prefer {@link CreateSharedEditorExtensionsOptions}. */
+export interface CreateRichMarkdownExtensionsOptions {
+  dialect?: RichMarkdownDialect;
+  placeholder?: string;
+  /**
+   * Yjs document for collaborative editing. When present, the editor binds the
+   * shared Collaboration + CollaborationCaret extensions and StarterKit's
+   * built-in undo/redo is disabled (Yjs owns history).
+   */
+  ydoc?: YDoc | null;
+  /** Shared awareness instance for live multi-user cursors. */
+  awareness?: Awareness | null;
+  /** Current user info for the collaborative cursor label. */
+  user?: RichMarkdownCollabUser | null;
+}
+
+/**
+ * Back-compat factory preserving today's GFM/plan behavior EXACTLY. Implemented
+ * in terms of {@link createSharedEditorExtensions}: it maps the flat
+ * `{ ydoc, awareness, user }` collab options into the nested `collab` shape the
+ * shared factory expects. The round-trip and collab specs build their `Editor`
+ * from this, so its output must stay byte-stable.
+ */
+export function createRichMarkdownExtensions({
+  dialect = "gfm",
+  placeholder = "Type '/' for commands...",
+  ydoc = null,
+  awareness = null,
+  user = null,
+}: CreateRichMarkdownExtensionsOptions = {}) {
+  return createSharedEditorExtensions({
+    dialect,
+    placeholder,
+    collab: ydoc ? { ydoc, awareness, user } : null,
+  });
+}
+
+/** @deprecated Prefer {@link SharedRichEditorProps}. */
+export type RichMarkdownEditorProps = SharedRichEditorProps;
+
+/**
+ * Historical name for {@link SharedRichEditor}. Kept so existing imports
+ * (`import { RichMarkdownEditor } from "@agent-native/core/client"`) and the
+ * plan editor tests (which assert the source mentions `RichMarkdownEditor`)
+ * keep working through the Core compatibility re-export. New code should import
+ * `SharedRichEditor` from `@agent-native/toolkit/editor`.
+ */
+export const RichMarkdownEditor = SharedRichEditor;

package/src/editor/RunId.ts

@@ -0,0 +1,61 @@
+import { Extension } from "@tiptap/core";
+
+/**
+ * Node types that carry the optional `runId` attribute.
+ *
+ * These are exactly the top-level block nodes a plan's `rich-text` block can
+ * serialize to. The plan's `doc ↔ blocks[]` bridge stamps `runId` onto the
+ * FIRST node of each rich-text run so a re-parse can map the run back to its
+ * originating block id (stable ids across edits). Atom/structured blocks live
+ * in their own `planBlock` node and do not need this attribute.
+ */
+export const RUN_ID_NODE_TYPES = [
+  "paragraph",
+  "heading",
+  "bulletList",
+  "orderedList",
+  "taskList",
+  "blockquote",
+  "codeBlock",
+] as const;
+
+/**
+ * Tiptap extension that adds a GLOBAL `runId` attribute (default `null`) to the
+ * block node types in {@link RUN_ID_NODE_TYPES}.
+ *
+ * - `renderHTML` emits `data-run-id` only when the attribute is set, so the
+ *   live editor's DOM carries the id for the doc↔blocks bridge.
+ * - `parseHTML` reads `data-run-id` back so a paste / re-parse preserves it.
+ * - Markdown serialization deliberately IGNORES `runId`: GFM never emits it.
+ *   `tiptap-markdown` drops attributes it has no serializer for, so we simply
+ *   don't register a markdown serializer here — the attribute is invisible to
+ *   the GFM round-trip and only lives in the ProseMirror JSON / DOM.
+ *
+ * Used by BOTH the headless `gfmDoc` editor and the live plan editor so the
+ * schema is identical on both sides of the bridge.
+ */
+export const RunId = Extension.create({
+  name: "runId",
+
+  addGlobalAttributes() {
+    return [
+      {
+        types: [...RUN_ID_NODE_TYPES],
+        attributes: {
+          runId: {
+            default: null,
+            // Read the id off the rendered DOM so paste / re-parse round-trips.
+            parseHTML: (element) => element.getAttribute("data-run-id"),
+            // Only emit the attribute when set; an unset (null) runId adds
+            // nothing to the DOM so untouched nodes stay clean.
+            renderHTML: (attributes) => {
+              const runId = (attributes as { runId?: string | null }).runId;
+              if (!runId) return {};
+              return { "data-run-id": runId };
+            },
+          },
+        },
+      },
+    ];
+  },
+});

package/src/editor/SharedRichEditor.spec.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { SharedRichEditor } from "./SharedRichEditor.js";
+
+describe("SharedRichEditor block controls", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("mounts the shared Notion-style block grip by default", async () => {
+    await act(async () => {
+      root.render(
+        <SharedRichEditor
+          value="<p>First</p><p>Second</p>"
+          onChange={() => undefined}
+        />,
+      );
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    const prose = container.querySelector<HTMLElement>(".an-rich-md-prose");
+    const firstBlock = prose?.firstElementChild;
+    for (const [element, rect] of [
+      [prose, { left: 0, top: 0, right: 640, bottom: 100 }],
+      [firstBlock, { left: 0, top: 0, right: 640, bottom: 24 }],
+    ] as const) {
+      if (!element) continue;
+      Object.defineProperty(element, "getBoundingClientRect", {
+        configurable: true,
+        value: () => ({
+          ...rect,
+          x: rect.left,
+          y: rect.top,
+          width: rect.right - rect.left,
+          height: rect.bottom - rect.top,
+          toJSON: () => ({}),
+        }),
+      });
+    }
+    document.dispatchEvent(
+      new MouseEvent("mousemove", {
+        bubbles: true,
+        clientX: 8,
+        clientY: 8,
+      }),
+    );
+    expect(container.querySelector(".an-rich-md-wrapper")).not.toBeNull();
+    expect(container.querySelector(".drag-handle")).not.toBeNull();
+  });
+
+  it("allows hosts to opt out when they own block controls", async () => {
+    await act(async () => {
+      root.render(
+        <SharedRichEditor
+          value="First"
+          onChange={() => undefined}
+          dragHandle={false}
+        />,
+      );
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    expect(container.querySelector(".drag-handle")).toBeNull();
+  });
+});