@ecsplico/editor 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 2.1.0
+
+### Added
+
+- The storage and connection layer of the former `@ecsplico/editor-adapters`, as 11 subpath entries (guide: `docs/integration.md` §14): `@ecsplico/editor/adapters` (types only), `/adapters/json`, `/adapters/drizzle`, `/adapters/forge`, `/adapters/vue` (`useEditorDocument`), `/anchors`, `/comments/server`, `/comments/json`, `/comments/drizzle`, `/comments/client` and `/server/nitro` (`installEditorServer`, the Nuxt-free Nitro host). Exported names are unchanged.
+- Optional peer dependency `drizzle-orm` (`^0.45.0`), needed only by `/adapters/drizzle` and `/comments/drizzle`.
+- Bundle-isolation fixtures `adapters-node`, `adapters-drizzle`, `adapters-nitro`, `adapters-vue` and `headless-comments-client`: Vue is reachable only from `/adapters/vue`, Nitro only from `/server/nitro`, drizzle only from the two drizzle entries, React from none.
+- Example `examples/vue-nitro-json` (`bun run proto:vue-nitro-json`): a Vue editor on a bare Nitro server with JSON-file storage.
+
+### Notes
+
+- `@ecsplico/editor-adapters` is deprecated and will receive no further releases. `@ecsplico/editor-adapters/vue` is now `@ecsplico/editor/adapters/vue`; every other subpath keeps its name under `@ecsplico/editor` (for example `@ecsplico/editor-adapters/adapters/json` → `@ecsplico/editor/adapters/json`, `@ecsplico/editor-adapters/server/nitro` → `@ecsplico/editor/server/nitro`, `@ecsplico/editor-adapters/anchors` → `@ecsplico/editor/anchors`). The root entry of the old package (types) is `@ecsplico/editor/adapters`.
+- `./adapters/react`, `./server/nest` and `./adapters/prisma` are reserved names and not exported.
+
+### Fixed
+
+- `createEditor()` without arguments threw a `TypeError` (destructuring `undefined`); `app.use(createEditor())` now installs with the default `nuxtUiKit()` as documented.
+
+## 2.0.0
+
+### Removed (breaking)
+
+- The PrimeVue kit: `@ecsplico/editor/vue/kit/primevue` (`primeVueKit()`) and the stylesheet `@ecsplico/editor/vue/kit/primevue.css`. The Vue binding renders through Nuxt UI only; hosts that used `primeVueKit()` move to `nuxtUiKit()` (`@ecsplico/editor/vue/kit/nuxt-ui`) and import `@ecsplico/editor/vue/kit/nuxt-ui.css`.
+- The Nuxt module option `kit` (`tiptapEditor: { kit: 'nuxt-ui' | 'primevue' }`). The module always adds `vue/kit/nuxt-ui.css`, patches Nuxt UI's `ui.css` so Tailwind scans the package and registers the Nuxt UI context plugin; `@nuxt/ui` must be registered before it.
+- The peer dependency `primevue` (and its optional peer metadata).
+- The `advanced-primevue` bundle-isolation fixture and the `examples/vue-primevue` example.
+
+### Changed
+
+- `createEditor({ kit })`: `kit` is optional and defaults to `nuxtUiKit()`. `app.use(createEditor())` is enough; pass a `VueUiKit` only to render the chrome with another library.
+- React: `react/styles/ui-vars.css` sets `--sk-success` from `--color-success` (the `@skaile/brand` token), falling back to the former `oklch(0.72 0.19 150)`.
+
+## 1.0.0
+
+First release on npmjs as `@ecsplico/editor` (Vue: Nuxt UI or PrimeVue kit; React: shadcn/ui; optional React and Vue peers).

package/README.md

@@ -123,10 +123,10 @@ Every entry is an explicit subpath of `package.json#exports`; there is no wildca
 | `@ecsplico/editor/transcript`, `/transcript/vue`, `/transcript/react`, `/transcript/schema` | `/vue` and `/react`: `transcriptFeature`, `TranscriptSegmentView`; framework-free: `transcriptFeatureCore`, `transcriptSegment`, `speakerConversions`, `segmentSpeakerLines`, `transcriptSchemaExtensions()`, `speakerParagraphsToSegments`, `lastSpeaker`, `speakersIn` |
 | `@ecsplico/editor/authors`, `/authors/vue`, `/authors/react`, `/authors/schema` | `/vue` and `/react`: `authorsFeature`, `AuthorColorsPanel`, `AuthorColorsButton`, `SettingsAuthorsTab`; framework-free: `authorsFeatureCore`, `currentAuthor`, `AuthorAttribution`, `authorsSchemaExtensions()`, `AuthorMark`, `documentAuthors`, `AuthorIdentity`, `AUTHOR_COLOR_STYLES`, `AuthorColorStyle` |
 | `@ecsplico/editor/themes`, `/themes/vue`, `/themes/react`, `/themes/schema` | `/vue` and `/react`: `themesFeature()` (site-wide Obsidian themes: its `setup` hook starts the theme runtime and returns its teardown, its `appearance` settings tab picks the theme), `SettingsAppearanceTab`; framework-free: `themesFeatureCore`, `startObsidianTheme(ctx)` (reference-counted per app, returns the release), `scopeThemeCss`, `THEME_SCOPE_CLASS`; Vue-free schema: `ThemeRecord`, `ThemeManifest`, `themeManifestSchema`, `THEME_ID`, `MAX_THEME_BYTES`. Needs an adapter with `listThemes`/`loadTheme`; see the [usage guide](./docs/usage.md#themes-obsidian) |
-| `@ecsplico/editor/comments`, `/comments/vue`, `/comments/react`, `/comments/schema` | `/vue` and `/react`: `commentsFeature` (requires `collab`), `useComments`, `CommentsMargin`, `CommentsPopover`, `CommentsListMenu`, `CommentThreadView`, `CommentComposer`, `CommentBubble`, `SettingsCommentsTab` (`/vue` also the type `CommentsStore`); framework-free: `commentsFeatureCore`, `createCommentsModel`, `Comments` plugin helpers, `commentsSchemaExtensions()`, `CommentMark`, `CommentThread`, `CommentReply`, `COMMENT_LIMITS`, `COMMENTS_LAYOUTS`, `CommentsLayout` |
+| `@ecsplico/editor/comments`, `/comments/vue`, `/comments/react`, `/comments/schema` | `/vue` and `/react`: `commentsFeature` (requires `collab`), `useComments`, `CommentsMargin`, `CommentsPopover`, `CommentsListMenu`, `CommentThreadView`, `CommentComposer`, `CommentBubble`, `SettingsCommentsTab` (`/vue` also the type `CommentsStore`); framework-free: `commentsFeatureCore`, `createCommentsModel`, `Comments` plugin helpers, `commentsSchemaExtensions()`, `CommentMark`, `CommentThread`, `CommentReply`, `COMMENT_LIMITS`, `COMMENTS_LAYOUTS`, `CommentsLayout`, and the margin's layout (the active thread pinned to its text's line, the others one-line cards out of its way): `layoutMargin(entries, activeId, { gap, minTop })` (with `MarginEntry`, `MarginLayout`, `MARGIN_GAP`), `marginCards` (with `MarginCard`, `DRAFT_CARD`; an orphaned thread sits at its deletion point, `CommentsSnapshot.orphanAt`, which host models may omit), `createMarginController` (with `MarginController`, `MarginSource`, `MarginState`: measuring and scheduling for both `CommentsMargin`s) |
 | `@ecsplico/editor/composites/vue`, `/composites/react` | `compositeFeature()` (Vue: Nuxt UI, React: shadcn), the host-placed `CompositeTable` and `CompositeInspector`, `SettingsEditingTab`, `CompositeChrome`, `CompositeDetails`, `CompositeView` and editors, `useCompositeRows`, `useCompositeAnchors` |
-| `@ecsplico/editor/composites`, `/composites/schema` | Framework-free: `compositeFeatureCore`, `Composite`, `defaultCompositeKinds`, `compositeKind`, `compositeOutline`, `moveBlockInto`, `canMoveBlockInto`, `headingsMarkdown`, `documentCompositeMarkdown`, `Structure`, `createCompositeRows`, `observeCompositeAnchors`, `compositeRows`, `setCompositeMetaField`, `setCompositeTags`, `setCompositeDescription`, `compositeDescriptionText`, `compositeSchemaExtensions()`, `compositeJSON`, `blocksFromMarkdown`, `splitCompositeFences`, `migrateLegacyContent`, conversions and heading↔composite transforms |
-| `@ecsplico/editor/ai`, `/ai/protocol` | Framework-free: `aiFeatureCore`, `modelProfiles(app)`, `createAiAssistant`, `createDocumentChat`, `createAgentOpReview({ notify, t })` (host-driven agent edit review), `notifyAiRateLimited(notify, t)`, review/apply helpers (`startAiReview`, `applyAiResult`, …) and the protocol (`AI_TASKS`, `ModelRef`, `AGENT_OP_TYPES`, `CHAT_LIMITS`, …), importable alone from `/ai/protocol`; the model-facing agent texts (`checkAgentOps`, `agentShownMessage`, `agentFeedbackText`, `agentRetryMessage`) take a `locale: 'de' \| 'en'` option (default `de`), and `agentRetryMessage(problems, scoped, { locale, tool })` names the `tool` the model must call again (default `edit_document`) |
+| `@ecsplico/editor/composites`, `/composites/schema` | Framework-free: `compositeFeatureCore`, `Composite`, `defaultCompositeKinds`, `compositeKind`, `kindAccepts` (the kinds' accepted children, `CompositeKind.accepts`), `AcceptedChildren` (the editor extension that enforces them; registered by `compositeFeatureCore`), `compositeOutline`, `moveBlockInto` (returns whether the document changed), `moveIntoVerdict(editor, id, targetId, t)` (with `MoveVerdict`: `{ ok: true }` or `{ ok: false, reason }` in the language of `t`), `canMoveBlockInto` (`moveIntoVerdict(...).ok`), `headingsMarkdown`, `documentCompositeMarkdown`, `Structure`, `createCompositeRows`, `createCompositeInspector`, `compositeFieldText`, `observeCompositeAnchors`, `compositeRows`, `setCompositeMetaField`, `setCompositeTags`, `setCompositeDescription`, `compositeDescriptionText`, `compositeSchemaExtensions()`, `compositeJSON`, `blocksFromMarkdown`, `splitCompositeFences`, `migrateLegacyContent`, conversions and heading↔composite transforms |
+| `@ecsplico/editor/ai`, `/ai/protocol` | Framework-free: `aiFeatureCore`, `modelProfiles(app)`, `createAiAssistant`, `createDocumentChat`, `createAiSelectionFlow` (with `AI_SELECTION_MENU_KEY`), `createAgentOpReview({ notify, t })` (host-driven agent edit review), `notifyAiRateLimited(notify, t)`, review/apply helpers (`startAiReview`, `applyAiResult`, …) and the protocol (`AI_TASKS`, `ModelRef`, `AGENT_OP_TYPES`, `AGENT_OP_OUTCOMES`, `CHAT_LIMITS`, …), importable alone from `/ai/protocol`; the model-facing agent texts (`checkAgentOps`, `agentShownMessage`, `agentFeedbackText`, `agentRetryMessage`) take a `locale: 'de' \| 'en'` option (default `de`), and `agentRetryMessage(problems, scoped, { locale, tool })` names the `tool` the model must call again (default `edit_document`). The `[id]` line format of the chat's document text has one owner there, `block-lines`: writer helpers (`blockLine`, `singleBlockLine`, `nestedLinePrefix`, `quoteLinePrefix`, `listLinePrefix`, `continuedLinePrefix`, `compositeChromePart`, `compositeLineHeader`, `compositeLineClose`, `TRUNCATED_LINE`), the reader `readBlockLines` (the block ids and which blocks lie inside which; lines in fenced code are not block lines; type `BlockLines`), the echo strippers `stripBlockLineEcho` and `stripListMarkerEcho`, and the (German, model-facing) prompt texts `BLOCK_LINES_LABEL`, `BLOCK_LINE_INTRO`, `BLOCK_LINE_MARKERS`, `BLOCK_LINE_LIST_TEXT`, `BLOCK_LINE_HOST_TEXT`, `BLOCK_LINE_COMPOSITE_TEXT`, `BLOCK_LINE_ECHO_TEXT`, `BLOCK_LINE_IDS_HINT` with the example (`BLOCK_LINE_EXAMPLE`, `BLOCK_LINE_EXAMPLE_ID`, `BLOCK_LINE_EXAMPLE_TEXT`) |
 | `@ecsplico/editor/ai/vue`, `/ai/react` | `aiFeature()`, `AiSidebar`, `ModelQuickSwitch`, `AiReviewBar`, `AiSelectionMenu`, `SettingsAiTab`, `SettingsModelProfiles`; `/ai/vue` also `useAiAssistant`, `useDocumentChat`, `useModelProfiles` (thin hooks over the models) |
 | `@ecsplico/editor/integrations/composite-ai` | Framework-free: `compositeAiFeature` (requires `composites`, `ai`, `media`), `fillComposite`, `summarizeComposite`, `transcribeDocument`, `compositeSourceText`, `mediaAssetOf` |
 | `@ecsplico/editor/integrations/composite-media` | Framework-free: `compositeMediaFeature` (requires `composites`, `media`): imported files become `document` composites |
@@ -137,7 +137,7 @@ Every entry is an explicit subpath of `package.json#exports`; there is no wildca
 | `@ecsplico/editor/server`, `/server/handlers`, `/server/node`, `/nuxt` | Server side without a web framework: `createCollabServer`, `createAiModels`, `createRateLimiter`, `EditorAdapter`, one request handler per route (`/server/handlers`), `listenCollab` for a plain Node script (`/server/node`); the Nitro registry `setEditorAdapter`, `forgetCollabDocument`, `liveContent`, `collabStats`; the Nuxt module (config key `tiptapEditor`) wraps the same core. See the [integration guide](./docs/integration.md) |
 | `@ecsplico/editor/styles/core.css` (required), `/composites.css`, `/media.css`, `/mentions.css`, `/tables.css`, `/authors.css`, `/comments.css`, `/transcript.css`, `/ai.css`, `/collab.css`, `/block-ui.css`, `/themes.css` | Feature CSS (import after Tailwind, Nuxt UI (Vue) or `ui-vars.css` (React) and `core.css`; `themes.css` after the feature sheets). The Nuxt module adds all of them itself |
 
-Nuxt apps use the same entries; the Nuxt client plugin (`src/nuxt/runtime/plugins/editor-context-<kit>.client.ts`, one file per `kit` option so an app never bundles the UI library it does not use) installs the editor context with account-synced settings.
+Nuxt apps use the same entries; the Nuxt client plugin (`src/nuxt/runtime/plugins/editor-context-nuxt-ui.client.ts`) installs the editor context with account-synced settings.
 
 ## Presets and features
 
@@ -167,9 +167,9 @@ Settings are stored as one inert, versioned JSON object shared by all editors of
 
 ## CSS and UI-provider requirements
 
-- Design tokens: `@ecsplico/editor/styles/tokens.css` declares the shared `--sk-*` variables (`--sk-bg`, `--sk-fg`, `--sk-muted`, `--sk-border`, `--sk-primary`, `--sk-primary-fg`, `--sk-success`, `--sk-warning`, `--sk-danger`, `--sk-radius`, `--sk-font`) with light defaults under `:where(:root)` and dark values under `:where(.dark)`. Every feature stylesheet reads them; a UI kit maps them onto its own variables (Nuxt UI: `vue/kit/nuxt-ui.css`, PrimeVue: `vue/kit/primevue.css`, React/shadcn: `react/styles/ui-vars.css`), a host may override them once.
+- Design tokens: `@ecsplico/editor/styles/tokens.css` declares the shared `--sk-*` variables (`--sk-bg`, `--sk-fg`, `--sk-muted`, `--sk-border`, `--sk-primary`, `--sk-primary-fg`, `--sk-success`, `--sk-warning`, `--sk-danger`, `--sk-radius`, `--sk-font`) with light defaults under `:where(:root)` and dark values under `:where(.dark)`. Every feature stylesheet reads them; a UI kit maps them onto its own variables (Nuxt UI: `vue/kit/nuxt-ui.css`, React/shadcn: `react/styles/ui-vars.css`), a host may override them once.
 
-- Vue UI kit: the Vue chrome renders through the kit handed to `createEditor({ kit })`. `nuxtUiKit()` (`@ecsplico/editor/vue/kit/nuxt-ui`, needs `@nuxt/ui`, stylesheet `@ecsplico/editor/vue/kit/nuxt-ui.css`) is the demo default; `primeVueKit()` (`@ecsplico/editor/vue/kit/primevue`, needs `primevue` + `@iconify/vue`, stylesheet `@ecsplico/editor/vue/kit/primevue.css`) works with the host's `app.use(PrimeVue)`, `ToastService` and a mounted `<Toast />`. `@ecsplico/editor/vue/kit` holds the `VueUiKit` contract and `useUiKit()`. Only those two entries import their UI library. The Nuxt module option `kit: 'nuxt-ui' | 'primevue'` (default `'nuxt-ui'`) selects the kit and the stylesheet; the `ui.css` patch runs only for `'nuxt-ui'`. `examples/vue-primevue` mounts the editor with PrimeVue.
+- Vue UI kit: the Vue binding is built on Nuxt UI. The chrome renders through the kit handed to `createEditor({ kit })`; `kit` is optional and defaults to `nuxtUiKit()` (`@ecsplico/editor/vue/kit/nuxt-ui`, needs `@nuxt/ui`, stylesheet `@ecsplico/editor/vue/kit/nuxt-ui.css`). `@ecsplico/editor/vue/kit` holds the `VueUiKit` contract and `useUiKit()`; pass your own `VueUiKit` only to render the chrome with another library. Only the `nuxt-ui` kit entry imports `@nuxt/ui`. The Nuxt module has no `kit` option: it always adds `vue/kit/nuxt-ui.css`, patches Nuxt UI's `ui.css` so Tailwind scans the package (`@nuxt/ui` must be registered before the module) and installs the Nuxt UI context plugin.
 
 - Import the core CSS **after** Tailwind and Nuxt UI, and let Tailwind see the library's classes:
 
@@ -208,12 +208,12 @@ bun run --cwd examples/react-simple dev     # http://localhost:3041
 bun run --cwd examples/react-simple typecheck
 bun run --cwd examples/react-advanced dev   # http://localhost:3043, needs `bun run dev` (Nuxt host, port 3031)
 bun run --cwd examples/react-advanced typecheck
-bun run --cwd examples/vue-primevue dev     # http://localhost:3044, the Vue surface on primeVueKit() (no Nuxt UI)
 bun run --cwd examples/vue-markdown dev     # http://localhost:3045, MarkdownSurface with frontmatter, tables and source mode
 bun run typecheck:editor                      # vue-tsc --noEmit -p packages/editor/tsconfig.json (no Nuxt globals)
 bun run check:editor-entries                  # production build per fixture, module-graph isolation rules
 bun run check:editor-markdown-clipboard       # MarkdownClipboard paste/copy cases (HTML, Markdown, plain text, data-URL opt-in) in happy-dom
 bun run check:editor-composition              # defineEditor rejects missing `requires`; accepted compositions; one formatAiResult contributor
+bun run test:editor                           # bun test over packages/editor/test: framework-free models on a mounted editor (happy-dom)
 ```
 
 On a clean checkout run the example build once before `typecheck:editor`.

package/dist/adapters/anchors.d.ts

@@ -0,0 +1,80 @@
+import { Node } from "@tiptap/pm/model";
+//#region src/adapters/anchors.d.ts
+/** A half-open range of ProseMirror positions; `from === to` is a cursor position. */
+export interface DocRange {
+  from: number;
+  to: number;
+}
+/** Selected text. */
+export interface RangeAnchor {
+  kind: 'range';
+  from: number;
+  to: number;
+  quote: string;
+  contextBefore?: string;
+  contextAfter?: string;
+}
+/** A zero-width cursor position. */
+export interface PointAnchor {
+  kind: 'point';
+  position: number;
+  contextBefore?: string;
+  contextAfter?: string;
+}
+/** What remains of an anchor whose target was deleted or cannot be found: the last good anchor plus its quote and context. */
+export interface OrphanedAnchor {
+  kind: 'orphan';
+  previous: RangeAnchor | PointAnchor;
+  quote?: string;
+  contextBefore?: string;
+  contextAfter?: string;
+  reason: 'target-changed' | 'target-deleted' | 'unresolvable';
+}
+/** The stored form of an anchor; the layout of skaile-forge's `concept-discussions.json`. */
+export type PortableAnchor = RangeAnchor | PointAnchor | OrphanedAnchor;
+/** Characters of quote a range anchor keeps. */
+export declare const QUOTE_LENGTH = 200;
+/** Characters of surrounding text kept on each side. */
+export declare const CONTEXT_LENGTH = 80;
+/** What `captureAnchor` and `capturePoint` read: a tiptap `Editor`, or anything with `state.doc`. */
+export interface AnchorSource {
+  state: {
+    doc: Node;
+  };
+}
+/** What `mapAnchor` reads of a ProseMirror transaction. */
+export interface AnchorTransaction {
+  /** The document after the transaction. */
+  doc: Node;
+  mapping: {
+    mapResult(pos: number, assoc?: number): {
+      pos: number;
+      deleted: boolean;
+    };
+  };
+}
+/** The anchor of the text in `range` (clamped to the document); its `quote` is the trimmed text, cut to `QUOTE_LENGTH`. */
+export declare function captureAnchor(source: AnchorSource, range: DocRange): RangeAnchor;
+/** The anchor of the cursor position `position` (clamped to the document). */
+export declare function capturePoint(source: AnchorSource, position: number): PointAnchor;
+/**
+ * The range `anchor` points at in `doc`, or `null` when it cannot be found (an orphan). Orphaned anchors resolve to
+ * `null` too: a deleted target is never silently re-attached to other text. A point resolves to `{ from, to }` with
+ * `from === to`.
+ *
+ * 1. The stored positions, if they lie in the document and the text there still reads as the quote (a point: the
+ *    text around still reads as its context).
+ * 2. A search for the quote (a point: for its context); among repeats the one whose surroundings agree most with the
+ *    stored context wins, ties go to the one nearest the stored position.
+ */
+export declare function resolveAnchor(doc: Node, anchor: PortableAnchor): DocRange | null;
+/**
+ * `anchor` carried through a transaction: positions follow the edit, quote and context are read again from the new
+ * document (so an edit inside the range changes the quote). The same object when nothing changed. A range collapsed by
+ * the edit, or a point inside deleted text, becomes an `orphan` that keeps the last good anchor; orphans stay as they are.
+ */
+export declare function mapAnchor(anchor: PortableAnchor, transaction: AnchorTransaction): PortableAnchor;
+/** Whether `value` has the shape of a stored anchor (range, point or orphan); for input from the network. */
+export declare function isPortableAnchor(value: unknown): value is PortableAnchor;
+//#endregion
+//# sourceMappingURL=anchors.d.ts.map

package/dist/adapters/anchors.js

@@ -0,0 +1,270 @@
+//#region src/adapters/anchors.ts
+/** Characters of quote a range anchor keeps. */
+const QUOTE_LENGTH = 200;
+/** Characters of surrounding text kept on each side. */
+const CONTEXT_LENGTH = 80;
+/** Characters of context compared to accept an exact position and to search a moved one. */
+const MATCH_LENGTH = 24;
+const projections = /* @__PURE__ */ new WeakMap();
+const isSpace = (char) => /\s/.test(char);
+function projectionOf(doc) {
+	const cached = projections.get(doc);
+	if (cached) return cached;
+	const chars = [];
+	const starts = [];
+	const ends = [];
+	const push = (char, start, end) => {
+		if (isSpace(char)) {
+			if (chars.length === 0 || chars[chars.length - 1] === " ") return;
+			char = " ";
+		}
+		chars.push(char);
+		starts.push(start);
+		ends.push(end);
+	};
+	doc.descendants((node, pos) => {
+		if (node.isText) {
+			const text = node.text ?? "";
+			for (let i = 0; i < text.length; i++) push(text[i], pos + i, pos + i + 1);
+			return;
+		}
+		if (node.isTextblock || node.isBlock && node.isLeaf) push(" ", pos, pos);
+		if (node.isLeaf) {
+			const leaf = node.type.spec.leafText?.(node) ?? "";
+			for (let i = 0; i < leaf.length; i++) push(leaf[i], pos, pos + node.nodeSize);
+		}
+	});
+	const projection = {
+		text: chars.join(""),
+		starts,
+		ends
+	};
+	projections.set(doc, projection);
+	return projection;
+}
+/** First index in the non-decreasing `values` whose value satisfies `ok` (monotone: false… then true…). */
+function firstIndex(values, ok) {
+	let low = 0;
+	let high = values.length;
+	while (low < high) {
+		const middle = low + high >> 1;
+		if (ok(values[middle])) high = middle;
+		else low = middle + 1;
+	}
+	return low;
+}
+/** The characters of `projection` inside `[from, to]`: `[first, last)` indexes. */
+function span(projection, from, to) {
+	const first = firstIndex(projection.starts, (start) => start >= from);
+	const last = firstIndex(projection.ends, (end) => end > to);
+	return [first, Math.max(first, last)];
+}
+/** `value` with whitespace collapsed, as the projection holds text. */
+const normalize = (value) => value.replace(/\s+/g, " ");
+const clampPosition = (doc, position) => Math.max(0, Math.min(doc.content.size, Math.floor(position)));
+/** The anchor of the text in `range` (clamped to the document); its `quote` is the trimmed text, cut to `QUOTE_LENGTH`. */
+function captureAnchor(source, range) {
+	const { doc } = source.state;
+	const from = clampPosition(doc, Math.min(range.from, range.to));
+	const to = clampPosition(doc, Math.max(range.from, range.to));
+	const projection = projectionOf(doc);
+	const [first, last] = span(projection, from, to);
+	return {
+		kind: "range",
+		from,
+		to,
+		quote: projection.text.slice(first, last).trim().slice(0, 200),
+		contextBefore: projection.text.slice(Math.max(0, first - 80), first),
+		contextAfter: projection.text.slice(last, last + 80)
+	};
+}
+/** The anchor of the cursor position `position` (clamped to the document). */
+function capturePoint(source, position) {
+	const { doc } = source.state;
+	const at = clampPosition(doc, position);
+	const projection = projectionOf(doc);
+	const [first, last] = span(projection, at, at);
+	return {
+		kind: "point",
+		position: at,
+		contextBefore: projection.text.slice(Math.max(0, last - 80), last),
+		contextAfter: projection.text.slice(first, first + 80)
+	};
+}
+const commonSuffix = (text, end, context) => {
+	let count = 0;
+	while (count < context.length && count < end && text[end - 1 - count] === context[context.length - 1 - count]) count++;
+	return count;
+};
+const commonPrefix = (text, start, context) => {
+	let count = 0;
+	while (count < context.length && start + count < text.length && text[start + count] === context[count]) count++;
+	return count;
+};
+/** Every index where `needle` occurs in `text` (overlaps included). */
+function occurrences(text, needle) {
+	const found = [];
+	if (!needle) return found;
+	for (let index = text.indexOf(needle); index >= 0; index = text.indexOf(needle, index + 1)) found.push(index);
+	return found;
+}
+const matchTail = (context) => context.slice(-24);
+const matchHead = (context) => context.slice(0, MATCH_LENGTH);
+/**
+* The range `anchor` points at in `doc`, or `null` when it cannot be found (an orphan). Orphaned anchors resolve to
+* `null` too: a deleted target is never silently re-attached to other text. A point resolves to `{ from, to }` with
+* `from === to`.
+*
+* 1. The stored positions, if they lie in the document and the text there still reads as the quote (a point: the
+*    text around still reads as its context).
+* 2. A search for the quote (a point: for its context); among repeats the one whose surroundings agree most with the
+*    stored context wins, ties go to the one nearest the stored position.
+*/
+function resolveAnchor(doc, anchor) {
+	if (anchor.kind === "orphan") return null;
+	const projection = projectionOf(doc);
+	const size = doc.content.size;
+	const contextBefore = normalize(anchor.contextBefore ?? "");
+	const contextAfter = normalize(anchor.contextAfter ?? "");
+	if (anchor.kind === "point") {
+		const stored = Number.isInteger(anchor.position) && anchor.position >= 0 && anchor.position <= size ? anchor.position : null;
+		if (stored !== null) {
+			const [first, last] = span(projection, stored, stored);
+			const beforeOk = !contextBefore || projection.text.slice(0, last).endsWith(matchTail(contextBefore));
+			const afterOk = !contextAfter || projection.text.startsWith(matchHead(contextAfter), first);
+			if (beforeOk && afterOk) return {
+				from: stored,
+				to: stored
+			};
+		}
+		const [firstIndex, ...otherIndexes] = pointCandidates(projection, contextBefore, contextAfter);
+		if (firstIndex === void 0) return null;
+		const near = anchor.position;
+		const entryOf = (index) => ({
+			index,
+			position: boundaryPosition(projection, index),
+			score: commonSuffix(projection.text, index, contextBefore) + commonPrefix(projection.text, index, contextAfter)
+		});
+		const best = pickBest(entryOf(firstIndex), otherIndexes.map(entryOf), (entry) => Math.abs(entry.position - near));
+		return {
+			from: best.position,
+			to: best.position
+		};
+	}
+	const quote = normalize(anchor.quote).trim();
+	if (Number.isInteger(anchor.from) && Number.isInteger(anchor.to) && anchor.from >= 0 && anchor.from <= anchor.to && anchor.to <= size) {
+		if (!quote) return {
+			from: anchor.from,
+			to: anchor.to
+		};
+		const [first, last] = span(projection, anchor.from, anchor.to);
+		if (projection.text.slice(first, last).trim().slice(0, 200) === quote) return {
+			from: anchor.from,
+			to: anchor.to
+		};
+	}
+	if (!quote) return null;
+	const [firstMatch, ...otherMatches] = occurrences(projection.text, quote);
+	if (firstMatch === void 0) return null;
+	const truncated = quote.length >= 200;
+	const entryOf = (index) => {
+		const from = projection.starts[index];
+		return {
+			index,
+			from,
+			to: truncated ? Math.min(size, from + Math.max(0, anchor.to - anchor.from)) : projection.ends[index + quote.length - 1],
+			score: commonSuffix(projection.text, index, contextBefore) + commonPrefix(projection.text, index + quote.length, contextAfter)
+		};
+	};
+	const best = pickBest(entryOf(firstMatch), otherMatches.map(entryOf), (entry) => Math.abs(entry.from - anchor.from));
+	return {
+		from: best.from,
+		to: best.to
+	};
+}
+/** The boundaries (between characters) where the context of a point reads: both sides, else either side alone. */
+function pointCandidates(projection, contextBefore, contextAfter) {
+	const before = matchTail(contextBefore);
+	const after = matchHead(contextAfter);
+	if (before && after) {
+		const both = occurrences(projection.text, before + after).map((index) => index + before.length);
+		if (both.length) return both;
+	}
+	if (before) {
+		const found = occurrences(projection.text, before).map((index) => index + before.length);
+		if (found.length) return found;
+	}
+	if (after) return occurrences(projection.text, after);
+	return [];
+}
+/** The cursor position of the boundary before character `index`. */
+function boundaryPosition(projection, index) {
+	const { text, starts, ends } = projection;
+	if (index >= text.length) return ends[text.length - 1] ?? 0;
+	if (text[index] === " " && starts[index] === ends[index] && index > 0) return ends[index - 1];
+	return starts[index];
+}
+/** The entry with the highest `score` among `first` and `rest`; among equals the one with the lowest `distance`. */
+function pickBest(first, rest, distance) {
+	let best = first;
+	for (const entry of rest) if (entry.score > best.score || entry.score === best.score && distance(entry) < distance(best)) best = entry;
+	return best;
+}
+const sameAnchor = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+* `anchor` carried through a transaction: positions follow the edit, quote and context are read again from the new
+* document (so an edit inside the range changes the quote). The same object when nothing changed. A range collapsed by
+* the edit, or a point inside deleted text, becomes an `orphan` that keeps the last good anchor; orphans stay as they are.
+*/
+function mapAnchor(anchor, transaction) {
+	if (anchor.kind === "orphan") return anchor;
+	const source = { state: { doc: transaction.doc } };
+	let next;
+	if (anchor.kind === "range") {
+		const from = transaction.mapping.mapResult(anchor.from, 1).pos;
+		const to = transaction.mapping.mapResult(anchor.to, -1).pos;
+		if (from >= to) next = {
+			kind: "orphan",
+			previous: anchor,
+			quote: anchor.quote,
+			contextBefore: anchor.contextBefore,
+			contextAfter: anchor.contextAfter,
+			reason: from === to ? "target-deleted" : "target-changed"
+		};
+		else next = captureAnchor(source, {
+			from,
+			to
+		});
+	} else {
+		const after = transaction.mapping.mapResult(anchor.position, 1);
+		const before = transaction.mapping.mapResult(anchor.position, -1);
+		next = after.deleted && before.deleted ? {
+			kind: "orphan",
+			previous: anchor,
+			contextBefore: anchor.contextBefore,
+			contextAfter: anchor.contextAfter,
+			reason: "target-deleted"
+		} : capturePoint(source, after.pos);
+	}
+	return sameAnchor(anchor, next) ? anchor : next;
+}
+const isPosition = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const isOptionalText = (value) => value === void 0 || typeof value === "string";
+function isLiveAnchor(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const anchor = value;
+	if (!isOptionalText(anchor.contextBefore) || !isOptionalText(anchor.contextAfter)) return false;
+	if (anchor.kind === "range") return isPosition(anchor.from) && isPosition(anchor.to) && anchor.from <= anchor.to && typeof anchor.quote === "string";
+	return anchor.kind === "point" && isPosition(anchor.position);
+}
+/** Whether `value` has the shape of a stored anchor (range, point or orphan); for input from the network. */
+function isPortableAnchor(value) {
+	if (isLiveAnchor(value)) return true;
+	if (typeof value !== "object" || value === null) return false;
+	const anchor = value;
+	return anchor.kind === "orphan" && isLiveAnchor(anchor.previous) && isOptionalText(anchor.quote) && isOptionalText(anchor.contextBefore) && isOptionalText(anchor.contextAfter) && (anchor.reason === "target-changed" || anchor.reason === "target-deleted" || anchor.reason === "unresolvable");
+}
+//#endregion
+export { CONTEXT_LENGTH, QUOTE_LENGTH, captureAnchor, capturePoint, isPortableAnchor, mapAnchor, resolveAnchor };
+
+//# sourceMappingURL=anchors.js.map

package/dist/adapters/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","names":[],"sources":["../../src/adapters/anchors.ts"],"sourcesContent":["import type { Node as PMNode } from '@tiptap/pm/model'\n\n// Portable text anchors: a durable reference from a comment to a place in a document that survives edits, re-parses\n// and content swaps. Pure and framework-free: no runtime import, so the entry loads in a browser, a worker or Node.\n//\n// An anchor stores ProseMirror positions (fast path) plus the quoted text and its surroundings (fallback). Resolving\n// trusts the positions while the text there still reads as the quote, otherwise searches the document for the quote\n// and lets the context decide between repeats; no match at all is an orphan (`null`), never a guess.\n\n/** A half-open range of ProseMirror positions; `from === to` is a cursor position. */\nexport interface DocRange {\n  from: number\n  to: number\n}\n\n/** Selected text. */\nexport interface RangeAnchor {\n  kind: 'range'\n  from: number\n  to: number\n  quote: string\n  contextBefore?: string\n  contextAfter?: string\n}\n\n/** A zero-width cursor position. */\nexport interface PointAnchor {\n  kind: 'point'\n  position: number\n  contextBefore?: string\n  contextAfter?: string\n}\n\n/** What remains of an anchor whose target was deleted or cannot be found: the last good anchor plus its quote and context. */\nexport interface OrphanedAnchor {\n  kind: 'orphan'\n  previous: RangeAnchor | PointAnchor\n  quote?: string\n  contextBefore?: string\n  contextAfter?: string\n  reason: 'target-changed' | 'target-deleted' | 'unresolvable'\n}\n\n/** The stored form of an anchor; the layout of skaile-forge's `concept-discussions.json`. */\nexport type PortableAnchor = RangeAnchor | PointAnchor | OrphanedAnchor\n\n/** Characters of quote a range anchor keeps. */\nexport const QUOTE_LENGTH = 200\n/** Characters of surrounding text kept on each side. */\nexport const CONTEXT_LENGTH = 80\n/** Characters of context compared to accept an exact position and to search a moved one. */\nconst MATCH_LENGTH = 24\n\n/** What `captureAnchor` and `capturePoint` read: a tiptap `Editor`, or anything with `state.doc`. */\nexport interface AnchorSource {\n  state: { doc: PMNode }\n}\n\n/** What `mapAnchor` reads of a ProseMirror transaction. */\nexport interface AnchorTransaction {\n  /** The document after the transaction. */\n  doc: PMNode\n  mapping: { mapResult(pos: number, assoc?: number): { pos: number, deleted: boolean } }\n}\n\n// -- Text projection ------------------------------------------------------------------------------------------------\n\n/**\n * The document as one string with its positions: runs of whitespace collapse to one space, a text block boundary is a\n * space (`starts`/`ends` = the boundary position), a non-text leaf is its `leafText` or U+FFFC. `starts[i]`/`ends[i]`\n * are the document positions before and after character `i`; both are non-decreasing.\n */\ninterface Projection {\n  text: string\n  starts: number[]\n  ends: number[]\n}\n\nconst projections = new WeakMap<PMNode, Projection>()\nconst isSpace = (char: string) => /\\s/.test(char)\n\nfunction projectionOf(doc: PMNode): Projection {\n  const cached = projections.get(doc)\n  if (cached) return cached\n  const chars: string[] = []\n  const starts: number[] = []\n  const ends: number[] = []\n  const push = (char: string, start: number, end: number) => {\n    if (isSpace(char)) {\n      if (chars.length === 0 || chars[chars.length - 1] === ' ') return\n      char = ' '\n    }\n    chars.push(char)\n    starts.push(start)\n    ends.push(end)\n  }\n  doc.descendants((node, pos) => {\n    if (node.isText) {\n      const text = node.text ?? ''\n      for (let i = 0; i < text.length; i++) push(text[i]!, pos + i, pos + i + 1)\n      return\n    }\n    if (node.isTextblock || (node.isBlock && node.isLeaf)) push(' ', pos, pos)\n    if (node.isLeaf) {\n      const leaf = node.type.spec.leafText?.(node) ?? '\\ufffc'\n      for (let i = 0; i < leaf.length; i++) push(leaf[i]!, pos, pos + node.nodeSize)\n    }\n  })\n  const projection = { text: chars.join(''), starts, ends }\n  projections.set(doc, projection)\n  return projection\n}\n\n/** First index in the non-decreasing `values` whose value satisfies `ok` (monotone: false… then true…). */\nfunction firstIndex(values: readonly number[], ok: (value: number) => boolean): number {\n  let low = 0\n  let high = values.length\n  while (low < high) {\n    const middle = (low + high) >> 1\n    if (ok(values[middle]!)) high = middle\n    else low = middle + 1\n  }\n  return low\n}\n\n/** The characters of `projection` inside `[from, to]`: `[first, last)` indexes. */\nfunction span(projection: Projection, from: number, to: number): [number, number] {\n  const first = firstIndex(projection.starts, start => start >= from)\n  const last = firstIndex(projection.ends, end => end > to)\n  return [first, Math.max(first, last)]\n}\n\n/** `value` with whitespace collapsed, as the projection holds text. */\nconst normalize = (value: string) => value.replace(/\\s+/g, ' ')\n\nconst clampPosition = (doc: PMNode, position: number) => Math.max(0, Math.min(doc.content.size, Math.floor(position)))\n\n// -- Capture ----------------------------------------------------------------------------------------------------------\n\n/** The anchor of the text in `range` (clamped to the document); its `quote` is the trimmed text, cut to `QUOTE_LENGTH`. */\nexport function captureAnchor(source: AnchorSource, range: DocRange): RangeAnchor {\n  const { doc } = source.state\n  const from = clampPosition(doc, Math.min(range.from, range.to))\n  const to = clampPosition(doc, Math.max(range.from, range.to))\n  const projection = projectionOf(doc)\n  const [first, last] = span(projection, from, to)\n  return {\n    kind: 'range',\n    from,\n    to,\n    quote: projection.text.slice(first, last).trim().slice(0, QUOTE_LENGTH),\n    contextBefore: projection.text.slice(Math.max(0, first - CONTEXT_LENGTH), first),\n    contextAfter: projection.text.slice(last, last + CONTEXT_LENGTH),\n  }\n}\n\n/** The anchor of the cursor position `position` (clamped to the document). */\nexport function capturePoint(source: AnchorSource, position: number): PointAnchor {\n  const { doc } = source.state\n  const at = clampPosition(doc, position)\n  const projection = projectionOf(doc)\n  const [first, last] = span(projection, at, at)\n  return {\n    kind: 'point',\n    position: at,\n    contextBefore: projection.text.slice(Math.max(0, last - CONTEXT_LENGTH), last),\n    contextAfter: projection.text.slice(first, first + CONTEXT_LENGTH),\n  }\n}\n\n// -- Resolve ----------------------------------------------------------------------------------------------------------\n\nconst commonSuffix = (text: string, end: number, context: string): number => {\n  let count = 0\n  while (count < context.length && count < end && text[end - 1 - count] === context[context.length - 1 - count]) count++\n  return count\n}\n\nconst commonPrefix = (text: string, start: number, context: string): number => {\n  let count = 0\n  while (count < context.length && start + count < text.length && text[start + count] === context[count]) count++\n  return count\n}\n\n/** Every index where `needle` occurs in `text` (overlaps included). */\nfunction occurrences(text: string, needle: string): number[] {\n  const found: number[] = []\n  if (!needle) return found\n  for (let index = text.indexOf(needle); index >= 0; index = text.indexOf(needle, index + 1)) found.push(index)\n  return found\n}\n\nconst matchTail = (context: string) => context.slice(-MATCH_LENGTH)\nconst matchHead = (context: string) => context.slice(0, MATCH_LENGTH)\n\n/**\n * The range `anchor` points at in `doc`, or `null` when it cannot be found (an orphan). Orphaned anchors resolve to\n * `null` too: a deleted target is never silently re-attached to other text. A point resolves to `{ from, to }` with\n * `from === to`.\n *\n * 1. The stored positions, if they lie in the document and the text there still reads as the quote (a point: the\n *    text around still reads as its context).\n * 2. A search for the quote (a point: for its context); among repeats the one whose surroundings agree most with the\n *    stored context wins, ties go to the one nearest the stored position.\n */\nexport function resolveAnchor(doc: PMNode, anchor: PortableAnchor): DocRange | null {\n  if (anchor.kind === 'orphan') return null\n  const projection = projectionOf(doc)\n  const size = doc.content.size\n  const contextBefore = normalize(anchor.contextBefore ?? '')\n  const contextAfter = normalize(anchor.contextAfter ?? '')\n\n  if (anchor.kind === 'point') {\n    const stored = Number.isInteger(anchor.position) && anchor.position >= 0 && anchor.position <= size ? anchor.position : null\n    if (stored !== null) {\n      const [first, last] = span(projection, stored, stored)\n      const beforeOk = !contextBefore || projection.text.slice(0, last).endsWith(matchTail(contextBefore))\n      const afterOk = !contextAfter || projection.text.startsWith(matchHead(contextAfter), first)\n      if (beforeOk && afterOk) return { from: stored, to: stored }\n    }\n    const [firstIndex, ...otherIndexes] = pointCandidates(projection, contextBefore, contextAfter)\n    if (firstIndex === undefined) return null\n    const near = anchor.position\n    const entryOf = (index: number) => ({\n      index,\n      position: boundaryPosition(projection, index),\n      score: commonSuffix(projection.text, index, contextBefore) + commonPrefix(projection.text, index, contextAfter),\n    })\n    const best = pickBest(entryOf(firstIndex), otherIndexes.map(entryOf), entry => Math.abs(entry.position - near))\n    return { from: best.position, to: best.position }\n  }\n\n  const quote = normalize(anchor.quote).trim()\n  if (Number.isInteger(anchor.from) && Number.isInteger(anchor.to) && anchor.from >= 0 && anchor.from <= anchor.to && anchor.to <= size) {\n    if (!quote) return { from: anchor.from, to: anchor.to }\n    const [first, last] = span(projection, anchor.from, anchor.to)\n    if (projection.text.slice(first, last).trim().slice(0, QUOTE_LENGTH) === quote) return { from: anchor.from, to: anchor.to }\n  }\n  if (!quote) return null\n  const [firstMatch, ...otherMatches] = occurrences(projection.text, quote)\n  if (firstMatch === undefined) return null\n  // A quote cut at `QUOTE_LENGTH` says where the text starts, not where it ends: keep the stored length.\n  const truncated = quote.length >= QUOTE_LENGTH\n  const entryOf = (index: number) => {\n    const from = projection.starts[index]!\n    const to = truncated ? Math.min(size, from + Math.max(0, anchor.to - anchor.from)) : projection.ends[index + quote.length - 1]!\n    return {\n      index,\n      from,\n      to,\n      score: commonSuffix(projection.text, index, contextBefore) + commonPrefix(projection.text, index + quote.length, contextAfter),\n    }\n  }\n  const best = pickBest(entryOf(firstMatch), otherMatches.map(entryOf), entry => Math.abs(entry.from - anchor.from))\n  return { from: best.from, to: best.to }\n}\n\n/** The boundaries (between characters) where the context of a point reads: both sides, else either side alone. */\nfunction pointCandidates(projection: Projection, contextBefore: string, contextAfter: string): number[] {\n  const before = matchTail(contextBefore)\n  const after = matchHead(contextAfter)\n  if (before && after) {\n    const both = occurrences(projection.text, before + after).map(index => index + before.length)\n    if (both.length) return both\n  }\n  if (before) {\n    const found = occurrences(projection.text, before).map(index => index + before.length)\n    if (found.length) return found\n  }\n  if (after) return occurrences(projection.text, after)\n  return []\n}\n\n/** The cursor position of the boundary before character `index`. */\nfunction boundaryPosition(projection: Projection, index: number): number {\n  const { text, starts, ends } = projection\n  if (index >= text.length) return ends[text.length - 1] ?? 0\n  // Before a block boundary the cursor belongs at the end of the text before it, not in the gap between blocks.\n  if (text[index] === ' ' && starts[index] === ends[index] && index > 0) return ends[index - 1]!\n  return starts[index]!\n}\n\n/** The entry with the highest `score` among `first` and `rest`; among equals the one with the lowest `distance`. */\nfunction pickBest<T extends { score: number }>(first: T, rest: readonly T[], distance: (entry: T) => number): T {\n  let best = first\n  for (const entry of rest) {\n    if (entry.score > best.score || (entry.score === best.score && distance(entry) < distance(best))) best = entry\n  }\n  return best\n}\n\n// -- Map --------------------------------------------------------------------------------------------------------------\n\nconst sameAnchor = (a: PortableAnchor, b: PortableAnchor) => JSON.stringify(a) === JSON.stringify(b)\n\n/**\n * `anchor` carried through a transaction: positions follow the edit, quote and context are read again from the new\n * document (so an edit inside the range changes the quote). The same object when nothing changed. A range collapsed by\n * the edit, or a point inside deleted text, becomes an `orphan` that keeps the last good anchor; orphans stay as they are.\n */\nexport function mapAnchor(anchor: PortableAnchor, transaction: AnchorTransaction): PortableAnchor {\n  if (anchor.kind === 'orphan') return anchor\n  const source = { state: { doc: transaction.doc } }\n  let next: PortableAnchor\n  if (anchor.kind === 'range') {\n    const from = transaction.mapping.mapResult(anchor.from, 1).pos\n    const to = transaction.mapping.mapResult(anchor.to, -1).pos\n    if (from >= to) {\n      next = { kind: 'orphan', previous: anchor, quote: anchor.quote, contextBefore: anchor.contextBefore, contextAfter: anchor.contextAfter, reason: from === to ? 'target-deleted' : 'target-changed' }\n    }\n    else {\n      next = captureAnchor(source, { from, to })\n    }\n  }\n  else {\n    const after = transaction.mapping.mapResult(anchor.position, 1)\n    const before = transaction.mapping.mapResult(anchor.position, -1)\n    next = after.deleted && before.deleted\n      ? { kind: 'orphan', previous: anchor, contextBefore: anchor.contextBefore, contextAfter: anchor.contextAfter, reason: 'target-deleted' }\n      : capturePoint(source, after.pos)\n  }\n  return sameAnchor(anchor, next) ? anchor : next\n}\n\n// -- Validation -------------------------------------------------------------------------------------------------------\n\nconst isPosition = (value: unknown): value is number => typeof value === 'number' && Number.isInteger(value) && value >= 0\nconst isOptionalText = (value: unknown) => value === undefined || typeof value === 'string'\n\nfunction isLiveAnchor(value: unknown): value is RangeAnchor | PointAnchor {\n  if (typeof value !== 'object' || value === null) return false\n  const anchor = value as Record<string, unknown>\n  if (!isOptionalText(anchor.contextBefore) || !isOptionalText(anchor.contextAfter)) return false\n  if (anchor.kind === 'range') return isPosition(anchor.from) && isPosition(anchor.to) && anchor.from <= anchor.to && typeof anchor.quote === 'string'\n  return anchor.kind === 'point' && isPosition(anchor.position)\n}\n\n/** Whether `value` has the shape of a stored anchor (range, point or orphan); for input from the network. */\nexport function isPortableAnchor(value: unknown): value is PortableAnchor {\n  if (isLiveAnchor(value)) return true\n  if (typeof value !== 'object' || value === null) return false\n  const anchor = value as Record<string, unknown>\n  return anchor.kind === 'orphan'\n    && isLiveAnchor(anchor.previous)\n    && isOptionalText(anchor.quote) && isOptionalText(anchor.contextBefore) && isOptionalText(anchor.contextAfter)\n    && (anchor.reason === 'target-changed' || anchor.reason === 'target-deleted' || anchor.reason === 'unresolvable')\n}\n"],"mappings":"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"}

package/dist/adapters/comments/client.d.ts

@@ -0,0 +1,64 @@
+import { AuthorIdentity } from "../../core/feature.js";
+import "../../core/index.js";
+import { CommentsModel } from "../../features/comments/model.js";
+import "../../features/comments/index.js";
+import { Editor } from "@tiptap/core";
+//#region src/adapters/comments/client.d.ts
+/** The part of a `Response` the model reads; `globalThis.fetch` fits. */
+export interface CommentsFetchResponse {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}
+export type CommentsFetch = (url: string, init?: {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}) => Promise<CommentsFetchResponse>;
+export interface RestCommentsModelOptions {
+  /** How requests are sent: `globalThis.fetch`, or a wrapper that adds the base URL and credentials. */
+  fetch: CommentsFetch;
+  /** The document the threads belong to. */
+  documentId: string;
+  /** The document's comments endpoint (`GET` → `Discussion`, `POST` → `CommentAction`); default `/comments/<encoded documentId>`. */
+  endpoint?: string;
+  /** Who writes: the author of new comments and the only one who may edit or delete them; `null` while nobody is signed in (no comments then). */
+  user: AuthorIdentity | null | (() => AuthorIdentity | null);
+  /** Whether the user may compose and change comments now; readers of a read-only document may be allowed. */
+  canComment: boolean | (() => boolean);
+  /** The editor the threads belong to; may return no editor yet or a destroyed one. */
+  getEditor: () => Editor | undefined;
+  /** Milliseconds a changed anchor waits before it is written back (typing moves many); default 500. `idle()` writes at once. */
+  persistDelay?: number;
+  /** Called with every failed request; the model reloads the threads afterwards, so the local state falls back to the server's. */
+  onError?: (error: Error) => void;
+}
+export interface RestCommentsModel extends CommentsModel {
+  /** Fetches the threads again and resolves their anchors against the current document. */
+  reload(): Promise<void>;
+  /** Resolves once every change made so far has been sent (and the threads loaded, if a load was requested). */
+  idle(): Promise<void>;
+}
+/**
+ * The comments of one editor over a REST endpoint, as a `CommentsModel` (the host passes `() => model` as the
+ * `model` factory of `commentsFeature`/`commentsFeatureCore`; one instance serves the plugin and every hook).
+ *
+ * - **Load.** `refresh()` (called by the feature once the editor exists) fetches `GET endpoint`; each annotation's
+ *   anchor is resolved against the document (exact offsets, else quote and context search). An anchor that moved is
+ *   re-captured and written back; an anchor whose text is gone becomes an `orphan` (the thread stays, without a range)
+ *   and an orphan whose text is back with the same surroundings is re-attached. While the document is still empty the
+ *   resolving waits for its content.
+ * - **Edits.** Every transaction carries all anchors with it (`mapAnchor`), so ranges, quotes and contexts follow the
+ *   text; changed anchors are written back after `persistDelay`. Text deleted under an anchor orphans it for good (it is
+ *   never silently re-attached to other text during editing; `reload()` re-attaches it when its text and context
+ *   are found again, e.g. after the content was replaced).
+ * - **Writes** are applied locally at once and sent in order; a failed request is reported to `onError` and the threads
+ *   are reloaded. Without a `user` or while `canComment` is false nothing is written. Only the author may edit or
+ *   delete a comment.
+ * - **Lifecycle.** The model follows the editor `getEditor` names until that editor is destroyed; `dispose()` writes
+ *   pending anchor changes and does not stop it (the feature and its hooks share the instance and dispose it on their
+ *   own schedule).
+ */
+export declare function createRestCommentsModel(options: RestCommentsModelOptions): RestCommentsModel;
+//#endregion
+//# sourceMappingURL=client.d.ts.map