@defensestation/y-comments-prosemirror 1.0.0-dev.84f89ec

package/dist/anchors.d.ts

@@ -0,0 +1,27 @@
+import type { Anchor } from "@defensestation/y-comments-core";
+import type { EditorState } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+export declare const MAX_QUOTE_LENGTH = 2000;
+export declare const DEFAULT_CONTEXT_LENGTH = 32;
+/**
+ * Block separator used for every plain-text projection of the document
+ * (quoted text, prefix/suffix, DocAdapter docText/containerText). All of
+ * them must agree, or a quote that spans blocks could never re-anchor.
+ */
+export declare const BLOCK_SEPARATOR = "\n";
+/** Inline leaf nodes project to one character, keeping offsets aligned. */
+export declare const LEAF_TEXT = " ";
+export interface AnchorFromSelectionOptions {
+    /** Max chars of prefix/suffix context stored. Default 32. */
+    contextLen?: number;
+    /**
+     * Max selection size (chars) we are willing to anchor. Larger selections
+     * are refused rather than truncated — a truncated quote would silently
+     * degrade re-anchoring. Default 2000.
+     */
+    maxQuoteLength?: number;
+}
+/** Build an Anchor for the current selection. Throws on empty selections. */
+export declare function anchorFromSelection(view: EditorView, opts?: AnchorFromSelectionOptions): Anchor;
+/** Build an Anchor for an arbitrary document range. */
+export declare function anchorFromRange(state: EditorState, from: number, to: number, opts?: AnchorFromSelectionOptions): Anchor;

package/dist/anchors.js

@@ -0,0 +1,72 @@
+import { absolutePositionToRelativePosition } from "y-prosemirror";
+import * as Y from "yjs";
+import { getYSyncState } from "./ysync.js";
+export const MAX_QUOTE_LENGTH = 2000;
+export const DEFAULT_CONTEXT_LENGTH = 32;
+/**
+ * Block separator used for every plain-text projection of the document
+ * (quoted text, prefix/suffix, DocAdapter docText/containerText). All of
+ * them must agree, or a quote that spans blocks could never re-anchor.
+ */
+export const BLOCK_SEPARATOR = "\n";
+/** Inline leaf nodes project to one character, keeping offsets aligned. */
+export const LEAF_TEXT = " ";
+/** Build an Anchor for the current selection. Throws on empty selections. */
+export function anchorFromSelection(view, opts) {
+    const { from, to } = view.state.selection;
+    return anchorFromRange(view.state, from, to, opts);
+}
+/** Build an Anchor for an arbitrary document range. */
+export function anchorFromRange(state, from, to, opts) {
+    const contextLen = opts?.contextLen ?? DEFAULT_CONTEXT_LENGTH;
+    const maxQuoteLength = opts?.maxQuoteLength ?? MAX_QUOTE_LENGTH;
+    const ystate = getYSyncState(state);
+    const quotedText = state.doc.textBetween(from, to, BLOCK_SEPARATOR, LEAF_TEXT);
+    if (quotedText.trim().length === 0) {
+        throw new Error("y-comments: cannot create an anchor for an empty or whitespace-only selection.");
+    }
+    if (quotedText.length > maxQuoteLength) {
+        throw new Error(`y-comments: refusing to anchor a selection of ${quotedText.length} chars ` +
+            `(limit ${maxQuoteLength}). Comment on a smaller selection instead.`);
+    }
+    const $from = state.doc.resolve(from);
+    const $to = state.doc.resolve(to);
+    // Context clamped to the enclosing textblock on each side.
+    const prefixStart = Math.max($from.start(), from - contextLen);
+    const prefix = state.doc.textBetween(prefixStart, from, BLOCK_SEPARATOR, LEAF_TEXT);
+    const suffixEnd = Math.min($to.end(), to + contextLen);
+    const suffix = state.doc.textBetween(to, suffixEnd, BLOCK_SEPARATOR, LEAF_TEXT);
+    // Nearest ancestor with a stable id attr — BlockNote's blockContainer.
+    let containerId;
+    for (let depth = $from.depth; depth > 0; depth--) {
+        const id = $from.node(depth).attrs?.id;
+        if (typeof id === "string" && id.length > 0) {
+            containerId = id;
+            break;
+        }
+    }
+    // `from` associates right and `to` associates left, so typing at the
+    // edges of the range does not grow the highlight.
+    const relFrom = absolutePositionToRelativePosition(from, ystate.type, ystate.binding.mapping);
+    const relTo = withLeftAssociation(absolutePositionToRelativePosition(to, ystate.type, ystate.binding.mapping), ystate.doc);
+    return {
+        relFrom: Y.encodeRelativePosition(relFrom),
+        relTo: Y.encodeRelativePosition(relTo),
+        containerId,
+        quotedText,
+        prefix,
+        suffix,
+    };
+}
+/**
+ * y-prosemirror always creates right-associated relative positions; rebuild
+ * the range end as left-associated so it sticks to the last selected
+ * character instead of whatever follows it.
+ */
+function withLeftAssociation(relPos, doc) {
+    const abs = Y.createAbsolutePositionFromRelativePosition(relPos, doc);
+    if (abs === null || !(abs.type instanceof Y.XmlText)) {
+        return relPos;
+    }
+    return Y.createRelativePositionFromTypeIndex(abs.type, abs.index, -1);
+}

package/dist/doc-adapter.d.ts

@@ -0,0 +1,12 @@
+import type { DocAdapter } from "@defensestation/y-comments-core";
+import type { EditorState } from "prosemirror-state";
+/**
+ * DocAdapter over a live y-prosemirror-bound EditorState. All resolved
+ * positions are ProseMirror document positions (`RelResolved.index`) inside
+ * a single shared position space (`RelResolved.type`), so core's
+ * "same type, from < to" exact check keeps working.
+ *
+ * Build a fresh adapter per resolution pass — text maps are cached for the
+ * lifetime of the adapter and go stale with the next document change.
+ */
+export declare function createDocAdapter(state: EditorState): DocAdapter;

package/dist/doc-adapter.js

@@ -0,0 +1,105 @@
+import { relativePositionToAbsolutePosition } from "y-prosemirror";
+import * as Y from "yjs";
+import { BLOCK_SEPARATOR, LEAF_TEXT } from "./anchors.js";
+import { getYSyncState } from "./ysync.js";
+/**
+ * Flatten every textblock under `root` into one string, joined with
+ * BLOCK_SEPARATOR, recording enough to map text offsets back to PM
+ * positions. Inline leaves count as one LEAF_TEXT char, matching how
+ * anchors capture quoted text.
+ */
+function buildTextMap(root, contentBase) {
+    let text = "";
+    const segments = [];
+    const addTextblock = (node, pmStart) => {
+        if (text.length > 0) {
+            text += BLOCK_SEPARATOR;
+        }
+        const blockText = node.textBetween(0, node.content.size, BLOCK_SEPARATOR, LEAF_TEXT);
+        segments.push({ textStart: text.length, pmStart, length: blockText.length });
+        text += blockText;
+    };
+    if (root.isTextblock) {
+        addTextblock(root, contentBase);
+    }
+    else {
+        root.descendants((node, pos) => {
+            if (node.isTextblock) {
+                addTextblock(node, contentBase + pos + 1);
+                return false;
+            }
+            return true;
+        });
+    }
+    return { text, segments };
+}
+function offsetToPmPos(map, offset) {
+    for (const seg of map.segments) {
+        if (offset >= seg.textStart && offset <= seg.textStart + seg.length) {
+            return seg.pmStart + (offset - seg.textStart);
+        }
+    }
+    return null;
+}
+/**
+ * DocAdapter over a live y-prosemirror-bound EditorState. All resolved
+ * positions are ProseMirror document positions (`RelResolved.index`) inside
+ * a single shared position space (`RelResolved.type`), so core's
+ * "same type, from < to" exact check keeps working.
+ *
+ * Build a fresh adapter per resolution pass — text maps are cached for the
+ * lifetime of the adapter and go stale with the next document change.
+ */
+export function createDocAdapter(state) {
+    const ystate = getYSyncState(state);
+    const positionSpace = { doc: state.doc };
+    let docMap = null;
+    const containerMaps = new Map();
+    const getDocMap = () => {
+        if (docMap === null) {
+            docMap = buildTextMap(state.doc, 0);
+        }
+        return docMap;
+    };
+    const getContainerMap = (containerId) => {
+        if (!containerMaps.has(containerId)) {
+            let found = null;
+            state.doc.descendants((node, pos) => {
+                if (found !== null) {
+                    return false;
+                }
+                if (node.attrs?.id === containerId) {
+                    found = buildTextMap(node, pos + 1);
+                    return false;
+                }
+                return true;
+            });
+            containerMaps.set(containerId, found);
+        }
+        return containerMaps.get(containerId) ?? null;
+    };
+    return {
+        resolveRel(encoded) {
+            const relPos = Y.decodeRelativePosition(encoded);
+            const pos = relativePositionToAbsolutePosition(ystate.doc, ystate.type, relPos, ystate.binding.mapping);
+            if (pos === null || pos < 0 || pos > state.doc.content.size) {
+                return null;
+            }
+            return { type: positionSpace, index: pos };
+        },
+        containerText(containerId) {
+            return getContainerMap(containerId)?.text ?? null;
+        },
+        docText() {
+            return getDocMap().text;
+        },
+        fromTextOffset(containerId, offset) {
+            const map = containerId === null ? getDocMap() : getContainerMap(containerId);
+            if (map === null) {
+                return null;
+            }
+            const pos = offsetToPmPos(map, offset);
+            return pos === null ? null : { type: positionSpace, index: pos };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { anchorFromSelection, anchorFromRange, MAX_QUOTE_LENGTH, DEFAULT_CONTEXT_LENGTH, BLOCK_SEPARATOR, LEAF_TEXT, type AnchorFromSelectionOptions, } from "./anchors.js";
+export { createDocAdapter } from "./doc-adapter.js";
+export { getYSyncState, type YSyncState } from "./ysync.js";
+export { yCommentsPlugin, yCommentsPluginKey, setThreads, selectThread, setPendingRange, getResolutions, getSelectedThreadId, getThreads, DEFAULT_HIGHLIGHT_CLASS, DEFAULT_ACTIVE_CLASS, DEFAULT_PENDING_CLASS, DEFAULT_DEBOUNCE_MS, type YCommentsState, type YCommentsPluginOptions, type PendingRange, } from "./plugin.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { anchorFromSelection, anchorFromRange, MAX_QUOTE_LENGTH, DEFAULT_CONTEXT_LENGTH, BLOCK_SEPARATOR, LEAF_TEXT, } from "./anchors.js";
+export { createDocAdapter } from "./doc-adapter.js";
+export { getYSyncState } from "./ysync.js";
+export { yCommentsPlugin, yCommentsPluginKey, setThreads, selectThread, setPendingRange, getResolutions, getSelectedThreadId, getThreads, DEFAULT_HIGHLIGHT_CLASS, DEFAULT_ACTIVE_CLASS, DEFAULT_PENDING_CLASS, DEFAULT_DEBOUNCE_MS, } from "./plugin.js";

package/dist/plugin.d.ts

@@ -0,0 +1,72 @@
+import { type Anchor, type Resolution, type Thread } from "@defensestation/y-comments-core";
+import { Plugin, PluginKey, type EditorState } from "prosemirror-state";
+import { DecorationSet, type EditorView } from "prosemirror-view";
+export declare const DEFAULT_HIGHLIGHT_CLASS = "y-comments-highlight";
+export declare const DEFAULT_ACTIVE_CLASS = "y-comments-active";
+export declare const DEFAULT_PENDING_CLASS = "y-comments-pending";
+export declare const DEFAULT_DEBOUNCE_MS = 150;
+export interface PendingRange {
+    from: number;
+    to: number;
+}
+export interface YCommentsState {
+    threads: Thread[];
+    /** Bumped on every setThreads, so the view can detect thread changes. */
+    threadsVersion: number;
+    resolutions: Map<string, Resolution>;
+    selectedThreadId: string | null;
+    /** Range currently being commented on (composer open) — highlighted so
+     *  the author can still see what they selected while typing. */
+    pendingRange: PendingRange | null;
+    decorations: DecorationSet;
+}
+export declare const yCommentsPluginKey: PluginKey<YCommentsState>;
+export interface YCommentsPluginOptions {
+    /** Trailing debounce for full re-resolution after doc changes. Default 150 ms. */
+    debounceMs?: number;
+    /** Fired when a highlight is clicked (threadId) or the selection is cleared (null). */
+    onThreadSelect?: (threadId: string | null) => void;
+    /** Fired after every re-resolution pass with the fresh resolutions. */
+    onResolutionsChange?: (resolutions: Map<string, Resolution>) => void;
+    /**
+     * After a `reanchored` resolution whose text still equals the stored
+     * quote exactly, persist a fresh anchor via `store.updateAnchor`.
+     * Off by default: it writes to the thread store on read, which surprises
+     * audit logs and requires update permission on every reader.
+     */
+    selfHeal?: boolean;
+    /** Store used for self-healing. Only `updateAnchor` is consulted. */
+    store?: {
+        updateAnchor?: (input: {
+            threadId: string;
+            anchor: Anchor;
+        }) => Promise<void>;
+    };
+    highlightClass?: string;
+    activeClass?: string;
+    pendingClass?: string;
+}
+/**
+ * View-only comment highlights: threads live in an external store, anchors
+ * resolve through Yjs relative positions, and highlights render as inline
+ * decorations. Nothing here ever writes to the document or the Y.Doc.
+ *
+ * Decorations are mapped through `tr.mapping` on every transaction (so they
+ * track keystrokes instantly) and fully re-resolved on a trailing debounce
+ * (so they stay correct after structural edits).
+ */
+export declare function yCommentsPlugin(options?: YCommentsPluginOptions): Plugin<YCommentsState>;
+/** Feed a fresh thread list into the plugin (dispatches a meta transaction). */
+export declare function setThreads(view: EditorView, threads: Thread[]): void;
+/** Select (highlight as active) a thread, or pass null to deselect. */
+export declare function selectThread(view: EditorView, threadId: string | null): void;
+/**
+ * Highlight the range currently being commented on (composer open), or
+ * pass null to clear. Keeps the author's selection visible while focus is
+ * in the composer.
+ */
+export declare function setPendingRange(view: EditorView, range: PendingRange | null): void;
+/** Latest resolutions, keyed by thread id. Sidebars use this for ordering. */
+export declare function getResolutions(state: EditorState): Map<string, Resolution>;
+export declare function getSelectedThreadId(state: EditorState): string | null;
+export declare function getThreads(state: EditorState): Thread[];

package/dist/plugin.js

@@ -0,0 +1,256 @@
+import { resolveThread, } from "@defensestation/y-comments-core";
+import { Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+import { anchorFromRange, BLOCK_SEPARATOR, LEAF_TEXT } from "./anchors.js";
+import { createDocAdapter } from "./doc-adapter.js";
+export const DEFAULT_HIGHLIGHT_CLASS = "y-comments-highlight";
+export const DEFAULT_ACTIVE_CLASS = "y-comments-active";
+export const DEFAULT_PENDING_CLASS = "y-comments-pending";
+export const DEFAULT_DEBOUNCE_MS = 150;
+export const yCommentsPluginKey = new PluginKey("yComments");
+function buildDecorations(doc, threads, resolutions, selectedThreadId, pendingRange, highlightClass, activeClass, pendingClass) {
+    const decorations = [];
+    if (pendingRange && pendingRange.from < pendingRange.to) {
+        decorations.push(Decoration.inline(Math.max(0, pendingRange.from), Math.min(doc.content.size, pendingRange.to), { class: pendingClass }));
+    }
+    for (const thread of threads) {
+        // Resolved threads get no persistent highlight (parity with BlockNote);
+        // container/orphaned threads render in the sidebar only.
+        if (thread.resolved) {
+            continue;
+        }
+        const resolution = resolutions.get(thread.id);
+        if (!resolution || (resolution.kind !== "exact" && resolution.kind !== "reanchored")) {
+            continue;
+        }
+        const from = Math.max(0, resolution.from.index);
+        const to = Math.min(doc.content.size, resolution.to.index);
+        if (from >= to) {
+            continue;
+        }
+        const active = thread.id === selectedThreadId;
+        decorations.push(Decoration.inline(from, to, {
+            class: active ? `${highlightClass} ${activeClass}` : highlightClass,
+            "data-thread-id": thread.id,
+        }));
+    }
+    return DecorationSet.create(doc, decorations);
+}
+function resolutionsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const [id, ra] of a) {
+        const rb = b.get(id);
+        if (!rb || ra.kind !== rb.kind) {
+            return false;
+        }
+        if ((ra.kind === "exact" || ra.kind === "reanchored") &&
+            (rb.kind === "exact" || rb.kind === "reanchored") &&
+            (ra.from.index !== rb.from.index || ra.to.index !== rb.to.index)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * View-only comment highlights: threads live in an external store, anchors
+ * resolve through Yjs relative positions, and highlights render as inline
+ * decorations. Nothing here ever writes to the document or the Y.Doc.
+ *
+ * Decorations are mapped through `tr.mapping` on every transaction (so they
+ * track keystrokes instantly) and fully re-resolved on a trailing debounce
+ * (so they stay correct after structural edits).
+ */
+export function yCommentsPlugin(options = {}) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const highlightClass = options.highlightClass ?? DEFAULT_HIGHLIGHT_CLASS;
+    const activeClass = options.activeClass ?? DEFAULT_ACTIVE_CLASS;
+    const pendingClass = options.pendingClass ?? DEFAULT_PENDING_CLASS;
+    const rebuild = (state, doc) => buildDecorations(doc, state.threads, state.resolutions, state.selectedThreadId, state.pendingRange, highlightClass, activeClass, pendingClass);
+    return new Plugin({
+        key: yCommentsPluginKey,
+        state: {
+            init() {
+                return {
+                    threads: [],
+                    threadsVersion: 0,
+                    resolutions: new Map(),
+                    selectedThreadId: null,
+                    pendingRange: null,
+                    decorations: DecorationSet.empty,
+                };
+            },
+            apply(tr, prev, _oldState, newState) {
+                let next = prev;
+                if (tr.docChanged) {
+                    // Map resolutions alongside the decorations: a meta rebuild (e.g.
+                    // a thread-store poll landing inside the debounce window) must
+                    // never rebuild from pre-edit positions.
+                    const mappedResolutions = new Map();
+                    for (const [id, res] of next.resolutions) {
+                        if (res.kind === "exact" || res.kind === "reanchored") {
+                            mappedResolutions.set(id, {
+                                ...res,
+                                from: { ...res.from, index: tr.mapping.map(res.from.index, 1) },
+                                to: { ...res.to, index: tr.mapping.map(res.to.index, -1) },
+                            });
+                        }
+                        else {
+                            mappedResolutions.set(id, res);
+                        }
+                    }
+                    next = {
+                        ...next,
+                        resolutions: mappedResolutions,
+                        pendingRange: next.pendingRange
+                            ? {
+                                from: tr.mapping.map(next.pendingRange.from, 1),
+                                to: tr.mapping.map(next.pendingRange.to, -1),
+                            }
+                            : null,
+                        decorations: next.decorations.map(tr.mapping, tr.doc),
+                    };
+                }
+                const meta = tr.getMeta(yCommentsPluginKey);
+                if (meta) {
+                    switch (meta.type) {
+                        case "setThreads":
+                            next = { ...next, threads: meta.threads, threadsVersion: next.threadsVersion + 1 };
+                            break;
+                        case "setResolutions":
+                            next = { ...next, resolutions: meta.resolutions };
+                            break;
+                        case "selectThread":
+                            next = { ...next, selectedThreadId: meta.threadId };
+                            break;
+                        case "setPendingRange":
+                            next = { ...next, pendingRange: meta.range };
+                            break;
+                    }
+                    next = { ...next, decorations: rebuild(next, newState.doc) };
+                }
+                return next;
+            },
+        },
+        view(editorView) {
+            let timer;
+            let destroyed = false;
+            const recompute = () => {
+                if (destroyed) {
+                    return;
+                }
+                const state = editorView.state;
+                const pluginState = yCommentsPluginKey.getState(state);
+                if (!pluginState) {
+                    return;
+                }
+                let adapter;
+                try {
+                    adapter = createDocAdapter(state);
+                }
+                catch {
+                    // Editor not (yet) collaborative — nothing to resolve against.
+                    return;
+                }
+                const resolutions = new Map();
+                for (const thread of pluginState.threads) {
+                    resolutions.set(thread.id, resolveThread(thread, adapter));
+                }
+                // Skip the dispatch AND the host callback when nothing changed —
+                // otherwise every debounce tick re-renders the host UI for free.
+                if (!resolutionsEqual(pluginState.resolutions, resolutions)) {
+                    editorView.dispatch(state.tr.setMeta(yCommentsPluginKey, { type: "setResolutions", resolutions }));
+                    options.onResolutionsChange?.(resolutions);
+                }
+                if (options.selfHeal && options.store?.updateAnchor) {
+                    for (const thread of pluginState.threads) {
+                        const resolution = resolutions.get(thread.id);
+                        if (resolution?.kind !== "reanchored") {
+                            continue;
+                        }
+                        const text = state.doc.textBetween(resolution.from.index, resolution.to.index, BLOCK_SEPARATOR, LEAF_TEXT);
+                        // Only heal when the re-resolved text equals the quote exactly.
+                        if (text !== thread.anchor.quotedText) {
+                            continue;
+                        }
+                        try {
+                            const anchor = anchorFromRange(state, resolution.from.index, resolution.to.index);
+                            void options.store.updateAnchor({ threadId: thread.id, anchor }).catch(() => {
+                                /* healing is best-effort */
+                            });
+                        }
+                        catch {
+                            /* healing is best-effort */
+                        }
+                    }
+                }
+            };
+            const schedule = () => {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                timer = setTimeout(recompute, debounceMs);
+            };
+            schedule();
+            return {
+                update(view, prevState) {
+                    const prev = yCommentsPluginKey.getState(prevState);
+                    const current = yCommentsPluginKey.getState(view.state);
+                    if (view.state.doc !== prevState.doc ||
+                        (prev && current && prev.threadsVersion !== current.threadsVersion)) {
+                        schedule();
+                    }
+                },
+                destroy() {
+                    destroyed = true;
+                    if (timer !== undefined) {
+                        clearTimeout(timer);
+                    }
+                },
+            };
+        },
+        props: {
+            decorations(state) {
+                return yCommentsPluginKey.getState(state)?.decorations ?? null;
+            },
+            handleClick(view, _pos, event) {
+                const target = event.target;
+                const span = target?.closest?.("[data-thread-id]");
+                const threadId = span?.getAttribute("data-thread-id") ?? null;
+                const current = yCommentsPluginKey.getState(view.state)?.selectedThreadId ?? null;
+                if (threadId !== current) {
+                    selectThread(view, threadId);
+                    options.onThreadSelect?.(threadId);
+                }
+                return false;
+            },
+        },
+    });
+}
+/** Feed a fresh thread list into the plugin (dispatches a meta transaction). */
+export function setThreads(view, threads) {
+    view.dispatch(view.state.tr.setMeta(yCommentsPluginKey, { type: "setThreads", threads }));
+}
+/** Select (highlight as active) a thread, or pass null to deselect. */
+export function selectThread(view, threadId) {
+    view.dispatch(view.state.tr.setMeta(yCommentsPluginKey, { type: "selectThread", threadId }));
+}
+/**
+ * Highlight the range currently being commented on (composer open), or
+ * pass null to clear. Keeps the author's selection visible while focus is
+ * in the composer.
+ */
+export function setPendingRange(view, range) {
+    view.dispatch(view.state.tr.setMeta(yCommentsPluginKey, { type: "setPendingRange", range }));
+}
+/** Latest resolutions, keyed by thread id. Sidebars use this for ordering. */
+export function getResolutions(state) {
+    return yCommentsPluginKey.getState(state)?.resolutions ?? new Map();
+}
+export function getSelectedThreadId(state) {
+    return yCommentsPluginKey.getState(state)?.selectedThreadId ?? null;
+}
+export function getThreads(state) {
+    return yCommentsPluginKey.getState(state)?.threads ?? [];
+}

package/dist/ysync.d.ts

@@ -0,0 +1,23 @@
+import type { Node as PMNode } from "prosemirror-model";
+import type { EditorState } from "prosemirror-state";
+import type * as Y from "yjs";
+/** ProsemirrorMapping from y-prosemirror (Y type → PM node). */
+export type YSyncMapping = Map<Y.AbstractType<any>, PMNode | PMNode[]>;
+export interface YSyncState {
+    type: Y.XmlFragment;
+    doc: Y.Doc;
+    binding: {
+        mapping: YSyncMapping;
+    } | null;
+}
+/**
+ * Read the y-prosemirror sync plugin state, throwing a descriptive error if
+ * the editor is not collaborative. This package requires the y-prosemirror
+ * binding that BlockNote's collaboration mode installs — without it there
+ * are no Yjs relative positions to anchor to.
+ */
+export declare function getYSyncState(state: EditorState): YSyncState & {
+    binding: {
+        mapping: YSyncMapping;
+    };
+};

package/dist/ysync.js

@@ -0,0 +1,16 @@
+import { ySyncPluginKey } from "y-prosemirror";
+/**
+ * Read the y-prosemirror sync plugin state, throwing a descriptive error if
+ * the editor is not collaborative. This package requires the y-prosemirror
+ * binding that BlockNote's collaboration mode installs — without it there
+ * are no Yjs relative positions to anchor to.
+ */
+export function getYSyncState(state) {
+    const ystate = ySyncPluginKey.getState(state);
+    if (!ystate || !ystate.type || !ystate.doc || !ystate.binding) {
+        throw new Error("y-comments: y-prosemirror sync plugin state not found. " +
+            "Decoration-anchored comments require a collaborative editor bound to a Y.Doc " +
+            "(for BlockNote, pass the `collaboration` option when creating the editor).");
+    }
+    return ystate;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@defensestation/y-comments-prosemirror",
+  "description": "ProseMirror adapter for decoration-anchored Yjs comments: anchor creation from selections, DocAdapter for the resolution chain, and a decorations plugin. No marks, no document writes.",
+  "keywords": [
+    "prosemirror",
+    "yjs",
+    "comments",
+    "decorations",
+    "y-prosemirror"
+  ],
+  "version": "1.0.0-dev.84f89ec",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@defensestation/y-comments-core": "1.0.0-dev.84f89ec"
+  },
+  "peerDependencies": {
+    "prosemirror-model": "^1.19.0",
+    "prosemirror-state": "^1.4.3",
+    "prosemirror-view": "^1.31.0",
+    "y-prosemirror": "^1.2.0",
+    "yjs": "^13.6.0"
+  },
+  "devDependencies": {
+    "prosemirror-model": "^1.25.4",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-view": "^1.41.4",
+    "y-prosemirror": "^1.3.7",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.31"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/defensestation/y-comments",
+    "directory": "packages/y-comments-prosemirror"
+  },
+  "license": "MIT"
+}