@ecsplico/editor 0.0.0-stage → 2.0.0

package/dist/schema/simple.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple.js","names":[],"sources":["../../src/schema/simple.ts"],"sourcesContent":["import type { AnyExtension } from '@tiptap/core'\nimport { coreSchemaExtensions } from '../core/schema'\nimport { tablesSchemaExtensions } from '../features/tables/schema'\n\n/**\n * The Vue-free schema of the simple editor: the core nodes (see `coreSchemaExtensions`) and the GFM table and task-list\n * nodes (`tablesSchemaExtensions`), so a server accepts documents of an editor with `tablesFeature()`. Servers and\n * validators build the schema from it with `getSchema(simpleSchemaExtensions())`.\n */\nexport const simpleSchemaExtensions = (): AnyExtension[] => [...coreSchemaExtensions(), ...tablesSchemaExtensions()]\n"],"mappings":";;;;;;;;AASA,MAAa,+BAA+C,CAAC,GAAG,qBAAqB,GAAG,GAAG,uBAAuB,CAAC"}

package/dist/server/adapter.d.ts

@@ -0,0 +1,101 @@
+import { EditorSettings } from "../settings/index.js";
+import { ModelProfile, ModelRef } from "../features/ai/protocol/models.js";
+import "../features/ai/protocol/index.js";
+import { AssetRecord } from "../features/media/assets.js";
+import "../features/media/schema.js";
+import { MentionUser } from "../features/mentions/mention.js";
+import "../features/mentions/schema.js";
+import { ThemeRecord } from "../features/themes/schema.js";
+import { AnyExtension, JSONContent } from "@tiptap/core";
+import { LanguageModel } from "ai";
+//#region src/server/adapter.d.ts
+/** What `EditorAdapter.authenticate` gets: the headers of the request (the websocket upgrade for collaboration) and the connection's `token`. */
+export interface AuthenticateRequest {
+  headers: Headers;
+  /** The collaboration client's token (`HocuspocusProvider` `token`, sent right after the socket opened); absent for plain HTTP requests and token-less clients. */
+  token?: string;
+}
+export interface EditorAdapter {
+  /**
+   * The user behind a request, `null` = not authenticated (HTTP routes answer 401). Collaboration: called in Hocuspocus
+   * `onAuthenticate` with the upgrade request's `headers` and the client's `token` (`undefined` when it sent none, so cookie
+   * hosts keep working and bearer-only hosts read `token`); `null` closes the connection with 4401. With the Nuxt module
+   * option `collab.authenticateUpgrade` it runs once at the upgrade with the `headers` only and `null` refuses the upgrade
+   * with HTTP 401. The value becomes the connection context's `user`.
+   */
+  authenticate(request: AuthenticateRequest): Promise<object | null>;
+  /**
+   * Per-document access for the collaboration websocket, called in Hocuspocus `onAuthenticate` (right after `authenticate`) with the user.
+   * `null` rejects the connection; `{ readOnly: true }` lets it sync but applies none of its edits. Omit it to let every
+   * authenticated user edit every document.
+   */
+  authorize?(user: object, id: string): Promise<{
+    readOnly: boolean;
+  } | null>;
+  /**
+   * Opaque version of the stored content of a document (mtime, hash, revision), `null` = unknown, no NUL. The collab server
+   * keeps it next to the Yjs state. When it differs from the live version (the content changed behind the editor's back) the
+   * state is discarded on load, removed through `removeState` and the document is re-seeded from `loadContent`. A document
+   * that is open when its version moves is not written back: the next store merges the new `loadContent` into the open
+   * Y.Doc. The version is read right after every `storeContent`, so it must reflect what the editor itself just wrote.
+   * Omit it to never discard state.
+   */
+  contentVersion?(id: string): Promise<string | null>;
+  /** TipTap extensions of host-defined nodes and marks, appended to `advancedSchemaExtensions()` in the server's collab schema so they survive JSON↔Yjs conversion. Vue-free node files only, no node views. */
+  schemaExtensions?(): AnyExtension[];
+  /** TipTap JSON to seed a document's Y.Doc from; `null` = the document does not exist. */
+  loadContent(id: string): Promise<JSONContent | null>;
+  /** Mirror of the current Yjs state, called debounced after edits and on shutdown. Must tolerate ids deleted meanwhile. */
+  storeContent(id: string, content: JSONContent): Promise<void>;
+  /** All users that can be `@`-mentioned (served by `GET /api/editor/users`); must not include credentials. */
+  listUsers(): Promise<MentionUser[]>;
+  /** Stored TipTap JSON of every document in the workspace, e.g. to collect the `#` tags in use (`GET /api/editor/tags`). */
+  listContents(): Promise<{
+    id: string;
+    content: JSONContent;
+  }[]>;
+  /** The bytes `storeState` stored (opaque to the host: the Yjs update behind a content-version prefix; state stored by earlier releases is a raw update and still loads); `null` = none yet (the Y.Doc is then seeded from `loadContent`). */
+  loadState(id: string): Promise<Uint8Array | null>;
+  /** Persists the state bytes unchanged; called on every store and when block IDs were backfilled. Must tolerate ids deleted meanwhile. */
+  storeState(id: string, state: Uint8Array): Promise<void>;
+  /** Drops the Yjs state of a deleted document (the next load re-seeds from `loadContent`). */
+  removeState(id: string): Promise<void>;
+  /** Stores an uploaded file (`GET /api/editor/assets/:id/:name` serves it). `id` is a document id or `SCRATCH_DOCUMENT_ID`; it may name no existing document. */
+  storeAsset(id: string, asset: AssetRecord & {
+    data: Buffer;
+  }): Promise<void>;
+  /** A stored file with its record; `null` = unknown id or name. */
+  loadAsset(id: string, name: string): Promise<{
+    record: AssetRecord;
+    data: Buffer;
+  } | null>;
+  /** Per-user editor settings as stored (`null` = none yet), validated by `GET /api/editor/settings`. Omit both settings methods to let the client keep settings in localStorage only. */
+  loadSettings?(user: object): Promise<unknown | null>;
+  /** Stores validated settings for the user from `authenticate`. */
+  storeSettings?(user: object, settings: EditorSettings): Promise<void>;
+  /** Theme library shared by all users (`GET /api/editor/themes`). Omit the theme methods to leave the themes feature uninstalled: its routes answer 501. */
+  listThemes?(): Promise<ThemeRecord[]>;
+  /** A theme's record and `theme.css` (`GET /api/editor/themes/:id`); `null` = unknown id. */
+  loadTheme?(id: string): Promise<{
+    record: ThemeRecord;
+    css: string;
+  } | null>;
+  /** Stores an uploaded theme (`POST /api/editor/themes`). */
+  storeTheme?(record: Omit<ThemeRecord, 'builtin'>, css: string): Promise<void>;
+  /** Deletes an uploaded theme (`DELETE /api/editor/themes/:id`); `false` = not found or builtin. */
+  removeTheme?(id: string): Promise<boolean>;
+  /**
+   * The language model for `ref`, so the AI endpoints use the host's own providers; consulted before the runtime-config
+   * presets for every model reference. `user` is what `authenticate` returned. `null` falls through to the presets
+   * (and answers 400 for a preset that is not configured either).
+   */
+  languageModel?(ref: ModelRef, user: object | null): Promise<LanguageModel | null>;
+  /**
+   * The models `GET /api/ai/models` lists for `user`, instead of the runtime-config presets (list them with
+   * `source: 'preset'` and the `id` that `languageModel` receives as `{ preset: id }`). `null` (or omitting the method)
+   * lists the presets.
+   */
+  listModels?(user: object | null): Promise<ModelProfile[] | null>;
+}
+//#endregion
+//# sourceMappingURL=adapter.d.ts.map

package/dist/server/ai.d.ts

@@ -0,0 +1,101 @@
+import { ModelSlot } from "../settings/values.js";
+import "../settings/index.js";
+import { ModelProfile, ModelRef } from "../features/ai/protocol/models.js";
+import "../features/ai/protocol/index.js";
+import { HttpError } from "./errors.js";
+import { LanguageModel, ModelMessage, ToolChoice, ToolSet } from "ai";
+//#region src/server/ai.d.ts
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+/** A streamed text delta, or a finished tool call (`invalid`: unparsable input or unknown tool). */
+export type ChatTurnPart = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  invalid: boolean;
+};
+/** Server-defined model preset (any OpenAI-compatible chat completions endpoint); its key falls back to the shared `apiKey`. */
+export interface PresetConfig {
+  label: string;
+  endpoint: string;
+  model: string;
+  apiKey?: string;
+}
+/** Speech-to-text endpoint: any OpenAI-compatible `<endpoint>/audio/transcriptions`. */
+export interface TranscriptionConfig {
+  endpoint: string;
+  model: string;
+  apiKey?: string;
+}
+/** Everything the AI endpoints need, passed explicitly: no runtime config, no globals. */
+export interface AiModelsConfig {
+  /** Server-defined model presets, keyed by preset id. */
+  presets: Record<string, PresetConfig>;
+  /** Shared key of presets without their own. */
+  apiKey?: string;
+  /** Default preset per model slot, answered by `GET /api/ai/models`. */
+  slots?: Record<ModelSlot, string>;
+  /** Speech-to-text for audio/video composites; absent = the transcription endpoint answers 501. */
+  transcription?: TranscriptionConfig;
+  /**
+   * The host's own language model for `ref` (`EditorAdapter.languageModel`), consulted before the presets for every
+   * model reference; `user` is what `authenticate` returned. `null` or nothing falls through to the presets.
+   */
+  languageModel?: (ref: ModelRef, user: object | null) => Promise<LanguageModel | null | undefined>;
+  /** The models listed for `user` instead of the presets (`EditorAdapter.listModels`); `null` or nothing lists the presets. */
+  listModels?: (user: object | null) => Promise<ModelProfile[] | null | undefined>;
+  /** Appended to the error of a preset without key, e.g. the environment variable names that set it. */
+  missingKeyHint?: (presetId: string) => string;
+}
+export interface AiModels {
+  /**
+   * AI SDK language model for `ref` (an OpenAI-compatible chat completions endpoint), for direct `ai` calls. The
+   * host's `languageModel(ref, user)` is asked first (`user`: what `authenticate` returned); a model it returns is
+   * used as is, `null` (or no such hook) falls through to the configured presets. A preset uses its own key or the
+   * shared `apiKey`; a user ref brings its own. Throws `HttpError` 400 for an unknown preset and 500 for a preset
+   * without key, so routes can call it before streaming starts.
+   */
+  resolveModel(ref: ModelRef, user: object | null): Promise<LanguageModel>;
+  /**
+   * The configured presets as the client may see them: without their keys. `user` is what the host's `authenticate`
+   * returned; the `listModels` hook supplies the list when it returns one (replacing the presets).
+   */
+  listModels(user: object | null): Promise<ModelProfile[]>;
+  readonly slots: Record<ModelSlot, string> | undefined;
+  readonly transcription: TranscriptionConfig | undefined;
+  streamChat: typeof streamChat;
+  streamChatTurn: typeof streamChatTurn;
+}
+/** The AI model utilities over an explicit configuration. */
+export declare function createAiModels(config: AiModelsConfig): AiModels;
+export declare function upstreamError(error: unknown): HttpError;
+/**
+ * Streams the text deltas of a chat completion (AI SDK `streamText`) on the resolved language model `model` (see
+ * `resolveModel`). System messages may appear in `messages`; a trailing assistant message is a prefill the model
+ * continues. Upstream failures throw a 502 `HttpError`; aborting `signal` cancels the upstream request and makes the
+ * generator throw.
+ */
+export declare function streamChat(opts: {
+  model: LanguageModel;
+  messages: ChatMessage[];
+  signal: AbortSignal;
+}): AsyncGenerator<string>;
+/**
+ * Like `streamChat`, with `tools` the model may call (tools without `execute`: the turn ends with the calls, which are
+ * yielded for the caller to handle) and structured `messages` (tool calls and results in the history).
+ */
+export declare function streamChatTurn(opts: {
+  model: LanguageModel;
+  messages: ModelMessage[];
+  signal: AbortSignal;
+  tools?: ToolSet;
+  toolChoice?: ToolChoice<ToolSet>;
+}): AsyncGenerator<ChatTurnPart>;
+//#endregion
+//# sourceMappingURL=ai.d.ts.map

package/dist/server/ai.js

@@ -0,0 +1,105 @@
+import { HttpError } from "./errors.js";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { APICallError, streamText } from "ai";
+//#region src/server/ai.ts
+/** The AI model utilities over an explicit configuration. */
+function createAiModels(config) {
+	return {
+		async resolveModel(ref, user) {
+			const hosted = await config.languageModel?.(ref, user);
+			if (hosted) return hosted;
+			if (!("preset" in ref)) return createOpenAICompatible({
+				name: "tiptap-editor",
+				baseURL: ref.endpoint,
+				apiKey: ref.apiKey
+			}).chatModel(ref.model);
+			const preset = config.presets[ref.preset];
+			if (!preset) throw new HttpError(400, "Unbekanntes Modell-Preset");
+			const apiKey = preset.apiKey || config.apiKey;
+			if (!apiKey) throw new HttpError(500, `API-Key für Preset „${ref.preset}“ fehlt${config.missingKeyHint?.(ref.preset) ?? ""}`);
+			return createOpenAICompatible({
+				name: "tiptap-editor",
+				baseURL: preset.endpoint,
+				apiKey
+			}).chatModel(preset.model);
+		},
+		async listModels(user) {
+			const listed = await config.listModels?.(user);
+			if (listed) return listed;
+			return Object.entries(config.presets).map(([id, { label, endpoint, model }]) => ({
+				id,
+				label,
+				endpoint,
+				model,
+				source: "preset"
+			}));
+		},
+		slots: config.slots,
+		transcription: config.transcription,
+		streamChat,
+		streamChatTurn
+	};
+}
+function upstreamError(error) {
+	let detail;
+	if (APICallError.isInstance(error)) detail = [error.statusCode, error.responseBody || error.message].filter(Boolean).join(" ");
+	else if (error instanceof Error) detail = error.message;
+	else detail = error?.message ?? JSON.stringify(error);
+	return new HttpError(502, `KI-Endpunkt: ${detail}`.slice(0, 500));
+}
+/**
+* Streams the text deltas of a chat completion (AI SDK `streamText`) on the resolved language model `model` (see
+* `resolveModel`). System messages may appear in `messages`; a trailing assistant message is a prefill the model
+* continues. Upstream failures throw a 502 `HttpError`; aborting `signal` cancels the upstream request and makes the
+* generator throw.
+*/
+async function* streamChat(opts) {
+	for await (const part of streamChatTurn(opts)) if (part.type === "text") yield part.text;
+}
+/**
+* Like `streamChat`, with `tools` the model may call (tools without `execute`: the turn ends with the calls, which are
+* yielded for the caller to handle) and structured `messages` (tool calls and results in the history).
+*/
+async function* streamChatTurn(opts) {
+	const { model } = opts;
+	const upstream = new AbortController();
+	const onAbort = () => upstream.abort(opts.signal.reason);
+	if (opts.signal.aborted) onAbort();
+	else opts.signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		const result = streamText({
+			model,
+			messages: opts.messages,
+			tools: opts.tools,
+			toolChoice: opts.toolChoice,
+			allowSystemInMessages: true,
+			abortSignal: upstream.signal,
+			maxRetries: 0,
+			onError: () => {}
+		});
+		for await (const part of result.stream) if (part.type === "text-delta") {
+			if (part.text) yield {
+				type: "text",
+				text: part.text
+			};
+		} else if (part.type === "tool-call") yield {
+			type: "tool-call",
+			toolCallId: part.toolCallId,
+			toolName: part.toolName,
+			input: part.input,
+			invalid: part.invalid === true
+		};
+		else if (part.type === "error") {
+			if (opts.signal.aborted) break;
+			throw upstreamError(part.error);
+		} else if (part.type === "abort") break;
+		opts.signal.throwIfAborted();
+	} finally {
+		opts.signal.removeEventListener("abort", onAbort);
+		upstream.abort();
+	}
+}
+//#endregion
+export { createAiModels, streamChat, streamChatTurn, upstreamError };
+
+//# sourceMappingURL=ai.js.map

package/dist/server/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","names":[],"sources":["../../src/server/ai.ts"],"sourcesContent":["import { createOpenAICompatible } from '@ai-sdk/openai-compatible'\nimport { APICallError, type LanguageModel, type ModelMessage, streamText, type ToolChoice, type ToolSet } from 'ai'\nimport type { ModelProfile, ModelRef } from '../features/ai/protocol'\nimport type { ModelSlot } from '../settings'\nimport { HttpError } from './errors'\n\nexport interface ChatMessage { role: 'system' | 'user' | 'assistant', content: string }\n\n/** A streamed text delta, or a finished tool call (`invalid`: unparsable input or unknown tool). */\nexport type ChatTurnPart =\n  | { type: 'text', text: string }\n  | { type: 'tool-call', toolCallId: string, toolName: string, input: unknown, invalid: boolean }\n\n/** Server-defined model preset (any OpenAI-compatible chat completions endpoint); its key falls back to the shared `apiKey`. */\nexport interface PresetConfig { label: string, endpoint: string, model: string, apiKey?: string }\n\n/** Speech-to-text endpoint: any OpenAI-compatible `<endpoint>/audio/transcriptions`. */\nexport interface TranscriptionConfig { endpoint: string, model: string, apiKey?: string }\n\n/** Everything the AI endpoints need, passed explicitly: no runtime config, no globals. */\nexport interface AiModelsConfig {\n  /** Server-defined model presets, keyed by preset id. */\n  presets: Record<string, PresetConfig>\n  /** Shared key of presets without their own. */\n  apiKey?: string\n  /** Default preset per model slot, answered by `GET /api/ai/models`. */\n  slots?: Record<ModelSlot, string>\n  /** Speech-to-text for audio/video composites; absent = the transcription endpoint answers 501. */\n  transcription?: TranscriptionConfig\n  /**\n   * The host's own language model for `ref` (`EditorAdapter.languageModel`), consulted before the presets for every\n   * model reference; `user` is what `authenticate` returned. `null` or nothing falls through to the presets.\n   */\n  languageModel?: (ref: ModelRef, user: object | null) => Promise<LanguageModel | null | undefined>\n  /** The models listed for `user` instead of the presets (`EditorAdapter.listModels`); `null` or nothing lists the presets. */\n  listModels?: (user: object | null) => Promise<ModelProfile[] | null | undefined>\n  /** Appended to the error of a preset without key, e.g. the environment variable names that set it. */\n  missingKeyHint?: (presetId: string) => string\n}\n\nexport interface AiModels {\n  /**\n   * AI SDK language model for `ref` (an OpenAI-compatible chat completions endpoint), for direct `ai` calls. The\n   * host's `languageModel(ref, user)` is asked first (`user`: what `authenticate` returned); a model it returns is\n   * used as is, `null` (or no such hook) falls through to the configured presets. A preset uses its own key or the\n   * shared `apiKey`; a user ref brings its own. Throws `HttpError` 400 for an unknown preset and 500 for a preset\n   * without key, so routes can call it before streaming starts.\n   */\n  resolveModel(ref: ModelRef, user: object | null): Promise<LanguageModel>\n  /**\n   * The configured presets as the client may see them: without their keys. `user` is what the host's `authenticate`\n   * returned; the `listModels` hook supplies the list when it returns one (replacing the presets).\n   */\n  listModels(user: object | null): Promise<ModelProfile[]>\n  readonly slots: Record<ModelSlot, string> | undefined\n  readonly transcription: TranscriptionConfig | undefined\n  streamChat: typeof streamChat\n  streamChatTurn: typeof streamChatTurn\n}\n\n/** The AI model utilities over an explicit configuration. */\nexport function createAiModels(config: AiModelsConfig): AiModels {\n  return {\n    async resolveModel(ref, user) {\n      const hosted = await config.languageModel?.(ref, user)\n      if (hosted) return hosted\n      if (!('preset' in ref)) return createOpenAICompatible({ name: 'tiptap-editor', baseURL: ref.endpoint, apiKey: ref.apiKey }).chatModel(ref.model)\n      const preset = config.presets[ref.preset]\n      if (!preset) throw new HttpError(400, 'Unbekanntes Modell-Preset')\n      const apiKey = preset.apiKey || config.apiKey\n      if (!apiKey) throw new HttpError(500, `API-Key für Preset „${ref.preset}“ fehlt${config.missingKeyHint?.(ref.preset) ?? ''}`)\n      return createOpenAICompatible({ name: 'tiptap-editor', baseURL: preset.endpoint, apiKey }).chatModel(preset.model)\n    },\n    async listModels(user) {\n      const listed = await config.listModels?.(user)\n      if (listed) return listed\n      return Object.entries(config.presets).map(([id, { label, endpoint, model }]) => ({ id, label, endpoint, model, source: 'preset' }))\n    },\n    slots: config.slots,\n    transcription: config.transcription,\n    streamChat,\n    streamChatTurn,\n  }\n}\n\nexport function upstreamError(error: unknown) {\n  let detail: string\n  if (APICallError.isInstance(error)) detail = [error.statusCode, error.responseBody || error.message].filter(Boolean).join(' ')\n  else if (error instanceof Error) detail = error.message\n  else detail = (error as { message?: string } | null)?.message ?? JSON.stringify(error)\n  return new HttpError(502, `KI-Endpunkt: ${detail}`.slice(0, 500))\n}\n\n/**\n * Streams the text deltas of a chat completion (AI SDK `streamText`) on the resolved language model `model` (see\n * `resolveModel`). System messages may appear in `messages`; a trailing assistant message is a prefill the model\n * continues. Upstream failures throw a 502 `HttpError`; aborting `signal` cancels the upstream request and makes the\n * generator throw.\n */\nexport async function* streamChat(opts: { model: LanguageModel, messages: ChatMessage[], signal: AbortSignal }): AsyncGenerator<string> {\n  for await (const part of streamChatTurn(opts)) {\n    if (part.type === 'text') yield part.text\n  }\n}\n\n/**\n * Like `streamChat`, with `tools` the model may call (tools without `execute`: the turn ends with the calls, which are\n * yielded for the caller to handle) and structured `messages` (tool calls and results in the history).\n */\nexport async function* streamChatTurn(opts: {\n  model: LanguageModel\n  messages: ModelMessage[]\n  signal: AbortSignal\n  tools?: ToolSet\n  toolChoice?: ToolChoice<ToolSet>\n}): AsyncGenerator<ChatTurnPart> {\n  const { model } = opts\n  // Also cancels the upstream request when the consumer stops iterating early (break / return).\n  const upstream = new AbortController()\n  const onAbort = () => upstream.abort(opts.signal.reason)\n  if (opts.signal.aborted) onAbort()\n  else opts.signal.addEventListener('abort', onAbort, { once: true })\n  try {\n    const result = streamText({\n      model,\n      messages: opts.messages,\n      tools: opts.tools,\n      toolChoice: opts.toolChoice,\n      allowSystemInMessages: true,\n      abortSignal: upstream.signal,\n      maxRetries: 0,\n      // Errors surface as `error` parts below and are rethrown; the default handler would only log them.\n      onError: () => {},\n    })\n    for await (const part of result.stream) {\n      if (part.type === 'text-delta') {\n        if (part.text) yield { type: 'text', text: part.text }\n      }\n      else if (part.type === 'tool-call') {\n        yield { type: 'tool-call', toolCallId: part.toolCallId, toolName: part.toolName, input: part.input, invalid: part.invalid === true }\n      }\n      else if (part.type === 'error') {\n        if (opts.signal.aborted) break\n        throw upstreamError(part.error)\n      }\n      else if (part.type === 'abort') {\n        break\n      }\n    }\n    opts.signal.throwIfAborted()\n  }\n  finally {\n    opts.signal.removeEventListener('abort', onAbort)\n    upstream.abort()\n  }\n}\n"],"mappings":";;;;;AA6DA,SAAgB,eAAe,QAAkC;CAC/D,OAAO;EACL,MAAM,aAAa,KAAK,MAAM;GAC5B,MAAM,SAAS,MAAM,OAAO,gBAAgB,KAAK,IAAI;GACrD,IAAI,QAAQ,OAAO;GACnB,IAAI,EAAE,YAAY,MAAM,OAAO,uBAAuB;IAAE,MAAM;IAAiB,SAAS,IAAI;IAAU,QAAQ,IAAI;GAAO,CAAC,CAAC,CAAC,UAAU,IAAI,KAAK;GAC/I,MAAM,SAAS,OAAO,QAAQ,IAAI;GAClC,IAAI,CAAC,QAAQ,MAAM,IAAI,UAAU,KAAK,2BAA2B;GACjE,MAAM,SAAS,OAAO,UAAU,OAAO;GACvC,IAAI,CAAC,QAAQ,MAAM,IAAI,UAAU,KAAK,uBAAuB,IAAI,OAAO,SAAS,OAAO,iBAAiB,IAAI,MAAM,KAAK,IAAI;GAC5H,OAAO,uBAAuB;IAAE,MAAM;IAAiB,SAAS,OAAO;IAAU;GAAO,CAAC,CAAC,CAAC,UAAU,OAAO,KAAK;EACnH;EACA,MAAM,WAAW,MAAM;GACrB,MAAM,SAAS,MAAM,OAAO,aAAa,IAAI;GAC7C,IAAI,QAAQ,OAAO;GACnB,OAAO,OAAO,QAAQ,OAAO,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,UAAU,cAAc;IAAE;IAAI;IAAO;IAAU;IAAO,QAAQ;GAAS,EAAE;EACpI;EACA,OAAO,OAAO;EACd,eAAe,OAAO;EACtB;EACA;CACF;AACF;AAEA,SAAgB,cAAc,OAAgB;CAC5C,IAAI;CACJ,IAAI,aAAa,WAAW,KAAK,GAAG,SAAS,CAAC,MAAM,YAAY,MAAM,gBAAgB,MAAM,OAAO,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,GAAG;MACxH,IAAI,iBAAiB,OAAO,SAAS,MAAM;MAC3C,SAAU,OAAuC,WAAW,KAAK,UAAU,KAAK;CACrF,OAAO,IAAI,UAAU,KAAK,gBAAgB,SAAS,MAAM,GAAG,GAAG,CAAC;AAClE;;;;;;;AAQA,gBAAuB,WAAW,MAAsG;CACtI,WAAW,MAAM,QAAQ,eAAe,IAAI,GAC1C,IAAI,KAAK,SAAS,QAAQ,MAAM,KAAK;AAEzC;;;;;AAMA,gBAAuB,eAAe,MAML;CAC/B,MAAM,EAAE,UAAU;CAElB,MAAM,WAAW,IAAI,gBAAgB;CACrC,MAAM,gBAAgB,SAAS,MAAM,KAAK,OAAO,MAAM;CACvD,IAAI,KAAK,OAAO,SAAS,QAAQ;MAC5B,KAAK,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAClE,IAAI;EACF,MAAM,SAAS,WAAW;GACxB;GACA,UAAU,KAAK;GACf,OAAO,KAAK;GACZ,YAAY,KAAK;GACjB,uBAAuB;GACvB,aAAa,SAAS;GACtB,YAAY;GAEZ,eAAe,CAAC;EAClB,CAAC;EACD,WAAW,MAAM,QAAQ,OAAO,QAC9B,IAAI,KAAK,SAAS,cACZ;OAAA,KAAK,MAAM,MAAM;IAAE,MAAM;IAAQ,MAAM,KAAK;GAAK;EAAA,OAElD,IAAI,KAAK,SAAS,aACrB,MAAM;GAAE,MAAM;GAAa,YAAY,KAAK;GAAY,UAAU,KAAK;GAAU,OAAO,KAAK;GAAO,SAAS,KAAK,YAAY;EAAK;OAEhI,IAAI,KAAK,SAAS,SAAS;GAC9B,IAAI,KAAK,OAAO,SAAS;GACzB,MAAM,cAAc,KAAK,KAAK;EAChC,OACK,IAAI,KAAK,SAAS,SACrB;EAGJ,KAAK,OAAO,eAAe;CAC7B,UACQ;EACN,KAAK,OAAO,oBAAoB,SAAS,OAAO;EAChD,SAAS,MAAM;CACjB;AACF"}

package/dist/server/collab-state.d.ts

@@ -0,0 +1,16 @@
+//#region src/server/collab-state.d.ts
+export interface CollabState {
+  /** `EditorAdapter.contentVersion` of the content the update was stored with; `null` = none known (also: legacy payload). */
+  version: string | null;
+  update: Uint8Array;
+}
+export declare function encodeCollabState({ version, update }: CollabState): Uint8Array;
+export declare function decodeCollabState(payload: Uint8Array): CollabState;
+/**
+ * Whether stored collaborative state is stale against the content behind it. Only hosts that implement
+ * `contentVersion` opt in (`live === undefined`: the adapter has no such method, state is never discarded). A legacy
+ * payload (`stored: null`) against a known live version counts as stale: it cannot prove it matches the content.
+ */
+export declare function isStateStale(stored: string | null, live: string | null | undefined): boolean;
+//#endregion
+//# sourceMappingURL=collab-state.d.ts.map

package/dist/server/collab-state.js

@@ -0,0 +1,43 @@
+//#region src/server/collab-state.ts
+const MARKER = [255, 118];
+const TERMINATOR = 0;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function encodeCollabState({ version, update }) {
+	const label = encoder.encode(version ?? "");
+	if (label.includes(TERMINATOR)) throw new Error("tiptap-editor: contentVersion darf kein NUL-Zeichen enthalten");
+	const out = new Uint8Array(MARKER.length + label.length + 1 + update.length);
+	out.set(MARKER, 0);
+	out.set(label, MARKER.length);
+	out[MARKER.length + label.length] = TERMINATOR;
+	out.set(update, MARKER.length + label.length + 1);
+	return out;
+}
+function decodeCollabState(payload) {
+	if (payload[0] !== MARKER[0] || payload[1] !== MARKER[1]) return {
+		version: null,
+		update: payload
+	};
+	const end = payload.indexOf(TERMINATOR, MARKER.length);
+	if (end === -1) return {
+		version: null,
+		update: payload
+	};
+	const label = decoder.decode(payload.subarray(MARKER.length, end));
+	return {
+		version: label === "" ? null : label,
+		update: payload.subarray(end + 1)
+	};
+}
+/**
+* Whether stored collaborative state is stale against the content behind it. Only hosts that implement
+* `contentVersion` opt in (`live === undefined`: the adapter has no such method, state is never discarded). A legacy
+* payload (`stored: null`) against a known live version counts as stale: it cannot prove it matches the content.
+*/
+function isStateStale(stored, live) {
+	return live !== void 0 && stored !== live;
+}
+//#endregion
+export { decodeCollabState, encodeCollabState, isStateStale };
+
+//# sourceMappingURL=collab-state.js.map

package/dist/server/collab-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collab-state.js","names":[],"sources":["../../src/server/collab-state.ts"],"sourcesContent":["// Stored Yjs state payload and the re-seed decision of the collab server. Pure: no Hocuspocus, no adapter, no Yjs.\n//\n// The adapter stores opaque bytes (`loadState`/`storeState` keep their signature); the server prefixes the Yjs update\n// with the content version it was written against:\n//\n//   [0xFF, 0x76]  marker (cannot start a legacy payload: a Yjs update opens with the varuint number of client groups,\n//                 and two continuation bytes would mean 16384 or more clients)\n//   utf8 version  empty = `null`\n//   0x00          terminator, so a version never contains NUL\n//   update bytes  `Y.encodeStateAsUpdate`\n//\n// Payloads without the marker are legacy raw updates and decode as `version: null`.\n\nconst MARKER = [0xFF, 0x76] as const\nconst TERMINATOR = 0\n\nconst encoder = new TextEncoder()\nconst decoder = new TextDecoder()\n\nexport interface CollabState {\n  /** `EditorAdapter.contentVersion` of the content the update was stored with; `null` = none known (also: legacy payload). */\n  version: string | null\n  update: Uint8Array\n}\n\nexport function encodeCollabState({ version, update }: CollabState): Uint8Array {\n  const label = encoder.encode(version ?? '')\n  if (label.includes(TERMINATOR)) throw new Error('tiptap-editor: contentVersion darf kein NUL-Zeichen enthalten')\n  const out = new Uint8Array(MARKER.length + label.length + 1 + update.length)\n  out.set(MARKER, 0)\n  out.set(label, MARKER.length)\n  out[MARKER.length + label.length] = TERMINATOR\n  out.set(update, MARKER.length + label.length + 1)\n  return out\n}\n\nexport function decodeCollabState(payload: Uint8Array): CollabState {\n  if (payload[0] !== MARKER[0] || payload[1] !== MARKER[1]) return { version: null, update: payload }\n  const end = payload.indexOf(TERMINATOR, MARKER.length)\n  // A marker without terminator is no payload this module wrote: treat it as an opaque legacy update.\n  if (end === -1) return { version: null, update: payload }\n  const label = decoder.decode(payload.subarray(MARKER.length, end))\n  return { version: label === '' ? null : label, update: payload.subarray(end + 1) }\n}\n\n/**\n * Whether stored collaborative state is stale against the content behind it. Only hosts that implement\n * `contentVersion` opt in (`live === undefined`: the adapter has no such method, state is never discarded). A legacy\n * payload (`stored: null`) against a known live version counts as stale: it cannot prove it matches the content.\n */\nexport function isStateStale(stored: string | null, live: string | null | undefined): boolean {\n  return live !== undefined && stored !== live\n}\n"],"mappings":";AAaA,MAAM,SAAS,CAAC,KAAM,GAAI;AAC1B,MAAM,aAAa;AAEnB,MAAM,UAAU,IAAI,YAAY;AAChC,MAAM,UAAU,IAAI,YAAY;AAQhC,SAAgB,kBAAkB,EAAE,SAAS,UAAmC;CAC9E,MAAM,QAAQ,QAAQ,OAAO,WAAW,EAAE;CAC1C,IAAI,MAAM,SAAS,UAAU,GAAG,MAAM,IAAI,MAAM,+DAA+D;CAC/G,MAAM,MAAM,IAAI,WAAW,OAAO,SAAS,MAAM,SAAS,IAAI,OAAO,MAAM;CAC3E,IAAI,IAAI,QAAQ,CAAC;CACjB,IAAI,IAAI,OAAO,OAAO,MAAM;CAC5B,IAAI,OAAO,SAAS,MAAM,UAAU;CACpC,IAAI,IAAI,QAAQ,OAAO,SAAS,MAAM,SAAS,CAAC;CAChD,OAAO;AACT;AAEA,SAAgB,kBAAkB,SAAkC;CAClE,IAAI,QAAQ,OAAO,OAAO,MAAM,QAAQ,OAAO,OAAO,IAAI,OAAO;EAAE,SAAS;EAAM,QAAQ;CAAQ;CAClG,MAAM,MAAM,QAAQ,QAAQ,YAAY,OAAO,MAAM;CAErD,IAAI,QAAQ,IAAI,OAAO;EAAE,SAAS;EAAM,QAAQ;CAAQ;CACxD,MAAM,QAAQ,QAAQ,OAAO,QAAQ,SAAS,OAAO,QAAQ,GAAG,CAAC;CACjE,OAAO;EAAE,SAAS,UAAU,KAAK,OAAO;EAAO,QAAQ,QAAQ,SAAS,MAAM,CAAC;CAAE;AACnF;;;;;;AAOA,SAAgB,aAAa,QAAuB,MAA0C;CAC5F,OAAO,SAAS,KAAA,KAAa,WAAW;AAC1C"}

package/dist/server/collab.d.ts

@@ -0,0 +1,68 @@
+import { EditorAdapter } from "./adapter.js";
+import { AnyExtension, JSONContent } from "@tiptap/core";
+import { Schema } from "@tiptap/pm/model";
+import { Configuration, Hocuspocus, WebSocketLike } from "@hocuspocus/server";
+//#region src/server/collab.d.ts
+/** Y.XmlFragment the TipTap Collaboration extension binds to (its default `field`). */
+export declare const COLLAB_FIELD = "default";
+export interface CollabServerOptions {
+  /** Storage and identity of the editor backend. */
+  adapter: EditorAdapter;
+  /** Extensions of host-defined nodes and marks appended to `advancedSchemaExtensions()`; defaults to `adapter.schemaExtensions`. */
+  schemaExtensions?: () => AnyExtension[];
+  /** Per-document access and content versioning; each defaults to the adapter's method of the same name. */
+  hooks?: {
+    authorize?: NonNullable<EditorAdapter['authorize']>;
+    contentVersion?: NonNullable<EditorAdapter['contentVersion']>;
+  };
+  /** Further Hocuspocus configuration (`debounce`, `timeout`, `quiet`, …); the editor's hooks win over equally named ones. */
+  configuration?: Partial<Configuration>;
+}
+/** One served websocket connection: feed it the socket's messages and its close event. */
+export interface CollabConnection {
+  handleMessage(data: Uint8Array): void;
+  handleClose(event?: CloseEvent): void;
+}
+export interface CollabServer {
+  /**
+   * The Hocuspocus instance of this server. The Yjs state (via the adapter's `loadState`/`storeState`) is the source of
+   * truth for content, the host's JSON content (via the adapter) is a mirror kept up to date on every store.
+   */
+  hocuspocus: Hocuspocus;
+  /** Schema of the collab server: `advancedSchemaExtensions()` plus the host's extensions, built on first use. */
+  schema(): Schema;
+  /**
+   * Serves one websocket connection (any transport: crossws, `ws`, Bun, Deno). The user is authenticated in Hocuspocus'
+   * `onAuthenticate` from the upgrade request's headers and the client's token, unless the transport already knows it
+   * and passes it as `context.user`. Wire `handleMessage` and `handleClose` of the returned connection to the socket's events.
+   */
+  handleConnection(socket: WebSocketLike, request: Request, context?: {
+    user?: object;
+  }): CollabConnection;
+  /** Tell connected clients the document is gone, disconnect them and drop the Yjs state. Call before removing the JSON. */
+  forgetDocument(id: string): Promise<void>;
+  /** Current content of a document that is open in Hocuspocus (unsaved edits included), `null` when nobody has it open. */
+  liveContent(id: string): JSONContent | null;
+  /**
+   * The host rewrote the content behind the editor's back (an agent wrote the file): merge it into the open document now,
+   * as a diff-update connected clients see as an ordinary edit. Without this the merge waits for the document's next store.
+   * No-op when nobody has the document open or the content version is unchanged; needs the adapter's `contentVersion`.
+   */
+  contentChanged(id: string): Promise<void>;
+  /** Open collaboration connections and loaded documents of this server. */
+  stats(): {
+    connections: number;
+    documents: number;
+  };
+  /** Disconnect every client, write pending stores and wait until all documents are unloaded. The server accepts no connection afterwards. */
+  close(): Promise<void>;
+}
+/**
+ * The editor's collaboration server, independent of any web framework: Hocuspocus with the editor's hooks (seeding from
+ * the adapter's JSON, versioned state, block-ID backfill, debounced `storeContent`/`storeState`) over `adapter`.
+ * `/nuxt` mounts one in Nitro; any Node/Bun/Deno process can serve `handleConnection` on its own websocket transport.
+ */
+export declare function createCollabServer(options: CollabServerOptions): CollabServer;
+//#endregion
+export type { WebSocketLike };
+//# sourceMappingURL=collab.d.ts.map