@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/editor/editor-access-denied-tool.ts

@@ -0,0 +1,58 @@
+import { tool } from '@langchain/core/tools';
+import type { StructuredTool } from 'langchain';
+import { z } from 'zod';
+import { EDITOR_AGENT_TOOL_NAME } from './editor-agent';
+import { GRANT_ACCESS_TOOL } from './failures';
+import type { EditorUnavailableReason } from './prompts';
+
+// Mirrors the real sub-agent tool's schema so a model that composed a task for
+// the document assistant still produces a valid call — the answer is just the
+// denial.
+const taskSchema = z.object({
+  task: z
+    .string()
+    .describe('The task you intended to send to the document assistant.'),
+});
+
+export interface EditorAccessDeniedToolOptions {
+  /** The document room the client reported open. */
+  editorRoomId: string;
+  /** Why the real document surface refused to bind. */
+  reason: EditorUnavailableReason;
+}
+
+/**
+ * Stand-in for `call_editor_agent` bound when a document is open but the real
+ * surface refused to attach (the user is not a verified member of the room, or
+ * the sub-agent build failed).
+ *
+ * Without it, the model is shown a document capability it cannot reach and
+ * either narrates its sub-agent task as user-facing text or hunts through
+ * `list_capabilities` / `load_capability` for a tool that will never appear.
+ */
+export function createEditorAccessDeniedTool(
+  options: EditorAccessDeniedToolOptions,
+): StructuredTool {
+  const { editorRoomId, reason } = options;
+
+  // Membership is resolved with the oracle's admin identity, so a failed check
+  // can mean either side is missing — the user OR this oracle (the lookup is
+  // forbidden and fails closed). Keep the wording unified.
+  const message =
+    reason === 'not-member'
+      ? `Document unavailable: membership of the document's room (${editorRoomId}) could not be verified — ` +
+        `either the user's account or this oracle is not a member, and BOTH must be for document access. ` +
+        `Tell the user the document can't be read or edited because either they or this oracle is missing from its room; ` +
+        `inviting this oracle to the document (or opening one they own) fixes it. ` +
+        `If they only need write access to a document you can already read, the \`${GRANT_ACCESS_TOOL}\` browser tool is what grants it. ` +
+        `Do not retry this tool.`
+      : `Document unavailable: the document service failed to attach to the room (${editorRoomId}). ` +
+        `Tell the user the document assistant is currently unavailable and they can retry shortly. Do not retry this tool.`;
+
+  return tool(async () => message, {
+    name: EDITOR_AGENT_TOOL_NAME,
+    description:
+      'Document assistant (unavailable for this request — calls return the denial reason).',
+    schema: taskSchema,
+  });
+}

package/src/plugins/editor/editor-agent.ts

@@ -0,0 +1,34 @@
+/**
+ * Identity of the `call_editor_agent` tool, and the per-room provider config
+ * behind it. The tool itself lives in `standalone-editor-tool.ts`: one tool
+ * that targets the open document by default and any `room_id` on request.
+ */
+
+import { computeSubAgentToolName } from '../../core/subagent-as-tool';
+import type { BlocknoteToolsConfig } from './editor-config';
+import type { AppConfig, MatrixRoomConfig } from './provider';
+
+/** Display name the tool name is derived from. */
+export const EDITOR_AGENT_NAME = 'Editor Agent';
+
+/**
+ * The tool name the main agent sees for the document surface. Derived through
+ * `computeSubAgentToolName` so it stays stable for the prompt composer, which
+ * checks this name before injecting the document-mode prompts: telling the
+ * model a document is open without this tool bound makes it narrate its
+ * delegation as user-facing text instead of calling anything.
+ */
+export const EDITOR_AGENT_TOOL_NAME =
+  computeSubAgentToolName(EDITOR_AGENT_NAME);
+
+/** Compose the per-room provider config from the plugin's boot-time config. */
+export function buildAppConfig(
+  base: BlocknoteToolsConfig,
+  room: MatrixRoomConfig,
+): AppConfig {
+  return {
+    matrix: { ...base.matrix, room },
+    provider: { ...base.provider },
+    blocknote: { ...base.blocknote },
+  };
+}

package/src/plugins/editor/editor-config.ts

@@ -0,0 +1,64 @@
+/**
+ * Matrix + provider configuration shared by every editor surface (and by the
+ * flows plugin, which opens the same Matrix-backed Y.Docs).
+ *
+ * The three Matrix env vars this reads are owned by the runtime's core base env
+ * schema, so the editor plugin declares no `configSchema` of its own — it only
+ * extracts typed values out of the already-validated `ctx.config`.
+ */
+
+import type { MatrixClient } from 'matrix-js-sdk';
+
+/** Matrix admin credentials the editor uses to read/write Y.Docs. */
+export interface BlocknoteToolsMatrixConfig {
+  baseUrl: string;
+  accessToken: string;
+  userId: string;
+}
+
+/**
+ * Build the provider/document config from Matrix credentials. Called once per
+ * request by the editor plugin and per call by the flows plugin.
+ *
+ * `writer.retryIfForbiddenInterval` / `maxForbiddenRetries` are deliberately
+ * tight: matrix-crdt defaults to retrying a rejected write every 30s up to 3
+ * times, which would keep a tool call open for ~90s before it could report the
+ * truth. Room power levels cannot change mid-call, so a rejected write is
+ * final — fail fast and let the caller surface `needs_access`.
+ */
+export function buildBlocknoteToolsConfig(matrix: BlocknoteToolsMatrixConfig) {
+  return {
+    matrix: {
+      baseUrl: matrix.baseUrl,
+      accessToken: matrix.accessToken,
+      userId: matrix.userId,
+      initialSyncTimeoutMs: 30_000,
+    },
+    provider: {
+      docName: 'document',
+      enableAwareness: false,
+      retryAttempts: 3,
+      retryDelayMs: 5_000,
+      flushInterval: 10,
+      retryIfForbiddenInterval: 1_000,
+      maxForbiddenRetries: 1,
+    },
+    blocknote: {
+      defaultBlockId: undefined,
+      blockNamespace: undefined,
+      mutableAttributeKeys: [] as string[],
+    },
+  };
+}
+
+/**
+ * The editor's config, optionally augmented with a host-provided
+ * `MatrixClient`. When `matrixClient` is set, `resolveEditorMatrixClient` uses
+ * it directly; when absent, the editor constructs its internal singleton from
+ * the Matrix credentials.
+ */
+export type BlocknoteToolsConfig = ReturnType<
+  typeof buildBlocknoteToolsConfig
+> & {
+  matrixClient?: MatrixClient;
+};

package/src/plugins/editor/editor-mx.ts

@@ -0,0 +1,128 @@
+import { createClient, type MatrixClient } from 'matrix-js-sdk';
+import { createConsoleLogger } from '../../core/utils';
+
+/** Matrix admin credentials needed to bootstrap the editor client. */
+export interface EditorMatrixClientConfig {
+  baseUrl: string;
+  userId: string;
+  accessToken: string;
+}
+
+const logger = createConsoleLogger({ module: 'editor-mx' });
+
+/**
+ * Per-isolate singleton wrapper around a `matrix-js-sdk` `MatrixClient`. Used
+ * by `@ixo/matrix-crdt` to read/write BlockNote Y.js documents.
+ *
+ * No `startClient()` / sync is performed — matrix-crdt's `MatrixReader`
+ * explicitly tells consumers NOT to use the Sync API and polls the
+ * `/events` endpoint itself. No crypto is initialised either
+ * (`initRustCrypto` is never called): editor rooms are not E2EE at the doc
+ * level in this runtime — matrix-crdt stores updates in its own plain state
+ * events — so a crypto-less client is correct, and the crypto WASM stays
+ * untouched outside the gateway Durable Object.
+ */
+export class EditorMatrixClient {
+  private static instance: EditorMatrixClient | null = null;
+
+  private readonly cfg: EditorMatrixClientConfig;
+  private matrixClient: MatrixClient | null = null;
+  private isInitialized = false;
+  private initializationPromise: Promise<void> | null = null;
+
+  private constructor(cfg: EditorMatrixClientConfig) {
+    this.cfg = cfg;
+  }
+
+  /**
+   * Get the singleton instance. First caller supplies the Matrix admin
+   * config used for the lifetime of the isolate; subsequent callers
+   * receive the same instance and the config argument is ignored.
+   */
+  public static getInstance(cfg: EditorMatrixClientConfig): EditorMatrixClient {
+    if (!EditorMatrixClient.instance) {
+      EditorMatrixClient.instance = new EditorMatrixClient(cfg);
+    }
+    return EditorMatrixClient.instance;
+  }
+
+  /**
+   * Test-only — reset the singleton so tests can swap the underlying client.
+   */
+  public static resetForTesting(): void {
+    EditorMatrixClient.instance = null;
+  }
+
+  /**
+   * Build the underlying `matrix-js-sdk` client. Idempotent — safe to call
+   * concurrently; only the first call does work.
+   */
+  public async init(): Promise<void> {
+    if (this.isInitialized && this.matrixClient) return;
+    if (this.initializationPromise) return this.initializationPromise;
+
+    this.initializationPromise = this.performInitialization();
+    try {
+      await this.initializationPromise;
+    } finally {
+      this.initializationPromise = null;
+    }
+  }
+
+  private async performInitialization(): Promise<void> {
+    const { baseUrl, userId, accessToken } = this.cfg;
+    if (!baseUrl || !userId || !accessToken) {
+      throw new Error(
+        'Missing Matrix configuration for the editor client (base URL, user id and the bot device token from the gateway).',
+      );
+    }
+
+    this.matrixClient = createClient({
+      baseUrl,
+      accessToken,
+      userId,
+      timelineSupport: true,
+      // Never hand the SDK the bare global: workerd rejects `fetch` invoked
+      // with a foreign `this` ("Illegal invocation"), and the SDK calls
+      // `this.fetchFn(...)` on its own http-api object.
+      fetchFn: (input, init) => fetch(input, init),
+    });
+    this.isInitialized = true;
+    logger.log('EditorMatrixClient ready (no sync, polling-only mode)');
+  }
+
+  public getClient(): MatrixClient {
+    if (!this.isInitialized || !this.matrixClient) {
+      throw new Error(
+        'EditorMatrixClient not initialized. Call await init() first.',
+      );
+    }
+    return this.matrixClient;
+  }
+
+  public isReady(): boolean {
+    return this.isInitialized && this.matrixClient !== null;
+  }
+
+  public async waitUntilReady(): Promise<void> {
+    if (this.isReady()) return;
+    await this.init();
+  }
+}
+
+/**
+ * Resolve the `MatrixClient` used by editor tools. Prefers the
+ * `matrixClient` from the plugin's runtime config (host/test-provided);
+ * otherwise lazily constructs the internal singleton.
+ *
+ * Centralised so every call site (standalone-editor-tool, the flows plugin's
+ * flow-doc) goes through one resolution path.
+ */
+export async function resolveEditorMatrixClient(
+  cfg: EditorMatrixClientConfig & { matrixClient?: MatrixClient },
+): Promise<MatrixClient> {
+  if (cfg.matrixClient) return cfg.matrixClient;
+  const inst = EditorMatrixClient.getInstance(cfg);
+  await inst.init();
+  return inst.getClient();
+}

package/src/plugins/editor/editor.plugin.ts

@@ -0,0 +1,143 @@
+import type { MatrixClient } from 'matrix-js-sdk';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import { EDITOR_AGENT_TOOL_NAME } from './editor-agent';
+import {
+  buildBlocknoteToolsConfig,
+  type BlocknoteToolsConfig,
+} from './editor-config';
+
+// This module must stay statically LIGHT: constructing `new EditorPlugin()`
+// happens at Worker module scope (src/plugins/index.ts), and the tool's
+// module graph (`standalone-editor-tool` → content-tools → provider →
+// @ixo/matrix-crdt → vscode-lib, plus @blocknote/server-util) schedules a
+// timer during module evaluation (vscode-lib's `IdleValue`/`runWhenIdle`),
+// which workerd forbids in global scope. The chain is therefore reached only
+// through `await import()` inside `getRequestTools`, which runs per turn
+// inside a Durable Object request context where timers are allowed.
+
+/**
+ * Constructor options for `EditorPlugin`. Pass `matrixClient` when the host
+ * (or a test) already owns a long-lived matrix-js-sdk client — every editor
+ * surface will reuse it instead of constructing the internal singleton.
+ */
+export interface EditorPluginOptions {
+  matrixClient?: MatrixClient;
+}
+
+/**
+ * The editor's own polling client needs a device token. It never comes from
+ * the env: the gateway keeps a dedicated crypto-less device for plugins and
+ * hands its credentials out through `ctx.matrix.botCredentials()`. If that
+ * fails the plugin logs and contributes no tools rather than failing the
+ * whole request build.
+ */
+
+const manifest: PluginManifest = {
+  title: 'Documents',
+  summary:
+    "Reads and edits the content of the user's editor documents — prose, " +
+    'structure, and ordering.',
+  whenToUse: [
+    'User asks to read, summarize, or explain the document they have open.',
+    'User asks to write, rewrite, shorten, expand, or restructure document content.',
+    'User asks to fix wording, insert a section, reorder sections, or delete content.',
+    'User names a document in their workspace and wants it read or edited.',
+  ],
+  whenNotToUse: [
+    'Building or configuring flows, action blocks, or forms — this surface edits content only.',
+    'Running or executing anything inside a document.',
+    'IXO entity lookups (use Domain Indexer) — documents are pages, not entities.',
+    'Web search or scraping (use Firecrawl); long-term user memory (use Memory).',
+  ],
+  examples: [
+    {
+      user: 'Summarize this page.',
+      thought:
+        'Delegate to the document assistant with the open room. It reads the document and returns a summary.',
+      tool: EDITOR_AGENT_TOOL_NAME,
+    },
+    {
+      user: 'Rename the "Introduction" heading to "Getting Started".',
+      thought:
+        'Content edit — delegate with the exact old and new text so the assistant can locate the block and replace the text.',
+      tool: EDITOR_AGENT_TOOL_NAME,
+    },
+  ],
+  tags: ['editor', 'documents', 'pages', 'blocknote', 'content'],
+  category: 'data',
+  // On-demand so ordinary chats carry no editor Tier-1 entry or gated tools.
+  visibility: 'on-demand',
+  stability: 'stable',
+};
+
+function toolsConfigFor(
+  creds: { baseUrl: string; userId: string; accessToken: string },
+  matrixClient?: MatrixClient,
+): BlocknoteToolsConfig {
+  return {
+    ...buildBlocknoteToolsConfig(creds),
+    matrixClient,
+  };
+}
+
+/**
+ * Document content plugin. Contributes one tool, `call_editor_agent`, on every
+ * request: it targets the document the user has open (`state.editorRoomId`)
+ * by default and any `room_id` the agent names per call.
+ *
+ * Access is enforced per call inside the tool with `isUserInRoom` (via the
+ * gateway Durable Object): the oracle acts with an admin Matrix identity, so
+ * "the user's documents" is always computed from the user's membership, never
+ * from what the admin can see.
+ */
+export class EditorPlugin extends OraclePlugin {
+  static readonly NAME = 'editor';
+
+  readonly name = EditorPlugin.NAME;
+
+  readonly version = '2.0.0';
+
+  readonly manifest = manifest;
+
+  // Intentionally no `configSchema` — the Matrix env vars the editor needs are
+  // owned by the core env schema. See `matrixConfigSchema` above.
+
+  private readonly matrixClient?: MatrixClient;
+
+  constructor(options: EditorPluginOptions = {}) {
+    super();
+    this.matrixClient = options.matrixClient;
+  }
+
+  override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
+    // Always bound. One tool covers every case: it targets the open document
+    // by default and any `room_id` the agent names, so a page created mid-turn
+    // (`create_page_room`) can be written into while another document is open.
+    //
+    // Not gated on `state.editorRoomId` or `state.spaceId` either — tools are
+    // resolved once per request, so a room that only exists after the turn
+    // starts is never in state. Access is enforced per call inside the tool
+    // (`isUserInRoom(room_id, user)`, fail closed); space membership never
+    // implied rights over a document, and the room need not live in that space.
+    try {
+      const toolsConfig = toolsConfigFor(
+        await rtCtx.matrix.botCredentials(),
+        this.matrixClient,
+      );
+      // Lazy on purpose — see the module header. The module registry caches
+      // the import, so only the first turn in an isolate pays for it.
+      const { createStandaloneEditorTool } =
+        await import('./standalone-editor-tool');
+      return [createStandaloneEditorTool({ toolsConfig })];
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      rtCtx.logger.error(`[editor] failed to build standalone tool: ${detail}`);
+      return [];
+    }
+  }
+}

package/src/plugins/editor/failures.ts

@@ -0,0 +1,154 @@
+/**
+ * Typed failures the content tools return as *values*, never as thrown strings.
+ *
+ * The agent has to be able to branch on the reason: `needs_access` means "ask
+ * the user to grant access", `read_only_flow` means "describe, do not edit",
+ * `prop_not_editable` means "that prop is off limits — say which".
+ */
+
+/** The Portal browser tool the user runs to give the assistant write access. */
+export const GRANT_ACCESS_TOOL = 'grant_assistant_access';
+
+export type EditorFailureCode =
+  | 'needs_access'
+  | 'read_only_flow'
+  | 'prop_not_editable'
+  | 'block_not_found'
+  | 'not_a_member'
+  | 'no_document'
+  | 'flush_timeout'
+  | 'error';
+
+export interface EditorFailure {
+  ok: false;
+  code: EditorFailureCode;
+  message: string;
+  /** The offending prop names, for `prop_not_editable`. */
+  props?: string[];
+  /** The block the failure is about, when there is one. */
+  blockId?: string;
+  roomId?: string;
+}
+
+export function isEditorFailure(value: unknown): value is EditorFailure {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'ok' in value &&
+    value.ok === false &&
+    'code' in value
+  );
+}
+
+/**
+ * The assistant is in the document but cannot write to it. The user has to
+ * grant access from the Portal; naming the tool is what lets the agent say
+ * exactly what to do.
+ */
+export function needsAccess(roomId: string, detail?: string): EditorFailure {
+  return {
+    ok: false,
+    code: 'needs_access',
+    roomId,
+    message:
+      `This assistant does not have permission to write to this document` +
+      (detail ? ` (${detail})` : '') +
+      `. CALL the \`${GRANT_ACCESS_TOOL}\` browser tool yourself — do not ask ` +
+      `the user to run it, and do not tell them you cannot grant yourself ` +
+      `access. The tool prompts them to confirm in a dialog; if they confirm, ` +
+      `retry the edit once. If it returns \`granted: false\` or a failure, ` +
+      `report that plainly. Reads are unaffected.`,
+  };
+}
+
+/** The document is a live flow: readable, never writable. */
+export function readOnlyFlow(roomId: string, alias?: string): EditorFailure {
+  return {
+    ok: false,
+    code: 'read_only_flow',
+    roomId,
+    message:
+      `This document is a live flow${alias ? ` (${alias})` : ''}. Flows are ` +
+      `read-only for this assistant — you can read and describe it, but edits ` +
+      `must be made in the flow builder. Do not retry the write.`,
+  };
+}
+
+/** One or more requested props are outside the block type's allowlist. */
+export function propNotEditable(
+  blockId: string,
+  blockType: string,
+  rejected: Array<{ prop: string; reason: string }>,
+): EditorFailure {
+  const detail = rejected
+    .map((entry) => `'${entry.prop}' — ${entry.reason}`)
+    .join('; ');
+  return {
+    ok: false,
+    code: 'prop_not_editable',
+    blockId,
+    props: rejected.map((entry) => entry.prop),
+    message:
+      `Refused: ${detail}. Nothing was written to block ${blockId} ` +
+      `(type '${blockType}'). Tell the user which property could not be ` +
+      `changed and why.`,
+  };
+}
+
+/** The block id is not in the document. */
+export function blockNotFound(blockId: string): EditorFailure {
+  return {
+    ok: false,
+    code: 'block_not_found',
+    blockId,
+    message:
+      `No block with id '${blockId}' exists in this document. Call ` +
+      `read_document to get current block ids — never guess or reuse an id ` +
+      `from an earlier turn.`,
+  };
+}
+
+/** The user is not a member of the room, so it is not one of their documents. */
+export function notAMember(roomId: string): EditorFailure {
+  return {
+    ok: false,
+    code: 'not_a_member',
+    roomId,
+    message:
+      `The user is not a member of document room ${roomId}, so it is not one ` +
+      `of their documents. Tell them they do not have access to it. Do not retry.`,
+  };
+}
+
+/** The write was made locally but could not be confirmed as sent. */
+export function flushTimeout(roomId: string): EditorFailure {
+  return {
+    ok: false,
+    code: 'flush_timeout',
+    roomId,
+    message:
+      `The edit could not be confirmed as saved within the time limit — treat ` +
+      `it as NOT applied. Tell the user the document service is not responding ` +
+      `and they can retry shortly. Do not claim the edit succeeded.`,
+  };
+}
+
+/**
+ * Nothing to act on: no document is open and the call named no `room_id`.
+ * Distinct from `not_a_member` — there is no room to be a member of yet.
+ */
+export function noDocument(): EditorFailure {
+  return {
+    ok: false,
+    code: 'no_document',
+    message:
+      'No document is open and no room_id was given. Pass the room id of the ' +
+      'document to work on (find it with list_workspace_pages), or create one ' +
+      'with create_page_room and pass the id it returns.',
+  };
+}
+
+/** Anything unexpected. Kept distinct so the agent does not misread it as a policy refusal. */
+export function editorError(message: string, roomId?: string): EditorFailure {
+  return { ok: false, code: 'error', message, ...(roomId && { roomId }) };
+}

package/src/plugins/editor/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Editor plugin barrel — statically LIGHT by contract.
+ *
+ * This barrel is re-exported from `src/plugins/index.ts`, which is evaluated
+ * at Worker module scope. Nothing here may (transitively) import
+ * `@ixo/matrix-crdt` / `@blocknote/server-util` / `@ixo/editor`: vscode-lib
+ * (inside matrix-crdt) schedules a timer at module-evaluation time, which
+ * workerd forbids in global scope. The heavy tool chain
+ * (`standalone-editor-tool`, `content-tools`, `provider`, `blocknote-bridge`,
+ * `editor-mx`, `content-session`) is reached only via `await import()` inside
+ * `EditorPlugin.getRequestTools` — import those modules directly (not through
+ * this barrel) if you need them, and only from a request context.
+ */
+export { EditorPlugin, type EditorPluginOptions } from './editor.plugin';
+export { EDITOR_AGENT_NAME, EDITOR_AGENT_TOOL_NAME } from './editor-agent';
+export {
+  createEditorAccessDeniedTool,
+  type EditorAccessDeniedToolOptions,
+} from './editor-access-denied-tool';
+export {
+  buildBlocknoteToolsConfig,
+  type BlocknoteToolsConfig,
+  type BlocknoteToolsMatrixConfig,
+} from './editor-config';
+export {
+  GRANT_ACCESS_TOOL,
+  isEditorFailure,
+  type EditorFailure,
+  type EditorFailureCode,
+} from './failures';
+export { isUserInRoom, invalidateRoomMembership } from './room-membership';

package/src/plugins/editor/jsdom-shim.ts

@@ -0,0 +1,55 @@
+/**
+ * Drop-in replacement for the `jsdom` package on workerd, backed by linkedom.
+ *
+ * `@blocknote/server-util` does `import * as jsdom from 'jsdom'` and
+ * `new jsdom.JSDOM()` purely to get a `window`/`document` pair it can swap
+ * onto `globalThis` while BlockNote's markdown/HTML parsing runs. Real jsdom
+ * cannot load on workerd (it needs `node:vm` script contexts, which
+ * nodejs_compat only stubs), so the module specifier `jsdom` is aliased to
+ * this file — in `vitest.config.ts` (`resolve.alias`) and
+ * `test/wrangler.test.jsonc` (`alias`) for tests, and deploying hosts must
+ * carry the same `alias` entry in their wrangler config.
+ *
+ * linkedom implements the exact DOM surface the BlockNote parse path touches
+ * (`createElement`, `innerHTML`, `querySelectorAll` with `>`/`+` combinators,
+ * `insertAdjacentElement`, prosemirror-model's `DOMParser.parse` walk) with
+ * one gap: `document.implementation.createHTMLDocument`, which BlockNote's
+ * `nestedListsToBlockNoteStructure` uses to build a detached document. The
+ * constructor polyfills it with a fresh linkedom document.
+ */
+import { parseHTML } from 'linkedom';
+
+const EMPTY_PAGE =
+  '<!doctype html><html><head><title>jsdom-shim</title></head><body></body></html>';
+
+interface DomImplementationLike {
+  createHTMLDocument(title?: string): unknown;
+}
+
+/**
+ * The `jsdom.JSDOM` surface `@blocknote/server-util` consumes: a constructible
+ * class exposing `window` (with `document` on it). Nothing else from jsdom's
+ * API is provided — BlockNote's server path never touches it.
+ */
+export class JSDOM {
+  readonly window: ReturnType<typeof parseHTML>;
+
+  constructor(html: string = EMPTY_PAGE) {
+    const { window } = parseHTML(html);
+    const doc = window.document;
+    if (!doc.implementation) {
+      const implementation: DomImplementationLike = {
+        createHTMLDocument(title = '') {
+          return parseHTML(
+            `<!doctype html><html><head><title>${title}</title></head><body></body></html>`,
+          ).document;
+        },
+      };
+      Object.defineProperty(doc, 'implementation', {
+        value: implementation,
+        configurable: true,
+      });
+    }
+    this.window = window;
+  }
+}