@agent-native/toolkit 0.4.9 → 0.5.0

package/dist/editor/RichMarkdownEditor.roundtrip.spec.js

@@ -0,0 +1,186 @@
+// @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) {
+    const editor = new Editor({
+        element: document.createElement("div"),
+        extensions: createRichMarkdownExtensions({ dialect: "gfm" }),
+        content: markdown,
+    });
+    try {
+        const storage = editor.storage;
+        return storage.markdown?.getMarkdown?.() ?? "";
+    }
+    finally {
+        editor.destroy();
+    }
+}
+/** Asserts the markdown survives parse→serialize unchanged (byte-stable). */
+function expectStable(markdown) {
+    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, normalized) {
+    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");
+        });
+    });
+});
+//# sourceMappingURL=RichMarkdownEditor.roundtrip.spec.js.map

package/dist/editor/RichMarkdownEditor.roundtrip.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RichMarkdownEditor.roundtrip.spec.js","sourceRoot":"","sources":["../../src/editor/RichMarkdownEditor.roundtrip.spec.ts"],"names":[],"mappings":"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"}

package/dist/editor/RunId.d.ts

@@ -0,0 +1,28 @@
+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 declare const RUN_ID_NODE_TYPES: readonly ["paragraph", "heading", "bulletList", "orderedList", "taskList", "blockquote", "codeBlock"];
+/**
+ * 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 declare const RunId: Extension<any, any>;
+//# sourceMappingURL=RunId.d.ts.map

package/dist/editor/RunId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunId.d.ts","sourceRoot":"","sources":["../../src/editor/RunId.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,YAC5B,WAAW,EACX,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,CACH,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,qBAwBhB,CAAC"}

package/dist/editor/RunId.js

@@ -0,0 +1,60 @@
+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",
+];
+/**
+ * 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.runId;
+                            if (!runId)
+                                return {};
+                            return { "data-run-id": runId };
+                        },
+                    },
+                },
+            },
+        ];
+    },
+});
+//# sourceMappingURL=RunId.js.map

package/dist/editor/RunId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunId.js","sourceRoot":"","sources":["../../src/editor/RunId.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,WAAW;IACX,SAAS;IACT,YAAY;IACZ,aAAa;IACb,UAAU;IACV,YAAY;IACZ,WAAW;CACH,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,OAAO;IAEb,mBAAmB;QACjB,OAAO;YACL;gBACE,KAAK,EAAE,CAAC,GAAG,iBAAiB,CAAC;gBAC7B,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,OAAO,EAAE,IAAI;wBACb,oEAAoE;wBACpE,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC;wBAC3D,+DAA+D;wBAC/D,oDAAoD;wBACpD,UAAU,EAAE,CAAC,UAAU,EAAE,EAAE;4BACzB,MAAM,KAAK,GAAI,UAAwC,CAAC,KAAK,CAAC;4BAC9D,IAAI,CAAC,KAAK;gCAAE,OAAO,EAAE,CAAC;4BACtB,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;wBAClC,CAAC;qBACF;iBACF;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/editor/SharedRichEditor.d.ts

@@ -0,0 +1,110 @@
+import type { Extension, Node, Mark } from "@tiptap/core";
+import type { Awareness } from "y-protocols/awareness";
+import type { Doc as YDoc } from "yjs";
+import { type BubbleToolbarItem } from "./BubbleToolbar.js";
+import { type RichMarkdownDialect, type RichMarkdownEditorPreset, type RichMarkdownCollabUser, type SharedEditorFeatures } from "./extensions.js";
+import type { ImageUploadFn } from "./ImageExtension.js";
+import { type SlashCommandItem } from "./SlashCommandMenu.js";
+import { type UseCollabReconcileOptions } from "./useCollabReconcile.js";
+export interface SharedRichEditorProps {
+    value: string;
+    onChange: (markdown: string) => void;
+    onBlur?: () => void;
+    contentUpdatedAt?: string | null;
+    editable?: boolean;
+    dialect?: RichMarkdownDialect;
+    preset?: RichMarkdownEditorPreset;
+    /** Toggle individual base extensions (tables/tasks/link/codeBlock/image). */
+    features?: SharedEditorFeatures;
+    /**
+     * Injectable image uploader for the shared image block. Used only when
+     * `features.image` is on. Pass `uploadEditorImage` (the framework
+     * `upload-image` action) for a real uploading image block.
+     */
+    onImageUpload?: ImageUploadFn | null;
+    /**
+     * App-specific extensions (Notion nodes, media, drag handles, comment
+     * anchors, …) appended after the shared base schema.
+     */
+    extraExtensions?: Array<Extension | Node | Mark>;
+    placeholder?: string;
+    className?: string;
+    editorClassName?: string;
+    ariaLabel?: string;
+    interactive?: boolean;
+    /**
+     * Yjs document for real-time multi-user editing. When provided, prose is
+     * authored against the shared Y.Doc and mirrored back to `value` as markdown
+     * (still the source of truth). When omitted, the editor is a plain controlled
+     * `value`/`onChange` editor — the existing, non-collaborative behavior.
+     */
+    ydoc?: YDoc | null;
+    /** True after the collab provider has loaded persisted Y.Doc state. */
+    collabSynced?: boolean;
+    /** Shared awareness instance for live cursors/presence. */
+    awareness?: Awareness | null;
+    /** Current user info for the collaborative cursor label. */
+    user?: RichMarkdownCollabUser | null;
+    /**
+     * Disable StarterKit's built-in undo/redo for a controlled (non-collab)
+     * editor whose host owns its own undo authority (see
+     * {@link CreateSharedEditorExtensionsOptions.disableHistory}). Ignored when a
+     * `ydoc` is present (Yjs always owns history then). Default `false`, so every
+     * existing embedder is unchanged.
+     */
+    disableHistory?: boolean;
+    /** Override the slash-menu block command list. */
+    slashItems?: SlashCommandItem[];
+    /** Override the bubble-toolbar item builder. */
+    buildBubbleItems?: (editor: import("@tiptap/react").Editor, toggleLink: () => void) => BubbleToolbarItem[];
+    /**
+     * Override how the editor's content is read into the canonical `value`.
+     * Defaults to the tiptap-markdown storage reader. Apps with a custom on-disk
+     * format (Content's NFM, the plan's `blocks[]` JSON) pass their serializer so
+     * seed/reconcile/onChange all speak the same value space.
+     */
+    getMarkdown?: (editor: import("@tiptap/react").Editor) => string;
+    /** Override how the canonical `value` is applied into the editor (seed + reconcile). */
+    setContent?: (editor: import("@tiptap/react").Editor, value: string, options: {
+        emitUpdate?: boolean;
+        addToHistory?: boolean;
+    }) => void;
+    /**
+     * Optional parser for surgical reconcile. Custom value formats that already
+     * handle surgical writes inside `setContent` can pass `false` so the default
+     * markdown parser never treats their source bytes as literal markdown.
+     */
+    parseValue?: UseCollabReconcileOptions["parseValue"];
+    /** Canonicalize `value` for the echo / already-in-sync equality checks. */
+    normalizeValue?: (value: string) => string;
+    /** Override the empty-doc seed predicate (see {@link useCollabReconcile}). */
+    shouldSeed?: (info: {
+        value: string;
+        currentMarkdown: string;
+        fragmentLength: number;
+    }) => boolean;
+    /** Initial "applied" watermark (see {@link useCollabReconcile}). */
+    initialAppliedUpdatedAt?: string | null;
+    /** Extra class on the editor wrapper (e.g. a drag-handle `wrapperSelector` hook). */
+    wrapperClassName?: string;
+    /**
+     * Fires once the editor instance exists. Lets a host capture the root
+     * `editor.view` — e.g. to repaint the WHOLE document after a structural block
+     * move (a column emptied and its container dissolved) that a surgical
+     * per-region patch can't express, since the change is in the root doc itself.
+     */
+    onEditorReady?: (editor: import("@tiptap/react").Editor) => void;
+}
+/**
+ * The single shared rich markdown editor surface. Combines
+ * {@link createSharedEditorExtensions} (schema + dialect-keyed markdown +
+ * optional collab + app extras), {@link useCollabReconcile} (seed / reconcile /
+ * lead-client logic), and the shared {@link SlashCommandMenu} +
+ * {@link BubbleToolbar}.
+ *
+ * With no `ydoc` it is a controlled `value`/`onChange` single-user editor.
+ * With a `ydoc` it binds the framework collaboration stack; markdown stays the
+ * canonical saved representation while the Y.Doc is transient live state.
+ */
+export declare function SharedRichEditor({ value, onChange, onBlur, contentUpdatedAt, editable, dialect, preset, features, onImageUpload, extraExtensions, placeholder, className, editorClassName, ariaLabel, interactive, ydoc, collabSynced, awareness, user, disableHistory, slashItems, buildBubbleItems, getMarkdown, setContent, parseValue, normalizeValue, shouldSeed, initialAppliedUpdatedAt, wrapperClassName, onEditorReady, }: SharedRichEditorProps): import("react").JSX.Element;
+//# sourceMappingURL=SharedRichEditor.d.ts.map

package/dist/editor/SharedRichEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedRichEditor.d.ts","sourceRoot":"","sources":["../../src/editor/SharedRichEditor.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAG1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,GAAG,IAAI,IAAI,EAAE,MAAM,KAAK,CAAC;AAGvC,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC;;;OAGG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,uEAAuE;IACvE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACrC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kDAAkD;IAClD,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,CACjB,MAAM,EAAE,OAAO,eAAe,EAAE,MAAM,EACtC,UAAU,EAAE,MAAM,IAAI,KACnB,iBAAiB,EAAE,CAAC;IACzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,eAAe,EAAE,MAAM,KAAK,MAAM,CAAC;IACjE,wFAAwF;IACxF,UAAU,CAAC,EAAE,CACX,MAAM,EAAE,OAAO,eAAe,EAAE,MAAM,EACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KACtD,IAAI,CAAC;IACV;;;;OAIG;IACH,UAAU,CAAC,EAAE,yBAAyB,CAAC,YAAY,CAAC,CAAC;IACrD,2EAA2E;IAC3E,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,8EAA8E;IAC9E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;KACxB,KAAK,OAAO,CAAC;IACd,oEAAoE;IACpE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,QAAQ,EACR,MAAM,EACN,gBAAgB,EAChB,QAAe,EACf,OAAe,EACf,MAAe,EACf,QAAQ,EACR,aAAoB,EACpB,eAAe,EACf,WAAwC,EACxC,SAAS,EACT,eAAe,EACf,SAAS,EACT,WAAsB,EACtB,IAAW,EACX,YAAmB,EACnB,SAAgB,EAChB,IAAW,EACX,cAAsB,EACtB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,UAAU,EACV,cAAc,EACd,UAAU,EACV,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,EAAE,qBAAqB,+BAgKvB"}

package/dist/editor/SharedRichEditor.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { EditorContent, useEditor } from "@tiptap/react";
+import { useEffect, useMemo, useRef } from "react";
+import { cn } from "../utils.js";
+import { BubbleToolbar } from "./BubbleToolbar.js";
+import { createSharedEditorExtensions, } from "./extensions.js";
+import { SlashCommandMenu } from "./SlashCommandMenu.js";
+import { useCollabReconcile, getEditorMarkdown, } from "./useCollabReconcile.js";
+/**
+ * The single shared rich markdown editor surface. Combines
+ * {@link createSharedEditorExtensions} (schema + dialect-keyed markdown +
+ * optional collab + app extras), {@link useCollabReconcile} (seed / reconcile /
+ * lead-client logic), and the shared {@link SlashCommandMenu} +
+ * {@link BubbleToolbar}.
+ *
+ * With no `ydoc` it is a controlled `value`/`onChange` single-user editor.
+ * With a `ydoc` it binds the framework collaboration stack; markdown stays the
+ * canonical saved representation while the Y.Doc is transient live state.
+ */
+export function SharedRichEditor({ value, onChange, onBlur, contentUpdatedAt, editable = true, dialect = "gfm", preset = "plan", features, onImageUpload = null, extraExtensions, placeholder = "Type '/' for commands...", className, editorClassName, ariaLabel, interactive = editable, ydoc = null, collabSynced = true, awareness = null, user = null, disableHistory = false, slashItems, buildBubbleItems, getMarkdown, setContent, parseValue, normalizeValue, shouldSeed, initialAppliedUpdatedAt, wrapperClassName, onEditorReady, }) {
+    const readMarkdown = getMarkdown ?? getEditorMarkdown;
+    const onChangeRef = useRef(onChange);
+    const onBlurRef = useRef(onBlur);
+    onChangeRef.current = onChange;
+    onBlurRef.current = onBlur;
+    const extensions = useMemo(() => createSharedEditorExtensions({
+        dialect,
+        preset,
+        placeholder,
+        features,
+        extraExtensions,
+        onImageUpload,
+        collab: ydoc ? { ydoc, awareness, user } : null,
+        disableHistory,
+    }), 
+    // `preset` is retained in the dependency list so future preset-specific
+    // schema branches re-create the editor; it is currently schema-neutral. The
+    // collab inputs are identity-stable per block (one Y.Doc per docId), so they
+    // only change on a genuine doc switch — exactly when the editor must
+    // re-create to rebind Collaboration.
+    [
+        dialect,
+        placeholder,
+        preset,
+        features,
+        extraExtensions,
+        onImageUpload,
+        ydoc,
+        awareness,
+        user?.name,
+        user?.email,
+        user?.color,
+        disableHistory,
+    ]);
+    const collab = !!ydoc;
+    // The collab hook needs the editor, but useEditor's `onUpdate` needs the
+    // hook's guards. Break the cycle with a ref: `onUpdate` reads the guards
+    // through `guardsRef`, which is populated right after the hook runs below.
+    // `onUpdate` only ever fires after the editor exists, by which point the ref
+    // holds the real guards.
+    const guardsRef = useRef(null);
+    const editor = useEditor({
+        extensions,
+        // With Collaboration active the prose is owned by the shared Y.XmlFragment.
+        // Seeding `content` here too would make the editor initialize from BOTH the
+        // prop and the Y.Doc, firing a spurious initial update that could autosave a
+        // stale value over newer SQL. The lead-client seed effect populates an empty
+        // doc instead. Non-collab editors keep initializing from `value`.
+        // With Collaboration the Y.Doc owns the prose (seeded by the lead client).
+        // With a custom `setContent` the reconcile seeds the editor too (the raw
+        // `value` is not directly settable content — e.g. the plan's blocks JSON),
+        // so only the plain markdown path seeds from `value` here.
+        content: collab || setContent ? null : value,
+        editable,
+        editorProps: {
+            attributes: {
+                class: cn("an-rich-md-prose", editorClassName),
+                ...(ariaLabel ? { role: "textbox", "aria-label": ariaLabel } : {}),
+            },
+        },
+        onUpdate: ({ editor, transaction }) => {
+            const guards = guardsRef.current;
+            if (!guards || guards.shouldIgnoreUpdate(transaction))
+                return;
+            try {
+                const markdown = readMarkdown(editor);
+                if (!guards.registerEmitted(markdown))
+                    return;
+                queueMicrotask(() => onChangeRef.current(markdown));
+            }
+            catch (error) {
+                console.error("Markdown serialization error:", error);
+            }
+        },
+        onBlur: () => {
+            onBlurRef.current?.();
+        },
+        // Recreate the editor when the shared Y.Doc identity changes — including
+        // null → doc. Extensions are baked in at creation, so a ydoc that arrives
+        // AFTER the first mount (fresh page load: the session/user resolves after
+        // the editor mounts) would otherwise never bind Collaboration: the editor
+        // looks fine but produces no Yjs updates and never receives peers' edits.
+    }, [ydoc]);
+    const collabState = useCollabReconcile({
+        editor,
+        ydoc,
+        collabSynced,
+        awareness,
+        value,
+        contentUpdatedAt,
+        editable,
+        getMarkdown: readMarkdown,
+        setContent,
+        parseValue,
+        normalizeValue,
+        shouldSeed,
+        initialAppliedUpdatedAt,
+    });
+    guardsRef.current = collabState;
+    useEffect(() => {
+        if (!editor || editor.isDestroyed)
+            return;
+        editor.setEditable(editable);
+    }, [editable, editor]);
+    useEffect(() => {
+        if (editor)
+            onEditorReady?.(editor);
+    }, [editor, onEditorReady]);
+    useEffect(() => () => editor?.destroy(), [editor]);
+    const handleWrapperClick = (event) => {
+        if (!editable || !editor || editor.isDestroyed)
+            return;
+        const target = event.target;
+        if (target.classList.contains("an-rich-md-wrapper") ||
+            target.classList.contains("an-rich-md-clickable")) {
+            editor.chain().focus("end").run();
+        }
+    };
+    if (!editor) {
+        return (_jsx("div", { className: cn("an-rich-md-wrapper an-rich-md-loading", className), "data-plan-interactive": interactive ? true : undefined }));
+    }
+    return (_jsxs("div", { className: cn("an-rich-md-wrapper an-rich-md-clickable", !editable && "an-rich-md-wrapper--readonly", wrapperClassName, className), onClick: handleWrapperClick, "data-plan-interactive": interactive ? true : undefined, children: [editable ? (_jsx(BubbleToolbar, { editor: editor, buildItems: buildBubbleItems })) : null, editable ? (_jsx(SlashCommandMenu, { editor: editor, items: slashItems })) : null, _jsx(EditorContent, { editor: editor })] }));
+}
+//# sourceMappingURL=SharedRichEditor.js.map

package/dist/editor/SharedRichEditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedRichEditor.js","sourceRoot":"","sources":["../../src/editor/SharedRichEditor.tsx"],"names":[],"mappings":"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"}

package/dist/editor/SlashCommandMenu.d.ts

@@ -0,0 +1,41 @@
+import type { Editor } from "@tiptap/react";
+import { type ImageUploadFn } from "./ImageExtension.js";
+/** A single slash-menu block command. Apps can extend the default list. */
+export interface SlashCommandItem {
+    title: string;
+    description: string;
+    /**
+     * Optional hidden search text. Use this for raw block types and aliases that
+     * should match slash queries without making the visible description verbose.
+     */
+    searchText?: string;
+    /** Short text glyph shown in the menu (T, H1, tbl, …). */
+    icon: string;
+    action: (editor: Editor) => void;
+}
+/**
+ * The default block commands — Plan's current set. Apps pass their own `items`
+ * (typically `[...DEFAULT_SLASH_COMMANDS, ...extra]`) to extend it.
+ */
+export declare const DEFAULT_SLASH_COMMANDS: SlashCommandItem[];
+/**
+ * Build the `/image` slash command for the shared image block. Requires the
+ * editor to mount the shared image extension (`features.image`) and an
+ * {@link ImageUploadFn}; the command opens a native file picker and uploads +
+ * inserts the chosen image(s). Add it to the list an app passes to
+ * {@link SlashCommandMenu} (e.g. `[...DEFAULT_SLASH_COMMANDS, createImageSlashCommand(upload)]`).
+ */
+export declare function createImageSlashCommand(upload: ImageUploadFn): SlashCommandItem;
+export interface SlashCommandMenuProps {
+    editor: Editor;
+    /** Block command list. Defaults to {@link DEFAULT_SLASH_COMMANDS}. */
+    items?: SlashCommandItem[];
+}
+/**
+ * The shared "/" block-insert menu. Detects a `/query` at the caret, filters the
+ * provided command list, and renders a fixed-position picker with keyboard
+ * navigation. Extracted from the inline plan menu so apps share one
+ * implementation and only swap the command list.
+ */
+export declare function SlashCommandMenu({ editor, items, }: SlashCommandMenuProps): import("react").JSX.Element | null;
+//# sourceMappingURL=SlashCommandMenu.d.ts.map

package/dist/editor/SlashCommandMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlashCommandMenu.d.ts","sourceRoot":"","sources":["../../src/editor/SlashCommandMenu.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAW5C,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE7E,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,gBAAgB,EA2EpD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,GACpB,gBAAgB,CAOlB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,KAA8B,GAC/B,EAAE,qBAAqB,sCAwKvB"}