@mh-gg/base-plugins 0.1.1-alpha.20260613T085325975Z

package/src/shared/embed.cjs

@@ -0,0 +1,82 @@
+const { optionalString } = require("./validation.cjs");
+const { hostEndsWith, hostIs, normalizeUrl } = require("./url.cjs");
+
+function optionalTitle(value, fallback = null) {
+  return optionalString(value, "title", 180) || fallback;
+}
+
+function defineMarkdownPlugin(plugin) {
+  if (!plugin || typeof plugin !== "object") throw new Error("Markdown plugin is required");
+  if (!plugin.id || !plugin.provider) throw new Error("Markdown plugin id and provider are required");
+  if (typeof plugin.matchUrl !== "function") throw new Error(`${plugin.id} matchUrl is required`);
+  if (typeof plugin.toEmbed !== "function") throw new Error(`${plugin.id} toEmbed is required`);
+  return Object.freeze({ ...plugin });
+}
+
+function createEmbedRecord({ provider, kind = "link", title, url, embedUrl, thumbnailUrl, externalUrl, renderMode = "card", metadata = {} }) {
+  const cleanUrl = normalizeUrl(url);
+  return Object.freeze({
+    provider,
+    kind,
+    title: optionalTitle(title, provider),
+    url: cleanUrl,
+    externalUrl: externalUrl ? normalizeUrl(externalUrl) : cleanUrl,
+    ...(embedUrl ? { embedUrl: normalizeUrl(embedUrl) } : {}),
+    ...(thumbnailUrl ? { thumbnailUrl: normalizeUrl(thumbnailUrl) } : {}),
+    renderMode,
+    metadata: Object.freeze({ ...metadata })
+  });
+}
+
+function mediaKindFromPath(pathname) {
+  const lower = pathname.toLowerCase();
+  if (/\.(?:png|jpe?g|webp|gif|avif|svg)(?:$|[?#])/.test(lower)) return "image";
+  if (/\.(?:mp4|webm|mov|m4v)(?:$|[?#])/.test(lower)) return "video";
+  if (/\.(?:mp3|wav|ogg|m4a|flac)(?:$|[?#])/.test(lower)) return "audio";
+  if (/\.(?:pdf)(?:$|[?#])/.test(lower)) return "document";
+  return "file";
+}
+
+function directRenderMode(kind) {
+  if (kind === "image") return "image";
+  if (kind === "video") return "video";
+  if (kind === "audio") return "audio";
+  if (kind === "document") return "file-preview";
+  return "card";
+}
+
+function simpleProvider({ id, provider, aliases = [], hosts = [], hostSuffixes = [], kind = "link", title, renderMode = "card", metadata = {}, matchPath, embedUrl, thumbnailUrl, externalUrl }) {
+  return defineMarkdownPlugin({
+    id,
+    provider,
+    aliases,
+    matchUrl(url) {
+      const hostMatches = hosts.length ? hostIs(url, hosts) : false;
+      const suffixMatches = hostSuffixes.length ? hostEndsWith(url, hostSuffixes) : false;
+      if (!hostMatches && !suffixMatches) return false;
+      if (typeof matchPath === "function") return Boolean(matchPath(new URL(url)));
+      return true;
+    },
+    toEmbed(url, ctx = {}) {
+      const parsed = new URL(url);
+      const resolvedKind = typeof kind === "function" ? kind(parsed) : kind;
+      const resolvedEmbedUrl = typeof embedUrl === "function" ? embedUrl(parsed) : embedUrl;
+      const resolvedThumbnailUrl = typeof thumbnailUrl === "function" ? thumbnailUrl(parsed) : thumbnailUrl;
+      const resolvedExternalUrl = typeof externalUrl === "function" ? externalUrl(parsed) : externalUrl;
+      const resolvedMetadata = typeof metadata === "function" ? metadata(parsed) : metadata;
+      return createEmbedRecord({
+        provider,
+        kind: resolvedKind,
+        title: ctx.title || (typeof title === "function" ? title(parsed) : title) || provider,
+        url,
+        ...(resolvedEmbedUrl ? { embedUrl: resolvedEmbedUrl } : {}),
+        ...(resolvedThumbnailUrl ? { thumbnailUrl: resolvedThumbnailUrl } : {}),
+        ...(resolvedExternalUrl ? { externalUrl: resolvedExternalUrl } : {}),
+        renderMode: typeof renderMode === "function" ? renderMode(parsed, resolvedKind) : renderMode,
+        metadata: { host: parsed.hostname.toLowerCase(), ...resolvedMetadata }
+      });
+    }
+  });
+}
+
+module.exports = { createEmbedRecord, defineMarkdownPlugin, directRenderMode, mediaKindFromPath, optionalTitle, simpleProvider };

package/src/shared/index.cjs

@@ -0,0 +1,20 @@
+const { allow, createOperationSchemaDescriptor, defineHostPlugin, deny } = require("@mh-gg/host-runtime");
+const constants = require("./constants.cjs");
+const embed = require("./embed.cjs");
+const roles = require("./roles.cjs");
+const scopes = require("./scopes.cjs");
+const url = require("./url.cjs");
+const validation = require("./validation.cjs");
+
+module.exports = {
+  ...constants,
+  ...embed,
+  ...roles,
+  ...scopes,
+  ...url,
+  ...validation,
+  allow,
+  createOperationSchemaDescriptor,
+  defineHostPlugin,
+  deny
+};

package/src/shared/roles.cjs

@@ -0,0 +1,5 @@
+const { roleAtLeast } = require("./validation.cjs");
+function memberOrBetter(actor) { return roleAtLeast(actor, ["owner", "admin", "moderator", "member"]); }
+function moderatorOrBetter(actor) { return roleAtLeast(actor, ["owner", "admin", "moderator"]); }
+function adminOrOwner(actor) { return roleAtLeast(actor, ["owner", "admin"]); }
+module.exports = { adminOrOwner, memberOrBetter, moderatorOrBetter, roleAtLeast };

package/src/shared/scopes.cjs

@@ -0,0 +1,15 @@
+const { object, string } = require("./validation.cjs");
+
+function scopePayload(payload, name = "scope") {
+  const value = object(payload, name);
+  return {
+    scopeType: string(value.scopeType, "scopeType", 80),
+    scopeId: string(value.scopeId, "scopeId", 180)
+  };
+}
+
+function scopeKey(scopeType, scopeId) {
+  return `${encodeURIComponent(scopeType)}:${encodeURIComponent(scopeId)}`;
+}
+
+module.exports = { scopeKey, scopePayload };

package/src/shared/url.cjs

@@ -0,0 +1,32 @@
+const { string } = require("./validation.cjs");
+const { MAX_EMBED_URL_BYTES } = require("./constants.cjs");
+
+function normalizeUrl(raw, { allowHttpLocalhost = true } = {}) {
+  const value = string(raw, "url", MAX_EMBED_URL_BYTES);
+  let parsed;
+  try { parsed = new URL(value); } catch { throw new Error("url must be a valid URL"); }
+  if (parsed.protocol !== "https:") {
+    const local = parsed.protocol === "http:" && allowHttpLocalhost && ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
+    if (!local) throw new Error("url must use https unless it is localhost");
+  }
+  parsed.hash = "";
+  return parsed.toString();
+}
+
+function safeHostname(url) {
+  try { return new URL(url).hostname.toLowerCase().replace(/^www\./, ""); } catch { return ""; }
+}
+function hostOf(url) { return safeHostname(url); }
+function hostIs(url, hosts) { return hosts.includes(hostOf(url)); }
+function hostEndsWith(url, suffixes) { const host = hostOf(url); return suffixes.some((suffix) => host === suffix || host.endsWith(`.${suffix}`)); }
+function pathParts(url) { return new URL(url).pathname.split("/").filter(Boolean).map((part) => decodeURIComponent(part)); }
+function cleanId(value, max = 120) { return String(value || "").replace(/[^A-Za-z0-9._~-]/g, "").slice(0, max); }
+function firstMatch(patterns, value) {
+  for (const pattern of patterns) {
+    const match = value.match(pattern);
+    if (match) return match;
+  }
+  return null;
+}
+
+module.exports = { cleanId, firstMatch, hostEndsWith, hostIs, hostOf, normalizeUrl, pathParts, safeHostname };

package/src/shared/validation.cjs

@@ -0,0 +1,31 @@
+const { isSnowflakeId, prefixedSnowflakeId, snowflakeIdForOperation } = require("@mh-gg/protocol");
+
+function clone(value) { return value === undefined ? undefined : JSON.parse(JSON.stringify(value)); }
+function object(value, name) { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`); return value; }
+function array(value, name) { if (!Array.isArray(value)) throw new Error(`${name} must be an array`); return value; }
+function string(value, name, max = 1000) { if (typeof value !== "string") throw new Error(`${name} must be a string`); const trimmed = value.trim(); if (!trimmed) throw new Error(`${name} must be a non-empty string`); if (trimmed.length > max) throw new Error(`${name} is too long`); return trimmed; }
+function optionalString(value, name, max = 1000) { if (value === undefined || value === null || value === "") return null; return string(String(value), name, max); }
+function number(value, name, options = {}) { const parsed = Number(value); if (!Number.isFinite(parsed)) throw new Error(`${name} must be a finite number`); if (options.min !== undefined && parsed < options.min) throw new Error(`${name} must be >= ${options.min}`); if (options.max !== undefined && parsed > options.max) throw new Error(`${name} must be <= ${options.max}`); return parsed; }
+function enumValue(value, name, allowed) { if (!allowed.includes(value)) throw new Error(`${name} must be one of ${allowed.join(", ")}`); return value; }
+function boolean(value) { return Boolean(value); }
+function roleAtLeast(actor, roles) { return actor && roles.includes(actor.role); }
+function displayText(value, max) {
+  if (typeof value !== "string") return "";
+  const cleaned = value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  return cleaned.length > max ? cleaned.slice(0, max) : cleaned;
+}
+function actorName(actor) { return displayText(actor?.displayName, 80) || displayText(actor?.memberId, 120) || "Unknown"; }
+function sanitizeId(value) { return String(value || "").replace(/[^a-zA-Z0-9_-]/g, "_"); }
+function entityId(prefix, op) {
+  if (op && typeof op === "object") {
+    const ledgerId = op.ledgerId || op.snowflakeId;
+    if (ledgerId && isSnowflakeId(ledgerId)) return prefixedSnowflakeId(prefix, ledgerId);
+    return prefixedSnowflakeId(prefix, snowflakeIdForOperation(op));
+  }
+  if (isSnowflakeId(op)) return prefixedSnowflakeId(prefix, op);
+  return `${prefix}_${sanitizeId(op)}`;
+}
+function activity(state, op, message, extra = {}) { return [...(state.activity || []), { id: entityId("activity", op), actorId: op.actor.memberId, actorName: actorName(op.actor), operationId: op.id, ledgerId: op.ledgerId, message, createdAt: op.createdAt, ...extra }]; }
+function readonlyState(state) { return clone(state); }
+function parseMaybeJsonList(value, name) { if (value === undefined || value === null) return []; if (!Array.isArray(value)) throw new Error(`${name} must be an array`); return value.map((entry, index) => string(entry, `${name}[${index}]`, 80)); }
+module.exports = { activity, actorName, array, boolean, clone, entityId, enumValue, number, object, optionalString, parseMaybeJsonList, readonlyState, roleAtLeast, string };

package/test/composable-plugins.test.cjs

@@ -0,0 +1,170 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { manifestHash } = require("@mh-gg/base");
+const { createMemoryOperationLog, createMemoryRoomStore, HostPluginRuntime } = require("@mh-gg/host-runtime");
+const { buildExampleMatterhornApp, createExampleActor, createExampleOperationFactory } = require("../../../examples/_shared/matterhornExample/index.cjs");
+const {
+  COMMENTS_PLUGIN_ID,
+  MEDIA_ROOMS_PLUGIN_ID,
+  PRESENCE_PLUGIN_ID,
+  SCREEN_SHARE_PLUGIN_ID,
+  MARKDOWN_PLUGIN_ID,
+  EMBEDS_PLUGIN_ID,
+  ATTACHMENTS_PLUGIN_ID,
+  FILES_PLUGIN_ID,
+  REACTIONS_PLUGIN_ID,
+  LABELS_PLUGIN_ID,
+  LOCATION_PINS_PLUGIN_ID,
+  APPROVALS_PLUGIN_ID,
+  CHECKLISTS_PLUGIN_ID,
+  CALENDAR_PLUGIN_ID,
+  appCapabilitySet,
+  commentsHostPlugin,
+  composeHostPluginEntries,
+  createCollaborationPluginSuite,
+  getReusablePluginEntry,
+  mediaRoomsHostPlugin,
+  presenceHostPlugin,
+  screenShareHostPlugin
+} = require("../src/index.cjs");
+
+const fullSuite = createCollaborationPluginSuite("all");
+
+const built = buildExampleMatterhornApp({
+  slug: "composable",
+  packageName: "@mh-gg/example-composable-test",
+  appId: "com.matterhorn.examples.composable-test",
+  name: "Composable Test",
+  version: "1.0.0",
+  hostPlugins: [fullSuite],
+  appCapabilities: { required: ["room.state", "room.roles", "comments.threaded", "media.voice", "media.video", "media.screen-share"], optional: [] },
+  hostCapabilities: { required: ["room.state", "room.roles"], optional: ["media.sfu"] }
+});
+
+function opFactory(roomId = "room_composable") {
+  return createExampleOperationFactory({ appPack: built.appPack, hostPlugin: commentsHostPlugin, roomId, actor: createExampleActor({ memberId: "admin", role: "admin", displayName: "Admin" }), startTime: 1000 });
+}
+
+async function runtime(roomId = "room_composable") {
+  const rt = new HostPluginRuntime({
+    room: { id: roomId, appPack: { id: built.appPack.id, version: built.appPack.version, hash: manifestHash(built.appPack), protocolHash: built.appPack.compatibility.appProtocolHash } },
+    plugins: fullSuite.plugins,
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (auth, actor) => {
+      assert.equal(auth.signature, "sig");
+      return actor;
+    }
+  });
+  await rt.start();
+  return rt;
+}
+
+async function rejected(promise, pattern) {
+  const result = await promise;
+  assert.equal(result.ok, false);
+  assert.match(result.reason, pattern);
+}
+
+test("reusable plugin package exposes composable host plugins", () => {
+  assert.deepEqual(fullSuite.pluginIds, [
+    COMMENTS_PLUGIN_ID,
+    PRESENCE_PLUGIN_ID,
+    MEDIA_ROOMS_PLUGIN_ID,
+    SCREEN_SHARE_PLUGIN_ID,
+    MARKDOWN_PLUGIN_ID,
+    EMBEDS_PLUGIN_ID,
+    ATTACHMENTS_PLUGIN_ID,
+    FILES_PLUGIN_ID,
+    REACTIONS_PLUGIN_ID,
+    LABELS_PLUGIN_ID,
+    APPROVALS_PLUGIN_ID,
+    CHECKLISTS_PLUGIN_ID,
+    CALENDAR_PLUGIN_ID,
+    LOCATION_PINS_PLUGIN_ID
+  ]);
+  assert.deepEqual(built.hostPack.plugins.map((plugin) => plugin.id), fullSuite.pluginIds);
+  assert.deepEqual(built.playerPack.supports[0].pluginIds, built.hostPluginDescriptors.map((plugin) => plugin.id));
+});
+
+test("comments plugin can attach threads to arbitrary app scopes", async () => {
+  const rt = await runtime();
+  const op = opFactory();
+  await rt.handleOperation(op("comments.thread.create", { scopeType: "card", scopeId: "card_1", title: "Card discussion" }, { id: "c_1", pluginId: COMMENTS_PLUGIN_ID }));
+  await rt.handleOperation(op("comments.add", { scopeType: "card", scopeId: "card_1", body: "Looks good" }, { id: "c_2", pluginId: COMMENTS_PLUGIN_ID, actor: createExampleActor({ memberId: "mina", role: "member", displayName: "Mina" }) }));
+  const state = await rt.getState();
+  const comment = Object.values(state.plugins[COMMENTS_PLUGIN_ID].comments)[0];
+  await rt.handleOperation(op("comments.react", { commentId: comment.id, emoji: "✅" }, { id: "c_3", pluginId: COMMENTS_PLUGIN_ID, actor: createExampleActor({ memberId: "lee", role: "member", displayName: "Lee" }) }));
+  const scoped = await rt.query(COMMENTS_PLUGIN_ID, "commentsForScope", { scopeType: "card", scopeId: "card_1" }, createExampleActor({ memberId: "mina", role: "member" }));
+  assert.equal(scoped.threads[0].title, "Card discussion");
+  assert.equal(scoped.comments[0].body, "Looks good");
+  assert.deepEqual(scoped.comments[0].reactions["✅"], ["lee"]);
+});
+
+test("comments permissions protect edits and deletes", async () => {
+  const rt = await runtime();
+  const op = opFactory();
+  await rt.handleOperation(op("comments.add", { scopeType: "wiki-page", scopeId: "page_1", body: "draft note" }, { id: "p_1", pluginId: COMMENTS_PLUGIN_ID, actor: createExampleActor({ memberId: "mina", role: "member" }) }));
+  const state = await rt.getState();
+  const commentId = Object.keys(state.plugins[COMMENTS_PLUGIN_ID].comments)[0];
+  await rejected(rt.handleOperation(op("comments.edit", { commentId, body: "hijack" }, { id: "p_2", pluginId: COMMENTS_PLUGIN_ID, actor: createExampleActor({ memberId: "guest", role: "guest" }) })), /Members only|requires member/);
+  await rejected(rt.handleOperation(op("comments.delete", { commentId }, { id: "p_3", pluginId: COMMENTS_PLUGIN_ID, actor: createExampleActor({ memberId: "lee", role: "member" }) })), /Only authors or moderators/);
+});
+
+test("presence plugin tracks reusable user state", async () => {
+  const rt = await runtime();
+  const op = opFactory();
+  await rt.handleOperation(op("presence.update", { status: "online", activity: "reviewing budget" }, { id: "presence_1", pluginId: PRESENCE_PLUGIN_ID, actor: createExampleActor({ memberId: "mina", role: "member", displayName: "Mina" }) }));
+  await rt.handleOperation(op("presence.update", { status: "busy", activity: "screen sharing" }, { id: "presence_2", pluginId: PRESENCE_PLUGIN_ID, actor: createExampleActor({ memberId: "lee", role: "member", displayName: "Lee" }) }));
+  const online = await rt.query(PRESENCE_PLUGIN_ID, "onlineMembers", {}, createExampleActor({ memberId: "admin", role: "admin" }));
+  assert.deepEqual(online.map((member) => `${member.name}:${member.status}`), ["Lee:busy", "Mina:online"]);
+});
+
+test("media rooms and screen-share plugins are independent but compose around the same scope", async () => {
+  const rt = await runtime();
+  const op = opFactory();
+  await rt.handleOperation(op("media.room.create", { name: "Design review", allowsVideo: true, scopeType: "kanban-card", scopeId: "card_42" }, { id: "media_1", pluginId: MEDIA_ROOMS_PLUGIN_ID }));
+  const roomId = Object.keys((await rt.getState()).plugins[MEDIA_ROOMS_PLUGIN_ID].rooms)[0];
+  await rt.handleOperation(op("media.room.join", { roomId, media: { audio: true, video: true } }, { id: "media_2", pluginId: MEDIA_ROOMS_PLUGIN_ID, actor: createExampleActor({ memberId: "mina", role: "member", displayName: "Mina" }) }));
+  await rt.handleOperation(op("screenshare.start", { roomId, scopeType: "kanban-card", scopeId: "card_42", title: "Card walkthrough" }, { id: "share_1", pluginId: SCREEN_SHARE_PLUGIN_ID, actor: createExampleActor({ memberId: "mina", role: "member", displayName: "Mina" }) }));
+  const rooms = await rt.query(MEDIA_ROOMS_PLUGIN_ID, "roomDirectory", {}, createExampleActor({ memberId: "admin", role: "admin" }));
+  const shares = await rt.query(SCREEN_SHARE_PLUGIN_ID, "activeShares", { scopeType: "kanban-card", scopeId: "card_42" }, createExampleActor({ memberId: "admin", role: "admin" }));
+  assert.equal(rooms[0].participantCount, 1);
+  assert.equal(shares[0].title, "Card walkthrough");
+  await rejected(rt.handleOperation(op("screenshare.stop", { shareId: shares[0].id }, { id: "share_2", pluginId: SCREEN_SHARE_PLUGIN_ID, actor: createExampleActor({ memberId: "sam", role: "member" }) })), /Only presenter or moderators/);
+});
+
+
+test("collaboration plugin suites normalize ordering, capabilities, and plugin entries", () => {
+  const suite = createCollaborationPluginSuite(["screenShare", "comments", "mediaRooms"]);
+  assert.deepEqual(suite.selection, ["comments", "mediaRooms", "screenShare"]);
+  assert.deepEqual(suite.pluginIds, [COMMENTS_PLUGIN_ID, MEDIA_ROOMS_PLUGIN_ID, SCREEN_SHARE_PLUGIN_ID]);
+  assert.equal(suite.hasCapability("media.voice"), true);
+  assert.equal(suite.hasCapability("media.screen-share"), true);
+
+  const commentsOnly = createCollaborationPluginSuite("comments");
+  assert.deepEqual(commentsOnly.pluginIds, [COMMENTS_PLUGIN_ID]);
+  assert.deepEqual(commentsOnly.capabilities.provides, ["comments.attachable", "comments.reactions", "comments.threaded"]);
+
+  const deduped = composeHostPluginEntries(commentsOnly, getReusablePluginEntry("comments"));
+  assert.equal(deduped.length, 1);
+  assert.equal(deduped[0].plugin.id, COMMENTS_PLUGIN_ID);
+});
+
+test("collaboration app capability sets include selected suite capabilities", () => {
+  const suite = createCollaborationPluginSuite(["mediaRooms", "screenShare"]);
+  const capabilities = appCapabilitySet({ suites: [suite], optional: ["relay.event-cache"] });
+  assert.deepEqual(capabilities.required, ["relay.route", "room.roles", "room.state"]);
+  assert.equal(capabilities.optional.includes("media.voice"), true);
+  assert.equal(capabilities.optional.includes("media.video"), true);
+  assert.equal(capabilities.optional.includes("media.screen-share"), true);
+  assert.equal(capabilities.optional.includes("relay.event-cache"), true);
+});
+
+test("collaboration composer rejects unknown selections and conflicting versions", () => {
+  assert.throws(() => createCollaborationPluginSuite(["missing-plugin"]), /Unknown reusable plugin selection/);
+  assert.throws(() => composeHostPluginEntries(
+    getReusablePluginEntry("comments"),
+    { plugin: { ...commentsHostPlugin, version: "9.9.9" }, packageName: "test", exportName: "commentsHostPlugin" }
+  ), /Conflicting versions for plugin/);
+});

package/test/crdt-plugin.test.cjs

@@ -0,0 +1,168 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { buildExampleMatterhornApp, createExampleActor, createExampleOperationFactory, createExampleRuntime } = require("../../../examples/_shared/matterhornExample/index.cjs");
+const {
+  CRDT_CURSOR_CLEAR_TYPE,
+  CRDT_CURSOR_UPDATE_TYPE,
+  CRDT_DOCUMENT_CHANGE_TYPE,
+  CRDT_PLUGIN_ID,
+  MATTERHORN_CRDT_NOSTR_KIND,
+  crdtHostPlugin,
+  createCollaborationPluginSuite,
+  getReusablePlugin
+} = require("../src/index.cjs");
+const { finalizeEvent } = require("nostr-tools/pure");
+
+const roomId = "room_crdt_test";
+const documentId = "doc_main";
+const actorA = createExampleActor({ memberId: "alice", deviceId: "dev_alice", role: "member", displayName: "Alice" });
+const actorB = createExampleActor({ memberId: "bob", deviceId: "dev_bob", role: "member", displayName: "Bob" });
+
+const built = buildExampleMatterhornApp({
+  slug: "crdt-plugin",
+  packageName: "@mh-gg/base-plugins",
+  appId: "com.matterhorn.tests.crdt-plugin",
+  name: "CRDT Plugin Test",
+  version: "1.0.0",
+  hostPlugin: crdtHostPlugin
+});
+
+function fakeEncrypt(kind, value) {
+  return {
+    encrypted: true,
+    alg: "A256GCM",
+    kind,
+    iv: "test-iv",
+    data: Buffer.from(JSON.stringify(value), "utf8").toString("base64url")
+  };
+}
+
+function fakeDecrypt(kind, payload) {
+  assert.equal(payload.kind, kind);
+  return JSON.parse(Buffer.from(payload.data, "base64url").toString("utf8"));
+}
+
+function opFactory(actor = actorA) {
+  return createExampleOperationFactory({ appPack: built.appPack, hostPlugin: crdtHostPlugin, roomId, actor, startTime: 1700000000000 });
+}
+
+function pluginState(state) {
+  return state.plugins[CRDT_PLUGIN_ID];
+}
+
+test("CRDT plugin is explicit and does not replace the default reusable suite", () => {
+  const fullSuite = createCollaborationPluginSuite("all");
+  assert.equal(fullSuite.pluginIds.includes(CRDT_PLUGIN_ID), false);
+  assert.equal(getReusablePlugin("crdt").id, CRDT_PLUGIN_ID);
+
+  const crdtSuite = createCollaborationPluginSuite(["crdt"]);
+  assert.deepEqual(crdtSuite.selection, ["crdt"]);
+  assert.deepEqual(crdtSuite.pluginIds, [CRDT_PLUGIN_ID]);
+});
+
+test("CRDT host plugin stores opaque encrypted events and clients resolve document changes", async () => {
+  const {
+    applyDocumentChangeEvent,
+    createCrdtEventKey,
+    createDocumentChangeEvent,
+    createSharedTextDocument
+  } = await import("../src/crdt/client.mjs");
+  const runtime = createExampleRuntime({ appPack: built.appPack, hostPlugin: crdtHostPlugin, roomId });
+  const makeA = opFactory(actorA);
+  const keyA = createCrdtEventKey();
+  const keyB = createCrdtEventKey();
+
+  const left = createSharedTextDocument();
+  const right = createSharedTextDocument();
+  left.replaceText("Hello from Alice");
+  const firstEvent = await createDocumentChangeEvent({
+    document: left,
+    roomName: roomId,
+    documentId,
+    privateKey: keyA,
+    createdAt: 1700000001000,
+    encryptRoomPayload: fakeEncrypt
+  });
+
+  const firstResult = await runtime.handleOperation(makeA(CRDT_DOCUMENT_CHANGE_TYPE, { documentId, event: firstEvent }, { id: "crdt_1" }));
+  assert.equal(firstResult.ok, true);
+  const afterFirst = pluginState(await runtime.getState());
+  assert.equal(JSON.stringify(afterFirst).includes("Hello from Alice"), false);
+
+  const changes = await runtime.query(CRDT_PLUGIN_ID, "documentChanges", { documentId }, actorB);
+  assert.equal(changes.length, 1);
+  await applyDocumentChangeEvent({ document: right, event: changes[0].event, decryptRoomPayload: fakeDecrypt });
+  assert.equal(right.getText(), "Hello from Alice");
+
+  right.replaceText("Hello from Bob");
+  const secondEvent = await createDocumentChangeEvent({
+    document: right,
+    roomName: roomId,
+    documentId,
+    privateKey: keyB,
+    createdAt: 1700000002000,
+    encryptRoomPayload: fakeEncrypt
+  });
+  const makeB = opFactory(actorB);
+  const secondResult = await runtime.handleOperation(makeB(CRDT_DOCUMENT_CHANGE_TYPE, { documentId, event: secondEvent }, { id: "crdt_2" }));
+  assert.equal(secondResult.ok, true);
+
+  await applyDocumentChangeEvent({ document: left, event: secondEvent, decryptRoomPayload: fakeDecrypt });
+  assert.equal(left.getText(), right.getText());
+  assert.equal(left.getText(), "Hello from Bob");
+});
+
+test("CRDT cursor updates stay encrypted until a client decrypts them", async () => {
+  const { createCrdtEventKey, createCursorEvent, readCursorEvent } = await import("../src/crdt/client.mjs");
+  const runtime = createExampleRuntime({ appPack: built.appPack, hostPlugin: crdtHostPlugin, roomId });
+  const event = await createCursorEvent({
+    roomName: roomId,
+    documentId,
+    privateKey: createCrdtEventKey(),
+    createdAt: 1700000003000,
+    encryptRoomPayload: fakeEncrypt,
+    cursor: { anchor: 2, head: 5, color: "oklch(58% 0.16 28)" }
+  });
+
+  const result = await runtime.handleOperation(opFactory(actorA)(CRDT_CURSOR_UPDATE_TYPE, { documentId, event }, { id: "cursor_1" }));
+  assert.equal(result.ok, true);
+  const state = pluginState(await runtime.getState());
+  assert.equal(JSON.stringify(state).includes("anchor"), false);
+
+  const cursors = await runtime.query(CRDT_PLUGIN_ID, "documentCursors", { documentId }, actorB);
+  assert.equal(cursors.length, 1);
+  const cursor = await readCursorEvent({ event: cursors[0].event, decryptRoomPayload: fakeDecrypt });
+  assert.deepEqual(cursor, { anchor: 2, head: 5, color: "oklch(58% 0.16 28)" });
+
+  const cleared = await runtime.handleOperation(opFactory(actorA)(CRDT_CURSOR_CLEAR_TYPE, { documentId }, { id: "cursor_clear_1" }));
+  assert.equal(cleared.ok, true);
+  assert.deepEqual(await runtime.query(CRDT_PLUGIN_ID, "documentCursors", { documentId }, actorB), []);
+});
+
+test("CRDT host rejects signed events with invalid encrypted content", async () => {
+  const { createCrdtEventKey } = await import("../src/crdt/client.mjs");
+  const runtime = createExampleRuntime({ appPack: built.appPack, hostPlugin: crdtHostPlugin, roomId });
+  const event = finalizeEvent({
+    kind: MATTERHORN_CRDT_NOSTR_KIND,
+    created_at: 1700000010,
+    tags: [
+      ["protocol", "matterhorn-sdk"],
+      ["version", "1"],
+      ["d", roomId],
+      ["crdt-doc", documentId],
+      ["crdt-kind", CRDT_DOCUMENT_CHANGE_TYPE],
+      ["created-at-ms", "1700000010000"]
+    ],
+    content: "not-json"
+  }, createCrdtEventKey());
+
+  const rejected = await runtime.handleOperation(opFactory(actorA)(CRDT_DOCUMENT_CHANGE_TYPE, { documentId, event }, { id: "crdt_bad_content" }));
+  assert.equal(rejected.ok, false);
+  assert.match(rejected.reason, /content must be JSON/);
+});
+
+test("CRDT reducer leaves unsupported direct operation types unchanged", async () => {
+  const state = await crdtHostPlugin.createInitialState({ room: { id: roomId } });
+  const next = await crdtHostPlugin.reduce({ room: { id: roomId } }, state, { type: "unknown", payload: {}, actor: actorA, createdAt: 1 });
+  assert.equal(next, state);
+});