collabmd 0.1.49 → 0.1.52

package/src/server/domain/collaboration/collaboration-room.js

@@ -3,13 +3,14 @@ import * as awarenessProtocol from 'y-protocols/awareness';
 import * as syncProtocol from 'y-protocols/sync';
 import * as encoding from 'lib0/encoding';
 import * as decoding from 'lib0/decoding';
+import { setTimeout as delay } from 'node:timers/promises';
 
 import {
   MSG_AGENT_FLUSH,
   MSG_AGENT_FLUSH_ACK,
   MSG_AWARENESS,
   MSG_SYNC,
-} from './protocol.js';
+} from '../../../domain/collaboration-protocol.js';
 import { CollaborationDocumentStore } from './collaboration-document-store.js';
 import { logPerfEvent } from '../../config/perf-logging.js';
 import { populateCommentThreads, serializeCommentThreads } from '../../../domain/comment-threads.js';
@@ -31,6 +32,10 @@ import { normalizeEditableText } from '../../../domain/editable-text.js';
 import { normalizeWorkspaceEvent } from '../../../domain/workspace-change.js';
 import { WORKSPACE_EVENT_MAX_MESSAGES, WORKSPACE_ROOM_NAME } from '../../../domain/workspace-room.js';
 
+// Coalesce scroll-driven awareness bursts (cursor/viewport) into one broadcast.
+// Awareness updates are last-write-wins, so flushing the latest state is safe.
+const AWARENESS_BROADCAST_DEBOUNCE_MS = 30;
+
 function closeSlowClient(ws, clientState, { maxBufferedAmountBytes, name }) {
   if (!clientState || clientState.backpressureCloseIssued) {
     return false;
@@ -248,6 +253,8 @@ export class CollaborationRoom {
     };
     this.persistTimer = null;
     this.destroyTimer = null;
+    this.awarenessBroadcastTimer = null;
+    this.pendingAwarenessClientIds = new Set();
     this.finalizePromise = null;
     this.shutdownGeneration = 0;
 
@@ -275,7 +282,7 @@ export class CollaborationRoom {
 
         try {
           if (hydrateDelayMs > 0) {
-            await new Promise((resolve) => setTimeout(resolve, hydrateDelayMs));
+            await delay(hydrateDelayMs);
           }
 
           if (this.documentStore?.hasPersistence()) {
@@ -393,6 +400,10 @@ export class CollaborationRoom {
         this.schedulePersist();
       }
 
+      if (this.clients.size === 0) {
+        return;
+      }
+
       const encoder = encoding.createEncoder();
       encoding.writeVarUint(encoder, MSG_SYNC);
       syncProtocol.writeUpdate(encoder, update);
@@ -402,31 +413,53 @@ export class CollaborationRoom {
     });
 
     this.awareness.on('update', ({ added, updated, removed }) => {
-      const changedClientIds = added.concat(updated, removed);
+      for (const clientId of added.concat(updated, removed)) {
+        this.pendingAwarenessClientIds.add(clientId);
+      }
 
-      if (changedClientIds.length === 0) {
+      if (this.pendingAwarenessClientIds.size === 0 || this.awarenessBroadcastTimer) {
         return;
       }
 
-      const encoder = encoding.createEncoder();
-      encoding.writeVarUint(encoder, MSG_AWARENESS);
-      encoding.writeVarUint8Array(
-        encoder,
-        awarenessProtocol.encodeAwarenessUpdate(this.awareness, changedClientIds),
-      );
-      const message = encoding.toUint8Array(encoder);
-
-      this.broadcastToClients(message, { failureLabel: 'awareness update' });
+      this.awarenessBroadcastTimer = setTimeout(() => {
+        this.flushAwarenessBroadcast();
+      }, AWARENESS_BROADCAST_DEBOUNCE_MS);
+      this.awarenessBroadcastTimer.unref?.();
     });
   }
 
+  flushAwarenessBroadcast() {
+    clearTimeout(this.awarenessBroadcastTimer);
+    this.awarenessBroadcastTimer = null;
+
+    if (this.pendingAwarenessClientIds.size === 0 || this.destroyed || this.clients.size === 0) {
+      this.pendingAwarenessClientIds.clear();
+      return;
+    }
+
+    const changedClientIds = Array.from(this.pendingAwarenessClientIds);
+    this.pendingAwarenessClientIds.clear();
+
+    const encoder = encoding.createEncoder();
+    encoding.writeVarUint(encoder, MSG_AWARENESS);
+    encoding.writeVarUint8Array(
+      encoder,
+      awarenessProtocol.encodeAwarenessUpdate(this.awareness, changedClientIds),
+    );
+
+    this.broadcastToClients(encoding.toUint8Array(encoder), { failureLabel: 'awareness update' });
+  }
+
   registerContentDirtyListeners() {
     const markFromTransaction = (transaction) => {
       if (isContentCleanOrigin(transaction?.origin)) {
         return;
       }
 
-      this.refreshContentDirty();
+      // Fast path: observed content changed, so mark dirty without
+      // re-serializing the whole document per keystroke. persist() still
+      // compares against the baseline, so edit-then-undo stays clean.
+      this.contentDirty = true;
     };
 
     if (isExcalidrawRoom(this.name)) {
@@ -527,7 +560,10 @@ export class CollaborationRoom {
         console.warn(`[room:${this.name}] Skipping persist because the Excalidraw scene is invalid`);
         return;
       }
-      const includeContent = this.refreshContentDirty();
+      // Compare inline: refreshContentDirty() would serialize the document
+      // a second time for the same check.
+      const includeContent = content !== this.persistedContentBaseline;
+      this.contentDirty = includeContent;
       const commentThreads = serializeCommentThreads(this.doc.getArray('comments'));
       await this.documentStore.persistState({
         commentThreads,
@@ -537,7 +573,7 @@ export class CollaborationRoom {
       });
       if (includeContent) {
         this.persistedContentBaseline = content;
-        this.refreshContentDirty();
+        this.contentDirty = false;
       }
     })();
 
@@ -662,8 +698,10 @@ export class CollaborationRoom {
     this.shutdownGeneration += 1;
     clearTimeout(this.persistTimer);
     clearTimeout(this.destroyTimer);
+    clearTimeout(this.awarenessBroadcastTimer);
     this.persistTimer = null;
     this.destroyTimer = null;
+    this.awarenessBroadcastTimer = null;
   }
 
   markDeleted() {

package/src/server/domain/docx-exporter.js

@@ -1,6 +1,40 @@
+import { createRequire } from 'node:module';
+
+import { mml2omml } from 'mathml2omml';
+
+// Use the converter's own parser dependency so both sides interpret HTML alike.
+const converterRequire = createRequire(import.meta.resolve('@turbodocx/html-to-docx'));
+const { Parser } = converterRequire('htmlparser2');
+const JSZip = converterRequire('jszip');
+const EMBEDDED_IMAGE_PATTERN = /^data:image\/(?:png|jpeg|gif|webp|svg\+xml);base64,[a-z0-9+/]+={0,2}$/i;
+const DOCX_MATH_KEY_PATTERN = /^COLLABMD-MATH-\d+$/;
+const MATHML_ANNOTATION_PATTERN = /<annotation\b[^>]*>[\s\S]*?<\/annotation>/g;
+// mpadded is purely presentational padding with no OMML equivalent; unwrap it
+// and let the supported children through instead of dropping the subtree.
+const MATHML_PADDED_PATTERN = /<mpadded\b[^>]*>([\s\S]*?)<\/mpadded>/g;
 const DOCX_EXPORTER_CREATOR = 'CollabMD';
 let converterPromise = null;
 
+function validateEmbeddedImages(html) {
+  let name = '';
+  const parser = new Parser({
+    onopentagname(tagName) {
+      name = tagName;
+    },
+    onattribute(attribute, value) {
+      // Inspect duplicates too: the converter preserves attribute case.
+      const isImageReference = attribute === 'src'
+        || ((name === 'image' || name === 'use') && (attribute === 'href' || attribute === 'xlink:href'));
+      if (isImageReference && !EMBEDDED_IMAGE_PATTERN.test(value) && !(name === 'use' && value.startsWith('#'))) {
+        const error = new Error('DOCX images must be embedded data URLs');
+        error.statusCode = 400;
+        throw error;
+      }
+    },
+  }, { decodeEntities: true });
+  parser.end(html);
+}
+
 function normalizeDocxBuffer(result) {
   if (Buffer.isBuffer(result)) {
     return result;
@@ -31,16 +65,230 @@ async function ensureConverter() {
   return converterPromise;
 }
 
+function collectDocxMath(html) {
+  // Markers are generated markup holding only text, so a flat open/text/close
+  // walk is enough; anything unexpected simply fails the key check below.
+  const equations = [];
+  let current = null;
+  const parser = new Parser({
+    onopentag(name, attribs = {}) {
+      if (current || name !== 'span') {
+        return;
+      }
+
+      const classes = String(attribs.class ?? '').split(/\s+/);
+      if (!classes.includes('export-math') || !attribs['data-mml']) {
+        return;
+      }
+
+      try {
+        const mml = decodeURIComponent(attribs['data-mml']);
+        if (mml.includes('<math')) {
+          current = { key: '', mml };
+        }
+      } catch {
+        current = null;
+      }
+    },
+    ontext(text) {
+      if (current) {
+        current.key += text;
+      }
+    },
+    onclosetag(name) {
+      if (name !== 'span' || !current) {
+        return;
+      }
+
+      const key = current.key.trim();
+      if (DOCX_MATH_KEY_PATTERN.test(key)) {
+        equations.push({ key, mml: current.mml });
+      }
+      current = null;
+    },
+  }, { decodeEntities: true });
+  parser.end(String(html ?? ''));
+  return equations;
+}
+
+function escapeDocxXml(text) {
+  return String(text ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// The OMML converter copies text content verbatim, so raw &/</> and HTML-only
+// entities such as &nbsp; would reach document.xml unescaped and break Word's
+// XML parsing. OMML output only uses m:/w: prefixed tags, so any other <
+// starts text.
+const OMML_TEXT_RUN_PATTERN = />([^<]*(?:<(?!\/?[A-Za-z][\w]*:)[^<]*)*)/g;
+
+function escapeOmmlTextContent(omml) {
+  return String(omml ?? '').replace(OMML_TEXT_RUN_PATTERN, (_match, text) => `>${
+    String(text ?? '')
+      .replace(/&(?!(?:amp|lt|gt|quot|apos|nbsp);|#\d+;|#x[\da-fA-F]+;)/g, '&amp;')
+      .replace(/&nbsp;/g, '&#160;')
+      .replace(/</g, '&lt;')
+  }`);
+}
+
+function extractMathmlAnnotation(mml) {
+  const match = String(mml ?? '').match(/<annotation\b[^>]*>([\s\S]*?)<\/annotation>/);
+  return match?.[1]?.trim() ?? '';
+}
+
+function deduplicateOmmlArgPr(omml) {
+  // The converter emits one m:argPr per transparent ancestor (mstyle, mrow),
+  // but OOXML allows at most one per argument. Adjacent duplicates are never
+  // legitimate, so collapse them; Word drops content after invalid markup.
+  // Both elements must be self-contained (self-closing or self-closing
+  // children only) so the match can never span a run or close tag.
+  const simpleArgPr = '<m:argPr\\b(?![^>]*\\/>)[^>]*>(?:<m:[a-zA-Z]+\\b[^>]*\\/>\\s*)*<\\/m:argPr>|<m:argPr\\b[^>]*\\/>';
+  const duplicatePattern = new RegExp(`(${simpleArgPr})\\s*(${simpleArgPr})`, 'g');
+  let previous = null;
+  let output = omml;
+  while (output !== previous) {
+    previous = output;
+    output = output.replace(duplicatePattern, '$1');
+  }
+  return output;
+}
+
+function convertMathmlToOmml(mml) {
+  try {
+    return escapeOmmlTextContent(deduplicateOmmlArgPr(mml2omml(
+      String(mml ?? '')
+        .replace(MATHML_ANNOTATION_PATTERN, '')
+        .replace(MATHML_PADDED_PATTERN, (_match, inner) => inner),
+    )));
+  } catch {
+    return null;
+  }
+}
+
+function findDocxParagraphStart(documentXml, index) {
+  // Plain lastIndexOf('<w:p') also matches <w:pPr> and <w:pStyle, so the
+  // character after the prefix must end the tag name.
+  let start = documentXml.lastIndexOf('<w:p', index);
+  while (start !== -1 && !/^[\s>/]/.test(documentXml[start + 4] ?? '')) {
+    start = documentXml.lastIndexOf('<w:p', start - 1);
+  }
+  return start;
+}
+
+function enclosingDocxParagraph(documentXml, index) {
+  const start = findDocxParagraphStart(documentXml, index);
+  if (start === -1) {
+    return null;
+  }
+
+  if (documentXml.lastIndexOf('</w:p>', index) > start) {
+    return null;
+  }
+
+  const end = documentXml.indexOf('</w:p>', index);
+  if (end === -1) {
+    return null;
+  }
+
+  const close = end + '</w:p>'.length;
+  return { end: close, start, xml: documentXml.slice(start, close) };
+}
+
+function isSoleMarkerParagraph(paragraphXml, key) {
+  const texts = [...paragraphXml.matchAll(/<w:t\b[^>]*>([^<]*)<\/w:t>/g)]
+    .map((match) => match[1])
+    .join('');
+  return texts === key;
+}
+
+// Display equations render as centered paragraphs: inline oMath shows in
+// Word, Docs, and Pages, while oMathPara blocks are dropped by several
+// renderers. The justification goes before run/section properties per the
+// OOXML paragraph-property order.
+const DOCX_CENTER_JUSTIFICATION = '<w:jc w:val="center"/>';
+
+function centerDocxParagraph(paragraphXml) {
+  if (/<w:jc\b/.test(paragraphXml)) {
+    return paragraphXml;
+  }
+
+  if (/<w:pPr\b[^>]*>/.test(paragraphXml)) {
+    return paragraphXml.replace(
+      /(<w:pPr\b[^>]*>)([\s\S]*?)(<(?:w:rPr|w:sectPr|w:pPrChange)\b|<\/w:pPr>)/,
+      `$1$2${DOCX_CENTER_JUSTIFICATION}$3`,
+    );
+  }
+
+  return paragraphXml.replace(/<w:p\b[^>]*>/, (match) => `${match}<w:pPr>${DOCX_CENTER_JUSTIFICATION}</w:pPr>`);
+}
+
+function replaceDocxMathMarker(documentXml, { fallbackTex, key, omml }) {
+  const fallbackRun = `<w:r><w:t xml:space="preserve">${escapeDocxXml(fallbackTex || key)}</w:t></w:r>`;
+  const runPattern = new RegExp(`<w:r\\b[^>]*>\\s*(?:<w:rPr\\b(?:/>|>[\\s\\S]*?</w:rPr>)\\s*)?<w:t\\b[^>]*>${key}</w:t>\\s*</w:r>`);
+  const runMatch = runPattern.exec(documentXml);
+
+  if (runMatch) {
+    const paragraph = enclosingDocxParagraph(documentXml, runMatch.index);
+    if (
+      omml
+      && paragraph
+      && !/<w:numPr\b/.test(paragraph.xml)
+      && isSoleMarkerParagraph(paragraph.xml, key)
+    ) {
+      const centered = centerDocxParagraph(paragraph.xml);
+      const innerMatch = runPattern.exec(centered);
+      const withMath = innerMatch
+        ? centered.slice(0, innerMatch.index) + omml + centered.slice(innerMatch.index + innerMatch[0].length)
+        : centered;
+      return documentXml.slice(0, paragraph.start) + withMath + documentXml.slice(paragraph.end);
+    }
+
+    const replacement = omml ?? fallbackRun;
+    return documentXml.slice(0, runMatch.index) + replacement + documentXml.slice(runMatch.index + runMatch[0].length);
+  }
+
+  return documentXml.split(key).join(escapeDocxXml(fallbackTex || key));
+}
+
+async function injectDocxMathEquations(docxBuffer, equations) {
+  const conversions = equations.map((equation) => ({
+    fallbackTex: extractMathmlAnnotation(equation.mml),
+    key: equation.key,
+    omml: convertMathmlToOmml(equation.mml),
+  }));
+
+  const zip = await JSZip.loadAsync(docxBuffer);
+  const documentFile = zip.file('word/document.xml');
+  if (!documentFile) {
+    return docxBuffer;
+  }
+
+  let documentXml = await documentFile.async('string');
+  for (const conversion of conversions) {
+    documentXml = replaceDocxMathMarker(documentXml, conversion);
+  }
+  zip.file('word/document.xml', documentXml);
+  const regenerated = await zip.generateAsync({ compression: 'DEFLATE', type: 'nodebuffer' });
+  return Buffer.from(regenerated);
+}
+
 export async function renderDocx({
   html,
   title = '',
 } = {}) {
+  const content = String(html ?? '');
+  validateEmbeddedImages(content);
   const converter = await ensureConverter();
-  const result = await converter(String(html ?? ''), null, {
+  const result = await converter(content, null, {
     creator: DOCX_EXPORTER_CREATOR,
     font: 'Arial',
     footer: false,
     pageNumber: false,
+    // Avoid a second HTML/CSS preprocessing pass after validation.
+    preprocessing: { skipHTMLMinify: true },
     table: {
       row: {
         cantSplit: true,
@@ -49,5 +297,11 @@ export async function renderDocx({
     title: String(title ?? ''),
   });
 
-  return normalizeDocxBuffer(result);
+  const docxBuffer = normalizeDocxBuffer(result);
+  const equations = collectDocxMath(content);
+  if (equations.length === 0) {
+    return docxBuffer;
+  }
+
+  return injectDocxMathEquations(docxBuffer, equations);
 }

package/src/server/domain/hosted-workspace-contract.js

@@ -5,6 +5,13 @@ export const HOSTED_ROLE_COLLABORATOR = 'collaborator';
 
 const SUPPORTED_ROLES = new Set([HOSTED_ROLE_ADMIN, HOSTED_ROLE_COLLABORATOR]);
 
+export function createHostedError(statusCode, message, code) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  error.code = code;
+  return error;
+}
+
 export function normalizeHostedEmail(value) {
   return normalizeEmailAddress(value);
 }

package/src/server/domain/hosted-workspace.js

@@ -3,6 +3,7 @@ import { randomUUID, timingSafeEqual, createHash } from 'node:crypto';
 import {
   HOSTED_ROLE_ADMIN,
   HOSTED_ROLE_COLLABORATOR,
+  createHostedError,
   normalizeHostedEmail,
   normalizeHostedRole,
 } from './hosted-workspace-contract.js';
@@ -31,13 +32,6 @@ function safeEqualHash(left, right) {
   return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
 }
 
-function createHostedError(statusCode, message, code) {
-  const error = new Error(message);
-  error.statusCode = statusCode;
-  error.code = code;
-  return error;
-}
-
 function createAuditEvent({
   actor,
   metadata = {},
@@ -381,7 +375,7 @@ export class HostedWorkspaceService {
     };
   }
 
-  async completeWorkspaceSetup() {
+  async completeWorkspaceSetup({ user = null } = {}) {
     await this.initialize();
     const team = await this.store.getTeam();
     if (!team) {
@@ -394,6 +388,15 @@ export class HostedWorkspaceService {
       setupCompletedAt: team.setupCompletedAt || timestamp,
     };
     await this.store.updateTeam(updatedTeam);
+    if (!team.setupCompletedAt) {
+      await this.store.createAuditEvent(createAuditEvent({
+        actor: user,
+        targetEmail: user?.email ?? '',
+        targetRole: user?.role ?? '',
+        timestamp,
+        type: 'workspace_setup_completed',
+      }));
+    }
     return updatedTeam;
   }
 
@@ -654,53 +657,33 @@ export class HostedWorkspaceService {
       throw createHostedError(400, 'Invalid membership role.', 'HOSTED_INVALID_ROLE');
     }
 
-    const membership = await this.store.getMembershipById(membershipId);
-    if (!membership) {
-      throw createHostedError(404, 'Membership was not found.', 'HOSTED_MEMBERSHIP_NOT_FOUND');
-    }
-
-    if (membership.role === HOSTED_ROLE_ADMIN && normalizedRole !== HOSTED_ROLE_ADMIN) {
-      await this.assertAnotherAdmin(membership.email);
-    }
-
     const timestamp = nowMs();
-    const updated = {
-      ...membership,
+    const updated = await this.store.changeMembership({
+      actorId: admin.id,
+      membershipId,
       role: normalizedRole,
-      updatedAt: timestamp,
-    };
-    await this.store.updateMembership(updated);
-    await this.store.createAuditEvent(createAuditEvent({
-      actor: admin,
-      targetEmail: updated.email,
-      targetRole: normalizedRole,
-      timestamp,
-      type: 'membership_role_changed',
-    }));
+      auditEvent: createAuditEvent({
+        actor: admin,
+        timestamp,
+        type: 'membership_role_changed',
+      }),
+    });
     this.emitAccessChanged(updated.email);
     return publicMembership(updated);
   }
 
   async removeMembership({ membershipId, user }) {
     const admin = await this.requireAdmin(user);
-    const membership = await this.store.getMembershipById(membershipId);
-    if (!membership) {
-      throw createHostedError(404, 'Membership was not found.', 'HOSTED_MEMBERSHIP_NOT_FOUND');
-    }
-
-    if (membership.role === HOSTED_ROLE_ADMIN) {
-      await this.assertAnotherAdmin(membership.email);
-    }
-
     const timestamp = nowMs();
-    await this.store.deleteMembership(membership.id);
-    await this.store.createAuditEvent(createAuditEvent({
-      actor: admin,
-      targetEmail: membership.email,
-      targetRole: membership.role,
-      timestamp,
-      type: 'membership_removed',
-    }));
+    const membership = await this.store.changeMembership({
+      actorId: admin.id,
+      membershipId,
+      auditEvent: createAuditEvent({
+        actor: admin,
+        timestamp,
+        type: 'membership_removed',
+      }),
+    });
     this.emitAccessChanged(membership.email);
     return { ok: true };
   }
@@ -715,17 +698,17 @@ export class HostedWorkspaceService {
     }
 
     const membership = access.membership;
-    if (membership.role === HOSTED_ROLE_ADMIN) {
-      await this.assertAnotherAdmin(membership.email);
-    }
-
     const timestamp = nowMs();
-    await this.store.deleteMembership(membership.id);
-    await this.store.createAuditEvent(createAuditEvent({
-      actor: membership,
-      timestamp,
-      type: 'membership_left',
-    }));
+    await this.store.changeMembership({
+      actorId: membership.id,
+      membershipId: membership.id,
+      requireAdmin: false,
+      auditEvent: createAuditEvent({
+        actor: membership,
+        timestamp,
+        type: 'membership_left',
+      }),
+    });
     this.emitAccessChanged(membership.email);
     return { ok: true };
   }
@@ -755,11 +738,4 @@ export class HostedWorkspaceService {
     await this.requireAdmin(user);
     return (await this.store.listAuditEvents()).map(publicAuditEvent);
   }
-
-  async assertAnotherAdmin(email) {
-    const adminCount = await this.store.countAdminsExcept(normalizeHostedEmail(email));
-    if (adminCount < 1) {
-      throw createHostedError(409, 'A team must always have at least one Team Admin.', 'HOSTED_LAST_ADMIN');
-    }
-  }
 }