@ecsplico/editor 2.1.2 → 3.0.0

package/dist/server/host.js

@@ -1,53 +1,67 @@
 import { HttpError } from "./errors.js";
-import { createAiModels } from "./ai.js";
-import { createCollabServer } from "./collab.js";
-import { createRateLimiter } from "./rate-limit.js";
 import { enforceRateLimit } from "./handlers/context.js";
 //#region src/server/host.ts
-let adapter;
-let config = {};
+let ports;
+let schema;
+/** Identity of the live installation; `adoptEditorServer` sets it, its release clears it. */
+let installation;
 let collab;
 let models;
 let limiter;
-/** Registers the host's adapter; the collaboration server and the AI models are created from it on first use. Replaces (and closes) those of a previous adapter. */
-function setEditorAdapter(next) {
-	const previous = collab;
-	adapter = next;
-	collab = void 0;
-	models = void 0;
-	if (previous) previous.close();
+function installed() {
+	if (!installation) throw new Error("@ecsplico/editor: server not installed");
 }
-function useEditorAdapter() {
-	if (!adapter) throw new Error("tiptap-editor: setEditorAdapter() wurde nicht aufgerufen");
-	return adapter;
+/**
+* Registers the host's ports for installers that read them later (the Nuxt module's server plugin installs on the first
+* request, after every Nitro plugin has run). `options.schema`: the collaboration schema, see `CollabServerOptions.schema`.
+*/
+function setEditorPorts(next, options = {}) {
+	ports = next;
+	schema = options.schema;
 }
-/** Sets the AI configuration and the rate limit of the process-wide server. Call before the first request. */
-function configureEditorServer(next) {
-	config = next;
-	models = void 0;
-	limiter = void 0;
+function useEditorPorts() {
+	if (!ports) throw new Error("@ecsplico/editor: setEditorPorts() was not called");
+	return ports;
 }
-/** The process-wide collaboration server, created from the registered adapter on first use. */
+/** The collaboration schema registered with `setEditorPorts`, for installers that build the collaboration server themselves. */
+function useEditorSchema() {
+	return schema;
+}
+/**
+* Makes the server `installEditorServer` built the process-wide one, so host code (`useCollabServer`, `useAiModels`,
+* `liveContent`, `enforceAiRateLimit`, …) reaches the same instances the routes use. Returns the function that drops them
+* again (only when no later installation replaced them); the installer calls it when its host closes.
+*/
+function adoptEditorServer(server) {
+	const own = {};
+	installation = own;
+	ports = server.ports;
+	schema = server.schema;
+	collab = server.collab;
+	models = server.models;
+	limiter = server.limiter;
+	return () => {
+		if (installation !== own) return;
+		installation = collab = models = limiter = void 0;
+	};
+}
+/** The process-wide collaboration server of the installed server. Throws when none is installed or `collab: false`. */
 function useCollabServer() {
-	return collab ??= createCollabServer({ adapter: useEditorAdapter() });
+	installed();
+	if (!collab) throw new Error("@ecsplico/editor: collaboration is off (installEditorServer with collab: false)");
+	return collab;
 }
-/** The process-wide AI models: the configured presets, with the adapter's `languageModel`/`listModels` hooks. */
+/** The process-wide AI models of the installed server: its configured presets, with the `models` port's `languageModel`/`listModels` hooks. Throws when none is installed or it was installed without `ai`. */
 function useAiModels() {
-	if (models) return models;
-	const current = useEditorAdapter();
-	return models = createAiModels({
-		presets: {},
-		languageModel: current.languageModel && ((ref, user) => current.languageModel(ref, user)),
-		listModels: current.listModels && ((user) => current.listModels(user)),
-		...config.ai
-	});
-}
-/** The process-wide AI rate limiter. */
+	installed();
+	if (!models) throw new Error("@ecsplico/editor: AI is off (installEditorServer without ai)");
+	return models;
+}
+/** The process-wide AI rate limiter of the installed server (present with `ai`). */
 function useRateLimiter() {
-	return limiter ??= createRateLimiter(config.rateLimit ?? {
-		max: 30,
-		windowMs: 6e4
-	});
+	installed();
+	if (!limiter) throw new Error("@ecsplico/editor: AI is off (installEditorServer without ai)");
+	return limiter;
 }
 /** Closes the process-wide collaboration server (pending stores are written first) and forgets it. */
 async function closeEditorServer() {
@@ -55,8 +69,9 @@ async function closeEditorServer() {
 	collab = void 0;
 	await open?.close();
 }
-/** Open collaboration connections and loaded documents of this process (zeros before the first connection). */
+/** Open collaboration connections and loaded documents of this process (zeros when collaboration is off). */
 function collabStats() {
+	installed();
 	return collab?.stats() ?? {
 		connections: 0,
 		documents: 0
@@ -68,10 +83,12 @@ function forgetCollabDocument(id) {
 }
 /** Current content of a document that is open in the collaboration server (unsaved edits included), `null` when nobody has it open. */
 function liveContent(id) {
+	installed();
 	return collab?.liveContent(id) ?? null;
 }
 /** The host rewrote a document's content (an agent wrote the file): merge it into the open document now, see `CollabServer.contentChanged`. */
 function collabContentChanged(id) {
+	installed();
 	return collab?.contentChanged(id) ?? Promise.resolve();
 }
 /** AI SDK language model for `ref`, see `AiModels.resolveModel`. */
@@ -84,13 +101,13 @@ function listAiModels(user) {
 }
 /**
 * Per-user limit for host-defined AI routes: the same limiter as the editor's own AI endpoints. Call first in the route.
-* Throws 401 (`HttpError`) without a user, 429 when exceeded; returns the user the adapter authenticated, for `resolveModel`.
+* Throws 401 (`HttpError`) without a user, 429 when exceeded; returns the user the identity port authenticated, for `resolveModel`.
 * With a Node-backed request (`event.node.res`, as h3 events have) the 429's `Retry-After` header is set on the response too.
 */
 async function enforceAiRateLimit(request) {
 	try {
 		return await enforceRateLimit({
-			adapter: useEditorAdapter(),
+			ports: useEditorPorts(),
 			ai: useAiModels(),
 			limiter: useRateLimiter()
 		}, { headers: request.headers });
@@ -100,6 +117,6 @@ async function enforceAiRateLimit(request) {
 	}
 }
 //#endregion
-export { closeEditorServer, collabContentChanged, collabStats, configureEditorServer, enforceAiRateLimit, forgetCollabDocument, listAiModels, liveContent, resolveModel, setEditorAdapter, useAiModels, useCollabServer, useEditorAdapter, useRateLimiter };
+export { adoptEditorServer, closeEditorServer, collabContentChanged, collabStats, enforceAiRateLimit, forgetCollabDocument, listAiModels, liveContent, resolveModel, setEditorPorts, useAiModels, useCollabServer, useEditorPorts, useEditorSchema, useRateLimiter };
 
 //# sourceMappingURL=host.js.map

package/dist/server/host.js.map

@@ -1 +1 @@
-{"version":3,"file":"host.js","names":[],"sources":["../../src/server/host.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\nimport type { LanguageModel } from 'ai'\nimport type { ModelProfile, ModelRef } from '../features/ai/protocol'\nimport type { EditorAdapter } from './adapter'\nimport { type AiModels, type AiModelsConfig, createAiModels } from './ai'\nimport { type CollabServer, createCollabServer } from './collab'\nimport { HttpError } from './errors'\nimport { enforceRateLimit } from './handlers/context'\nimport { createRateLimiter, type RateLimiter } from './rate-limit'\n\n// The process-wide editor server of hosts that wire the editor once at startup (the Nuxt module, a script with several\n// modules): one adapter, one collaboration server, one set of AI models, one rate limiter. Everything here is a\n// convenience over `createCollabServer` / `createAiModels` / `createRateLimiter`, which take their configuration\n// explicitly and can be instantiated any number of times (tests, several tenants).\n\nexport interface EditorServerConfig {\n  /**\n   * The AI models: presets, shared key, transcription, slots. `languageModel`/`listModels` default to the adapter's\n   * methods of the same names.\n   */\n  ai?: Partial<AiModelsConfig>\n  /** Per-user limit shared by the AI endpoints. Default 30 requests per minute. */\n  rateLimit?: { max: number, windowMs: number }\n}\n\nlet adapter: EditorAdapter | undefined\nlet config: EditorServerConfig = {}\nlet collab: CollabServer | undefined\nlet models: AiModels | undefined\nlet limiter: RateLimiter | undefined\n\n/** Registers the host's adapter; the collaboration server and the AI models are created from it on first use. Replaces (and closes) those of a previous adapter. */\nexport function setEditorAdapter(next: EditorAdapter) {\n  const previous = collab\n  adapter = next\n  collab = undefined\n  models = undefined\n  if (previous) void previous.close()\n}\n\nexport function useEditorAdapter(): EditorAdapter {\n  if (!adapter) throw new Error('tiptap-editor: setEditorAdapter() wurde nicht aufgerufen')\n  return adapter\n}\n\n/** Sets the AI configuration and the rate limit of the process-wide server. Call before the first request. */\nexport function configureEditorServer(next: EditorServerConfig) {\n  config = next\n  models = undefined\n  limiter = undefined\n}\n\n/** The process-wide collaboration server, created from the registered adapter on first use. */\nexport function useCollabServer(): CollabServer {\n  return collab ??= createCollabServer({ adapter: useEditorAdapter() })\n}\n\n/** The process-wide AI models: the configured presets, with the adapter's `languageModel`/`listModels` hooks. */\nexport function useAiModels(): AiModels {\n  if (models) return models\n  const current = useEditorAdapter()\n  return models = createAiModels({\n    presets: {},\n    languageModel: current.languageModel && ((ref, user) => current.languageModel!(ref, user)),\n    listModels: current.listModels && (user => current.listModels!(user)),\n    ...config.ai,\n  })\n}\n\n/** The process-wide AI rate limiter. */\nexport function useRateLimiter(): RateLimiter {\n  return limiter ??= createRateLimiter(config.rateLimit ?? { max: 30, windowMs: 60_000 })\n}\n\n/** Closes the process-wide collaboration server (pending stores are written first) and forgets it. */\nexport async function closeEditorServer() {\n  const open = collab\n  collab = undefined\n  await open?.close()\n}\n\n/** Open collaboration connections and loaded documents of this process (zeros before the first connection). */\nexport function collabStats(): { connections: number, documents: number } {\n  return collab?.stats() ?? { connections: 0, documents: 0 }\n}\n\n/** Tell connected clients the document is gone, disconnect them and drop the Yjs state. Call before removing the JSON. */\nexport function forgetCollabDocument(id: string): Promise<void> {\n  return useCollabServer().forgetDocument(id)\n}\n\n/** Current content of a document that is open in the collaboration server (unsaved edits included), `null` when nobody has it open. */\nexport function liveContent(id: string): JSONContent | null {\n  return collab?.liveContent(id) ?? null\n}\n\n/** The host rewrote a document's content (an agent wrote the file): merge it into the open document now, see `CollabServer.contentChanged`. */\nexport function collabContentChanged(id: string): Promise<void> {\n  return collab?.contentChanged(id) ?? Promise.resolve()\n}\n\n/** AI SDK language model for `ref`, see `AiModels.resolveModel`. */\nexport function resolveModel(ref: ModelRef, user: object | null): Promise<LanguageModel> {\n  return useAiModels().resolveModel(ref, user)\n}\n\n/** The models listed for `user`, see `AiModels.listModels`. */\nexport function listAiModels(user: object | null): Promise<ModelProfile[]> {\n  return useAiModels().listModels(user)\n}\n\n/**\n * Per-user limit for host-defined AI routes: the same limiter as the editor's own AI endpoints. Call first in the route.\n * Throws 401 (`HttpError`) without a user, 429 when exceeded; returns the user the adapter authenticated, for `resolveModel`.\n * With a Node-backed request (`event.node.res`, as h3 events have) the 429's `Retry-After` header is set on the response too.\n */\nexport async function enforceAiRateLimit(request: { headers: Headers, node?: { res: { setHeader(name: string, value: string): unknown } } }): Promise<object> {\n  try {\n    return await enforceRateLimit({ adapter: useEditorAdapter(), ai: useAiModels(), limiter: useRateLimiter() }, { headers: request.headers })\n  }\n  catch (error) {\n    if (error instanceof HttpError) for (const [name, value] of Object.entries(error.headers)) request.node?.res.setHeader(name, value)\n    throw error\n  }\n}\n"],"mappings":";;;;;;AAyBA,IAAI;AACJ,IAAI,SAA6B,CAAC;AAClC,IAAI;AACJ,IAAI;AACJ,IAAI;;AAGJ,SAAgB,iBAAiB,MAAqB;CACpD,MAAM,WAAW;CACjB,UAAU;CACV,SAAS,KAAA;CACT,SAAS,KAAA;CACT,IAAI,UAAU,SAAc,MAAM;AACpC;AAEA,SAAgB,mBAAkC;CAChD,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,0DAA0D;CACxF,OAAO;AACT;;AAGA,SAAgB,sBAAsB,MAA0B;CAC9D,SAAS;CACT,SAAS,KAAA;CACT,UAAU,KAAA;AACZ;;AAGA,SAAgB,kBAAgC;CAC9C,OAAO,WAAW,mBAAmB,EAAE,SAAS,iBAAiB,EAAE,CAAC;AACtE;;AAGA,SAAgB,cAAwB;CACtC,IAAI,QAAQ,OAAO;CACnB,MAAM,UAAU,iBAAiB;CACjC,OAAO,SAAS,eAAe;EAC7B,SAAS,CAAC;EACV,eAAe,QAAQ,mBAAmB,KAAK,SAAS,QAAQ,cAAe,KAAK,IAAI;EACxF,YAAY,QAAQ,gBAAe,SAAQ,QAAQ,WAAY,IAAI;EACnE,GAAG,OAAO;CACZ,CAAC;AACH;;AAGA,SAAgB,iBAA8B;CAC5C,OAAO,YAAY,kBAAkB,OAAO,aAAa;EAAE,KAAK;EAAI,UAAU;CAAO,CAAC;AACxF;;AAGA,eAAsB,oBAAoB;CACxC,MAAM,OAAO;CACb,SAAS,KAAA;CACT,MAAM,MAAM,MAAM;AACpB;;AAGA,SAAgB,cAA0D;CACxE,OAAO,QAAQ,MAAM,KAAK;EAAE,aAAa;EAAG,WAAW;CAAE;AAC3D;;AAGA,SAAgB,qBAAqB,IAA2B;CAC9D,OAAO,gBAAgB,CAAC,CAAC,eAAe,EAAE;AAC5C;;AAGA,SAAgB,YAAY,IAAgC;CAC1D,OAAO,QAAQ,YAAY,EAAE,KAAK;AACpC;;AAGA,SAAgB,qBAAqB,IAA2B;CAC9D,OAAO,QAAQ,eAAe,EAAE,KAAK,QAAQ,QAAQ;AACvD;;AAGA,SAAgB,aAAa,KAAe,MAA6C;CACvF,OAAO,YAAY,CAAC,CAAC,aAAa,KAAK,IAAI;AAC7C;;AAGA,SAAgB,aAAa,MAA8C;CACzE,OAAO,YAAY,CAAC,CAAC,WAAW,IAAI;AACtC;;;;;;AAOA,eAAsB,mBAAmB,SAAqH;CAC5J,IAAI;EACF,OAAO,MAAM,iBAAiB;GAAE,SAAS,iBAAiB;GAAG,IAAI,YAAY;GAAG,SAAS,eAAe;EAAE,GAAG,EAAE,SAAS,QAAQ,QAAQ,CAAC;CAC3I,SACO,OAAO;EACZ,IAAI,iBAAiB,WAAW,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,OAAO,GAAG,QAAQ,MAAM,IAAI,UAAU,MAAM,KAAK;EAClI,MAAM;CACR;AACF"}
+{"version":3,"file":"host.js","names":[],"sources":["../../src/server/host.ts"],"sourcesContent":["import type { AnyExtension, JSONContent } from '@tiptap/core'\nimport type { LanguageModel } from 'ai'\nimport type { ModelProfile, ModelRef } from '../features/ai/protocol'\nimport type { AiModels } from './ai'\nimport type { CollabServer } from './collab'\nimport { HttpError } from './errors'\nimport { enforceRateLimit } from './handlers/context'\nimport type { EditorPorts } from './ports'\nimport type { RateLimiter } from './rate-limit'\n\n// The process-wide editor server of hosts that wire the editor once at startup (the Nuxt module, a script with several\n// modules): the ports, collaboration server, AI models and rate limiter `installEditorServer` built, reachable from host\n// code (`useCollabServer`, `resolveModel`, `liveContent`, …). Their configuration is the installer's options (see\n// `defineEditorConfig` for the defaults); instances for tests or several tenants come from `createCollabServer` /\n// `createAiModels` / `createRateLimiter`, which take their configuration explicitly.\n\nlet ports: EditorPorts | undefined\nlet schema: (() => AnyExtension[]) | undefined\n/** Identity of the live installation; `adoptEditorServer` sets it, its release clears it. */\nlet installation: object | undefined\nlet collab: CollabServer | undefined\nlet models: AiModels | undefined\nlet limiter: RateLimiter | undefined\n\nfunction installed() {\n  if (!installation) throw new Error('@ecsplico/editor: server not installed')\n}\n\n/**\n * Registers the host's ports for installers that read them later (the Nuxt module's server plugin installs on the first\n * request, after every Nitro plugin has run). `options.schema`: the collaboration schema, see `CollabServerOptions.schema`.\n */\nexport function setEditorPorts(next: EditorPorts, options: { schema?: () => AnyExtension[] } = {}) {\n  ports = next\n  schema = options.schema\n}\n\nexport function useEditorPorts(): EditorPorts {\n  if (!ports) throw new Error('@ecsplico/editor: setEditorPorts() was not called')\n  return ports\n}\n\n/** The collaboration schema registered with `setEditorPorts`, for installers that build the collaboration server themselves. */\nexport function useEditorSchema(): (() => AnyExtension[]) | undefined {\n  return schema\n}\n\n/**\n * Makes the server `installEditorServer` built the process-wide one, so host code (`useCollabServer`, `useAiModels`,\n * `liveContent`, `enforceAiRateLimit`, …) reaches the same instances the routes use. Returns the function that drops them\n * again (only when no later installation replaced them); the installer calls it when its host closes.\n */\nexport function adoptEditorServer(server: { ports: EditorPorts, schema?: () => AnyExtension[], collab?: CollabServer, models?: AiModels, limiter?: RateLimiter }): () => void {\n  const own = {}\n  installation = own\n  ports = server.ports\n  schema = server.schema\n  collab = server.collab\n  models = server.models\n  limiter = server.limiter\n  return () => {\n    if (installation !== own) return\n    installation = collab = models = limiter = undefined\n  }\n}\n\n/** The process-wide collaboration server of the installed server. Throws when none is installed or `collab: false`. */\nexport function useCollabServer(): CollabServer {\n  installed()\n  if (!collab) throw new Error('@ecsplico/editor: collaboration is off (installEditorServer with collab: false)')\n  return collab\n}\n\n/** The process-wide AI models of the installed server: its configured presets, with the `models` port's `languageModel`/`listModels` hooks. Throws when none is installed or it was installed without `ai`. */\nexport function useAiModels(): AiModels {\n  installed()\n  if (!models) throw new Error('@ecsplico/editor: AI is off (installEditorServer without ai)')\n  return models\n}\n\n/** The process-wide AI rate limiter of the installed server (present with `ai`). */\nexport function useRateLimiter(): RateLimiter {\n  installed()\n  if (!limiter) throw new Error('@ecsplico/editor: AI is off (installEditorServer without ai)')\n  return limiter\n}\n\n/** Closes the process-wide collaboration server (pending stores are written first) and forgets it. */\nexport async function closeEditorServer() {\n  const open = collab\n  collab = undefined\n  await open?.close()\n}\n\n/** Open collaboration connections and loaded documents of this process (zeros when collaboration is off). */\nexport function collabStats(): { connections: number, documents: number } {\n  installed()\n  return collab?.stats() ?? { connections: 0, documents: 0 }\n}\n\n/** Tell connected clients the document is gone, disconnect them and drop the Yjs state. Call before removing the JSON. */\nexport function forgetCollabDocument(id: string): Promise<void> {\n  return useCollabServer().forgetDocument(id)\n}\n\n/** Current content of a document that is open in the collaboration server (unsaved edits included), `null` when nobody has it open. */\nexport function liveContent(id: string): JSONContent | null {\n  installed()\n  return collab?.liveContent(id) ?? null\n}\n\n/** The host rewrote a document's content (an agent wrote the file): merge it into the open document now, see `CollabServer.contentChanged`. */\nexport function collabContentChanged(id: string): Promise<void> {\n  installed()\n  return collab?.contentChanged(id) ?? Promise.resolve()\n}\n\n/** AI SDK language model for `ref`, see `AiModels.resolveModel`. */\nexport function resolveModel(ref: ModelRef, user: object | null): Promise<LanguageModel> {\n  return useAiModels().resolveModel(ref, user)\n}\n\n/** The models listed for `user`, see `AiModels.listModels`. */\nexport function listAiModels(user: object | null): Promise<ModelProfile[]> {\n  return useAiModels().listModels(user)\n}\n\n/**\n * Per-user limit for host-defined AI routes: the same limiter as the editor's own AI endpoints. Call first in the route.\n * Throws 401 (`HttpError`) without a user, 429 when exceeded; returns the user the identity port authenticated, for `resolveModel`.\n * With a Node-backed request (`event.node.res`, as h3 events have) the 429's `Retry-After` header is set on the response too.\n */\nexport async function enforceAiRateLimit(request: { headers: Headers, node?: { res: { setHeader(name: string, value: string): unknown } } }): Promise<object> {\n  try {\n    return await enforceRateLimit({ ports: useEditorPorts(), ai: useAiModels(), limiter: useRateLimiter() }, { headers: request.headers })\n  }\n  catch (error) {\n    if (error instanceof HttpError) for (const [name, value] of Object.entries(error.headers)) request.node?.res.setHeader(name, value)\n    throw error\n  }\n}\n"],"mappings":";;;AAgBA,IAAI;AACJ,IAAI;;AAEJ,IAAI;AACJ,IAAI;AACJ,IAAI;AACJ,IAAI;AAEJ,SAAS,YAAY;CACnB,IAAI,CAAC,cAAc,MAAM,IAAI,MAAM,wCAAwC;AAC7E;;;;;AAMA,SAAgB,eAAe,MAAmB,UAA6C,CAAC,GAAG;CACjG,QAAQ;CACR,SAAS,QAAQ;AACnB;AAEA,SAAgB,iBAA8B;CAC5C,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,mDAAmD;CAC/E,OAAO;AACT;;AAGA,SAAgB,kBAAsD;CACpE,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAkB,QAA4I;CAC5K,MAAM,MAAM,CAAC;CACb,eAAe;CACf,QAAQ,OAAO;CACf,SAAS,OAAO;CAChB,SAAS,OAAO;CAChB,SAAS,OAAO;CAChB,UAAU,OAAO;CACjB,aAAa;EACX,IAAI,iBAAiB,KAAK;EAC1B,eAAe,SAAS,SAAS,UAAU,KAAA;CAC7C;AACF;;AAGA,SAAgB,kBAAgC;CAC9C,UAAU;CACV,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,iFAAiF;CAC9G,OAAO;AACT;;AAGA,SAAgB,cAAwB;CACtC,UAAU;CACV,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,8DAA8D;CAC3F,OAAO;AACT;;AAGA,SAAgB,iBAA8B;CAC5C,UAAU;CACV,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,8DAA8D;CAC5F,OAAO;AACT;;AAGA,eAAsB,oBAAoB;CACxC,MAAM,OAAO;CACb,SAAS,KAAA;CACT,MAAM,MAAM,MAAM;AACpB;;AAGA,SAAgB,cAA0D;CACxE,UAAU;CACV,OAAO,QAAQ,MAAM,KAAK;EAAE,aAAa;EAAG,WAAW;CAAE;AAC3D;;AAGA,SAAgB,qBAAqB,IAA2B;CAC9D,OAAO,gBAAgB,CAAC,CAAC,eAAe,EAAE;AAC5C;;AAGA,SAAgB,YAAY,IAAgC;CAC1D,UAAU;CACV,OAAO,QAAQ,YAAY,EAAE,KAAK;AACpC;;AAGA,SAAgB,qBAAqB,IAA2B;CAC9D,UAAU;CACV,OAAO,QAAQ,eAAe,EAAE,KAAK,QAAQ,QAAQ;AACvD;;AAGA,SAAgB,aAAa,KAAe,MAA6C;CACvF,OAAO,YAAY,CAAC,CAAC,aAAa,KAAK,IAAI;AAC7C;;AAGA,SAAgB,aAAa,MAA8C;CACzE,OAAO,YAAY,CAAC,CAAC,WAAW,IAAI;AACtC;;;;;;AAOA,eAAsB,mBAAmB,SAAqH;CAC5J,IAAI;EACF,OAAO,MAAM,iBAAiB;GAAE,OAAO,eAAe;GAAG,IAAI,YAAY;GAAG,SAAS,eAAe;EAAE,GAAG,EAAE,SAAS,QAAQ,QAAQ,CAAC;CACvI,SACO,OAAO;EACZ,IAAI,iBAAiB,WAAW,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,OAAO,GAAG,QAAQ,MAAM,IAAI,UAAU,MAAM,KAAK;EAClI,MAAM;CACR;AACF"}

package/dist/server/index.d.ts

@@ -1,8 +1,10 @@
-import { AuthenticateRequest, EditorAdapter } from "./adapter.js";
+import { PresetConfig, TranscriptionConfig } from "../config/index.js";
+import { AuthenticateRequest } from "./auth.js";
 import { HttpError } from "./errors.js";
-import { AiModels, AiModelsConfig, ChatMessage, ChatTurnPart, PresetConfig, TranscriptionConfig, createAiModels, streamChat, streamChatTurn, upstreamError } from "./ai.js";
+import { AiModels, AiModelsConfig, ChatMessage, ChatTurnPart, createAiModels, streamChat, streamChatTurn, upstreamError } from "./ai.js";
+import { AssetStore, CollabStateStore, Directory, DocumentAdmin, DocumentStore, EditorPorts, Identity, ModelProvider, PORT_CAPABILITY, SettingsStore, ThemeStore, serverCapabilities } from "./ports.js";
 import { COLLAB_FIELD, CollabConnection, CollabServer, CollabServerOptions, WebSocketLike, createCollabServer } from "./collab.js";
 import { decodeCollabState, encodeCollabState, isStateStale } from "./collab-state.js";
 import { RateLimiter, RateLimiterOptions, createRateLimiter, userKey } from "./rate-limit.js";
-import { EditorServerConfig, closeEditorServer, collabContentChanged, collabStats, configureEditorServer, enforceAiRateLimit, forgetCollabDocument, listAiModels, liveContent, resolveModel, setEditorAdapter, useAiModels, useCollabServer, useEditorAdapter } from "./host.js";
-export { type AiModels, type AiModelsConfig, type AuthenticateRequest, COLLAB_FIELD, type ChatMessage, type ChatTurnPart, type CollabConnection, type CollabServer, type CollabServerOptions, type EditorAdapter, type EditorServerConfig, HttpError, type PresetConfig, type RateLimiter, type RateLimiterOptions, type TranscriptionConfig, type WebSocketLike, closeEditorServer, collabContentChanged, collabStats, configureEditorServer, createAiModels, createCollabServer, createRateLimiter, decodeCollabState, encodeCollabState, enforceAiRateLimit, forgetCollabDocument, isStateStale, listAiModels, liveContent, resolveModel, setEditorAdapter, streamChat, streamChatTurn, upstreamError, useAiModels, useCollabServer, useEditorAdapter, userKey };
+import { closeEditorServer, collabContentChanged, collabStats, enforceAiRateLimit, forgetCollabDocument, listAiModels, liveContent, resolveModel, setEditorPorts, useAiModels, useCollabServer, useEditorPorts } from "./host.js";
+export { type AiModels, type AiModelsConfig, type AssetStore, type AuthenticateRequest, COLLAB_FIELD, type ChatMessage, type ChatTurnPart, type CollabConnection, type CollabServer, type CollabServerOptions, type CollabStateStore, type Directory, type DocumentAdmin, type DocumentStore, type EditorPorts, HttpError, type Identity, type ModelProvider, PORT_CAPABILITY, type PresetConfig, type RateLimiter, type RateLimiterOptions, type SettingsStore, type ThemeStore, type TranscriptionConfig, type WebSocketLike, closeEditorServer, collabContentChanged, collabStats, createAiModels, createCollabServer, createRateLimiter, decodeCollabState, encodeCollabState, enforceAiRateLimit, forgetCollabDocument, isStateStale, listAiModels, liveContent, resolveModel, serverCapabilities, setEditorPorts, streamChat, streamChatTurn, upstreamError, useAiModels, useCollabServer, useEditorPorts, userKey };

package/dist/server/index.js

@@ -3,5 +3,6 @@ import { createAiModels, streamChat, streamChatTurn, upstreamError } from "./ai.
 import { decodeCollabState, encodeCollabState, isStateStale } from "./collab-state.js";
 import { COLLAB_FIELD, createCollabServer } from "./collab.js";
 import { createRateLimiter, userKey } from "./rate-limit.js";
-import { closeEditorServer, collabContentChanged, collabStats, configureEditorServer, enforceAiRateLimit, forgetCollabDocument, listAiModels, liveContent, resolveModel, setEditorAdapter, useAiModels, useCollabServer, useEditorAdapter } from "./host.js";
-export { COLLAB_FIELD, HttpError, closeEditorServer, collabContentChanged, collabStats, configureEditorServer, createAiModels, createCollabServer, createRateLimiter, decodeCollabState, encodeCollabState, enforceAiRateLimit, forgetCollabDocument, isStateStale, listAiModels, liveContent, resolveModel, setEditorAdapter, streamChat, streamChatTurn, upstreamError, useAiModels, useCollabServer, useEditorAdapter, userKey };
+import { closeEditorServer, collabContentChanged, collabStats, enforceAiRateLimit, forgetCollabDocument, listAiModels, liveContent, resolveModel, setEditorPorts, useAiModels, useCollabServer, useEditorPorts } from "./host.js";
+import { PORT_CAPABILITY, serverCapabilities } from "./ports.js";
+export { COLLAB_FIELD, HttpError, PORT_CAPABILITY, closeEditorServer, collabContentChanged, collabStats, createAiModels, createCollabServer, createRateLimiter, decodeCollabState, encodeCollabState, enforceAiRateLimit, forgetCollabDocument, isStateStale, listAiModels, liveContent, resolveModel, serverCapabilities, setEditorPorts, streamChat, streamChatTurn, upstreamError, useAiModels, useCollabServer, useEditorPorts, userKey };

package/dist/server/pdf.js

@@ -0,0 +1,97 @@
+import { HttpError } from "./errors.js";
+//#region src/server/pdf.ts
+const size = (value) => Math.max(1, Math.ceil(value));
+/** The canvas module of `@napi-rs/canvas`, or `null` when the optional dependency is not installed (or its native part does not load). */
+async function loadCanvas() {
+	try {
+		return await import("@napi-rs/canvas");
+	} catch {
+		return null;
+	}
+}
+/** The class `getDocument` takes as `CanvasFactory`: pdfjs creates the canvases of images and patterns through `@napi-rs/canvas`. */
+function canvasFactoryOf(canvasModule) {
+	return class NodeCanvasFactory {
+		create(width, height) {
+			const canvas = canvasModule.createCanvas(size(width), size(height));
+			return {
+				canvas,
+				context: canvas.getContext("2d")
+			};
+		}
+		reset({ canvas }, width, height) {
+			if (!canvas) return;
+			canvas.width = size(width);
+			canvas.height = size(height);
+		}
+		destroy(canvasAndContext) {
+			if (canvasAndContext.canvas) {
+				canvasAndContext.canvas.width = 0;
+				canvasAndContext.canvas.height = 0;
+			}
+			canvasAndContext.canvas = null;
+			canvasAndContext.context = null;
+		}
+	};
+}
+/** Opens `data`; 422 when it is no readable PDF. `data` is copied (pdfjs takes over the buffer it is given). */
+async function openPdf(data) {
+	const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+	const canvasModule = await loadCanvas();
+	const task = pdfjs.getDocument({
+		data: Uint8Array.from(data),
+		useSystemFonts: true,
+		verbosity: 0,
+		...canvasModule && { CanvasFactory: canvasFactoryOf(canvasModule) }
+	});
+	let doc;
+	try {
+		doc = await task.promise;
+	} catch (error) {
+		await task.destroy().catch(() => {});
+		throw new HttpError(422, `PDF nicht lesbar: ${error instanceof Error ? error.message : String(error)}`.slice(0, 300));
+	}
+	return {
+		pageCount: doc.numPages,
+		async pageText(pageNumber) {
+			const page = await doc.getPage(pageNumber);
+			try {
+				const content = await page.getTextContent();
+				let text = "";
+				let baseline = null;
+				for (const item of content.items) {
+					if (!("str" in item)) continue;
+					const y = item.transform[5];
+					if (text && baseline !== null && Math.abs(y - baseline) > 1 && !text.endsWith("\n")) text += "\n";
+					text += item.str;
+					if (item.hasEOL) text += "\n";
+					baseline = y;
+				}
+				return text.trim();
+			} finally {
+				page.cleanup();
+			}
+		},
+		async pagePng(pageNumber, scale) {
+			if (!canvasModule) throw new Error("@napi-rs/canvas fehlt");
+			const page = await doc.getPage(pageNumber);
+			try {
+				const viewport = page.getViewport({ scale });
+				const canvas = canvasModule.createCanvas(size(viewport.width), size(viewport.height));
+				await page.render({
+					canvas,
+					canvasContext: canvas.getContext("2d"),
+					viewport
+				}).promise;
+				return canvas.toBuffer("image/png");
+			} finally {
+				page.cleanup();
+			}
+		},
+		close: () => task.destroy()
+	};
+}
+//#endregion
+export { openPdf };
+
+//# sourceMappingURL=pdf.js.map

package/dist/server/pdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.js","names":[],"sources":["../../src/server/pdf.ts"],"sourcesContent":["import type { Canvas } from '@napi-rs/canvas'\nimport type * as CanvasModule from '@napi-rs/canvas'\nimport type { PDFDocumentProxy } from 'pdfjs-dist/legacy/build/pdf.mjs'\n// pdf.js's render parameters, typed against the DOM canvas (which a server tsconfig without the `dom` lib does not name); not re-exported from the package entry.\nimport type { RenderParameters } from 'pdfjs-dist/types/src/display/api'\nimport { HttpError } from './errors'\n\n// PDF reading for `POST /api/ai/extract`: the text layer per page, and page rasterisation for OCR. `pdfjs-dist` and the\n// optional `@napi-rs/canvas` are imported on first use: a server that never extracts a PDF does not load them, and the\n// canvas package may be absent or fail to load its native part, which a static import could not survive.\n\ntype CanvasApi = typeof CanvasModule\n\nconst size = (value: number) => Math.max(1, Math.ceil(value))\n\n/** An opened PDF: `pageCount` pages, `close` releases the parser. */\nexport interface PdfFile {\n  pageCount: number\n  /** The text layer of page `pageNumber` (1-based): items joined, a newline where a line ends or the baseline moves. */\n  pageText: (pageNumber: number) => Promise<string>\n  /** Page `pageNumber` as PNG at `scale`; throws when no canvas is available or rendering fails. */\n  pagePng: (pageNumber: number, scale: number) => Promise<Uint8Array>\n  close: () => Promise<void>\n}\n\n/** The canvas module of `@napi-rs/canvas`, or `null` when the optional dependency is not installed (or its native part does not load). */\nasync function loadCanvas(): Promise<CanvasApi | null> {\n  try {\n    return await import('@napi-rs/canvas')\n  }\n  catch {\n    return null\n  }\n}\n\n/** The class `getDocument` takes as `CanvasFactory`: pdfjs creates the canvases of images and patterns through `@napi-rs/canvas`. */\nfunction canvasFactoryOf(canvasModule: CanvasApi) {\n  interface CanvasAndContext { canvas: Canvas | null, context: unknown }\n  return class NodeCanvasFactory {\n    create(width: number, height: number): CanvasAndContext {\n      const canvas = canvasModule.createCanvas(size(width), size(height))\n      return { canvas, context: canvas.getContext('2d') }\n    }\n\n    reset({ canvas }: CanvasAndContext, width: number, height: number): void {\n      if (!canvas) return\n      canvas.width = size(width)\n      canvas.height = size(height)\n    }\n\n    destroy(canvasAndContext: CanvasAndContext): void {\n      if (canvasAndContext.canvas) {\n        canvasAndContext.canvas.width = 0\n        canvasAndContext.canvas.height = 0\n      }\n      canvasAndContext.canvas = null\n      canvasAndContext.context = null\n    }\n  }\n}\n\n/** Opens `data`; 422 when it is no readable PDF. `data` is copied (pdfjs takes over the buffer it is given). */\nexport async function openPdf(data: Uint8Array): Promise<PdfFile> {\n  const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs')\n  const canvasModule = await loadCanvas()\n  const task = pdfjs.getDocument({\n    data: Uint8Array.from(data),\n    useSystemFonts: true,\n    verbosity: 0,\n    ...(canvasModule && { CanvasFactory: canvasFactoryOf(canvasModule) }),\n  })\n  let doc: PDFDocumentProxy\n  try {\n    doc = await task.promise\n  }\n  catch (error) {\n    await task.destroy().catch(() => {})\n    throw new HttpError(422, `PDF nicht lesbar: ${error instanceof Error ? error.message : String(error)}`.slice(0, 300))\n  }\n\n  return {\n    pageCount: doc.numPages,\n    async pageText(pageNumber) {\n      const page = await doc.getPage(pageNumber)\n      try {\n        const content = await page.getTextContent()\n        let text = ''\n        let baseline: number | null = null\n        for (const item of content.items) {\n          if (!('str' in item)) continue\n          const y = item.transform[5] as number\n          if (text && baseline !== null && Math.abs(y - baseline) > 1 && !text.endsWith('\\n')) text += '\\n'\n          text += item.str\n          if (item.hasEOL) text += '\\n'\n          baseline = y\n        }\n        return text.trim()\n      }\n      finally {\n        page.cleanup()\n      }\n    },\n    async pagePng(pageNumber, scale) {\n      if (!canvasModule) throw new Error('@napi-rs/canvas fehlt')\n      const page = await doc.getPage(pageNumber)\n      try {\n        const viewport = page.getViewport({ scale })\n        const canvas = canvasModule.createCanvas(size(viewport.width), size(viewport.height))\n        await page.render({\n          canvas: canvas as unknown as RenderParameters['canvas'],\n          canvasContext: canvas.getContext('2d') as unknown as RenderParameters['canvasContext'],\n          viewport,\n        }).promise\n        return canvas.toBuffer('image/png')\n      }\n      finally {\n        page.cleanup()\n      }\n    },\n    close: () => task.destroy(),\n  }\n}\n"],"mappings":";;AAaA,MAAM,QAAQ,UAAkB,KAAK,IAAI,GAAG,KAAK,KAAK,KAAK,CAAC;;AAa5D,eAAe,aAAwC;CACrD,IAAI;EACF,OAAO,MAAM,OAAO;CACtB,QACM;EACJ,OAAO;CACT;AACF;;AAGA,SAAS,gBAAgB,cAAyB;CAEhD,OAAO,MAAM,kBAAkB;EAC7B,OAAO,OAAe,QAAkC;GACtD,MAAM,SAAS,aAAa,aAAa,KAAK,KAAK,GAAG,KAAK,MAAM,CAAC;GAClE,OAAO;IAAE;IAAQ,SAAS,OAAO,WAAW,IAAI;GAAE;EACpD;EAEA,MAAM,EAAE,UAA4B,OAAe,QAAsB;GACvE,IAAI,CAAC,QAAQ;GACb,OAAO,QAAQ,KAAK,KAAK;GACzB,OAAO,SAAS,KAAK,MAAM;EAC7B;EAEA,QAAQ,kBAA0C;GAChD,IAAI,iBAAiB,QAAQ;IAC3B,iBAAiB,OAAO,QAAQ;IAChC,iBAAiB,OAAO,SAAS;GACnC;GACA,iBAAiB,SAAS;GAC1B,iBAAiB,UAAU;EAC7B;CACF;AACF;;AAGA,eAAsB,QAAQ,MAAoC;CAChE,MAAM,QAAQ,MAAM,OAAO;CAC3B,MAAM,eAAe,MAAM,WAAW;CACtC,MAAM,OAAO,MAAM,YAAY;EAC7B,MAAM,WAAW,KAAK,IAAI;EAC1B,gBAAgB;EAChB,WAAW;EACX,GAAI,gBAAgB,EAAE,eAAe,gBAAgB,YAAY,EAAE;CACrE,CAAC;CACD,IAAI;CACJ,IAAI;EACF,MAAM,MAAM,KAAK;CACnB,SACO,OAAO;EACZ,MAAM,KAAK,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC;EACnC,MAAM,IAAI,UAAU,KAAK,qBAAqB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,IAAI,MAAM,GAAG,GAAG,CAAC;CACtH;CAEA,OAAO;EACL,WAAW,IAAI;EACf,MAAM,SAAS,YAAY;GACzB,MAAM,OAAO,MAAM,IAAI,QAAQ,UAAU;GACzC,IAAI;IACF,MAAM,UAAU,MAAM,KAAK,eAAe;IAC1C,IAAI,OAAO;IACX,IAAI,WAA0B;IAC9B,KAAK,MAAM,QAAQ,QAAQ,OAAO;KAChC,IAAI,EAAE,SAAS,OAAO;KACtB,MAAM,IAAI,KAAK,UAAU;KACzB,IAAI,QAAQ,aAAa,QAAQ,KAAK,IAAI,IAAI,QAAQ,IAAI,KAAK,CAAC,KAAK,SAAS,IAAI,GAAG,QAAQ;KAC7F,QAAQ,KAAK;KACb,IAAI,KAAK,QAAQ,QAAQ;KACzB,WAAW;IACb;IACA,OAAO,KAAK,KAAK;GACnB,UACQ;IACN,KAAK,QAAQ;GACf;EACF;EACA,MAAM,QAAQ,YAAY,OAAO;GAC/B,IAAI,CAAC,cAAc,MAAM,IAAI,MAAM,uBAAuB;GAC1D,MAAM,OAAO,MAAM,IAAI,QAAQ,UAAU;GACzC,IAAI;IACF,MAAM,WAAW,KAAK,YAAY,EAAE,MAAM,CAAC;IAC3C,MAAM,SAAS,aAAa,aAAa,KAAK,SAAS,KAAK,GAAG,KAAK,SAAS,MAAM,CAAC;IACpF,MAAM,KAAK,OAAO;KACR;KACR,eAAe,OAAO,WAAW,IAAI;KACrC;IACF,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,SAAS,WAAW;GACpC,UACQ;IACN,KAAK,QAAQ;GACf;EACF;EACA,aAAa,KAAK,QAAQ;CAC5B;AACF"}

package/dist/server/{adapter.d.ts → ports.d.ts}

@@ -1,21 +1,18 @@
-import { EditorSettings } from "../settings/index.js";
 import { AssetRecord } from "../features/media/assets.js";
 import "../features/media/schema.js";
-import { MentionUser } from "../features/mentions/mention.js";
+import { EditorSettings } from "../settings/index.js";
+import { BackendCapability } from "../core/backend-capability.js";
+import { MentionUser, ModelProfile, ModelRef, ThemeRecord } from "../core/backend-types.js";
 import "../features/mentions/schema.js";
-import { ModelProfile, ModelRef } from "../features/ai/protocol/models.js";
+import { AuthenticateRequest } from "./auth.js";
 import "../features/ai/protocol/index.js";
-import { ThemeRecord } from "../features/themes/schema.js";
-import { AnyExtension, JSONContent } from "@tiptap/core";
+import { CommentStore } from "../adapters/comments/types.js";
+import "../features/themes/schema.js";
+import { 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 {
+//#region src/server/ports.d.ts
+/** Who a request or websocket connection belongs to, and which documents that user may open. */
+export interface Identity {
   /**
    * 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
@@ -32,6 +29,13 @@ export interface EditorAdapter {
   authorize?(user: object, id: string): Promise<{
     readOnly: boolean;
   } | null>;
+}
+/** The stored TipTap JSON of the workspace's documents. */
+export interface DocumentStore {
+  /** 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>;
   /**
    * 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
@@ -41,25 +45,37 @@ export interface EditorAdapter {
    * 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;
   }[]>;
+}
+/** Document management a host needs next to the editor's own storage methods: `DocumentStore.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[]>;
+}
+/** Where the collaboration server keeps the Yjs state of open documents. */
+export interface CollabStateStore {
   /** 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>;
+}
+/** The users that can be `@`-mentioned. */
+export interface Directory {
+  /** All users that can be `@`-mentioned (served by `GET /api/editor/users`); must not include credentials. */
+  listUsers(): Promise<MentionUser[]>;
+}
+/** Uploaded files. */
+export interface AssetStore {
   /** 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;
@@ -69,21 +85,30 @@ export interface EditorAdapter {
     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>;
+}
+/** Per-user editor settings. Without this port the client keeps settings in localStorage only. */
+export interface SettingsStore {
+  /** Per-user editor settings as stored (`null` = none yet), validated by `GET /api/editor/settings`. */
+  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[]>;
+  storeSettings(user: object, settings: EditorSettings): Promise<void>;
+}
+/** The theme library shared by all users. Without this port the themes feature is uninstalled: its routes answer 501. */
+export interface ThemeStore {
+  /** All themes (`GET /api/editor/themes`). */
+  listThemes(): Promise<ThemeRecord[]>;
   /** A theme's record and `theme.css` (`GET /api/editor/themes/:id`); `null` = unknown id. */
-  loadTheme?(id: string): Promise<{
+  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>;
+  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>;
+  removeTheme(id: string): Promise<boolean>;
+}
+/** The host's own language models for the AI endpoints; both members fall through to the runtime-config presets. */
+export interface ModelProvider {
   /**
    * 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
@@ -97,5 +122,31 @@ export interface EditorAdapter {
    */
   listModels?(user: object | null): Promise<ModelProfile[] | null>;
 }
+/** Everything the editor's server reads from the host, one port per capability. Only `identity` and `documents` are required. */
+export interface EditorPorts {
+  identity: Identity;
+  documents: DocumentStore & Partial<DocumentAdmin>;
+  /** Required by the collaboration server. */
+  collabState?: CollabStateStore;
+  directory?: Directory;
+  assets?: AssetStore;
+  settings?: SettingsStore;
+  themes?: ThemeStore;
+  models?: ModelProvider;
+  /** Where the comment threads live (`adapters/comments/{json,drizzle}`). */
+  comments?: CommentStore;
+}
+/** The capability each optional port provides; `identity` is no capability, `tags` derive from `documents` (see `serverCapabilities`). */
+export declare const PORT_CAPABILITY: Record<Exclude<keyof EditorPorts, 'identity'>, BackendCapability>;
+/**
+ * The capabilities `ports` serves: those of every present port, plus `tags` (derived from `documents.listContents`).
+ * Two capabilities depend on more than a port: `ai` (the AI routes need configured models) and `collaboration` (the
+ * websocket needs the collab server). `served` states what the installed server really mounts and overrides the port-based
+ * answer for them; omitted keys follow the ports.
+ */
+export declare function serverCapabilities(ports: EditorPorts, served?: {
+  ai?: boolean;
+  collaboration?: boolean;
+}): BackendCapability[];
 //#endregion
-//# sourceMappingURL=adapter.d.ts.map
+//# sourceMappingURL=ports.d.ts.map

package/dist/server/ports.js

@@ -0,0 +1,29 @@
+//#region src/server/ports.ts
+/** The capability each optional port provides; `identity` is no capability, `tags` derive from `documents` (see `serverCapabilities`). */
+const PORT_CAPABILITY = {
+	documents: "documents",
+	collabState: "collaboration",
+	directory: "users",
+	assets: "assets",
+	settings: "settings",
+	themes: "themes",
+	models: "ai",
+	comments: "comments"
+};
+/**
+* The capabilities `ports` serves: those of every present port, plus `tags` (derived from `documents.listContents`).
+* Two capabilities depend on more than a port: `ai` (the AI routes need configured models) and `collaboration` (the
+* websocket needs the collab server). `served` states what the installed server really mounts and overrides the port-based
+* answer for them; omitted keys follow the ports.
+*/
+function serverCapabilities(ports, served = {}) {
+	const capabilities = new Set(Object.keys(PORT_CAPABILITY).filter((port) => ports[port] !== void 0).map((port) => PORT_CAPABILITY[port]));
+	for (const capability of ["ai", "collaboration"]) if (served[capability] === true) capabilities.add(capability);
+	else if (served[capability] === false) capabilities.delete(capability);
+	if (ports.documents) capabilities.add("tags");
+	return [...capabilities];
+}
+//#endregion
+export { PORT_CAPABILITY, serverCapabilities };
+
+//# sourceMappingURL=ports.js.map

package/dist/server/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","names":[],"sources":["../../src/server/ports.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\nimport type { LanguageModel } from 'ai'\nimport type { CommentStore } from '../adapters/comments/types'\nimport type { BackendCapability } from '../core/backend-capability'\nimport type { ModelProfile, ModelRef } from '../features/ai/protocol'\nimport type { AssetRecord } from '../features/media/schema'\nimport type { MentionUser } from '../features/mentions/schema'\nimport type { ThemeRecord } from '../features/themes/schema'\nimport type { EditorSettings } from '../settings'\nimport type { AuthenticateRequest } from './auth'\n\n// The server side of the editor's backend, split by capability: a host (or an adapter) implements the ports it serves\n// and leaves the others out; routes and features that need an absent port answer 501.\n\n/** Who a request or websocket connection belongs to, and which documents that user may open. */\nexport interface Identity {\n  /**\n   * The user behind a request, `null` = not authenticated (HTTP routes answer 401). Collaboration: called in Hocuspocus\n   * `onAuthenticate` with the upgrade request's `headers` and the client's `token` (`undefined` when it sent none, so cookie\n   * hosts keep working and bearer-only hosts read `token`); `null` closes the connection with 4401. With the Nuxt module\n   * option `collab.authenticateUpgrade` it runs once at the upgrade with the `headers` only and `null` refuses the upgrade\n   * with HTTP 401. The value becomes the connection context's `user`.\n   */\n  authenticate(request: AuthenticateRequest): Promise<object | null>\n  /**\n   * Per-document access for the collaboration websocket, called in Hocuspocus `onAuthenticate` (right after `authenticate`) with the user.\n   * `null` rejects the connection; `{ readOnly: true }` lets it sync but applies none of its edits. Omit it to let every\n   * authenticated user edit every document.\n   */\n  authorize?(user: object, id: string): Promise<{ readOnly: boolean } | null>\n}\n\n/** The stored TipTap JSON of the workspace's documents. */\nexport interface DocumentStore {\n  /** TipTap JSON to seed a document's Y.Doc from; `null` = the document does not exist. */\n  loadContent(id: string): Promise<JSONContent | null>\n  /** Mirror of the current Yjs state, called debounced after edits and on shutdown. Must tolerate ids deleted meanwhile. */\n  storeContent(id: string, content: JSONContent): Promise<void>\n  /**\n   * Opaque version of the stored content of a document (mtime, hash, revision), `null` = unknown, no NUL. The collab server\n   * keeps it next to the Yjs state. When it differs from the live version (the content changed behind the editor's back) the\n   * state is discarded on load, removed through `removeState` and the document is re-seeded from `loadContent`. A document\n   * that is open when its version moves is not written back: the next store merges the new `loadContent` into the open\n   * Y.Doc. The version is read right after every `storeContent`, so it must reflect what the editor itself just wrote.\n   * Omit it to never discard state.\n   */\n  contentVersion?(id: string): Promise<string | null>\n  /** Stored TipTap JSON of every document in the workspace, e.g. to collect the `#` tags in use (`GET /api/editor/tags`). */\n  listContents(): Promise<{ id: string, content: JSONContent }[]>\n}\n\n/** Document management a host needs next to the editor's own storage methods: `DocumentStore.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/** Where the collaboration server keeps the Yjs state of open documents. */\nexport interface CollabStateStore {\n  /** 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`). */\n  loadState(id: string): Promise<Uint8Array | null>\n  /** Persists the state bytes unchanged; called on every store and when block IDs were backfilled. Must tolerate ids deleted meanwhile. */\n  storeState(id: string, state: Uint8Array): Promise<void>\n  /** Drops the Yjs state of a deleted document (the next load re-seeds from `loadContent`). */\n  removeState(id: string): Promise<void>\n}\n\n/** The users that can be `@`-mentioned. */\nexport interface Directory {\n  /** All users that can be `@`-mentioned (served by `GET /api/editor/users`); must not include credentials. */\n  listUsers(): Promise<MentionUser[]>\n}\n\n/** Uploaded files. */\nexport interface AssetStore {\n  /** 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. */\n  storeAsset(id: string, asset: AssetRecord & { data: Buffer }): Promise<void>\n  /** A stored file with its record; `null` = unknown id or name. */\n  loadAsset(id: string, name: string): Promise<{ record: AssetRecord, data: Buffer } | null>\n}\n\n/** Per-user editor settings. Without this port the client keeps settings in localStorage only. */\nexport interface SettingsStore {\n  /** Per-user editor settings as stored (`null` = none yet), validated by `GET /api/editor/settings`. */\n  loadSettings(user: object): Promise<unknown | null>\n  /** Stores validated settings for the user from `authenticate`. */\n  storeSettings(user: object, settings: EditorSettings): Promise<void>\n}\n\n/** The theme library shared by all users. Without this port the themes feature is uninstalled: its routes answer 501. */\nexport interface ThemeStore {\n  /** All themes (`GET /api/editor/themes`). */\n  listThemes(): Promise<ThemeRecord[]>\n  /** A theme's record and `theme.css` (`GET /api/editor/themes/:id`); `null` = unknown id. */\n  loadTheme(id: string): Promise<{ record: ThemeRecord, css: string } | null>\n  /** Stores an uploaded theme (`POST /api/editor/themes`). */\n  storeTheme(record: Omit<ThemeRecord, 'builtin'>, css: string): Promise<void>\n  /** Deletes an uploaded theme (`DELETE /api/editor/themes/:id`); `false` = not found or builtin. */\n  removeTheme(id: string): Promise<boolean>\n}\n\n/** The host's own language models for the AI endpoints; both members fall through to the runtime-config presets. */\nexport interface ModelProvider {\n  /**\n   * The language model for `ref`, so the AI endpoints use the host's own providers; consulted before the runtime-config\n   * presets for every model reference. `user` is what `authenticate` returned. `null` falls through to the presets\n   * (and answers 400 for a preset that is not configured either).\n   */\n  languageModel?(ref: ModelRef, user: object | null): Promise<LanguageModel | null>\n  /**\n   * The models `GET /api/ai/models` lists for `user`, instead of the runtime-config presets (list them with\n   * `source: 'preset'` and the `id` that `languageModel` receives as `{ preset: id }`). `null` (or omitting the method)\n   * lists the presets.\n   */\n  listModels?(user: object | null): Promise<ModelProfile[] | null>\n}\n\n/** Everything the editor's server reads from the host, one port per capability. Only `identity` and `documents` are required. */\nexport interface EditorPorts {\n  identity: Identity\n  documents: DocumentStore & Partial<DocumentAdmin>\n  /** Required by the collaboration server. */\n  collabState?: CollabStateStore\n  directory?: Directory\n  assets?: AssetStore\n  settings?: SettingsStore\n  themes?: ThemeStore\n  models?: ModelProvider\n  /** Where the comment threads live (`adapters/comments/{json,drizzle}`). */\n  comments?: CommentStore\n}\n\n/** The capability each optional port provides; `identity` is no capability, `tags` derive from `documents` (see `serverCapabilities`). */\nexport const PORT_CAPABILITY: Record<Exclude<keyof EditorPorts, 'identity'>, BackendCapability> = {\n  documents: 'documents',\n  collabState: 'collaboration',\n  directory: 'users',\n  assets: 'assets',\n  settings: 'settings',\n  themes: 'themes',\n  models: 'ai',\n  comments: 'comments',\n}\n\n/**\n * The capabilities `ports` serves: those of every present port, plus `tags` (derived from `documents.listContents`).\n * Two capabilities depend on more than a port: `ai` (the AI routes need configured models) and `collaboration` (the\n * websocket needs the collab server). `served` states what the installed server really mounts and overrides the port-based\n * answer for them; omitted keys follow the ports.\n */\nexport function serverCapabilities(ports: EditorPorts, served: { ai?: boolean, collaboration?: boolean } = {}): BackendCapability[] {\n  const capabilities = new Set<BackendCapability>(\n    (Object.keys(PORT_CAPABILITY) as (keyof typeof PORT_CAPABILITY)[])\n      .filter(port => ports[port] !== undefined)\n      .map(port => PORT_CAPABILITY[port]),\n  )\n  for (const capability of ['ai', 'collaboration'] as const) {\n    if (served[capability] === true) capabilities.add(capability)\n    else if (served[capability] === false) capabilities.delete(capability)\n  }\n  if (ports.documents) capabilities.add('tags')\n  return [...capabilities]\n}\n"],"mappings":";;AAyIA,MAAa,kBAAqF;CAChG,WAAW;CACX,aAAa;CACb,WAAW;CACX,QAAQ;CACR,UAAU;CACV,QAAQ;CACR,QAAQ;CACR,UAAU;AACZ;;;;;;;AAQA,SAAgB,mBAAmB,OAAoB,SAAoD,CAAC,GAAwB;CAClI,MAAM,eAAe,IAAI,IACtB,OAAO,KAAK,eAAe,CAAC,CAC1B,QAAO,SAAQ,MAAM,UAAU,KAAA,CAAS,CAAC,CACzC,KAAI,SAAQ,gBAAgB,KAAK,CACtC;CACA,KAAK,MAAM,cAAc,CAAC,MAAM,eAAe,GAC7C,IAAI,OAAO,gBAAgB,MAAM,aAAa,IAAI,UAAU;MACvD,IAAI,OAAO,gBAAgB,OAAO,aAAa,OAAO,UAAU;CAEvE,IAAI,MAAM,WAAW,aAAa,IAAI,MAAM;CAC5C,OAAO,CAAC,GAAG,YAAY;AACzB"}