@ecsplico/editor 2.0.0 → 2.1.0

package/dist/features/comments/index.js

@@ -1,6 +1,8 @@
 import { COMMENTS_LAYOUTS } from "../../settings/values.js";
-import { Comments, cancelCommentDraft, commentsAvailable, commentsCanComment, commentsDoc, commentsKey, commentsState, commentsUser, setActiveComment, startCommentDraft } from "./comments-plugin.js";
 import { COMMENTS_FIELD, COMMENT_LIMITS, CommentMark, commentsSchemaExtensions } from "./schema.js";
+import { Comments, cancelCommentDraft, commentsAvailable, commentsCanComment, commentsDoc, commentsKey, commentsState, commentsUser, setActiveComment, startCommentDraft } from "./comments-plugin.js";
 import { commentsModelOf, createCommentsModel, createEditorCommentsModel } from "./model.js";
 import { commentsFeatureCore } from "./feature.js";
-export { COMMENTS_FIELD, COMMENTS_LAYOUTS, COMMENT_LIMITS, CommentMark, Comments, cancelCommentDraft, commentsAvailable, commentsCanComment, commentsDoc, commentsFeatureCore, commentsKey, commentsModelOf, commentsSchemaExtensions, commentsState, commentsUser, createCommentsModel, createEditorCommentsModel, setActiveComment, startCommentDraft };
+import { DRAFT_CARD, MARGIN_GAP, layoutMargin, marginCards } from "./margin-layout.js";
+import { createMarginController } from "./margin-controller.js";
+export { COMMENTS_FIELD, COMMENTS_LAYOUTS, COMMENT_LIMITS, CommentMark, Comments, DRAFT_CARD, MARGIN_GAP, cancelCommentDraft, commentsAvailable, commentsCanComment, commentsDoc, commentsFeatureCore, commentsKey, commentsModelOf, commentsSchemaExtensions, commentsState, commentsUser, createCommentsModel, createEditorCommentsModel, createMarginController, layoutMargin, marginCards, setActiveComment, startCommentDraft };

package/dist/features/comments/margin-controller.d.ts

@@ -0,0 +1,44 @@
+import { ReadonlyStore } from "../../core/store.js";
+import { MarginCard } from "./margin-layout.js";
+import { Editor } from "@tiptap/core";
+//#region src/features/comments/margin-controller.d.ts
+/** What the margin renders from the measurements. */
+export interface MarginState {
+  /** Top of every card by id, relative to the column; empty until the first measurement (cards stay invisible till then). */
+  tops: ReadonlyMap<string, number>;
+  /** Top of the section below the cards (the resolved threads) and the column's minimum height. */
+  resolvedTop: number;
+  minHeight: number;
+}
+/** What the controller lays out, read afresh at every measurement. */
+export interface MarginSource {
+  /** The cards in document order. */
+  cards: () => readonly MarginCard[];
+  /** The card that owns its line (the draft composer or the active thread), if any. */
+  activeId: () => string | null;
+}
+/**
+ * The measuring and scheduling glue of the comments margin, for both frameworks: where each card's line is
+ * (`coordsAtPos`), how tall each card is, one `layoutMargin` per animation frame, re-run after transactions, window and
+ * element resizes. Created inert; `connect()` starts it (call it on mount) and `disconnect()` stops it, and both may
+ * follow each other again (StrictMode mounts twice). Elements are handed in with the `set*` functions (framework
+ * refs), the editor and container with `setEditor` / `setContainer`; none of them needs to exist before `connect()`.
+ */
+export interface MarginController {
+  readonly state: ReadonlyStore<MarginState>;
+  setEditor: (editor: Editor | undefined) => void;
+  /** The editor's scroll container, which the column sits in: its size changes re-run the layout. */
+  setContainer: (container: HTMLElement | null) => void;
+  /** The column (its size flips between zero and real when the host hides it) and the section of resolved threads; `null` or anything but an element clears. */
+  setColumn: (el: unknown) => void;
+  setResolvedSection: (el: unknown) => void;
+  /** A card's element by id (`null` is ignored: cards that are gone are dropped at the next measurement). */
+  setCard: (id: string, el: unknown) => void;
+  /** Measures again on the next animation frame; call when the cards or the active card changed. */
+  schedule: () => void;
+  connect: () => void;
+  disconnect: () => void;
+}
+export declare function createMarginController(source: MarginSource): MarginController;
+//#endregion
+//# sourceMappingURL=margin-controller.d.ts.map

package/dist/features/comments/margin-controller.js

@@ -0,0 +1,132 @@
+import { createStore } from "../../core/store.js";
+import { layoutMargin } from "./margin-layout.js";
+//#region src/features/comments/margin-controller.ts
+const INITIAL = {
+	tops: /* @__PURE__ */ new Map(),
+	resolvedTop: 0,
+	minHeight: 0
+};
+function sameState(a, b) {
+	if (a.resolvedTop !== b.resolvedTop || a.minHeight !== b.minHeight || a.tops.size !== b.tops.size) return false;
+	for (const [id, top] of a.tops) if (b.tops.get(id) !== top) return false;
+	return true;
+}
+const asElement = (el) => el instanceof HTMLElement ? el : null;
+function createMarginController(source) {
+	const state = createStore(INITIAL);
+	const cards = /* @__PURE__ */ new Map();
+	let editor;
+	let container = null;
+	let column = null;
+	let resolvedSection = null;
+	let observer = null;
+	let connected = false;
+	let frame = 0;
+	function schedule() {
+		if (!connected || frame || typeof requestAnimationFrame === "undefined") return;
+		frame = requestAnimationFrame(measure);
+	}
+	/** Top of the line at document position `pos`, relative to the column; null where the position is not rendered (yet). */
+	function lineTop(instance, pos, base) {
+		try {
+			return instance.view.coordsAtPos(Math.max(0, Math.min(pos, instance.state.doc.content.size))).top - base;
+		} catch {
+			return null;
+		}
+	}
+	function measure() {
+		frame = 0;
+		const instance = editor;
+		if (!instance || instance.isDestroyed || !column || !column.getClientRects().length) return;
+		const list = source.cards();
+		const live = new Set(list.map((card) => card.id));
+		for (const [id, el] of cards) {
+			if (live.has(id)) continue;
+			observer?.unobserve(el);
+			cards.delete(id);
+		}
+		const base = column.getBoundingClientRect().top;
+		const entries = list.map((card) => ({
+			id: card.id,
+			top: card.pos === null ? null : lineTop(instance, card.pos, base),
+			height: cards.get(card.id)?.offsetHeight ?? 0
+		}));
+		const { tops, bottom } = layoutMargin(entries, source.activeId());
+		const resolvedTop = entries.length ? bottom + 16 : 0;
+		const next = {
+			tops,
+			resolvedTop,
+			minHeight: resolvedTop + (resolvedSection?.offsetHeight ?? 0)
+		};
+		if (!sameState(state.get(), next)) state.set(next);
+	}
+	/** Replaces the element held in a slot, moving the resize observation along. */
+	function swap(previous, next) {
+		if (previous === next) return previous;
+		if (previous) observer?.unobserve(previous);
+		if (next) observer?.observe(next);
+		schedule();
+		return next;
+	}
+	const onTransaction = () => schedule();
+	function connect() {
+		if (connected) return;
+		connected = true;
+		if (typeof ResizeObserver !== "undefined") {
+			observer = new ResizeObserver(schedule);
+			for (const el of [
+				column,
+				resolvedSection,
+				container,
+				...cards.values()
+			]) if (el) observer.observe(el);
+		}
+		editor?.on("transaction", onTransaction);
+		window.addEventListener("resize", schedule);
+		schedule();
+	}
+	function disconnect() {
+		if (!connected) return;
+		connected = false;
+		editor?.off("transaction", onTransaction);
+		window.removeEventListener("resize", schedule);
+		observer?.disconnect();
+		observer = null;
+		if (frame) cancelAnimationFrame(frame);
+		frame = 0;
+	}
+	return {
+		state,
+		setEditor(next) {
+			if (next === editor) return;
+			if (connected) editor?.off("transaction", onTransaction);
+			editor = next;
+			if (connected) next?.on("transaction", onTransaction);
+			schedule();
+		},
+		setContainer(next) {
+			container = swap(container, next);
+		},
+		setColumn(el) {
+			column = swap(column, asElement(el));
+		},
+		setResolvedSection(el) {
+			resolvedSection = swap(resolvedSection, asElement(el));
+		},
+		setCard(id, el) {
+			const next = asElement(el);
+			if (!next || cards.get(id) === next) return;
+			const previous = cards.get(id);
+			if (previous) observer?.unobserve(previous);
+			cards.set(id, next);
+			observer?.observe(next);
+		},
+		schedule,
+		connect,
+		disconnect
+	};
+}
+//#endregion
+export { createMarginController };
+
+//# sourceMappingURL=margin-controller.js.map

package/dist/features/comments/margin-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"margin-controller.js","names":[],"sources":["../../../src/features/comments/margin-controller.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport { createStore, type ReadonlyStore } from '../../core/store'\nimport { layoutMargin, type MarginCard, type MarginEntry, MARGIN_GAP } from './margin-layout'\n\n/** What the margin renders from the measurements. */\nexport interface MarginState {\n  /** Top of every card by id, relative to the column; empty until the first measurement (cards stay invisible till then). */\n  tops: ReadonlyMap<string, number>\n  /** Top of the section below the cards (the resolved threads) and the column's minimum height. */\n  resolvedTop: number\n  minHeight: number\n}\n\n/** What the controller lays out, read afresh at every measurement. */\nexport interface MarginSource {\n  /** The cards in document order. */\n  cards: () => readonly MarginCard[]\n  /** The card that owns its line (the draft composer or the active thread), if any. */\n  activeId: () => string | null\n}\n\n/**\n * The measuring and scheduling glue of the comments margin, for both frameworks: where each card's line is\n * (`coordsAtPos`), how tall each card is, one `layoutMargin` per animation frame, re-run after transactions, window and\n * element resizes. Created inert; `connect()` starts it (call it on mount) and `disconnect()` stops it, and both may\n * follow each other again (StrictMode mounts twice). Elements are handed in with the `set*` functions (framework\n * refs), the editor and container with `setEditor` / `setContainer`; none of them needs to exist before `connect()`.\n */\nexport interface MarginController {\n  readonly state: ReadonlyStore<MarginState>\n  setEditor: (editor: Editor | undefined) => void\n  /** The editor's scroll container, which the column sits in: its size changes re-run the layout. */\n  setContainer: (container: HTMLElement | null) => void\n  /** The column (its size flips between zero and real when the host hides it) and the section of resolved threads; `null` or anything but an element clears. */\n  setColumn: (el: unknown) => void\n  setResolvedSection: (el: unknown) => void\n  /** A card's element by id (`null` is ignored: cards that are gone are dropped at the next measurement). */\n  setCard: (id: string, el: unknown) => void\n  /** Measures again on the next animation frame; call when the cards or the active card changed. */\n  schedule: () => void\n  connect: () => void\n  disconnect: () => void\n}\n\nconst INITIAL: MarginState = { tops: new Map(), resolvedTop: 0, minHeight: 0 }\n\nfunction sameState(a: MarginState, b: MarginState): boolean {\n  if (a.resolvedTop !== b.resolvedTop || a.minHeight !== b.minHeight || a.tops.size !== b.tops.size) return false\n  for (const [id, top] of a.tops) {\n    if (b.tops.get(id) !== top) return false\n  }\n  return true\n}\n\nconst asElement = (el: unknown): HTMLElement | null => el instanceof HTMLElement ? el : null\n\nexport function createMarginController(source: MarginSource): MarginController {\n  const state = createStore<MarginState>(INITIAL)\n  const cards = new Map<string, HTMLElement>()\n  let editor: Editor | undefined\n  let container: HTMLElement | null = null\n  let column: HTMLElement | null = null\n  let resolvedSection: HTMLElement | null = null\n  let observer: ResizeObserver | null = null\n  let connected = false\n  let frame = 0\n\n  function schedule() {\n    if (!connected || frame || typeof requestAnimationFrame === 'undefined') return\n    frame = requestAnimationFrame(measure)\n  }\n\n  /** Top of the line at document position `pos`, relative to the column; null where the position is not rendered (yet). */\n  function lineTop(instance: Editor, pos: number, base: number): number | null {\n    try {\n      return instance.view.coordsAtPos(Math.max(0, Math.min(pos, instance.state.doc.content.size))).top - base\n    }\n    catch {\n      return null\n    }\n  }\n\n  function measure() {\n    frame = 0\n    const instance = editor\n    // Hidden columns have no layout box; the column's own ResizeObserver re-runs this once shown.\n    if (!instance || instance.isDestroyed || !column || !column.getClientRects().length) return\n    const list = source.cards()\n    const live = new Set(list.map(card => card.id))\n    for (const [id, el] of cards) {\n      if (live.has(id)) continue\n      observer?.unobserve(el)\n      cards.delete(id)\n    }\n    const base = column.getBoundingClientRect().top\n    const entries: MarginEntry[] = list.map(card => ({\n      id: card.id,\n      top: card.pos === null ? null : lineTop(instance, card.pos, base),\n      height: cards.get(card.id)?.offsetHeight ?? 0,\n    }))\n    const { tops, bottom } = layoutMargin(entries, source.activeId())\n    const resolvedTop = entries.length ? bottom + 2 * MARGIN_GAP : 0\n    const next: MarginState = { tops, resolvedTop, minHeight: resolvedTop + (resolvedSection?.offsetHeight ?? 0) }\n    if (!sameState(state.get(), next)) state.set(next)\n  }\n\n  /** Replaces the element held in a slot, moving the resize observation along. */\n  function swap(previous: HTMLElement | null, next: HTMLElement | null): HTMLElement | null {\n    if (previous === next) return previous\n    if (previous) observer?.unobserve(previous)\n    if (next) observer?.observe(next)\n    schedule()\n    return next\n  }\n\n  const onTransaction = () => schedule()\n\n  function connect() {\n    if (connected) return\n    connected = true\n    if (typeof ResizeObserver !== 'undefined') {\n      observer = new ResizeObserver(schedule)\n      for (const el of [column, resolvedSection, container, ...cards.values()]) {\n        if (el) observer.observe(el)\n      }\n    }\n    editor?.on('transaction', onTransaction)\n    window.addEventListener('resize', schedule)\n    schedule()\n  }\n\n  function disconnect() {\n    if (!connected) return\n    connected = false\n    editor?.off('transaction', onTransaction)\n    window.removeEventListener('resize', schedule)\n    observer?.disconnect()\n    observer = null\n    if (frame) cancelAnimationFrame(frame)\n    frame = 0\n  }\n\n  return {\n    state,\n    setEditor(next) {\n      if (next === editor) return\n      if (connected) editor?.off('transaction', onTransaction)\n      editor = next\n      if (connected) next?.on('transaction', onTransaction)\n      schedule()\n    },\n    setContainer(next) {\n      container = swap(container, next)\n    },\n    setColumn(el) {\n      column = swap(column, asElement(el))\n    },\n    setResolvedSection(el) {\n      resolvedSection = swap(resolvedSection, asElement(el))\n    },\n    setCard(id, el) {\n      const next = asElement(el)\n      if (!next || cards.get(id) === next) return\n      const previous = cards.get(id)\n      if (previous) observer?.unobserve(previous)\n      cards.set(id, next)\n      observer?.observe(next)\n    },\n    schedule,\n    connect,\n    disconnect,\n  }\n}\n"],"mappings":"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"}

package/dist/features/comments/margin-layout.d.ts

@@ -0,0 +1,55 @@
+import { CommentThread } from "./schema.js";
+import { DocRange } from "./model.js";
+//#region src/features/comments/margin-layout.d.ts
+/** Vertical gap between two cards of the comments margin, in px. */
+export declare const MARGIN_GAP = 8;
+/** The id of the draft composer's card (a thread id never looks like this). */
+export declare const DRAFT_CARD = "__draft";
+/** One card of the comments margin as the layout rule sees it. */
+export interface MarginEntry {
+  id: string;
+  /** Top of the line the card belongs to, relative to the column; `null`: the card has no place and follows the others. */
+  top: number | null;
+  /** Measured height of the card. */
+  height: number;
+}
+export interface MarginLayout {
+  /** Top of every entry, relative to the column. */
+  tops: ReadonlyMap<string, number>;
+  /** Bottom edge of the lowest card (`minTop` without entries). */
+  bottom: number;
+}
+/**
+ * The layout rule of the comments margin („Aktiver Faden“). `entries` come in document order. The active card sits
+ * exactly at the top of its line; the cards above it are pushed up, the ones below pushed down, each as close to its own
+ * line as its neighbour allows, and none overlap (`gap` apart). When pushing up would leave the column (above `minTop`,
+ * the column's top offset), the whole stack shifts down just enough. Without an active card (`activeId` null or not among
+ * the entries) the cards stack top-down: each at its line, or right below the previous card when that is taken. Entries
+ * without a line (`top: null`) come last, stacked below the others, and are never pinned.
+ */
+export declare function layoutMargin(entries: readonly MarginEntry[], activeId: string | null, { gap, minTop }?: {
+  gap?: number;
+  minTop?: number;
+}): MarginLayout;
+/** A card of the comments margin: the draft composer, or a thread with the document position its line sits at. */
+export interface MarginCard {
+  id: string;
+  /** Document position of the card's line: the text of an attached thread (its first character), the draft's start, or where an orphan's text was. `null`: unknown, the card goes to the end of the margin. */
+  pos: number | null;
+  /** The thread; `null` for the draft composer. */
+  thread: CommentThread | null;
+  /** The thread's text was deleted. */
+  orphan: boolean;
+}
+/**
+ * The cards of the margin in document order: the draft composer, then the open threads, each at its text. An orphaned
+ * thread sits at its deletion point (`orphanAt`), one without a known deletion point after all the others.
+ */
+export declare function marginCards(source: {
+  draft: DocRange | null;
+  open: readonly CommentThread[];
+  ranges: ReadonlyMap<string, DocRange>;
+  orphanAt: ReadonlyMap<string, number>;
+}): MarginCard[];
+//#endregion
+//# sourceMappingURL=margin-layout.d.ts.map

package/dist/features/comments/margin-layout.js

@@ -0,0 +1,79 @@
+//#region src/features/comments/margin-layout.ts
+/** Vertical gap between two cards of the comments margin, in px. */
+const MARGIN_GAP = 8;
+/** The id of the draft composer's card (a thread id never looks like this). */
+const DRAFT_CARD = "__draft";
+/**
+* The layout rule of the comments margin („Aktiver Faden“). `entries` come in document order. The active card sits
+* exactly at the top of its line; the cards above it are pushed up, the ones below pushed down, each as close to its own
+* line as its neighbour allows, and none overlap (`gap` apart). When pushing up would leave the column (above `minTop`,
+* the column's top offset), the whole stack shifts down just enough. Without an active card (`activeId` null or not among
+* the entries) the cards stack top-down: each at its line, or right below the previous card when that is taken. Entries
+* without a line (`top: null`) come last, stacked below the others, and are never pinned.
+*/
+function layoutMargin(entries, activeId, { gap = 8, minTop = 0 } = {}) {
+	const placed = entries.flatMap((e) => e.top === null ? [] : [{
+		id: e.id,
+		want: e.top,
+		height: e.height
+	}]);
+	const floating = entries.filter((e) => e.top === null);
+	const pinned = activeId === null ? -1 : placed.findIndex((e) => e.id === activeId);
+	let tops = [];
+	if (pinned < 0) {
+		let bottom = minTop - gap;
+		for (const entry of placed) {
+			const top = Math.max(entry.want, bottom + gap);
+			tops.push(top);
+			bottom = top + entry.height;
+		}
+	} else {
+		tops[pinned] = placed[pinned].want;
+		for (let i = pinned - 1; i >= 0; i--) tops[i] = Math.min(placed[i].want, tops[i + 1] - gap - placed[i].height);
+		for (let i = pinned + 1; i < placed.length; i++) tops[i] = Math.max(placed[i].want, tops[i - 1] + placed[i - 1].height + gap);
+		const overflow = minTop - Math.min(...tops);
+		if (overflow > 0) tops = tops.map((top) => top + overflow);
+	}
+	const result = /* @__PURE__ */ new Map();
+	let bottom = minTop - gap;
+	placed.forEach((entry, i) => {
+		result.set(entry.id, tops[i]);
+		bottom = Math.max(bottom, tops[i] + entry.height);
+	});
+	for (const entry of floating) {
+		const top = bottom + gap;
+		result.set(entry.id, top);
+		bottom = top + entry.height;
+	}
+	return {
+		tops: result,
+		bottom: Math.max(bottom, minTop)
+	};
+}
+/**
+* The cards of the margin in document order: the draft composer, then the open threads, each at its text. An orphaned
+* thread sits at its deletion point (`orphanAt`), one without a known deletion point after all the others.
+*/
+function marginCards(source) {
+	const cards = [];
+	if (source.draft) cards.push({
+		id: DRAFT_CARD,
+		pos: source.draft.from,
+		thread: null,
+		orphan: false
+	});
+	for (const thread of source.open) {
+		const range = source.ranges.get(thread.id);
+		cards.push({
+			id: thread.id,
+			pos: range ? range.from : source.orphanAt.get(thread.id) ?? null,
+			thread,
+			orphan: !range
+		});
+	}
+	return cards.sort((a, b) => a.pos === b.pos ? 0 : a.pos === null ? 1 : b.pos === null ? -1 : a.pos - b.pos);
+}
+//#endregion
+export { DRAFT_CARD, MARGIN_GAP, layoutMargin, marginCards };
+
+//# sourceMappingURL=margin-layout.js.map

package/dist/features/comments/margin-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"margin-layout.js","names":[],"sources":["../../../src/features/comments/margin-layout.ts"],"sourcesContent":["import type { DocRange } from './model'\nimport type { CommentThread } from './schema'\n\n/** Vertical gap between two cards of the comments margin, in px. */\nexport const MARGIN_GAP = 8\n\n/** The id of the draft composer's card (a thread id never looks like this). */\nexport const DRAFT_CARD = '__draft'\n\n/** One card of the comments margin as the layout rule sees it. */\nexport interface MarginEntry {\n  id: string\n  /** Top of the line the card belongs to, relative to the column; `null`: the card has no place and follows the others. */\n  top: number | null\n  /** Measured height of the card. */\n  height: number\n}\n\nexport interface MarginLayout {\n  /** Top of every entry, relative to the column. */\n  tops: ReadonlyMap<string, number>\n  /** Bottom edge of the lowest card (`minTop` without entries). */\n  bottom: number\n}\n\n/**\n * The layout rule of the comments margin („Aktiver Faden“). `entries` come in document order. The active card sits\n * exactly at the top of its line; the cards above it are pushed up, the ones below pushed down, each as close to its own\n * line as its neighbour allows, and none overlap (`gap` apart). When pushing up would leave the column (above `minTop`,\n * the column's top offset), the whole stack shifts down just enough. Without an active card (`activeId` null or not among\n * the entries) the cards stack top-down: each at its line, or right below the previous card when that is taken. Entries\n * without a line (`top: null`) come last, stacked below the others, and are never pinned.\n */\nexport function layoutMargin(\n  entries: readonly MarginEntry[],\n  activeId: string | null,\n  { gap = MARGIN_GAP, minTop = 0 }: { gap?: number, minTop?: number } = {},\n): MarginLayout {\n  const placed = entries.flatMap(e => e.top === null ? [] : [{ id: e.id, want: e.top, height: e.height }])\n  const floating = entries.filter(e => e.top === null)\n  const pinned = activeId === null ? -1 : placed.findIndex(e => e.id === activeId)\n\n  let tops: number[] = []\n  if (pinned < 0) {\n    let bottom = minTop - gap\n    for (const entry of placed) {\n      const top = Math.max(entry.want, bottom + gap)\n      tops.push(top)\n      bottom = top + entry.height\n    }\n  }\n  else {\n    tops[pinned] = placed[pinned]!.want\n    for (let i = pinned - 1; i >= 0; i--) tops[i] = Math.min(placed[i]!.want, tops[i + 1]! - gap - placed[i]!.height)\n    for (let i = pinned + 1; i < placed.length; i++) tops[i] = Math.max(placed[i]!.want, tops[i - 1]! + placed[i - 1]!.height + gap)\n    const overflow = minTop - Math.min(...tops)\n    if (overflow > 0) tops = tops.map(top => top + overflow)\n  }\n\n  const result = new Map<string, number>()\n  let bottom = minTop - gap\n  placed.forEach((entry, i) => {\n    result.set(entry.id, tops[i]!)\n    bottom = Math.max(bottom, tops[i]! + entry.height)\n  })\n  for (const entry of floating) {\n    const top = bottom + gap\n    result.set(entry.id, top)\n    bottom = top + entry.height\n  }\n  return { tops: result, bottom: Math.max(bottom, minTop) }\n}\n\n/** A card of the comments margin: the draft composer, or a thread with the document position its line sits at. */\nexport interface MarginCard {\n  id: string\n  /** Document position of the card's line: the text of an attached thread (its first character), the draft's start, or where an orphan's text was. `null`: unknown, the card goes to the end of the margin. */\n  pos: number | null\n  /** The thread; `null` for the draft composer. */\n  thread: CommentThread | null\n  /** The thread's text was deleted. */\n  orphan: boolean\n}\n\n/**\n * The cards of the margin in document order: the draft composer, then the open threads, each at its text. An orphaned\n * thread sits at its deletion point (`orphanAt`), one without a known deletion point after all the others.\n */\nexport function marginCards(source: {\n  draft: DocRange | null\n  open: readonly CommentThread[]\n  ranges: ReadonlyMap<string, DocRange>\n  orphanAt: ReadonlyMap<string, number>\n}): MarginCard[] {\n  const cards: MarginCard[] = []\n  if (source.draft) cards.push({ id: DRAFT_CARD, pos: source.draft.from, thread: null, orphan: false })\n  for (const thread of source.open) {\n    const range = source.ranges.get(thread.id)\n    cards.push({ id: thread.id, pos: range ? range.from : source.orphanAt.get(thread.id) ?? null, thread, orphan: !range })\n  }\n  // Stable: cards at the same place keep their order (draft first, then the threads' order).\n  return cards.sort((a, b) => a.pos === b.pos ? 0 : a.pos === null ? 1 : b.pos === null ? -1 : a.pos - b.pos)\n}\n"],"mappings":";;AAIA,MAAa,aAAa;;AAG1B,MAAa,aAAa;;;;;;;;;AA0B1B,SAAgB,aACd,SACA,UACA,EAAE,MAAA,GAAkB,SAAS,MAAyC,CAAC,GACzD;CACd,MAAM,SAAS,QAAQ,SAAQ,MAAK,EAAE,QAAQ,OAAO,CAAC,IAAI,CAAC;EAAE,IAAI,EAAE;EAAI,MAAM,EAAE;EAAK,QAAQ,EAAE;CAAO,CAAC,CAAC;CACvG,MAAM,WAAW,QAAQ,QAAO,MAAK,EAAE,QAAQ,IAAI;CACnD,MAAM,SAAS,aAAa,OAAO,KAAK,OAAO,WAAU,MAAK,EAAE,OAAO,QAAQ;CAE/E,IAAI,OAAiB,CAAC;CACtB,IAAI,SAAS,GAAG;EACd,IAAI,SAAS,SAAS;EACtB,KAAK,MAAM,SAAS,QAAQ;GAC1B,MAAM,MAAM,KAAK,IAAI,MAAM,MAAM,SAAS,GAAG;GAC7C,KAAK,KAAK,GAAG;GACb,SAAS,MAAM,MAAM;EACvB;CACF,OACK;EACH,KAAK,UAAU,OAAO,OAAO,CAAE;EAC/B,KAAK,IAAI,IAAI,SAAS,GAAG,KAAK,GAAG,KAAK,KAAK,KAAK,KAAK,IAAI,OAAO,EAAE,CAAE,MAAM,KAAK,IAAI,KAAM,MAAM,OAAO,EAAE,CAAE,MAAM;EAChH,KAAK,IAAI,IAAI,SAAS,GAAG,IAAI,OAAO,QAAQ,KAAK,KAAK,KAAK,KAAK,IAAI,OAAO,EAAE,CAAE,MAAM,KAAK,IAAI,KAAM,OAAO,IAAI,EAAE,CAAE,SAAS,GAAG;EAC/H,MAAM,WAAW,SAAS,KAAK,IAAI,GAAG,IAAI;EAC1C,IAAI,WAAW,GAAG,OAAO,KAAK,KAAI,QAAO,MAAM,QAAQ;CACzD;CAEA,MAAM,yBAAS,IAAI,IAAoB;CACvC,IAAI,SAAS,SAAS;CACtB,OAAO,SAAS,OAAO,MAAM;EAC3B,OAAO,IAAI,MAAM,IAAI,KAAK,EAAG;EAC7B,SAAS,KAAK,IAAI,QAAQ,KAAK,KAAM,MAAM,MAAM;CACnD,CAAC;CACD,KAAK,MAAM,SAAS,UAAU;EAC5B,MAAM,MAAM,SAAS;EACrB,OAAO,IAAI,MAAM,IAAI,GAAG;EACxB,SAAS,MAAM,MAAM;CACvB;CACA,OAAO;EAAE,MAAM;EAAQ,QAAQ,KAAK,IAAI,QAAQ,MAAM;CAAE;AAC1D;;;;;AAiBA,SAAgB,YAAY,QAKX;CACf,MAAM,QAAsB,CAAC;CAC7B,IAAI,OAAO,OAAO,MAAM,KAAK;EAAE,IAAI;EAAY,KAAK,OAAO,MAAM;EAAM,QAAQ;EAAM,QAAQ;CAAM,CAAC;CACpG,KAAK,MAAM,UAAU,OAAO,MAAM;EAChC,MAAM,QAAQ,OAAO,OAAO,IAAI,OAAO,EAAE;EACzC,MAAM,KAAK;GAAE,IAAI,OAAO;GAAI,KAAK,QAAQ,MAAM,OAAO,OAAO,SAAS,IAAI,OAAO,EAAE,KAAK;GAAM;GAAQ,QAAQ,CAAC;EAAM,CAAC;CACxH;CAEA,OAAO,MAAM,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,QAAQ,OAAO,IAAI,EAAE,QAAQ,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG;AAC5G"}

package/dist/features/comments/model.d.ts

@@ -22,6 +22,12 @@ export interface CommentsSnapshot {
   threads: readonly CommentThread[];
   /** Current text range per thread id (threads without one are orphans). */
   ranges: ReadonlyMap<string, DocRange>;
+  /**
+   * Where the text of an orphaned open thread was: the document position of the deletion point, resolved from the
+   * thread's stored anchor (so it is the same place for every collaborator and follows edits). Absent for orphans
+   * without a usable anchor (threads from before anchors, or whose block is gone for good).
+   */
+  orphanAt: ReadonlyMap<string, number>;
   active: string | null;
   /** Current range of the draft a new comment is being written for. */
   draft: DocRange | null;
@@ -69,6 +75,8 @@ export interface CommentsModel extends CommentsActions {
  * active thread and draft, and the mutations. Mutations are no-ops without collaboration or user; editing and
  * deleting are limited to the user's own comments and replies (a client-side rule: the Y.Doc itself has no ACL).
  * `getEditor` names the editor to work on (it may change over time and may return a destroyed or no editor).
+ * Each thread also keeps `anchor` (a Yjs relative position of its text's start, see `CommentAnchor`): `orphanAt` resolves
+ * it for the threads whose text is gone. Threads from before anchors get theirs written once they are seen with a range.
  */
 export declare function createCommentsModel(getEditor: () => Editor | undefined): CommentsModel;
 /** Creates the comments model of one editor, as a host supplies it to `commentsFeatureCore`. */

package/dist/features/comments/model.js

@@ -1,25 +1,13 @@
 import { newBlockId } from "../../core/schema/block-ids.js";
 import { createStore } from "../../core/store.js";
-import { releaseRanges, resolveRange } from "../../core/doc-anchors.js";
+import { anchorResolverOf, releaseRanges, resolveRange } from "../../core/doc-anchors.js";
 import { editorEntryOf } from "../../core/editor-ui.js";
-import { cancelCommentDraft, commentsDoc, commentsKey, commentsUser, setActiveComment, startCommentDraft } from "./comments-plugin.js";
 import { COMMENTS_FIELD, COMMENT_LIMITS } from "./schema.js";
+import { cancelCommentDraft, commentsDoc, commentsKey, commentsUser, setActiveComment, startCommentDraft } from "./comments-plugin.js";
+import { EMPTY_SNAPSHOT, NO_POSITIONS, NO_RANGES, NO_THREADS, sameOrphanAt, sameRange, sameRanges, sameUser } from "./snapshot-equality.js";
+import { captureThreadAnchor, resolveThreadAnchor } from "./thread-anchor.js";
 import * as Y from "yjs";
 //#region src/features/comments/model.ts
-const NO_RANGES = /* @__PURE__ */ new Map();
-const NO_THREADS = [];
-const EMPTY = {
-	available: false,
-	canComment: false,
-	user: null,
-	threads: NO_THREADS,
-	ranges: NO_RANGES,
-	active: null,
-	draft: null,
-	draftQuote: "",
-	open: NO_THREADS,
-	resolved: NO_THREADS
-};
 /** A thread's `Y.Map` as plain data; `replies` converted explicitly so it is always a plain array. */
 function snapshotOf(thread) {
 	const replies = thread.get("replies");
@@ -28,18 +16,6 @@ function snapshotOf(thread) {
 		replies: replies instanceof Y.Array ? replies.toArray() : []
 	};
 }
-function sameRange(a, b) {
-	return a === b || !!a && !!b && a.from === b.from && a.to === b.to;
-}
-function sameRanges(a, b) {
-	if (a === b) return true;
-	if (a.size !== b.size) return false;
-	for (const [id, range] of a) if (!sameRange(range, b.get(id) ?? null)) return false;
-	return true;
-}
-function sameUser(a, b) {
-	return a === b || !!a && !!b && a.id === b.id && a.name === b.name && a.color === b.color;
-}
 /**
 * The comment threads of a collaborative editor, stored in its Y.Doc (`COMMENTS_FIELD`, one nested `Y.Map` per thread,
 * replies in a nested `Y.Array`), so they sync live with the document and persist with its Yjs state. Keeps the
@@ -47,9 +23,11 @@ function sameUser(a, b) {
 * active thread and draft, and the mutations. Mutations are no-ops without collaboration or user; editing and
 * deleting are limited to the user's own comments and replies (a client-side rule: the Y.Doc itself has no ACL).
 * `getEditor` names the editor to work on (it may change over time and may return a destroyed or no editor).
+* Each thread also keeps `anchor` (a Yjs relative position of its text's start, see `CommentAnchor`): `orphanAt` resolves
+* it for the threads whose text is gone. Threads from before anchors get theirs written once they are seen with a range.
 */
 function createCommentsModel(getEditor) {
-	const store = createStore(EMPTY);
+	const store = createStore(EMPTY_SNAPSHOT);
 	const current = () => {
 		const instance = getEditor();
 		return instance && !instance.isDestroyed ? instance : void 0;
@@ -59,6 +37,8 @@ function createCommentsModel(getEditor) {
 	let threads = NO_THREADS;
 	let syncQueued = false;
 	let told = NO_THREADS;
+	const anchorTried = /* @__PURE__ */ new Set();
+	let healQueued = false;
 	function unobserve() {
 		observed?.map.unobserveDeep(onThreadsChanged);
 		observed = void 0;
@@ -81,7 +61,7 @@ function createCommentsModel(getEditor) {
 	function recompute() {
 		const instance = current();
 		if (!instance) {
-			store.set(EMPTY);
+			store.set(EMPTY_SNAPSHOT);
 			return;
 		}
 		const previous = store.get();
@@ -89,6 +69,7 @@ function createCommentsModel(getEditor) {
 		const user = commentsUser(instance);
 		const plugin = commentsKey.getState(instance.state);
 		const ranges = plugin?.ranges ?? NO_RANGES;
+		const orphanAt = orphanPositions(instance, ranges);
 		const active = plugin?.active ?? null;
 		const anchor = plugin?.draft;
 		const draft = anchor ? resolveRange(instance.state, anchor) : null;
@@ -97,7 +78,8 @@ function createCommentsModel(getEditor) {
 		const canComment = available && instance.isEditable;
 		const sameThreads = threads === previous.threads;
 		const sameRangeMap = sameRanges(ranges, previous.ranges);
-		if (available === previous.available && canComment === previous.canComment && sameUser(user, previous.user) && sameThreads && sameRangeMap && active === previous.active && sameRange(draft, previous.draft) && draftQuote === previous.draftQuote) return;
+		const sameOrphanMap = sameOrphanAt(orphanAt, previous.orphanAt);
+		if (available === previous.available && canComment === previous.canComment && sameUser(user, previous.user) && sameThreads && sameRangeMap && sameOrphanMap && active === previous.active && sameRange(draft, previous.draft) && draftQuote === previous.draftQuote) return;
 		const open = sameThreads && sameRangeMap ? previous.open : threads.filter((t) => !t.resolved).sort((a, b) => (ranges.get(a.id)?.from ?? Infinity) - (ranges.get(b.id)?.from ?? Infinity) || a.createdAt.localeCompare(b.createdAt));
 		const resolved = sameThreads ? previous.resolved : threads.filter((t) => t.resolved).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 		store.set({
@@ -106,12 +88,51 @@ function createCommentsModel(getEditor) {
 			user,
 			threads,
 			ranges: sameRangeMap ? previous.ranges : ranges,
+			orphanAt: sameOrphanMap ? previous.orphanAt : orphanAt,
 			active,
 			draft: sameRange(draft, previous.draft) ? previous.draft : draft,
 			draftQuote,
 			open,
 			resolved
 		});
+		if (available) queueHeal();
+	}
+	/** Where each unresolved thread without a text range was, from its anchor; empty without a Yjs session. */
+	function orphanPositions(instance, ranges) {
+		const resolver = anchorResolverOf(instance);
+		if (!resolver) return NO_POSITIONS;
+		const size = instance.state.doc.content.size;
+		let found;
+		for (const thread of threads) {
+			if (thread.resolved || ranges.has(thread.id) || !thread.anchor) continue;
+			const position = resolveThreadAnchor(instance.state, resolver, thread.anchor);
+			if (position !== null && position <= size) (found ??= /* @__PURE__ */ new Map()).set(thread.id, position);
+		}
+		return found ?? NO_POSITIONS;
+	}
+	function queueHeal() {
+		if (healQueued || !threads.some((t) => !t.anchor && !anchorTried.has(t.id))) return;
+		healQueued = true;
+		queueMicrotask(() => {
+			healQueued = false;
+			healAnchors();
+		});
+	}
+	function healAnchors() {
+		const ctx = writable();
+		const resolver = ctx && anchorResolverOf(ctx.editor);
+		if (!ctx || !resolver || ctx.editor !== bound) return;
+		const { ranges } = store.get();
+		const written = [];
+		for (const { id, anchor } of threads) {
+			const range = ranges.get(id);
+			if (anchor || anchorTried.has(id) || !range) continue;
+			anchorTried.add(id);
+			const thread = threadMap(ctx.map, id);
+			const captured = thread && captureThreadAnchor(ctx.editor.state, resolver, range);
+			if (thread && captured) written.push([thread, captured]);
+		}
+		if (written.length) ctx.ydoc.transact(() => written.forEach(([thread, captured]) => thread.set("anchor", captured)));
 	}
 	function queueSync() {
 		if (syncQueued) return;
@@ -146,6 +167,7 @@ function createCommentsModel(getEditor) {
 			bound = instance;
 			threads = NO_THREADS;
 			told = NO_THREADS;
+			anchorTried.clear();
 			instance?.on("transaction", onTransaction);
 			instance?.on("update", onTransaction);
 			queueSync();
@@ -171,7 +193,8 @@ function createCommentsModel(getEditor) {
 		unobserve();
 		threads = NO_THREADS;
 		told = NO_THREADS;
-		store.set(EMPTY);
+		anchorTried.clear();
+		store.set(EMPTY_SNAPSHOT);
 	}
 	/** Editor, thread map and user while comments are available; null otherwise. */
 	function writable() {
@@ -209,6 +232,8 @@ function createCommentsModel(getEditor) {
 		if (!ctx || !anchor || !range || range.from >= range.to || !body || !type) return null;
 		const id = newBlockId();
 		const { state } = ctx.editor;
+		const resolver = anchorResolverOf(ctx.editor);
+		const threadAnchor = resolver ? captureThreadAnchor(state, resolver, range) : null;
 		const quote = state.doc.textBetween(range.from, range.to, " ").slice(0, COMMENT_LIMITS.quote);
 		const tr = state.tr.addMark(range.from, range.to, type.create({ id }));
 		if (!tr.docChanged) return null;
@@ -225,6 +250,7 @@ function createCommentsModel(getEditor) {
 		thread.set("createdAt", (/* @__PURE__ */ new Date()).toISOString());
 		thread.set("quote", quote);
 		thread.set("resolved", false);
+		if (threadAnchor) thread.set("anchor", threadAnchor);
 		thread.set("replies", new Y.Array());
 		ctx.map.set(id, thread);
 		return id;
@@ -343,7 +369,7 @@ function commentsModelOf(ctx) {
 * consumer of this function, so a host model that must share state across them keeps it outside the factory.
 */
 function createEditorCommentsModel(getEditor) {
-	const store = createStore(EMPTY);
+	const store = createStore(EMPTY_SNAPSHOT);
 	let inner;
 	function release() {
 		inner?.stop();
@@ -371,7 +397,7 @@ function createEditorCommentsModel(getEditor) {
 		refresh: () => current().refresh(),
 		dispose: () => {
 			release();
-			store.set(EMPTY);
+			store.set(EMPTY_SNAPSHOT);
 		},
 		add: (text) => current().add(text),
 		reply: (threadId, text) => current().reply(threadId, text),