@ecsplico/editor 2.1.1 → 3.0.0

package/dist/adapters/shared.d.ts

@@ -1,37 +1,31 @@
-import { MentionUser } from "../features/mentions/mention.js";
+import { MentionUser } from "../core/backend-types.js";
 import "../features/mentions/schema.js";
-import { EditorAdapter } from "../server/adapter.js";
+import { AssetStore, CollabStateStore, Directory, DocumentAdmin, DocumentStore, EditorPorts, Identity, SettingsStore } from "../server/ports.js";
 import "../server/index.js";
-import { JSONContent } from "@tiptap/core";
 //#region src/adapters/shared.d.ts
 /**
- * The identity half of every adapter in this package: who the user is, which documents they may open, which host
- * nodes the collaboration schema needs and who can be `@`-mentioned. Storage is the adapter's own business.
+ * The identity half of every adapter in this package: who the user is, which documents they may open and who can be
+ * `@`-mentioned. Storage is the adapter's own business.
  */
 export interface AdapterHooks {
   /**
-   * The user behind a request, `null` = not authenticated (see `EditorAdapter.authenticate`). Default: an anonymous
+   * The user behind a request, `null` = not authenticated (see `Identity.authenticate`). Default: an anonymous
    * development user outside `NODE_ENV=production`, `null` (everyone refused) in production, so a deployment never
    * serves documents to the world by omission.
    */
-  authenticate?: EditorAdapter['authenticate'];
-  /** Per-document access for the collaboration websocket (see `EditorAdapter.authorize`). Omitted: every authenticated user edits every document. */
-  authorize?: EditorAdapter['authorize'];
-  /** Vue-free TipTap extensions of host-defined nodes and marks for the collaboration schema (see `EditorAdapter.schemaExtensions`). */
-  schemaExtensions?: EditorAdapter['schemaExtensions'];
+  authenticate?: Identity['authenticate'];
+  /** Per-document access for the collaboration websocket (see `Identity.authorize`). Omitted: every authenticated user edits every document. */
+  authorize?: Identity['authorize'];
   /** Users that can be `@`-mentioned (`GET /api/editor/users`); no credentials. Default: none. */
   users?: () => MentionUser[] | Promise<MentionUser[]>;
 }
-/** Document management a host needs next to the editor's own storage methods: the adapter contract cannot create documents (`storeContent` only updates). */
-export interface DocumentAdmin {
-  /** Creates the document or replaces its content; the content version changes. */
-  putDocument(id: string, content: JSONContent): Promise<void>;
-  /** Removes the content, the Yjs state and the assets of a document; unknown ids are fine. Call `forgetCollabDocument(id)` first when it may be open. */
-  deleteDocument(id: string): Promise<void>;
-  /** Ids of all stored documents. */
-  listDocumentIds(): Promise<string[]>;
+/** The ports of an adapter that stores documents itself (`json`, `drizzle`): the contract including versioning, settings and document management. */
+export interface StoredPorts extends EditorPorts {
+  documents: DocumentStore & DocumentAdmin & Required<Pick<DocumentStore, 'contentVersion'>>;
+  collabState: CollabStateStore;
+  directory: Directory;
+  assets: AssetStore;
+  settings: SettingsStore;
 }
-/** An adapter that stores documents itself (`json`, `drizzle`): the full contract including versioning, settings and document management. */
-export type StoredEditorAdapter = EditorAdapter & Required<Pick<EditorAdapter, 'contentVersion' | 'loadSettings' | 'storeSettings'>> & DocumentAdmin;
 //#endregion
 //# sourceMappingURL=shared.d.ts.map

package/dist/adapters/shared.js

@@ -5,16 +5,18 @@ const DEV_USER = {
 	color: "#6366f1"
 };
 const authenticateDefault = async () => process.env.NODE_ENV === "production" ? null : { ...DEV_USER };
-/** `hooks` as adapter members; optional hooks are only present when given (the collab server tests for them). */
-function identityPart(hooks) {
-	const { authenticate = authenticateDefault, authorize, schemaExtensions, users } = hooks;
+/** The `identity` port of `hooks`; `authorize` is only present when given (the collab server and the document routes test for it). */
+function identityOf(hooks) {
+	const { authenticate = authenticateDefault, authorize } = hooks;
 	return {
 		authenticate: (request) => authenticate(request),
-		listUsers: async () => await users?.() ?? [],
-		...authorize && { authorize: (user, id) => authorize(user, id) },
-		...schemaExtensions && { schemaExtensions: () => schemaExtensions() }
+		...authorize && { authorize: (user, id) => authorize(user, id) }
 	};
 }
+/** The `directory` port of the `users` hook. */
+function directoryOf({ users }) {
+	return { listUsers: async () => await users?.() ?? [] };
+}
 /** The key per-user settings are stored under: the user's `id`, else its `username`. */
 function settingsKey(user) {
 	const { id, username } = user;
@@ -24,9 +26,9 @@ function settingsKey(user) {
 	}
 	throw new TypeError("@ecsplico/editor: the authenticated user has neither an `id` nor a `username`, so its settings have no key");
 }
-/** An independent copy of the bytes (a driver's `Buffer` may view a larger pool), as the plain `Uint8Array` the adapter contract names. */
+/** An independent copy of the bytes (a driver's `Buffer` may view a larger pool), as the plain `Uint8Array` the port contract names. */
 const bytesOf = (data) => new Uint8Array(data);
 //#endregion
-export { bytesOf, identityPart, settingsKey };
+export { bytesOf, directoryOf, identityOf, settingsKey };
 
 //# sourceMappingURL=shared.js.map

package/dist/adapters/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","names":[],"sources":["../../src/adapters/shared.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\nimport type { MentionUser } from '../features/mentions/schema'\nimport type { EditorAdapter } from '../server'\n\n/**\n * The identity half of every adapter in this package: who the user is, which documents they may open, which host\n * nodes the collaboration schema needs and who can be `@`-mentioned. Storage is the adapter's own business.\n */\nexport interface AdapterHooks {\n  /**\n   * The user behind a request, `null` = not authenticated (see `EditorAdapter.authenticate`). Default: an anonymous\n   * development user outside `NODE_ENV=production`, `null` (everyone refused) in production, so a deployment never\n   * serves documents to the world by omission.\n   */\n  authenticate?: EditorAdapter['authenticate']\n  /** Per-document access for the collaboration websocket (see `EditorAdapter.authorize`). Omitted: every authenticated user edits every document. */\n  authorize?: EditorAdapter['authorize']\n  /** Vue-free TipTap extensions of host-defined nodes and marks for the collaboration schema (see `EditorAdapter.schemaExtensions`). */\n  schemaExtensions?: EditorAdapter['schemaExtensions']\n  /** Users that can be `@`-mentioned (`GET /api/editor/users`); no credentials. Default: none. */\n  users?: () => MentionUser[] | Promise<MentionUser[]>\n}\n\n/** Document management a host needs next to the editor's own storage methods: the adapter contract cannot create documents (`storeContent` only updates). */\nexport interface DocumentAdmin {\n  /** Creates the document or replaces its content; the content version changes. */\n  putDocument(id: string, content: JSONContent): Promise<void>\n  /** Removes the content, the Yjs state and the assets of a document; unknown ids are fine. Call `forgetCollabDocument(id)` first when it may be open. */\n  deleteDocument(id: string): Promise<void>\n  /** Ids of all stored documents. */\n  listDocumentIds(): Promise<string[]>\n}\n\n/** An adapter that stores documents itself (`json`, `drizzle`): the full contract including versioning, settings and document management. */\nexport type StoredEditorAdapter = EditorAdapter\n  & Required<Pick<EditorAdapter, 'contentVersion' | 'loadSettings' | 'storeSettings'>>\n  & DocumentAdmin\n\nconst DEV_USER = { id: 'dev', username: 'dev', color: '#6366f1' } as const\n\nconst authenticateDefault: EditorAdapter['authenticate'] = async () => process.env.NODE_ENV === 'production' ? null : { ...DEV_USER }\n\n/** The members of `EditorAdapter` that `AdapterHooks` fill in. */\nexport type IdentityPart = Pick<EditorAdapter, 'authenticate' | 'listUsers'> & Partial<Pick<EditorAdapter, 'authorize' | 'schemaExtensions'>>\n\n/** `hooks` as adapter members; optional hooks are only present when given (the collab server tests for them). */\nexport function identityPart(hooks: AdapterHooks): IdentityPart {\n  const { authenticate = authenticateDefault, authorize, schemaExtensions, users } = hooks\n  return {\n    authenticate: request => authenticate(request),\n    listUsers: async () => (await users?.()) ?? [],\n    ...(authorize && { authorize: (user: object, id: string) => authorize(user, id) }),\n    ...(schemaExtensions && { schemaExtensions: () => schemaExtensions() }),\n  }\n}\n\n/** The key per-user settings are stored under: the user's `id`, else its `username`. */\nexport function settingsKey(user: object): string {\n  const { id, username } = user as { id?: unknown, username?: unknown }\n  for (const candidate of [id, username]) {\n    if (typeof candidate === 'string' && candidate !== '') return candidate\n    if (typeof candidate === 'number') return String(candidate)\n  }\n  throw new TypeError('@ecsplico/editor: the authenticated user has neither an `id` nor a `username`, so its settings have no key')\n}\n\n/** An independent copy of the bytes (a driver's `Buffer` may view a larger pool), as the plain `Uint8Array` the adapter contract names. */\nexport const bytesOf = (data: Uint8Array): Uint8Array => new Uint8Array(data)\n"],"mappings":";AAsCA,MAAM,WAAW;CAAE,IAAI;CAAO,UAAU;CAAO,OAAO;AAAU;AAEhE,MAAM,sBAAqD,YAAY,QAAQ,IAAI,aAAa,eAAe,OAAO,EAAE,GAAG,SAAS;;AAMpI,SAAgB,aAAa,OAAmC;CAC9D,MAAM,EAAE,eAAe,qBAAqB,WAAW,kBAAkB,UAAU;CACnF,OAAO;EACL,eAAc,YAAW,aAAa,OAAO;EAC7C,WAAW,YAAa,MAAM,QAAQ,KAAM,CAAC;EAC7C,GAAI,aAAa,EAAE,YAAY,MAAc,OAAe,UAAU,MAAM,EAAE,EAAE;EAChF,GAAI,oBAAoB,EAAE,wBAAwB,iBAAiB,EAAE;CACvE;AACF;;AAGA,SAAgB,YAAY,MAAsB;CAChD,MAAM,EAAE,IAAI,aAAa;CACzB,KAAK,MAAM,aAAa,CAAC,IAAI,QAAQ,GAAG;EACtC,IAAI,OAAO,cAAc,YAAY,cAAc,IAAI,OAAO;EAC9D,IAAI,OAAO,cAAc,UAAU,OAAO,OAAO,SAAS;CAC5D;CACA,MAAM,IAAI,UAAU,4GAA4G;AAClI;;AAGA,MAAa,WAAW,SAAiC,IAAI,WAAW,IAAI"}
+{"version":3,"file":"shared.js","names":[],"sources":["../../src/adapters/shared.ts"],"sourcesContent":["import type { MentionUser } from '../features/mentions/schema'\nimport type { AssetStore, CollabStateStore, Directory, DocumentAdmin, DocumentStore, EditorPorts, Identity, SettingsStore } from '../server'\n\n/**\n * The identity half of every adapter in this package: who the user is, which documents they may open and who can be\n * `@`-mentioned. Storage is the adapter's own business.\n */\nexport interface AdapterHooks {\n  /**\n   * The user behind a request, `null` = not authenticated (see `Identity.authenticate`). Default: an anonymous\n   * development user outside `NODE_ENV=production`, `null` (everyone refused) in production, so a deployment never\n   * serves documents to the world by omission.\n   */\n  authenticate?: Identity['authenticate']\n  /** Per-document access for the collaboration websocket (see `Identity.authorize`). Omitted: every authenticated user edits every document. */\n  authorize?: Identity['authorize']\n  /** Users that can be `@`-mentioned (`GET /api/editor/users`); no credentials. Default: none. */\n  users?: () => MentionUser[] | Promise<MentionUser[]>\n}\n\n/** The ports of an adapter that stores documents itself (`json`, `drizzle`): the contract including versioning, settings and document management. */\nexport interface StoredPorts extends EditorPorts {\n  documents: DocumentStore & DocumentAdmin & Required<Pick<DocumentStore, 'contentVersion'>>\n  collabState: CollabStateStore\n  directory: Directory\n  assets: AssetStore\n  settings: SettingsStore\n}\n\nconst DEV_USER = { id: 'dev', username: 'dev', color: '#6366f1' } as const\n\nconst authenticateDefault: Identity['authenticate'] = async () => process.env.NODE_ENV === 'production' ? null : { ...DEV_USER }\n\n/** The `identity` port of `hooks`; `authorize` is only present when given (the collab server and the document routes test for it). */\nexport function identityOf(hooks: Pick<AdapterHooks, 'authenticate' | 'authorize'>): Identity {\n  const { authenticate = authenticateDefault, authorize } = hooks\n  return {\n    authenticate: request => authenticate(request),\n    ...(authorize && { authorize: (user: object, id: string) => authorize(user, id) }),\n  }\n}\n\n/** The `directory` port of the `users` hook. */\nexport function directoryOf({ users }: Pick<AdapterHooks, 'users'>): Directory {\n  return { listUsers: async () => (await users?.()) ?? [] }\n}\n\n/** The key per-user settings are stored under: the user's `id`, else its `username`. */\nexport function settingsKey(user: object): string {\n  const { id, username } = user as { id?: unknown, username?: unknown }\n  for (const candidate of [id, username]) {\n    if (typeof candidate === 'string' && candidate !== '') return candidate\n    if (typeof candidate === 'number') return String(candidate)\n  }\n  throw new TypeError('@ecsplico/editor: the authenticated user has neither an `id` nor a `username`, so its settings have no key')\n}\n\n/** An independent copy of the bytes (a driver's `Buffer` may view a larger pool), as the plain `Uint8Array` the port contract names. */\nexport const bytesOf = (data: Uint8Array): Uint8Array => new Uint8Array(data)\n"],"mappings":";AA6BA,MAAM,WAAW;CAAE,IAAI;CAAO,UAAU;CAAO,OAAO;AAAU;AAEhE,MAAM,sBAAgD,YAAY,QAAQ,IAAI,aAAa,eAAe,OAAO,EAAE,GAAG,SAAS;;AAG/H,SAAgB,WAAW,OAAmE;CAC5F,MAAM,EAAE,eAAe,qBAAqB,cAAc;CAC1D,OAAO;EACL,eAAc,YAAW,aAAa,OAAO;EAC7C,GAAI,aAAa,EAAE,YAAY,MAAc,OAAe,UAAU,MAAM,EAAE,EAAE;CAClF;AACF;;AAGA,SAAgB,YAAY,EAAE,SAAiD;CAC7E,OAAO,EAAE,WAAW,YAAa,MAAM,QAAQ,KAAM,CAAC,EAAE;AAC1D;;AAGA,SAAgB,YAAY,MAAsB;CAChD,MAAM,EAAE,IAAI,aAAa;CACzB,KAAK,MAAM,aAAa,CAAC,IAAI,QAAQ,GAAG;EACtC,IAAI,OAAO,cAAc,YAAY,cAAc,IAAI,OAAO;EAC9D,IAAI,OAAO,cAAc,UAAU,OAAO,OAAO,SAAS;CAC5D;CACA,MAAM,IAAI,UAAU,4GAA4G;AAClI;;AAGA,MAAa,WAAW,SAAiC,IAAI,WAAW,IAAI"}

package/dist/adapters/vue.d.ts

@@ -1,27 +1,10 @@
-import { AuthorIdentity, CollaborationSession } from "../core/feature.js";
+import { CollaborationSession } from "../core/feature.js";
+import { CommentsModel } from "../core/backend-types.js";
 import "../core/index.js";
-import { CommentsFetch, RestCommentsModel } from "./comments/client.js";
+import { EditorDocumentOptions } from "./document-state.js";
 import { Editor, JSONContent } from "@tiptap/core";
 import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
 //#region src/adapters/vue.d.ts
-export interface EditorDocumentOptions {
-  /** How requests are sent: `globalThis.fetch`, or a wrapper that adds the base URL and credentials. Used for the content and the comments. */
-  fetch: CommentsFetch;
-  /**
-   * Live collaboration: the collaboration server's websocket URL (`ws://host/collab`; the document id is appended as the
-   * provider's `name`) and the optional token its `EditorAdapter.authenticate` receives. With it the Y.Doc is the document:
-   * the server loads and stores the content, so the composable neither fetches nor saves it (`modelValue` stays
-   * `undefined`, `dirty` stays `false`, `save()` resolves at once).
-   */
-  collaboration?: {
-    url: string;
-    token?: string | (() => string) | (() => Promise<string>);
-  };
-  /** Who writes: labels remote carets and is the author of new comments; `null` or omitted = nobody (no comments). */
-  user?: AuthorIdentity | null | (() => AuthorIdentity | null);
-  /** Whether the user may comment now (a reader of a read-only document may be refused); default `true`. */
-  canComment?: boolean | (() => boolean);
-}
 /** The props and events of the editor surface (`SimpleEditor`, `AdvancedEditor`, `EditorSurface`) that `useEditorDocument` fills. */
 export interface EditorDocumentBinding {
   /** The document (standalone mode); `undefined` in collaboration mode and until it has loaded. */
@@ -38,16 +21,16 @@ export interface EditorDocument {
   ready: Ref<boolean>;
   /** Edits since the content was loaded or last saved. */
   dirty: ComputedRef<boolean>;
-  /** Stores the current content (`PUT`); several calls run one after another and an edit made while one is in flight stays dirty. Rejects with the server's refusal. */
+  /** Stores the current content (`backend.documents.save`); several calls run one after another and an edit made while one is in flight stays dirty. Rejects with the backend's refusal. */
   save(): Promise<void>;
-  /** Fetches the content again and drops unsaved edits. */
+  /** Loads the content again and drops unsaved edits. */
   reload(): Promise<void>;
   /** The last load or save error, `null` while all is well. */
   error: Ref<Error | null>;
   /** The collaboration session for the surface's `collaboration` prop; `undefined` without the `collaboration` option. */
   collaboration: ShallowRef<CollaborationSession | undefined>;
-  /** The comments model of this document (`commentsFeature({ model: () => comments.value })`), threads behind the host's comments endpoint. A new one per id. */
-  comments: Readonly<ShallowRef<RestCommentsModel>>;
+  /** The comments model of this document (`commentsFeature({ model: () => comments.value! })`), made by `backend.comments`; `undefined` when the backend has none. A new one per id. */
+  comments: Readonly<ShallowRef<CommentsModel | undefined>>;
   /** The live editor, once the surface reported it. */
   editor: ShallowRef<Editor | undefined>;
   /** `v-bind` target for the surface: `<AdvancedEditor v-if="ready" :key="id" v-bind="bind" />`. */
@@ -56,12 +39,14 @@ export interface EditorDocument {
   dispose(): void;
 }
 /**
- * Loads document `id` from `GET /api/editor/documents/<id>` (a `404` starts an empty document that the first `save()`
- * creates), tracks edits, saves with `PUT`, and prepares the collaboration session and comments model for the editor
- * surface. `id` may be reactive: a change loads the other document and replaces the session and the comments model.
- * Call it in a component's `setup`; the collaboration session is created synchronously, so the surface mounts in the same tick.
+ * Loads document `id` through `backend.documents` (a missing document starts empty; the first `save()` creates it),
+ * tracks edits, saves, and prepares the collaboration session (`backend.collaboration`) and comments model
+ * (`backend.comments`) for the editor surface. The backend is `options.backend`, else the editor context's
+ * (`createEditor`). `id` may be reactive: a change loads the other document and replaces the session and the comments
+ * model. Call it in a component's `setup`; the collaboration session is created synchronously, so the surface mounts in
+ * the same tick. Throws when `collaboration` is set and the backend cannot collaborate, or when it keeps no documents.
  */
-export declare function useEditorDocument(id: MaybeRefOrGetter<string>, options: EditorDocumentOptions): EditorDocument;
+export declare function useEditorDocument(id: MaybeRefOrGetter<string>, options?: EditorDocumentOptions): EditorDocument;
 //#endregion
-export type { CommentsFetch };
+export type { EditorDocumentOptions };
 //# sourceMappingURL=vue.d.ts.map

package/dist/adapters/vue.js

@@ -1,74 +1,35 @@
-import { commentsUrl, documentUrl } from "./routes.js";
-import { createRestCommentsModel } from "./comments/client.js";
-import * as Y from "yjs";
-import { HocuspocusProvider } from "@hocuspocus/provider";
-import { computed, getCurrentScope, onScopeDispose, ref, shallowRef, toValue, watch } from "vue";
+import { errorOf, fingerprintToSave, isDirty, loadedDocument, openSession, requireCapability } from "./document-state.js";
+import { EDITOR_CONTEXT } from "../vue/context-key.js";
+import { computed, getCurrentScope, inject, onScopeDispose, ref, shallowRef, toValue, watch } from "vue";
 //#region src/adapters/vue.ts
-const EMPTY_DOCUMENT = {
-	type: "doc",
-	content: [{ type: "paragraph" }]
-};
 /**
-* The document as compared for "unsaved changes": without block ids. The editor gives every block of loaded content an
-* id the moment it mounts (stored files have none yet); that is not an edit the user made, so it must not mark a
-* freshly opened document dirty. Saving still writes the ids.
+* Loads document `id` through `backend.documents` (a missing document starts empty; the first `save()` creates it),
+* tracks edits, saves, and prepares the collaboration session (`backend.collaboration`) and comments model
+* (`backend.comments`) for the editor surface. The backend is `options.backend`, else the editor context's
+* (`createEditor`). `id` may be reactive: a change loads the other document and replaces the session and the comments
+* model. Call it in a component's `setup`; the collaboration session is created synchronously, so the surface mounts in
+* the same tick. Throws when `collaboration` is set and the backend cannot collaborate, or when it keeps no documents.
 */
-const withoutBlockIds = (node) => {
-	const { attrs, content, ...rest } = node;
-	const kept = attrs && Object.fromEntries(Object.entries(attrs).filter(([name]) => name !== "id"));
-	return {
-		...rest,
-		...kept && Object.keys(kept).length > 0 && { attrs: kept },
-		...content && { content: content.map(withoutBlockIds) }
-	};
-};
-const fingerprint = (content) => JSON.stringify(withoutBlockIds(content));
-/** Document ids are percent-encoded into one path segment; the collab provider's `name` is the plain id. */
-function sessionOf(id, { url, token }, user) {
-	const ydoc = new Y.Doc();
-	const provider = new HocuspocusProvider({
-		url: `${url.replace(/\/+$/, "")}/${encodeURIComponent(id)}`,
-		name: id,
-		document: ydoc,
-		...token !== void 0 && { token }
-	});
-	return {
-		session: {
-			ydoc,
-			provider,
-			...user && { user }
-		},
-		close() {
-			provider.destroy();
-			ydoc.destroy();
-		}
-	};
-}
-const errorOf = (cause) => cause instanceof Error ? cause : new Error(String(cause));
-/**
-* Loads document `id` from `GET /api/editor/documents/<id>` (a `404` starts an empty document that the first `save()`
-* creates), tracks edits, saves with `PUT`, and prepares the collaboration session and comments model for the editor
-* surface. `id` may be reactive: a change loads the other document and replaces the session and the comments model.
-* Call it in a component's `setup`; the collaboration session is created synchronously, so the surface mounts in the same tick.
-*/
-function useEditorDocument(id, options) {
+function useEditorDocument(id, options = {}) {
+	const backend = options.backend ?? inject(EDITOR_CONTEXT, null)?.backend;
+	if (!backend) throw new Error("@ecsplico/editor: useEditorDocument needs a backend: pass `backend` or install the editor context with app.use(createEditor())");
+	const collaborating = Boolean(options.collaboration);
+	const documents = collaborating ? void 0 : requireCapability(backend, "documents");
+	const collaborationPort = collaborating ? requireCapability(backend, "collaboration") : void 0;
 	const userOf = () => toValue(options.user) ?? null;
 	const modelValue = ref();
 	const ready = ref(false);
 	const error = ref(null);
 	const collaboration = shallowRef();
 	const editor = shallowRef();
-	/** Fingerprint (`fingerprint`) of the JSON the server holds (the empty document while it does not exist), `null` before the first load. */
+	/** Fingerprint (`fingerprint`) of the JSON the backend holds (the empty document while it does not exist), `null` before the first load. */
 	const savedJson = ref(null);
-	/** The document does not exist on the server yet: the first save creates it even if nothing was typed. */
+	/** The document does not exist in the backend yet: the first save creates it even if nothing was typed. */
 	let missing = false;
 	let closeSession;
 	let generation = 0;
 	let tail = Promise.resolve();
-	const commentsFor = (documentId) => createRestCommentsModel({
-		fetch: options.fetch,
-		documentId,
-		endpoint: commentsUrl(documentId),
+	const commentsFor = (documentId) => backend.comments?.(documentId, {
 		user: userOf,
 		canComment: () => toValue(options.canComment) ?? true,
 		getEditor: () => editor.value,
@@ -90,54 +51,42 @@ function useEditorDocument(id, options) {
 		closeSession = void 0;
 		collaboration.value = void 0;
 		if (commentsId !== documentId) {
-			comments.value.dispose();
+			comments.value?.dispose();
 			comments.value = commentsFor(documentId);
 			commentsId = documentId;
 		}
-		if (options.collaboration) {
-			const { session, close } = sessionOf(documentId, options.collaboration, userOf());
+		if (collaborationPort) {
+			const { session, close } = openSession(collaborationPort, documentId, options.collaboration, userOf());
 			closeSession = close;
 			collaboration.value = session;
 			ready.value = true;
 			return;
 		}
 		try {
-			const response = await options.fetch(documentUrl(documentId));
+			const content = await documents.load(documentId);
 			if (mine !== generation) return;
-			if (response.status === 404) {
-				modelValue.value = structuredClone(EMPTY_DOCUMENT);
-				savedJson.value = fingerprint(EMPTY_DOCUMENT);
-				missing = true;
-			} else if (response.ok) {
-				const content = await response.json();
-				if (mine !== generation) return;
-				modelValue.value = content;
-				savedJson.value = fingerprint(content);
-			} else throw new Error(`@ecsplico/editor: loading "${documentId}" failed (${response.status})`);
+			const loaded = loadedDocument(content);
+			modelValue.value = loaded.modelValue;
+			savedJson.value = loaded.saved;
+			missing = loaded.missing;
 			ready.value = true;
 		} catch (cause) {
 			if (mine === generation) error.value = errorOf(cause);
 		}
 	}
-	const dirty = computed(() => !options.collaboration && modelValue.value !== void 0 && savedJson.value !== null && fingerprint(modelValue.value) !== savedJson.value);
+	const dirty = computed(() => isDirty(collaborating, modelValue.value, savedJson.value));
 	function save() {
-		if (options.collaboration) return Promise.resolve();
+		if (!documents) return Promise.resolve();
 		const run = async () => {
 			const documentId = toValue(id);
 			const content = modelValue.value;
-			if (content === void 0 || !ready.value) return;
-			const saved = fingerprint(content);
-			if (saved === savedJson.value && !missing) return;
-			const json = JSON.stringify(content);
-			const response = await options.fetch(documentUrl(documentId), {
-				method: "PUT",
-				headers: { "content-type": "application/json" },
-				body: json
-			});
-			if (!response.ok) {
-				const failure = /* @__PURE__ */ new Error(`@ecsplico/editor: saving "${documentId}" failed (${response.status})`);
-				error.value = failure;
-				throw failure;
+			const saved = fingerprintToSave(content, ready.value, savedJson.value, missing);
+			if (content === void 0 || saved === null) return;
+			try {
+				await documents.save(documentId, content);
+			} catch (cause) {
+				error.value = errorOf(cause);
+				throw cause;
 			}
 			error.value = null;
 			if (documentId === toValue(id)) {
@@ -154,7 +103,7 @@ function useEditorDocument(id, options) {
 		closeSession?.();
 		closeSession = void 0;
 		collaboration.value = void 0;
-		comments.value.dispose();
+		comments.value?.dispose();
 	}
 	watch(() => toValue(id), (documentId) => void load(documentId), { immediate: true });
 	if (getCurrentScope()) onScopeDispose(dispose);

package/dist/adapters/vue.js.map

@@ -1 +1 @@
-{"version":3,"file":"vue.js","names":[],"sources":["../../src/adapters/vue.ts"],"sourcesContent":["import { HocuspocusProvider } from '@hocuspocus/provider'\nimport type { Editor, JSONContent } from '@tiptap/core'\nimport type { AuthorIdentity, CollaborationSession } from '../core'\nimport { computed, type ComputedRef, getCurrentScope, type MaybeRefOrGetter, onScopeDispose, ref, type Ref, shallowRef, type ShallowRef, toValue, watch } from 'vue'\nimport * as Y from 'yjs'\nimport { type CommentsFetch, createRestCommentsModel, type RestCommentsModel } from './comments/client'\nimport { commentsUrl, documentUrl } from './routes'\n\n// The Vue side of an editor document: load it from the host's document endpoint, keep track of unsaved edits, save it,\n// and hand the editor surface what it needs (v-model, collaboration session, comments model). The server side is\n// `installEditorServer` (`./server/nitro`); any server that answers the same two routes works.\n\nexport type { CommentsFetch } from './comments/client'\n\nexport interface EditorDocumentOptions {\n  /** How requests are sent: `globalThis.fetch`, or a wrapper that adds the base URL and credentials. Used for the content and the comments. */\n  fetch: CommentsFetch\n  /**\n   * Live collaboration: the collaboration server's websocket URL (`ws://host/collab`; the document id is appended as the\n   * provider's `name`) and the optional token its `EditorAdapter.authenticate` receives. With it the Y.Doc is the document:\n   * the server loads and stores the content, so the composable neither fetches nor saves it (`modelValue` stays\n   * `undefined`, `dirty` stays `false`, `save()` resolves at once).\n   */\n  collaboration?: { url: string, token?: string | (() => string) | (() => Promise<string>) }\n  /** Who writes: labels remote carets and is the author of new comments; `null` or omitted = nobody (no comments). */\n  user?: AuthorIdentity | null | (() => AuthorIdentity | null)\n  /** Whether the user may comment now (a reader of a read-only document may be refused); default `true`. */\n  canComment?: boolean | (() => boolean)\n}\n\n/** The props and events of the editor surface (`SimpleEditor`, `AdvancedEditor`, `EditorSurface`) that `useEditorDocument` fills. */\nexport interface EditorDocumentBinding {\n  /** The document (standalone mode); `undefined` in collaboration mode and until it has loaded. */\n  modelValue: JSONContent | undefined\n  'onUpdate:modelValue': (content: JSONContent) => void\n  /** Hands the live editor to the comments model. */\n  onReady: (editor: Editor) => void\n  collaboration: CollaborationSession | undefined\n}\n\nexport interface EditorDocument {\n  /** The document's TipTap JSON: the surface's `v-model`. `undefined` until loaded, and always in collaboration mode. */\n  modelValue: Ref<JSONContent | undefined>\n  /** `true` once the surface can be mounted: the content has loaded (a missing document starts empty), or the collaboration session exists. Mount with `:key` = the id, so a changed id remounts it. */\n  ready: Ref<boolean>\n  /** Edits since the content was loaded or last saved. */\n  dirty: ComputedRef<boolean>\n  /** Stores the current content (`PUT`); several calls run one after another and an edit made while one is in flight stays dirty. Rejects with the server's refusal. */\n  save(): Promise<void>\n  /** Fetches the content again and drops unsaved edits. */\n  reload(): Promise<void>\n  /** The last load or save error, `null` while all is well. */\n  error: Ref<Error | null>\n  /** The collaboration session for the surface's `collaboration` prop; `undefined` without the `collaboration` option. */\n  collaboration: ShallowRef<CollaborationSession | undefined>\n  /** The comments model of this document (`commentsFeature({ model: () => comments.value })`), threads behind the host's comments endpoint. A new one per id. */\n  comments: Readonly<ShallowRef<RestCommentsModel>>\n  /** The live editor, once the surface reported it. */\n  editor: ShallowRef<Editor | undefined>\n  /** `v-bind` target for the surface: `<AdvancedEditor v-if=\"ready\" :key=\"id\" v-bind=\"bind\" />`. */\n  bind: ComputedRef<EditorDocumentBinding>\n  /** Closes the collaboration session and the comments model; runs with the effect scope that called `useEditorDocument`. */\n  dispose(): void\n}\n\nconst EMPTY_DOCUMENT: JSONContent = { type: 'doc', content: [{ type: 'paragraph' }] }\n\n/**\n * The document as compared for \"unsaved changes\": without block ids. The editor gives every block of loaded content an\n * id the moment it mounts (stored files have none yet); that is not an edit the user made, so it must not mark a\n * freshly opened document dirty. Saving still writes the ids.\n */\nconst withoutBlockIds = (node: JSONContent): JSONContent => {\n  const { attrs, content, ...rest } = node\n  const kept = attrs && Object.fromEntries(Object.entries(attrs).filter(([name]) => name !== 'id'))\n  return {\n    ...rest,\n    ...(kept && Object.keys(kept).length > 0 && { attrs: kept }),\n    ...(content && { content: content.map(withoutBlockIds) }),\n  }\n}\nconst fingerprint = (content: JSONContent): string => JSON.stringify(withoutBlockIds(content))\n\n/** Document ids are percent-encoded into one path segment; the collab provider's `name` is the plain id. */\nfunction sessionOf(id: string, { url, token }: NonNullable<EditorDocumentOptions['collaboration']>, user: AuthorIdentity | null): { session: CollaborationSession, close: () => void } {\n  const ydoc = new Y.Doc()\n  const provider = new HocuspocusProvider({ url: `${url.replace(/\\/+$/, '')}/${encodeURIComponent(id)}`, name: id, document: ydoc, ...(token !== undefined && { token }) })\n  return {\n    session: { ydoc, provider, ...(user && { user }) },\n    close() {\n      provider.destroy()\n      ydoc.destroy()\n    },\n  }\n}\n\nconst errorOf = (cause: unknown) => cause instanceof Error ? cause : new Error(String(cause))\n\n/**\n * Loads document `id` from `GET /api/editor/documents/<id>` (a `404` starts an empty document that the first `save()`\n * creates), tracks edits, saves with `PUT`, and prepares the collaboration session and comments model for the editor\n * surface. `id` may be reactive: a change loads the other document and replaces the session and the comments model.\n * Call it in a component's `setup`; the collaboration session is created synchronously, so the surface mounts in the same tick.\n */\nexport function useEditorDocument(id: MaybeRefOrGetter<string>, options: EditorDocumentOptions): EditorDocument {\n  const userOf = () => toValue(options.user) ?? null\n  const modelValue = ref<JSONContent>()\n  const ready = ref(false)\n  const error = ref<Error | null>(null)\n  const collaboration = shallowRef<CollaborationSession>()\n  const editor = shallowRef<Editor>()\n  /** Fingerprint (`fingerprint`) of the JSON the server holds (the empty document while it does not exist), `null` before the first load. */\n  const savedJson = ref<string | null>(null)\n  /** The document does not exist on the server yet: the first save creates it even if nothing was typed. */\n  let missing = false\n  let closeSession: (() => void) | undefined\n  let generation = 0\n  let tail: Promise<unknown> = Promise.resolve()\n\n  const commentsFor = (documentId: string) => createRestCommentsModel({\n    fetch: options.fetch,\n    documentId,\n    endpoint: commentsUrl(documentId),\n    user: userOf,\n    canComment: () => toValue(options.canComment) ?? true,\n    getEditor: () => editor.value,\n    onError: (cause) => { error.value = cause },\n  })\n  const comments = shallowRef(commentsFor(toValue(id)))\n  let commentsId = toValue(id)\n\n  async function load(documentId: string): Promise<void> {\n    const mine = ++generation\n    ready.value = false\n    error.value = null\n    modelValue.value = undefined\n    savedJson.value = null\n    missing = false\n    editor.value = undefined\n    closeSession?.()\n    closeSession = undefined\n    collaboration.value = undefined\n    if (commentsId !== documentId) {\n      comments.value.dispose()\n      comments.value = commentsFor(documentId)\n      commentsId = documentId\n    }\n\n    if (options.collaboration) {\n      const { session, close } = sessionOf(documentId, options.collaboration, userOf())\n      closeSession = close\n      collaboration.value = session\n      ready.value = true\n      return\n    }\n    try {\n      const response = await options.fetch(documentUrl(documentId))\n      if (mine !== generation) return\n      if (response.status === 404) {\n        modelValue.value = structuredClone(EMPTY_DOCUMENT)\n        savedJson.value = fingerprint(EMPTY_DOCUMENT)\n        missing = true\n      }\n      else if (response.ok) {\n        const content = await response.json() as JSONContent\n        if (mine !== generation) return\n        modelValue.value = content\n        savedJson.value = fingerprint(content)\n      }\n      else {\n        throw new Error(`@ecsplico/editor: loading \"${documentId}\" failed (${response.status})`)\n      }\n      ready.value = true\n    }\n    catch (cause) {\n      if (mine === generation) error.value = errorOf(cause)\n    }\n  }\n\n  const dirty = computed(() => !options.collaboration && modelValue.value !== undefined && savedJson.value !== null && fingerprint(modelValue.value) !== savedJson.value)\n\n  function save(): Promise<void> {\n    if (options.collaboration) return Promise.resolve()\n    const run = async () => {\n      const documentId = toValue(id)\n      const content = modelValue.value\n      if (content === undefined || !ready.value) return\n      const saved = fingerprint(content)\n      if (saved === savedJson.value && !missing) return\n      const json = JSON.stringify(content)\n      const response = await options.fetch(documentUrl(documentId), { method: 'PUT', headers: { 'content-type': 'application/json' }, body: json })\n      if (!response.ok) {\n        const failure = new Error(`@ecsplico/editor: saving \"${documentId}\" failed (${response.status})`)\n        error.value = failure\n        throw failure\n      }\n      error.value = null\n      // Only if the document did not change to another id while the request was in flight.\n      if (documentId === toValue(id)) {\n        savedJson.value = saved\n        missing = false\n      }\n    }\n    const result = tail.then(run, run)\n    tail = result.catch(() => {})\n    return result\n  }\n\n  function dispose() {\n    generation++\n    closeSession?.()\n    closeSession = undefined\n    collaboration.value = undefined\n    comments.value.dispose()\n  }\n\n  watch(() => toValue(id), documentId => void load(documentId), { immediate: true })\n  if (getCurrentScope()) onScopeDispose(dispose)\n\n  const bind = computed<EditorDocumentBinding>(() => ({\n    modelValue: modelValue.value,\n    'onUpdate:modelValue': (content) => { modelValue.value = content },\n    onReady: (instance) => { editor.value = instance },\n    collaboration: collaboration.value,\n  }))\n\n  return { modelValue, ready, dirty, save, reload: () => load(toValue(id)), error, collaboration, comments, editor, bind, dispose }\n}\n"],"mappings":"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"}
+{"version":3,"file":"vue.js","names":[],"sources":["../../src/adapters/vue.ts"],"sourcesContent":["import type { Editor, JSONContent } from '@tiptap/core'\nimport type { CollaborationSession } from '../core'\nimport type { CommentsModel } from '../core/backend-types'\nimport { EDITOR_CONTEXT } from '../vue/context-key'\nimport { computed, type ComputedRef, getCurrentScope, inject, type MaybeRefOrGetter, onScopeDispose, ref, type Ref, shallowRef, type ShallowRef, toValue, watch } from 'vue'\nimport { type EditorDocumentOptions, errorOf, fingerprintToSave, isDirty, loadedDocument, openSession, requireCapability } from './document-state'\n\n// The Vue side of an editor document: load it through the backend's `documents`, keep track of unsaved edits, save it,\n// and hand the editor surface what it needs (v-model, collaboration session, comments model). All three go through\n// `EditorBackend` (`createHttpBackend()` for the editor's routes, or the host's own); nothing here knows a URL.\n\nexport type { EditorDocumentOptions } from './document-state'\n\n/** The props and events of the editor surface (`SimpleEditor`, `AdvancedEditor`, `EditorSurface`) that `useEditorDocument` fills. */\nexport interface EditorDocumentBinding {\n  /** The document (standalone mode); `undefined` in collaboration mode and until it has loaded. */\n  modelValue: JSONContent | undefined\n  'onUpdate:modelValue': (content: JSONContent) => void\n  /** Hands the live editor to the comments model. */\n  onReady: (editor: Editor) => void\n  collaboration: CollaborationSession | undefined\n}\n\nexport interface EditorDocument {\n  /** The document's TipTap JSON: the surface's `v-model`. `undefined` until loaded, and always in collaboration mode. */\n  modelValue: Ref<JSONContent | undefined>\n  /** `true` once the surface can be mounted: the content has loaded (a missing document starts empty), or the collaboration session exists. Mount with `:key` = the id, so a changed id remounts it. */\n  ready: Ref<boolean>\n  /** Edits since the content was loaded or last saved. */\n  dirty: ComputedRef<boolean>\n  /** Stores the current content (`backend.documents.save`); several calls run one after another and an edit made while one is in flight stays dirty. Rejects with the backend's refusal. */\n  save(): Promise<void>\n  /** Loads the content again and drops unsaved edits. */\n  reload(): Promise<void>\n  /** The last load or save error, `null` while all is well. */\n  error: Ref<Error | null>\n  /** The collaboration session for the surface's `collaboration` prop; `undefined` without the `collaboration` option. */\n  collaboration: ShallowRef<CollaborationSession | undefined>\n  /** The comments model of this document (`commentsFeature({ model: () => comments.value! })`), made by `backend.comments`; `undefined` when the backend has none. A new one per id. */\n  comments: Readonly<ShallowRef<CommentsModel | undefined>>\n  /** The live editor, once the surface reported it. */\n  editor: ShallowRef<Editor | undefined>\n  /** `v-bind` target for the surface: `<AdvancedEditor v-if=\"ready\" :key=\"id\" v-bind=\"bind\" />`. */\n  bind: ComputedRef<EditorDocumentBinding>\n  /** Closes the collaboration session and the comments model; runs with the effect scope that called `useEditorDocument`. */\n  dispose(): void\n}\n\n/**\n * Loads document `id` through `backend.documents` (a missing document starts empty; the first `save()` creates it),\n * tracks edits, saves, and prepares the collaboration session (`backend.collaboration`) and comments model\n * (`backend.comments`) for the editor surface. The backend is `options.backend`, else the editor context's\n * (`createEditor`). `id` may be reactive: a change loads the other document and replaces the session and the comments\n * model. Call it in a component's `setup`; the collaboration session is created synchronously, so the surface mounts in\n * the same tick. Throws when `collaboration` is set and the backend cannot collaborate, or when it keeps no documents.\n */\nexport function useEditorDocument(id: MaybeRefOrGetter<string>, options: EditorDocumentOptions = {}): EditorDocument {\n  const backend = options.backend ?? inject(EDITOR_CONTEXT, null)?.backend\n  if (!backend) throw new Error('@ecsplico/editor: useEditorDocument needs a backend: pass `backend` or install the editor context with app.use(createEditor())')\n  const collaborating = Boolean(options.collaboration)\n  const documents = collaborating ? undefined : requireCapability(backend, 'documents')\n  const collaborationPort = collaborating ? requireCapability(backend, 'collaboration') : undefined\n\n  const userOf = () => toValue(options.user) ?? null\n  const modelValue = ref<JSONContent>()\n  const ready = ref(false)\n  const error = ref<Error | null>(null)\n  const collaboration = shallowRef<CollaborationSession>()\n  const editor = shallowRef<Editor>()\n  /** Fingerprint (`fingerprint`) of the JSON the backend holds (the empty document while it does not exist), `null` before the first load. */\n  const savedJson = ref<string | null>(null)\n  /** The document does not exist in the backend yet: the first save creates it even if nothing was typed. */\n  let missing = false\n  let closeSession: (() => void) | undefined\n  let generation = 0\n  let tail: Promise<unknown> = Promise.resolve()\n\n  const commentsFor = (documentId: string) => backend.comments?.(documentId, {\n    user: userOf,\n    canComment: () => toValue(options.canComment) ?? true,\n    getEditor: () => editor.value,\n    onError: (cause) => { error.value = cause },\n  })\n  const comments = shallowRef(commentsFor(toValue(id)))\n  let commentsId = toValue(id)\n\n  async function load(documentId: string): Promise<void> {\n    const mine = ++generation\n    ready.value = false\n    error.value = null\n    modelValue.value = undefined\n    savedJson.value = null\n    missing = false\n    editor.value = undefined\n    closeSession?.()\n    closeSession = undefined\n    collaboration.value = undefined\n    if (commentsId !== documentId) {\n      comments.value?.dispose()\n      comments.value = commentsFor(documentId)\n      commentsId = documentId\n    }\n\n    if (collaborationPort) {\n      const { session, close } = openSession(collaborationPort, documentId, options.collaboration, userOf())\n      closeSession = close\n      collaboration.value = session\n      ready.value = true\n      return\n    }\n    try {\n      const content = await documents!.load(documentId)\n      if (mine !== generation) return\n      const loaded = loadedDocument(content)\n      modelValue.value = loaded.modelValue\n      savedJson.value = loaded.saved\n      missing = loaded.missing\n      ready.value = true\n    }\n    catch (cause) {\n      if (mine === generation) error.value = errorOf(cause)\n    }\n  }\n\n  const dirty = computed(() => isDirty(collaborating, modelValue.value, savedJson.value))\n\n  function save(): Promise<void> {\n    if (!documents) return Promise.resolve()\n    const run = async () => {\n      const documentId = toValue(id)\n      const content = modelValue.value\n      const saved = fingerprintToSave(content, ready.value, savedJson.value, missing)\n      if (content === undefined || saved === null) return\n      try {\n        await documents.save(documentId, content)\n      }\n      catch (cause) {\n        error.value = errorOf(cause)\n        throw cause\n      }\n      error.value = null\n      // Only if the document did not change to another id while the request was in flight.\n      if (documentId === toValue(id)) {\n        savedJson.value = saved\n        missing = false\n      }\n    }\n    const result = tail.then(run, run)\n    tail = result.catch(() => {})\n    return result\n  }\n\n  function dispose() {\n    generation++\n    closeSession?.()\n    closeSession = undefined\n    collaboration.value = undefined\n    comments.value?.dispose()\n  }\n\n  watch(() => toValue(id), documentId => void load(documentId), { immediate: true })\n  if (getCurrentScope()) onScopeDispose(dispose)\n\n  const bind = computed<EditorDocumentBinding>(() => ({\n    modelValue: modelValue.value,\n    'onUpdate:modelValue': (content) => { modelValue.value = content },\n    onReady: (instance) => { editor.value = instance },\n    collaboration: collaboration.value,\n  }))\n\n  return { modelValue, ready, dirty, save, reload: () => load(toValue(id)), error, collaboration, comments, editor, bind, dispose }\n}\n"],"mappings":"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"}

package/dist/code/CodeSurface.vue.d.ts

@@ -12,16 +12,16 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
   view: import("vue").ShallowRef<EditorView | undefined, EditorView | undefined>;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
   "update:modelValue": (text: string) => any;
-  save: (text: string) => any;
   ready: (view: EditorView) => any;
+  save: (text: string) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
   "onUpdate:modelValue"?: ((text: string) => any) | undefined;
-  onSave?: ((text: string) => any) | undefined;
   onReady?: ((view: EditorView) => any) | undefined;
+  onSave?: ((text: string) => any) | undefined;
 }>, {
   editable: boolean;
-  wordWrap: boolean;
   modelValue: string;
+  wordWrap: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 //#endregion

package/dist/config/index.d.ts

@@ -0,0 +1,105 @@
+import { Locale, Messages } from "../i18n/index.js";
+import { ModelSlot } from "../settings/values.js";
+import "../settings/index.js";
+//#region src/config/index.d.ts
+/** 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. `provider` `'openai'` (default): any OpenAI-compatible `<endpoint>/audio/transcriptions`
+ * (e.g. OpenAI `whisper-1`). `'deepgram'`: Deepgram's pre-recorded `<endpoint>/listen` (endpoint
+ * `https://api.deepgram.com/v1`, model e.g. `nova-3`). `language` (e.g. `'de'`) fixes the spoken language; without it
+ * OpenAI guesses and Deepgram detects it.
+ */
+export interface TranscriptionConfig {
+  provider?: 'openai' | 'deepgram';
+  endpoint: string;
+  model: string;
+  apiKey?: string;
+  language?: string;
+}
+export interface EditorConfig {
+  /** Language of the editor's strings: `'de'` (default) or `'en'`. Set once per app; a host that switches languages at run time recreates the editor context. */
+  locale: Locale;
+  /** Overrides of single messages by key (see `MessageKey`), applied on top of the catalog of `locale`; must be JSON-serialisable. */
+  messages?: Partial<Messages>;
+  ai: {
+    /**
+     * Server-defined model presets (any OpenAI-compatible chat completions endpoint), keyed by preset id. The key is
+     * per preset or the shared `apiKey`, both from env only (Nuxt: `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY`, `<ID>` =
+     * the preset id in upper snake case, e.g. `flashLite` → `FLASH_LITE`, or `NUXT_TIPTAP_EDITOR_AI_API_KEY`). Preset ids
+     * must be camelCase so the env names map onto them. Presets named like a default (`sonnet`, `flashLite`) override its fields.
+     */
+    presets: Record<string, PresetConfig>;
+    /** Shared key of presets without their own. Default `''` (so the env variable has a key to override). */
+    apiKey: string;
+    /** Default preset per slot; users may override in settings. The `complete` model must support assistant prefill. */
+    slots: Record<ModelSlot, string>;
+    /** Per-user limit shared by all AI endpoints: at most `max` requests per sliding `windowMs`. */
+    rateLimit: {
+      max: number;
+      windowMs: number;
+    };
+    /**
+     * Speech-to-text for audio/video Bausteine: an OpenAI-compatible `<endpoint>/audio/transcriptions` or Deepgram
+     * (`provider: 'deepgram'`; OpenRouter presets provide neither). Absent = the action and the endpoint are off.
+     * The key comes from env only (Nuxt: `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY`).
+     */
+    transcription?: TranscriptionConfig;
+  };
+  collab: {
+    /**
+     * Authenticate the `/collab/:id` websocket upgrade itself (`Identity.authenticate` with the upgrade request's
+     * headers) and refuse it with HTTP 401 for an unknown user. Default `false`: the upgrade always succeeds, the user
+     * is authenticated afterwards from the headers or the provider's `token`, and an unauthenticated socket is closed
+     * with code 4401. Enable only when every client authenticates by cookie/headers: a client that sends its identity
+     * as `collaboration.token` (no cookies) cannot connect then. Nuxt env override:
+     * `NUXT_TIPTAP_EDITOR_COLLAB_AUTHENTICATE_UPGRADE=true`.
+     */
+    authenticateUpgrade: boolean;
+  };
+}
+type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]>; } : T;
+/** What a host writes: every key optional, `undefined` (an unset env variable) means the default. */
+export type EditorConfigInput = DeepPartial<EditorConfig>;
+/**
+ * Applies every default once: locale `'de'`, the OpenRouter presets `sonnet` and `flashLite` with the slots that use
+ * them, 30 AI requests per user and minute, no upgrade authentication. Every preset and the transcription get an empty
+ * `apiKey` unless one is given, so an environment variable has a key to override.
+ */
+export declare function defineEditorConfig(input?: EditorConfigInput): EditorConfig;
+/** What the browser may see: the language and the default model slots, never a key. */
+export interface EditorPublicConfig {
+  locale: Locale;
+  messages?: Partial<Messages>;
+  /** Inert AI configuration: default preset per slot before the models list has answered, and whether transcription is on. */
+  ai: {
+    slots: Record<ModelSlot, string>;
+    transcription: boolean;
+  };
+}
+export declare function publicConfig(config: EditorConfig): EditorPublicConfig;
+/** What the server needs, secrets included: the shape `installEditorServer` takes for `ai`, `rateLimit` and `collab`. */
+export interface EditorServerConfig {
+  ai: {
+    presets: Record<string, PresetConfig>;
+    apiKey: string;
+    slots: Record<ModelSlot, string>;
+    transcription?: TranscriptionConfig;
+  };
+  rateLimit: {
+    max: number;
+    windowMs: number;
+  };
+  collab: {
+    authenticateUpgrade: boolean;
+  };
+}
+export declare function serverConfig(config: EditorConfig): EditorServerConfig;
+//#endregion
+export {};
+//# sourceMappingURL=index.d.ts.map