@ecsplico/editor 2.1.2 → 3.1.0

package/dist/adapters/nitro.d.ts

@@ -1,10 +1,10 @@
-import { EditorAdapter } from "../server/adapter.js";
 import { AiModels, AiModelsConfig } from "../server/ai.js";
+import { EditorPorts } from "../server/ports.js";
 import { CollabServer, CollabServerOptions } from "../server/collab.js";
 import { RateLimiterOptions } from "../server/rate-limit.js";
 import "../server/index.js";
-import { DocumentAdmin } from "./shared.js";
-import { CommentStore } from "./comments/types.js";
+import { RouteDef } from "../server/routes.js";
+import { AnyExtension } from "@tiptap/core";
 import { Router } from "h3";
 //#region src/adapters/nitro.d.ts
 /** The part of a Nitro app this entry uses; `nitroApp` of a Nitro plugin fits. */
@@ -15,28 +15,33 @@ export interface NitroHost {
   };
 }
 export interface EditorServerOptions {
-  /** Storage and identity. An adapter that also manages documents (`json`, `drizzle`) lets `PUT /api/editor/documents/:id` create them. */
-  adapter: EditorAdapter & Partial<DocumentAdmin>;
+  /** Identity, storage and everything else the backend serves, one port per capability: a route is mounted only when its port is present. A documents port that also manages documents (`json`, `drizzle`) lets `PUT /api/editor/documents/:id` create them; the `comments` port mounts the comments endpoint, `models` the host's language models. */
+  ports: EditorPorts;
   /**
-   * The collaboration websocket (`/collab/:id`). Extensions, hooks and Hocuspocus configuration of `createCollabServer`;
-   * `{}` takes everything from the adapter. `false` mounts no websocket (documents then only load and save over HTTP).
+   * The collaboration websocket (`/collab/:id`). Schema, hooks and Hocuspocus configuration of `createCollabServer`;
+   * `{}` takes everything from the ports (the `collabState` port is required). `false` mounts no websocket (documents then only load and save over HTTP).
+   * `authenticateUpgrade`: authenticate the upgrade request itself (`Identity.authenticate` with its headers; cookies,
+   * not the provider's `token`) and refuse it with HTTP 401, instead of closing an unauthenticated socket with 4401
+   * after the upgrade; the user then travels with the connection and is not authenticated a second time.
    * Needs `experimental: { websocket: true }` in the Nitro config.
    */
-  collab: Omit<CollabServerOptions, 'adapter'> | false;
+  collab: (Omit<CollabServerOptions, 'ports'> & {
+    authenticateUpgrade?: boolean;
+  }) | false;
   /**
    * Mounts the AI endpoints (`/api/ai/*`): presets, shared key, transcription, slots of `createAiModels`; `languageModel`
-   * and `listModels` default to the adapter's. Omitted: no AI routes.
+   * and `listModels` default to those of the `models` port. Omitted: no AI routes.
    */
   ai?: Partial<AiModelsConfig>;
-  /** Per-user limit of the AI endpoints; default 30 requests per minute. */
+  /** Per-user limit of the AI endpoints; default: that of `defineEditorConfig` (30 requests per minute). */
   rateLimit?: RateLimiterOptions;
-  /** Mounts the comments endpoint (`/api/editor/comments/:id`) over this store; omitted: no comments routes. */
-  comments?: {
-    store: CommentStore;
-  };
+  /** Filters or reorders the routes before they are mounted (a host that serves `/api/editor/assets/*` itself drops them); default: all. Receives what `serverRoutesOf(ports, { ai })` returns, so a route of an absent port, or an AI route without the `ai` option, is not in it. */
+  routes?: (routes: readonly RouteDef[]) => readonly RouteDef[];
+  /** The collaboration schema (see `CollabServerOptions.schema`); default `advancedSchemaExtensions()`, host nodes: `() => [...advancedSchemaExtensions(), Callout]`. */
+  schema?: () => AnyExtension[];
 }
 export interface EditorServer {
-  adapter: EditorServerOptions['adapter'];
+  ports: EditorPorts;
   /** The collaboration server, `undefined` with `collab: false`. */
   collab: CollabServer | undefined;
   /** The AI models, `undefined` without `ai`. */
@@ -47,15 +52,17 @@ export interface EditorServer {
 /**
  * Wires the editor backend into `nitroApp` (call it from a Nitro plugin):
  *
- *     /api/editor/{settings,users,tags,assets/…,themes/…}   the editor's own endpoints
+ *     /api/editor/{capabilities,settings,users,tags,assets/…,themes/…}   the editor's own endpoints, each with its port; `capabilities` lists what is served
  *     /api/editor/documents/:id                              GET/PUT a document's TipTap JSON (what `useEditorDocument` uses)
- *     /api/editor/comments/:id                               GET/POST comments, with `comments`
- *     /api/ai/{models,chat,complete,generate,transcribe,transcript-cleanup}   with `ai`
+ *     /api/editor/comments/:id                               GET/POST comments, with `ports.comments`
+ *     /api/ai/{models,chat,complete,generate,extract,transcript-cleanup}   with `ai`
  *     /collab/:id                                            the collaboration websocket, unless `collab: false`
  *
- * Every route authenticates through `adapter.authenticate`. The collaboration server is closed with Nitro's `close`
- * hook. The paths are the ones `@ecsplico/editor/nuxt` serves, so the editor's client works unchanged.
+ * Every route authenticates through `ports.identity.authenticate`. The collaboration server is closed with Nitro's `close`
+ * hook. The installed server is also the process-wide one of `@ecsplico/editor/server` (`useCollabServer`, `useAiModels`,
+ * `liveContent`, …) until it closes. The paths are the ones the editor's client (`createHttpBackend`) calls.
  */
 export declare function installEditorServer(nitroApp: NitroHost, options: EditorServerOptions): EditorServer;
 //#endregion
+export type { RouteDef };
 //# sourceMappingURL=nitro.d.ts.map

package/dist/adapters/nitro.js

@@ -1,135 +1,26 @@
-import { HttpError } from "../server/errors.js";
+import { COLLAB_PATH } from "../core/api-routes.js";
 import { createAiModels } from "../server/ai.js";
 import { createCollabServer } from "../server/collab.js";
 import { createRateLimiter } from "../server/rate-limit.js";
-import { chatPost, completePost, generatePost, modelsGet, transcribePost, transcriptCleanupPost } from "../server/handlers/ai.js";
-import { assetGet, assetPost, settingsGet, settingsPut, tagsGet, themeDelete, themeGet, themePost, themesGet, usersGet } from "../server/handlers/editor.js";
-import { AI_API, COLLAB_PATH, COMMENTS_ROUTE, DOCUMENT_ROUTE, EDITOR_API } from "./routes.js";
-import { commentsGet, commentsPost, documentGet, documentPut } from "./documents.js";
-import { createError, defineEventHandler, defineWebSocketHandler, getQuery, getRouterParams, readBody, readFormData, setResponseHeaders, setResponseStatus } from "h3";
+import { adoptEditorServer } from "../server/host.js";
+import { defineEditorConfig } from "../config/index.js";
+import { routeOf } from "../server/h3.js";
+import { serverRoutesOf } from "../server/routes.js";
+import { defineWebSocketHandler } from "h3";
 //#region src/adapters/nitro.ts
-const API = EDITOR_API;
-/** The `HandlerRequest` of a Nitro event. `signal` aborts when the client goes away. */
-function requestOf(event) {
-	const abort = new AbortController();
-	event.node.res.once("close", () => abort.abort());
-	return {
-		headers: event.headers,
-		params: getRouterParams(event, { decode: true }),
-		query: Object.fromEntries(Object.entries(getQuery(event)).map(([key, value]) => [key, value === void 0 ? void 0 : String(value)])),
-		readJson: () => readBody(event),
-		readForm: () => readFormData(event),
-		signal: abort.signal
-	};
-}
-/** An event handler that runs `handler` with `ctx` and sends its `HandlerResponse`; an `HttpError` becomes Nitro's error response. */
-function routeOf(ctx, handler) {
-	return defineEventHandler(async (event) => {
-		let response;
-		try {
-			response = await handler(ctx, requestOf(event));
-		} catch (error) {
-			if (!(error instanceof HttpError)) throw error;
-			setResponseHeaders(event, error.headers);
-			throw createError({
-				statusCode: error.statusCode,
-				statusMessage: error.statusMessage,
-				message: error.statusMessage,
-				data: error.data
-			});
-		}
-		setResponseStatus(event, response.status);
-		setResponseHeaders(event, response.headers);
-		return response.body;
-	});
-}
-const editorRoutes = [
-	[
-		"get",
-		`${API}/settings`,
-		settingsGet
-	],
-	[
-		"put",
-		`${API}/settings`,
-		settingsPut
-	],
-	[
-		"get",
-		`${API}/users`,
-		usersGet
-	],
-	[
-		"get",
-		`${API}/tags`,
-		tagsGet
-	],
-	[
-		"post",
-		`${API}/assets/:id`,
-		assetPost
-	],
-	[
-		"get",
-		`${API}/assets/:id/:name`,
-		assetGet
-	],
-	[
-		"get",
-		`${API}/themes`,
-		themesGet
-	],
-	[
-		"post",
-		`${API}/themes`,
-		themePost
-	],
-	[
-		"get",
-		`${API}/themes/:id`,
-		themeGet
-	],
-	[
-		"delete",
-		`${API}/themes/:id`,
-		themeDelete
-	]
-];
-const aiRoutes = [
-	[
-		"get",
-		`${AI_API}/models`,
-		modelsGet
-	],
-	[
-		"post",
-		`${AI_API}/chat`,
-		chatPost
-	],
-	[
-		"post",
-		`${AI_API}/complete`,
-		completePost
-	],
-	[
-		"post",
-		`${AI_API}/generate`,
-		generatePost
-	],
-	[
-		"post",
-		`${AI_API}/transcribe`,
-		transcribePost
-	],
-	[
-		"post",
-		`${AI_API}/transcript-cleanup`,
-		transcriptCleanupPost
-	]
-];
-const collabRoute = (collab) => defineWebSocketHandler({
+const collabRoute = (collab, ports, authenticateUpgrade) => defineWebSocketHandler({
+	async upgrade(request) {
+		if (!authenticateUpgrade) return;
+		const user = await ports.identity.authenticate({ headers: request.headers });
+		if (!user) return new Response(null, {
+			status: 401,
+			statusText: "Unauthorized"
+		});
+		request.context.user = user;
+	},
 	open(peer) {
-		peer._hocuspocus = collab.handleConnection(peer.websocket, peer.request);
+		const user = peer.context.user;
+		peer._hocuspocus = collab.handleConnection(peer.websocket, peer.request, user && { user });
 	},
 	message(peer, message) {
 		peer._hocuspocus?.handleMessage(message.uint8Array());
@@ -147,60 +38,65 @@ const collabRoute = (collab) => defineWebSocketHandler({
 /**
 * Wires the editor backend into `nitroApp` (call it from a Nitro plugin):
 *
-*     /api/editor/{settings,users,tags,assets/…,themes/…}   the editor's own endpoints
+*     /api/editor/{capabilities,settings,users,tags,assets/…,themes/…}   the editor's own endpoints, each with its port; `capabilities` lists what is served
 *     /api/editor/documents/:id                              GET/PUT a document's TipTap JSON (what `useEditorDocument` uses)
-*     /api/editor/comments/:id                               GET/POST comments, with `comments`
-*     /api/ai/{models,chat,complete,generate,transcribe,transcript-cleanup}   with `ai`
+*     /api/editor/comments/:id                               GET/POST comments, with `ports.comments`
+*     /api/ai/{models,chat,complete,generate,extract,transcript-cleanup}   with `ai`
 *     /collab/:id                                            the collaboration websocket, unless `collab: false`
 *
-* Every route authenticates through `adapter.authenticate`. The collaboration server is closed with Nitro's `close`
-* hook. The paths are the ones `@ecsplico/editor/nuxt` serves, so the editor's client works unchanged.
+* Every route authenticates through `ports.identity.authenticate`. The collaboration server is closed with Nitro's `close`
+* hook. The installed server is also the process-wide one of `@ecsplico/editor/server` (`useCollabServer`, `useAiModels`,
+* `liveContent`, …) until it closes. The paths are the ones the editor's client (`createHttpBackend`) calls.
 */
 function installEditorServer(nitroApp, options) {
-	const { adapter } = options;
+	const { ports, schema } = options;
+	const { authenticateUpgrade = false, ...collabOptions } = options.collab || {};
 	const collab = options.collab === false ? void 0 : createCollabServer({
-		adapter,
-		...options.collab
+		ports,
+		...schema && { schema },
+		...collabOptions
 	});
+	const provider = ports.models;
 	const models = options.ai && createAiModels({
 		presets: {},
-		languageModel: adapter.languageModel && ((ref, user) => adapter.languageModel(ref, user)),
-		listModels: adapter.listModels && ((user) => adapter.listModels(user)),
+		languageModel: provider?.languageModel && ((ref, user) => provider.languageModel(ref, user)),
+		listModels: provider?.listModels && ((user) => provider.listModels(user)),
 		...options.ai
 	});
+	const limiter = models && createRateLimiter(options.rateLimit ?? defineEditorConfig().ai.rateLimit);
 	const context = {
-		adapter,
-		...collab && { collab }
+		ports,
+		...collab && { collab },
+		served: {
+			ai: models !== void 0,
+			collaboration: collab !== void 0
+		}
 	};
-	for (const [method, path, handler] of editorRoutes) nitroApp.router.add(path, routeOf(context, handler), method);
-	nitroApp.router.add(DOCUMENT_ROUTE, routeOf(context, documentGet), "get");
-	nitroApp.router.add(DOCUMENT_ROUTE, routeOf(context, documentPut), "put");
-	if (options.comments) {
-		const comments = {
-			...context,
-			store: options.comments.store
-		};
-		nitroApp.router.add(COMMENTS_ROUTE, routeOf(comments, commentsGet), "get");
-		nitroApp.router.add(COMMENTS_ROUTE, routeOf(comments, commentsPost), "post");
-	}
-	if (models) {
-		const ai = {
-			...context,
-			ai: models,
-			limiter: createRateLimiter(options.rateLimit ?? {
-				max: 30,
-				windowMs: 6e4
-			})
-		};
-		for (const [method, path, handler] of aiRoutes) nitroApp.router.add(path, routeOf(ai, handler), method);
+	const aiContext = models && limiter && {
+		...context,
+		ai: models,
+		limiter
+	};
+	const mounted = serverRoutesOf(ports, { ai: aiContext !== void 0 });
+	for (const route of options.routes ? options.routes(mounted) : mounted) {
+		const handler = route.port === "ai" ? routeOf(aiContext, route.handler) : routeOf(context, route.handler);
+		nitroApp.router.add(route.path, handler, route.method);
 	}
-	if (collab) nitroApp.router.use(`${COLLAB_PATH}/:id`, collabRoute(collab));
+	if (collab) nitroApp.router.use(`${COLLAB_PATH}/:id`, collabRoute(collab, ports, authenticateUpgrade));
+	const release = adoptEditorServer({
+		ports,
+		schema,
+		collab,
+		models,
+		limiter
+	});
 	const server = {
-		adapter,
+		ports,
 		collab,
 		models,
-		close: async () => {
+		async close() {
 			await collab?.close();
+			release();
 		}
 	};
 	nitroApp.hooks.hook("close", () => server.close());

package/dist/adapters/nitro.js.map

@@ -1 +1 @@
-{"version":3,"file":"nitro.js","names":[],"sources":["../../src/adapters/nitro.ts"],"sourcesContent":["import { type AiModels, type AiModelsConfig, type CollabConnection, type CollabServer, type CollabServerOptions, createAiModels, createCollabServer, createRateLimiter, type EditorAdapter, HttpError, type RateLimiterOptions } from '../server'\nimport {\n  type AiHandlerContext,\n  assetGet,\n  assetPost,\n  chatPost,\n  completePost,\n  generatePost,\n  type HandlerContext,\n  type HandlerRequest,\n  type HandlerResponse,\n  modelsGet,\n  settingsGet,\n  settingsPut,\n  tagsGet,\n  themeDelete,\n  themeGet,\n  themePost,\n  themesGet,\n  transcribePost,\n  transcriptCleanupPost,\n  usersGet,\n} from '../server/handlers'\nimport { createError, defineEventHandler, defineWebSocketHandler, getQuery, getRouterParams, type H3Event, readBody, readFormData, type Router, setResponseHeaders, setResponseStatus } from 'h3'\nimport type { DocumentAdmin } from './shared'\nimport type { CommentStore } from './comments/types'\nimport { AI_API, COLLAB_PATH, COMMENTS_ROUTE, DOCUMENT_ROUTE, EDITOR_API } from './routes'\nimport { commentsGet, type CommentsRouteContext, commentsPost, type DocumentsContext, documentGet, documentPut } from './documents'\n\n// The editor backend on a plain Nitro app (nitropack 2, no Nuxt module): the framework's own routes (settings, users,\n// tags, assets, themes, the optional AI endpoints), the collaboration websocket and this package's document and comments\n// routes, registered in one call from a Nitro plugin. It is the explicit-wiring twin of `@ecsplico/editor/nuxt`, which\n// registers the same routes by scanning files; both end in the same `@ecsplico/editor/server/handlers`.\n\n/** The part of a Nitro app this entry uses; `nitroApp` of a Nitro plugin fits. */\nexport interface NitroHost {\n  router: Pick<Router, 'add' | 'use'>\n  hooks: { hook(name: 'close', listener: () => void | Promise<void>): unknown }\n}\n\nexport interface EditorServerOptions {\n  /** Storage and identity. An adapter that also manages documents (`json`, `drizzle`) lets `PUT /api/editor/documents/:id` create them. */\n  adapter: EditorAdapter & Partial<DocumentAdmin>\n  /**\n   * The collaboration websocket (`/collab/:id`). Extensions, hooks and Hocuspocus configuration of `createCollabServer`;\n   * `{}` takes everything from the adapter. `false` mounts no websocket (documents then only load and save over HTTP).\n   * Needs `experimental: { websocket: true }` in the Nitro config.\n   */\n  collab: Omit<CollabServerOptions, 'adapter'> | false\n  /**\n   * Mounts the AI endpoints (`/api/ai/*`): presets, shared key, transcription, slots of `createAiModels`; `languageModel`\n   * and `listModels` default to the adapter's. Omitted: no AI routes.\n   */\n  ai?: Partial<AiModelsConfig>\n  /** Per-user limit of the AI endpoints; default 30 requests per minute. */\n  rateLimit?: RateLimiterOptions\n  /** Mounts the comments endpoint (`/api/editor/comments/:id`) over this store; omitted: no comments routes. */\n  comments?: { store: CommentStore }\n}\n\nexport interface EditorServer {\n  adapter: EditorServerOptions['adapter']\n  /** The collaboration server, `undefined` with `collab: false`. */\n  collab: CollabServer | undefined\n  /** The AI models, `undefined` without `ai`. */\n  models: AiModels | undefined\n  /** Writes pending collaboration stores and disconnects every client. Nitro's `close` hook calls it. */\n  close(): Promise<void>\n}\n\ntype Method = 'get' | 'post' | 'put' | 'delete'\ntype Handler<C> = (ctx: C, request: HandlerRequest) => Promise<HandlerResponse>\n\nconst API = EDITOR_API\n\n/** The `HandlerRequest` of a Nitro event. `signal` aborts when the client goes away. */\nfunction requestOf(event: H3Event): HandlerRequest {\n  const abort = new AbortController()\n  event.node.res.once('close', () => abort.abort())\n  return {\n    headers: event.headers,\n    params: getRouterParams(event, { decode: true }),\n    query: Object.fromEntries(Object.entries(getQuery(event)).map(([key, value]) => [key, value === undefined ? undefined : String(value)])),\n    readJson: () => readBody(event),\n    readForm: () => readFormData(event),\n    signal: abort.signal,\n  }\n}\n\n/** An event handler that runs `handler` with `ctx` and sends its `HandlerResponse`; an `HttpError` becomes Nitro's error response. */\nfunction routeOf<C>(ctx: C, handler: Handler<C>) {\n  return defineEventHandler(async (event) => {\n    let response: HandlerResponse\n    try {\n      response = await handler(ctx, requestOf(event))\n    }\n    catch (error) {\n      if (!(error instanceof HttpError)) throw error\n      setResponseHeaders(event, error.headers)\n      throw createError({ statusCode: error.statusCode, statusMessage: error.statusMessage, message: error.statusMessage, data: error.data })\n    }\n    setResponseStatus(event, response.status)\n    setResponseHeaders(event, response.headers)\n    // `null` ends the response without a body and keeps the status set above.\n    return response.body\n  })\n}\n\nconst editorRoutes: [Method, string, Handler<HandlerContext>][] = [\n  ['get', `${API}/settings`, settingsGet],\n  ['put', `${API}/settings`, settingsPut],\n  ['get', `${API}/users`, usersGet],\n  ['get', `${API}/tags`, tagsGet],\n  ['post', `${API}/assets/:id`, assetPost],\n  ['get', `${API}/assets/:id/:name`, assetGet],\n  ['get', `${API}/themes`, themesGet],\n  ['post', `${API}/themes`, themePost],\n  ['get', `${API}/themes/:id`, themeGet],\n  ['delete', `${API}/themes/:id`, themeDelete],\n]\n\nconst aiRoutes: [Method, string, Handler<AiHandlerContext>][] = [\n  ['get', `${AI_API}/models`, modelsGet],\n  ['post', `${AI_API}/chat`, chatPost],\n  ['post', `${AI_API}/complete`, completePost],\n  ['post', `${AI_API}/generate`, generatePost],\n  ['post', `${AI_API}/transcribe`, transcribePost],\n  ['post', `${AI_API}/transcript-cleanup`, transcriptCleanupPost],\n]\n\ntype CollabPeer = { _hocuspocus?: CollabConnection }\n\nconst collabRoute = (collab: CollabServer) => defineWebSocketHandler({\n  open(peer) {\n    ;(peer as unknown as CollabPeer)._hocuspocus = collab.handleConnection(peer.websocket as unknown as Parameters<CollabServer['handleConnection']>[0], peer.request as Request)\n  },\n  message(peer, message) {\n    ;(peer as unknown as CollabPeer)._hocuspocus?.handleMessage(message.uint8Array())\n  },\n  close(peer, details) {\n    ;(peer as unknown as CollabPeer)._hocuspocus?.handleClose({ code: details.code ?? 1000, reason: details.reason ?? '' } as CloseEvent)\n  },\n  error(peer, error) {\n    console.error('[collab]', peer.id, error)\n  },\n})\n\n/**\n * Wires the editor backend into `nitroApp` (call it from a Nitro plugin):\n *\n *     /api/editor/{settings,users,tags,assets/…,themes/…}   the editor's own endpoints\n *     /api/editor/documents/:id                              GET/PUT a document's TipTap JSON (what `useEditorDocument` uses)\n *     /api/editor/comments/:id                               GET/POST comments, with `comments`\n *     /api/ai/{models,chat,complete,generate,transcribe,transcript-cleanup}   with `ai`\n *     /collab/:id                                            the collaboration websocket, unless `collab: false`\n *\n * Every route authenticates through `adapter.authenticate`. The collaboration server is closed with Nitro's `close`\n * hook. The paths are the ones `@ecsplico/editor/nuxt` serves, so the editor's client works unchanged.\n */\nexport function installEditorServer(nitroApp: NitroHost, options: EditorServerOptions): EditorServer {\n  const { adapter } = options\n  const collab = options.collab === false ? undefined : createCollabServer({ adapter, ...options.collab })\n  const models = options.ai && createAiModels({\n    presets: {},\n    languageModel: adapter.languageModel && ((ref, user) => adapter.languageModel!(ref, user)),\n    listModels: adapter.listModels && (user => adapter.listModels!(user)),\n    ...options.ai,\n  })\n\n  const context: DocumentsContext = { adapter, ...(collab && { collab }) }\n  for (const [method, path, handler] of editorRoutes) nitroApp.router.add(path, routeOf<HandlerContext>(context, handler), method)\n  nitroApp.router.add(DOCUMENT_ROUTE, routeOf(context, documentGet), 'get')\n  nitroApp.router.add(DOCUMENT_ROUTE, routeOf(context, documentPut), 'put')\n\n  if (options.comments) {\n    const comments: CommentsRouteContext = { ...context, store: options.comments.store }\n    nitroApp.router.add(COMMENTS_ROUTE, routeOf(comments, commentsGet), 'get')\n    nitroApp.router.add(COMMENTS_ROUTE, routeOf(comments, commentsPost), 'post')\n  }\n  if (models) {\n    const ai: AiHandlerContext = { ...context, ai: models, limiter: createRateLimiter(options.rateLimit ?? { max: 30, windowMs: 60_000 }) }\n    for (const [method, path, handler] of aiRoutes) nitroApp.router.add(path, routeOf(ai, handler), method)\n  }\n  // No method: the websocket upgrade resolves its handler by path only.\n  if (collab) nitroApp.router.use(`${COLLAB_PATH}/:id`, collabRoute(collab))\n\n  const server: EditorServer = { adapter, collab, models, close: async () => { await collab?.close() } }\n  nitroApp.hooks.hook('close', () => server.close())\n  return server\n}\n"],"mappings":"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"}
+{"version":3,"file":"nitro.js","names":[],"sources":["../../src/adapters/nitro.ts"],"sourcesContent":["import type { AnyExtension } from '@tiptap/core'\nimport { type AiModels, type AiModelsConfig, type CollabConnection, type CollabServer, type CollabServerOptions, createAiModels, createCollabServer, createRateLimiter, type EditorPorts, type RateLimiter, type RateLimiterOptions } from '../server'\nimport { defineEditorConfig } from '../config'\nimport { routeOf } from '../server/h3'\nimport type { AiHandlerContext, HandlerContext } from '../server/handlers'\nimport { adoptEditorServer } from '../server/host'\nimport { type RouteDef, serverRoutesOf } from '../server/routes'\nimport { defineWebSocketHandler, type Router } from 'h3'\nimport { COLLAB_PATH } from '../core/api-routes'\n\n// The editor backend on a Nitro app: the routes the ports can serve (`serverRoutesOf`: settings, users, tags, assets,\n// themes, documents, comments, the optional AI endpoints) and the collaboration websocket, registered in one call from a\n// Nitro plugin. One installer serves both hosts: a plain Nitro app (nitropack 2) calls it from its own plugin, the\n// Nuxt module (`@ecsplico/editor/nuxt`) from its server plugin. Both end in the same `@ecsplico/editor/server/handlers`.\n\n/** The part of a Nitro app this entry uses; `nitroApp` of a Nitro plugin fits. */\nexport interface NitroHost {\n  router: Pick<Router, 'add' | 'use'>\n  hooks: { hook(name: 'close', listener: () => void | Promise<void>): unknown }\n}\n\n/** The route type of the table `EditorServerOptions.routes` filters. */\nexport type { RouteDef }\n\nexport interface EditorServerOptions {\n  /** Identity, storage and everything else the backend serves, one port per capability: a route is mounted only when its port is present. A documents port that also manages documents (`json`, `drizzle`) lets `PUT /api/editor/documents/:id` create them; the `comments` port mounts the comments endpoint, `models` the host's language models. */\n  ports: EditorPorts\n  /**\n   * The collaboration websocket (`/collab/:id`). Schema, hooks and Hocuspocus configuration of `createCollabServer`;\n   * `{}` takes everything from the ports (the `collabState` port is required). `false` mounts no websocket (documents then only load and save over HTTP).\n   * `authenticateUpgrade`: authenticate the upgrade request itself (`Identity.authenticate` with its headers; cookies,\n   * not the provider's `token`) and refuse it with HTTP 401, instead of closing an unauthenticated socket with 4401\n   * after the upgrade; the user then travels with the connection and is not authenticated a second time.\n   * Needs `experimental: { websocket: true }` in the Nitro config.\n   */\n  collab: (Omit<CollabServerOptions, 'ports'> & { authenticateUpgrade?: boolean }) | false\n  /**\n   * Mounts the AI endpoints (`/api/ai/*`): presets, shared key, transcription, slots of `createAiModels`; `languageModel`\n   * and `listModels` default to those of the `models` port. Omitted: no AI routes.\n   */\n  ai?: Partial<AiModelsConfig>\n  /** Per-user limit of the AI endpoints; default: that of `defineEditorConfig` (30 requests per minute). */\n  rateLimit?: RateLimiterOptions\n  /** Filters or reorders the routes before they are mounted (a host that serves `/api/editor/assets/*` itself drops them); default: all. Receives what `serverRoutesOf(ports, { ai })` returns, so a route of an absent port, or an AI route without the `ai` option, is not in it. */\n  routes?: (routes: readonly RouteDef[]) => readonly RouteDef[]\n  /** The collaboration schema (see `CollabServerOptions.schema`); default `advancedSchemaExtensions()`, host nodes: `() => [...advancedSchemaExtensions(), Callout]`. */\n  schema?: () => AnyExtension[]\n}\n\nexport interface EditorServer {\n  ports: EditorPorts\n  /** The collaboration server, `undefined` with `collab: false`. */\n  collab: CollabServer | undefined\n  /** The AI models, `undefined` without `ai`. */\n  models: AiModels | undefined\n  /** Writes pending collaboration stores and disconnects every client. Nitro's `close` hook calls it. */\n  close(): Promise<void>\n}\n\ntype CollabPeer = { _hocuspocus?: CollabConnection }\n\n// Same crossws wiring as Hocuspocus' own Server; the document name comes from the provider's `name`. By default the user\n// is authenticated in Hocuspocus' `onAuthenticate` (cookie headers of the upgrade request or the provider's `token`), so\n// the upgrade always succeeds and an unauthenticated socket is closed with 4401 afterwards. With `authenticateUpgrade` the\n// upgrade request itself is authenticated (headers only) and refused with HTTP 401.\nconst collabRoute = (collab: CollabServer, ports: EditorPorts, authenticateUpgrade: boolean) => defineWebSocketHandler({\n  async upgrade(request) {\n    if (!authenticateUpgrade) return\n    const user = await ports.identity.authenticate({ headers: request.headers })\n    // No body: crossws' node adapter writes the response headers percent-encoded, which would mangle an automatic `content-type`.\n    if (!user) return new Response(null, { status: 401, statusText: 'Unauthorized' })\n    // crossws creates the context before it calls the hook (its type is optional only for other callers); `open` reads it as `peer.context`.\n    request.context!.user = user\n  },\n  open(peer) {\n    const user = peer.context.user as object | undefined\n    ;(peer as unknown as CollabPeer)._hocuspocus = collab.handleConnection(peer.websocket as unknown as Parameters<CollabServer['handleConnection']>[0], peer.request as Request, user && { user })\n  },\n  message(peer, message) {\n    ;(peer as unknown as CollabPeer)._hocuspocus?.handleMessage(message.uint8Array())\n  },\n  close(peer, details) {\n    ;(peer as unknown as CollabPeer)._hocuspocus?.handleClose({ code: details.code ?? 1000, reason: details.reason ?? '' } as CloseEvent)\n  },\n  error(peer, error) {\n    console.error('[collab]', peer.id, error)\n  },\n})\n\n/**\n * Wires the editor backend into `nitroApp` (call it from a Nitro plugin):\n *\n *     /api/editor/{capabilities,settings,users,tags,assets/…,themes/…}   the editor's own endpoints, each with its port; `capabilities` lists what is served\n *     /api/editor/documents/:id                              GET/PUT a document's TipTap JSON (what `useEditorDocument` uses)\n *     /api/editor/comments/:id                               GET/POST comments, with `ports.comments`\n *     /api/ai/{models,chat,complete,generate,extract,transcript-cleanup}   with `ai`\n *     /collab/:id                                            the collaboration websocket, unless `collab: false`\n *\n * Every route authenticates through `ports.identity.authenticate`. The collaboration server is closed with Nitro's `close`\n * hook. The installed server is also the process-wide one of `@ecsplico/editor/server` (`useCollabServer`, `useAiModels`,\n * `liveContent`, …) until it closes. The paths are the ones the editor's client (`createHttpBackend`) calls.\n */\nexport function installEditorServer(nitroApp: NitroHost, options: EditorServerOptions): EditorServer {\n  const { ports, schema } = options\n  const { authenticateUpgrade = false, ...collabOptions }: Exclude<EditorServerOptions['collab'], false> = options.collab || {}\n  const collab = options.collab === false ? undefined : createCollabServer({ ports, ...(schema && { schema }), ...collabOptions })\n  const provider = ports.models\n  const models = options.ai && createAiModels({\n    presets: {},\n    languageModel: provider?.languageModel && ((ref, user) => provider.languageModel!(ref, user)),\n    listModels: provider?.listModels && (user => provider.listModels!(user)),\n    ...options.ai,\n  })\n  const limiter: RateLimiter | undefined = models && createRateLimiter(options.rateLimit ?? defineEditorConfig().ai.rateLimit)\n\n  const context: HandlerContext = { ports, ...(collab && { collab }), served: { ai: models !== undefined, collaboration: collab !== undefined } }\n  const aiContext: AiHandlerContext | undefined = models && limiter && { ...context, ai: models, limiter }\n  const mounted = serverRoutesOf(ports, { ai: aiContext !== undefined })\n  for (const route of options.routes ? options.routes(mounted) : mounted) {\n    // `serverRoutesOf` returns the AI routes only with `ai`, so `aiContext` is set for them.\n    const handler = route.port === 'ai' ? routeOf(aiContext!, route.handler) : routeOf(context, route.handler)\n    nitroApp.router.add(route.path, handler, route.method)\n  }\n  // No method: the websocket upgrade resolves its handler by path only.\n  if (collab) nitroApp.router.use(`${COLLAB_PATH}/:id`, collabRoute(collab, ports, authenticateUpgrade))\n\n  const release = adoptEditorServer({ ports, schema, collab, models, limiter })\n  const server: EditorServer = {\n    ports,\n    collab,\n    models,\n    async close() {\n      await collab?.close()\n      release()\n    },\n  }\n  nitroApp.hooks.hook('close', () => server.close())\n  return server\n}\n"],"mappings":";;;;;;;;;;AAiEA,MAAM,eAAe,QAAsB,OAAoB,wBAAiC,uBAAuB;CACrH,MAAM,QAAQ,SAAS;EACrB,IAAI,CAAC,qBAAqB;EAC1B,MAAM,OAAO,MAAM,MAAM,SAAS,aAAa,EAAE,SAAS,QAAQ,QAAQ,CAAC;EAE3E,IAAI,CAAC,MAAM,OAAO,IAAI,SAAS,MAAM;GAAE,QAAQ;GAAK,YAAY;EAAe,CAAC;EAEhF,QAAQ,QAAS,OAAO;CAC1B;CACA,KAAK,MAAM;EACT,MAAM,OAAO,KAAK,QAAQ;EACzB,KAAgC,cAAc,OAAO,iBAAiB,KAAK,WAAyE,KAAK,SAAoB,QAAQ,EAAE,KAAK,CAAC;CAChM;CACA,QAAQ,MAAM,SAAS;EACpB,KAAgC,aAAa,cAAc,QAAQ,WAAW,CAAC;CAClF;CACA,MAAM,MAAM,SAAS;EAClB,KAAgC,aAAa,YAAY;GAAE,MAAM,QAAQ,QAAQ;GAAM,QAAQ,QAAQ,UAAU;EAAG,CAAe;CACtI;CACA,MAAM,MAAM,OAAO;EACjB,QAAQ,MAAM,YAAY,KAAK,IAAI,KAAK;CAC1C;AACF,CAAC;;;;;;;;;;;;;;AAeD,SAAgB,oBAAoB,UAAqB,SAA4C;CACnG,MAAM,EAAE,OAAO,WAAW;CAC1B,MAAM,EAAE,sBAAsB,OAAO,GAAG,kBAAiE,QAAQ,UAAU,CAAC;CAC5H,MAAM,SAAS,QAAQ,WAAW,QAAQ,KAAA,IAAY,mBAAmB;EAAE;EAAO,GAAI,UAAU,EAAE,OAAO;EAAI,GAAG;CAAc,CAAC;CAC/H,MAAM,WAAW,MAAM;CACvB,MAAM,SAAS,QAAQ,MAAM,eAAe;EAC1C,SAAS,CAAC;EACV,eAAe,UAAU,mBAAmB,KAAK,SAAS,SAAS,cAAe,KAAK,IAAI;EAC3F,YAAY,UAAU,gBAAe,SAAQ,SAAS,WAAY,IAAI;EACtE,GAAG,QAAQ;CACb,CAAC;CACD,MAAM,UAAmC,UAAU,kBAAkB,QAAQ,aAAa,mBAAmB,CAAC,CAAC,GAAG,SAAS;CAE3H,MAAM,UAA0B;EAAE;EAAO,GAAI,UAAU,EAAE,OAAO;EAAI,QAAQ;GAAE,IAAI,WAAW,KAAA;GAAW,eAAe,WAAW,KAAA;EAAU;CAAE;CAC9I,MAAM,YAA0C,UAAU,WAAW;EAAE,GAAG;EAAS,IAAI;EAAQ;CAAQ;CACvG,MAAM,UAAU,eAAe,OAAO,EAAE,IAAI,cAAc,KAAA,EAAU,CAAC;CACrE,KAAK,MAAM,SAAS,QAAQ,SAAS,QAAQ,OAAO,OAAO,IAAI,SAAS;EAEtE,MAAM,UAAU,MAAM,SAAS,OAAO,QAAQ,WAAY,MAAM,OAAO,IAAI,QAAQ,SAAS,MAAM,OAAO;EACzG,SAAS,OAAO,IAAI,MAAM,MAAM,SAAS,MAAM,MAAM;CACvD;CAEA,IAAI,QAAQ,SAAS,OAAO,IAAI,GAAG,YAAY,OAAO,YAAY,QAAQ,OAAO,mBAAmB,CAAC;CAErG,MAAM,UAAU,kBAAkB;EAAE;EAAO;EAAQ;EAAQ;EAAQ;CAAQ,CAAC;CAC5E,MAAM,SAAuB;EAC3B;EACA;EACA;EACA,MAAM,QAAQ;GACZ,MAAM,QAAQ,MAAM;GACpB,QAAQ;EACV;CACF;CACA,SAAS,MAAM,KAAK,eAAe,OAAO,MAAM,CAAC;CACjD,OAAO;AACT"}

package/dist/adapters/react.d.ts

@@ -0,0 +1,55 @@
+import { CollaborationSession } from "../core/feature.js";
+import { CommentsModel } from "../core/backend-types.js";
+import "../core/index.js";
+import { EditorDocumentOptions } from "./document-state.js";
+import { Editor, JSONContent } from "@tiptap/core";
+//#region src/adapters/react.d.ts
+/** The props of the editor surface (`EditorSurface`, `AdvancedEditor`) that `useEditorDocument` fills. */
+export interface EditorDocumentBinding {
+  /** The document (standalone mode); `undefined` in collaboration mode and until it has loaded. */
+  value: JSONContent | undefined;
+  onChange: (content: JSONContent) => void;
+  /** Hands the live editor to the comments model. */
+  onReady: (editor: Editor) => void;
+  collaboration: CollaborationSession | undefined;
+}
+export interface EditorDocument {
+  /** The document's TipTap JSON: the surface's `value`. `undefined` until loaded, and always in collaboration mode. */
+  modelValue: JSONContent | undefined;
+  /** Replaces `modelValue` (the surface's `onChange`). */
+  onChange: (content: JSONContent) => void;
+  /** `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. */
+  ready: boolean;
+  /** Edits since the content was loaded or last saved. */
+  dirty: boolean;
+  /** 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>;
+  /** Loads the content again and drops unsaved edits (in collaboration mode: reconnects). */
+  reload: () => Promise<void>;
+  /** The last load or save error, `null` while all is well. */
+  error: Error | null;
+  /** The collaboration session for the surface's `collaboration` prop; `undefined` without the `collaboration` option, and never the session of another document. */
+  collaboration: CollaborationSession | undefined;
+  /**
+   * The comments model of this document, made by `backend.comments` (`undefined` when the backend has none, and until
+   * the first effect ran). A new one per id. The feature's `model` factory runs when the editor is created, so read it
+   * through a ref the host keeps current: `commentsFeature({ model: () => commentsRef.current! })`.
+   */
+  comments: CommentsModel | undefined;
+  /** The live editor, once the surface reported it. */
+  editor: Editor | undefined;
+  /** Spread target for the surface: `<AdvancedEditor key={id} {...bind} />` once `ready`. */
+  bind: EditorDocumentBinding;
+}
+/**
+ * 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
+ * (`EditorContextProvider`); keep it stable across renders (a new object reloads the document). A changed `id` loads the
+ * other document and replaces the session and the comments model. Throws when `collaboration` is set and the backend
+ * cannot collaborate, or when it keeps no documents.
+ */
+export declare function useEditorDocument(documentId: string | null | undefined, options?: EditorDocumentOptions): EditorDocument;
+//#endregion
+export type { EditorDocumentOptions };
+//# sourceMappingURL=react.d.ts.map

package/dist/adapters/react.js

@@ -0,0 +1,209 @@
+import { useOptionalEditorContext } from "../react/context.js";
+import { errorOf, fingerprintToSave, isDirty, loadedDocument, openSession, requireCapability } from "./document-state.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region src/adapters/react.ts
+const fresh = (id) => ({
+	id,
+	ready: false,
+	modelValue: void 0,
+	saved: null,
+	error: null,
+	session: void 0,
+	editor: void 0
+});
+/**
+* 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
+* (`EditorContextProvider`); keep it stable across renders (a new object reloads the document). A changed `id` loads the
+* other document and replaces the session and the comments model. Throws when `collaboration` is set and the backend
+* cannot collaborate, or when it keeps no documents.
+*/
+function useEditorDocument(documentId, options = {}) {
+	/** `''` = no document open (the host has none yet, e.g. it still waits for the signed-in user): the hook stays idle. */
+	const id = documentId ?? "";
+	const context = useOptionalEditorContext();
+	const backend = options.backend ?? context?.backend;
+	if (!backend) throw new Error("@ecsplico/editor: useEditorDocument needs a backend: pass `backend` or wrap the tree in <EditorContextProvider context={createEditorContext()}>");
+	const collaborating = Boolean(options.collaboration);
+	const documents = collaborating ? void 0 : requireCapability(backend, "documents");
+	const collaborationPort = collaborating ? requireCapability(backend, "collaboration") : void 0;
+	const [state, setState] = useState(() => fresh(id));
+	const [comments, setComments] = useState();
+	const [attempt, setAttempt] = useState(0);
+	/** What the callbacks read: the open id, and the latest options and values (an edit just reported is here before the next render). */
+	const live = useRef({
+		id,
+		options,
+		modelValue: void 0,
+		saved: null,
+		ready: false,
+		missing: false,
+		editor: void 0
+	});
+	live.current.id = id;
+	live.current.options = options;
+	const generation = useRef(0);
+	const tail = useRef(Promise.resolve());
+	const current = state.id === id ? state : fresh(id);
+	const userOf = useCallback(() => {
+		const { user } = live.current.options;
+		return (typeof user === "function" ? user() : user) ?? null;
+	}, []);
+	const commit = useCallback((documentId, change) => {
+		if (documentId !== live.current.id) return;
+		if ("modelValue" in change) live.current.modelValue = change.modelValue;
+		if ("saved" in change) live.current.saved = change.saved ?? null;
+		if ("ready" in change) live.current.ready = change.ready ?? false;
+		if ("editor" in change) live.current.editor = change.editor;
+		setState((previous) => previous.id === documentId ? {
+			...previous,
+			...change
+		} : previous);
+	}, []);
+	const fetchContent = useCallback(async (documentId, mine) => {
+		try {
+			const content = await documents.load(documentId);
+			if (mine !== generation.current) return;
+			const { modelValue, saved, missing } = loadedDocument(content);
+			live.current.missing = missing;
+			commit(documentId, {
+				modelValue,
+				saved,
+				ready: true
+			});
+		} catch (cause) {
+			if (mine === generation.current) commit(documentId, { error: errorOf(cause) });
+		}
+	}, [documents, commit]);
+	const start = useCallback((documentId) => {
+		const mine = ++generation.current;
+		Object.assign(live.current, {
+			modelValue: void 0,
+			saved: null,
+			ready: false,
+			missing: false,
+			editor: void 0
+		});
+		setState(fresh(documentId));
+		return mine;
+	}, []);
+	useEffect(() => {
+		const mine = start(id);
+		if (!id) return;
+		if (collaborationPort) {
+			const { session, close } = openSession(collaborationPort, id, live.current.options.collaboration, userOf());
+			commit(id, {
+				session,
+				ready: true
+			});
+			return () => {
+				generation.current++;
+				close();
+			};
+		}
+		fetchContent(id, mine);
+		return () => {
+			generation.current++;
+		};
+	}, [
+		id,
+		collaborationPort,
+		attempt,
+		start,
+		commit,
+		fetchContent,
+		userOf
+	]);
+	useEffect(() => {
+		if (!id) return;
+		const model = backend.comments?.(id, {
+			user: userOf,
+			canComment: () => {
+				const { canComment } = live.current.options;
+				return (typeof canComment === "function" ? canComment() : canComment) ?? true;
+			},
+			getEditor: () => live.current.editor,
+			onError: (cause) => commit(id, { error: cause })
+		});
+		setComments(model);
+		return () => {
+			model?.dispose();
+			setComments(void 0);
+		};
+	}, [
+		backend,
+		id,
+		userOf,
+		commit
+	]);
+	const save = useCallback(() => {
+		if (!documents) return Promise.resolve();
+		const run = async () => {
+			const documentId = live.current.id;
+			const content = live.current.modelValue;
+			const saved = fingerprintToSave(content, live.current.ready, live.current.saved, live.current.missing);
+			if (content === void 0 || saved === null) return;
+			try {
+				await documents.save(documentId, content);
+			} catch (cause) {
+				commit(documentId, { error: errorOf(cause) });
+				throw cause;
+			}
+			if (documentId === live.current.id) live.current.missing = false;
+			commit(documentId, {
+				saved,
+				error: null
+			});
+		};
+		const result = tail.current.then(run, run);
+		tail.current = result.catch(() => {});
+		return result;
+	}, [documents, commit]);
+	const reload = useCallback(async () => {
+		if (collaborationPort) {
+			setAttempt((count) => count + 1);
+			return;
+		}
+		await fetchContent(live.current.id, start(live.current.id));
+	}, [
+		collaborationPort,
+		fetchContent,
+		start
+	]);
+	const onChange = useCallback((content) => commit(live.current.id, { modelValue: content }), [commit]);
+	const onReady = useCallback((editor) => commit(live.current.id, { editor }), [commit]);
+	const dirty = useMemo(() => isDirty(collaborating, current.modelValue, current.saved), [
+		collaborating,
+		current.modelValue,
+		current.saved
+	]);
+	const bind = useMemo(() => ({
+		value: current.modelValue,
+		onChange,
+		onReady,
+		collaboration: current.session
+	}), [
+		current.modelValue,
+		current.session,
+		onChange,
+		onReady
+	]);
+	return {
+		modelValue: current.modelValue,
+		onChange,
+		ready: current.ready,
+		dirty,
+		save,
+		reload,
+		error: current.error,
+		collaboration: current.session,
+		comments,
+		editor: current.editor,
+		bind
+	};
+}
+//#endregion
+export { useEditorDocument };
+
+//# sourceMappingURL=react.js.map