@superdoc-dev/cli 0.2.0-next.53 → 0.2.0-next.55

package/dist/index.js

@@ -1210,7 +1210,7 @@ var init_operation_definitions = __esm(() => {
     },
     insert: {
       memberPath: "insert",
-      description: "Insert content at a target position. Supports text (default), markdown, and html content types via the `type` field.",
+      description: "Insert content at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the `type` field.",
       expectedResult: "Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the insertion point is invalid or content is empty.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
@@ -1293,7 +1293,7 @@ var init_operation_definitions = __esm(() => {
     ...FORMAT_INLINE_ALIAS_OPERATION_DEFINITIONS,
     "styles.apply": {
       memberPath: "styles.apply",
-      description: "Apply document-level default style changes to the stylesheet (word/styles.xml). Targets docDefaults run properties with boolean patch semantics.",
+      description: "Apply document-level default style changes to the stylesheet (word/styles.xml). Targets docDefaults run and paragraph channels with set-style patch semantics.",
       expectedResult: "Returns a StylesApplyReceipt with per-channel success/failure details for each property change.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
@@ -8292,6 +8292,16 @@ function normalizeSessionType(value) {
     return "collab";
   return "local";
 }
+function normalizeUser(value) {
+  const record = asRecord(value);
+  if (!record)
+    return;
+  if (typeof record.name !== "string" || record.name.length === 0)
+    return;
+  if (typeof record.email !== "string")
+    return;
+  return { name: record.name, email: record.email };
+}
 function normalizeCollaborationProfile(value) {
   const record = asRecord(value);
   if (!record)
@@ -8301,6 +8311,8 @@ function normalizeCollaborationProfile(value) {
   const documentId = record.documentId;
   const tokenEnv = record.tokenEnv;
   const syncTimeoutMs = record.syncTimeoutMs;
+  const onMissing = record.onMissing;
+  const bootstrapSettlingMs = record.bootstrapSettlingMs;
   if (providerType !== "hocuspocus" && providerType !== "y-websocket")
     return;
   if (typeof url !== "string" || url.length === 0)
@@ -8312,28 +8324,39 @@ function normalizeCollaborationProfile(value) {
   if (syncTimeoutMs != null && (typeof syncTimeoutMs !== "number" || !Number.isFinite(syncTimeoutMs) || syncTimeoutMs <= 0)) {
     return;
   }
+  if (onMissing != null && onMissing !== "seedFromDoc" && onMissing !== "blank" && onMissing !== "error") {
+    return;
+  }
+  if (bootstrapSettlingMs != null && (typeof bootstrapSettlingMs !== "number" || !Number.isFinite(bootstrapSettlingMs) || bootstrapSettlingMs <= 0)) {
+    return;
+  }
   return {
     providerType,
     url,
     documentId,
     tokenEnv: typeof tokenEnv === "string" ? tokenEnv : undefined,
-    syncTimeoutMs: typeof syncTimeoutMs === "number" ? syncTimeoutMs : undefined
+    syncTimeoutMs: typeof syncTimeoutMs === "number" ? syncTimeoutMs : undefined,
+    onMissing,
+    bootstrapSettlingMs: typeof bootstrapSettlingMs === "number" ? bootstrapSettlingMs : undefined
   };
 }
 function normalizeContextMetadata(metadata) {
   const sessionType = normalizeSessionType(metadata.sessionType);
   const collaboration = normalizeCollaborationProfile(metadata.collaboration);
+  const user = normalizeUser(metadata.user);
   if (sessionType === "collab" && collaboration) {
     return {
       ...metadata,
       sessionType,
-      collaboration
+      collaboration,
+      user
     };
   }
   return {
     ...metadata,
     sessionType: "local",
-    collaboration: undefined
+    collaboration: undefined,
+    user
   };
 }
 function sleep(ms) {
@@ -8747,6 +8770,7 @@ function createInitialContextMetadata(io, paths, contextId, input) {
     revision: 0,
     sessionType,
     collaboration: sessionType === "collab" ? input.collaboration : undefined,
+    user: input.user,
     openedAt: timestamp,
     updatedAt: timestamp,
     sourceSnapshot: input.sourceSnapshot
@@ -9196,6 +9220,14 @@ var init_cli_only_operation_definitions = __esm(() => {
               documentId: { type: "string" },
               url: { type: "string" }
             }
+          },
+          bootstrap: {
+            type: "object",
+            properties: {
+              roomState: { type: "string" },
+              bootstrapApplied: { type: "boolean" },
+              bootstrapSource: { type: "string" }
+            }
           }
         },
         required: ["contextId", "sessionType"]
@@ -10153,6 +10185,36 @@ function resolveSegmentPosition(targetOffset, segmentStart, segmentLength, docFr
   }
   return docFrom + (targetOffset - segmentStart);
 }
+function computeTextContentLength(blockNode) {
+  let length = 0;
+  const walk = (node2) => {
+    if (node2.isText) {
+      length += (node2.text ?? "").length;
+      return;
+    }
+    if (node2.isLeaf) {
+      length += 1;
+      return;
+    }
+    let first2 = true;
+    for (let i = 0;i < node2.childCount; i++) {
+      const child = node2.child(i);
+      if (child.isBlock && !first2)
+        length += 1;
+      walk(child);
+      first2 = false;
+    }
+  };
+  let first = true;
+  for (let i = 0;i < blockNode.childCount; i++) {
+    const child = blockNode.child(i);
+    if (child.isBlock && !first)
+      length += 1;
+    walk(child);
+    first = false;
+  }
+  return length;
+}
 function resolveTextRangeInBlock(blockNode, blockPos, range) {
   if (range.start < 0 || range.end < range.start)
     return null;
@@ -10210,6 +10272,21 @@ function resolveTextRangeInBlock(blockNode, blockPos, range) {
   return { from: fromPos, to: toPos };
 }
 
+// ../../packages/super-editor/src/document-api-adapters/helpers/text-mutation-resolution.ts
+function readTextAtResolvedRange(editor, range) {
+  return editor.state.doc.textBetween(range.from, range.to, `
+`, OBJECT_REPLACEMENT_CHAR);
+}
+function buildTextMutationResolution(input) {
+  return {
+    ...input.requestedTarget ? { requestedTarget: input.requestedTarget } : {},
+    target: input.target,
+    range: { from: input.range.from, to: input.range.to },
+    text: input.text
+  };
+}
+var OBJECT_REPLACEMENT_CHAR = "";
+
 // ../../packages/super-editor/src/document-api-adapters/helpers/adapter-utils.ts
 function findTextBlockCandidates(index, blockId) {
   return index.candidates.filter((candidate) => candidate.nodeId === blockId && isTextBlockCandidate(candidate));
@@ -10236,22 +10313,100 @@ function resolveTextTarget(editor, target) {
     return null;
   return resolveTextRangeInBlock(block.node, block.pos, target.range);
 }
+function collectTopLevelPositions(doc) {
+  const positions = new Set;
+  let offset = 0;
+  for (let i = 0;i < doc.childCount; i++) {
+    positions.add(offset);
+    offset += doc.child(i).nodeSize;
+  }
+  return positions;
+}
 function resolveDefaultInsertTarget(editor) {
   const index = getBlockIndex(editor);
-  const firstParagraph = index.candidates.find((candidate) => candidate.nodeType === "paragraph" && isTextBlockCandidate(candidate));
-  const firstTextBlock = firstParagraph ?? index.candidates.find((candidate) => isTextBlockCandidate(candidate));
-  if (!firstTextBlock)
+  const doc = editor.state.doc;
+  const topLevelPositions = collectTopLevelPositions(doc);
+  for (let i = index.candidates.length - 1;i >= 0; i--) {
+    const candidate = index.candidates[i];
+    if (topLevelPositions.has(candidate.pos) && isTextBlockCandidate(candidate)) {
+      const textLength = computeTextContentLength(candidate.node);
+      const range = resolveTextRangeInBlock(candidate.node, candidate.pos, { start: textLength, end: textLength });
+      if (!range)
+        continue;
+      return {
+        kind: "text-block",
+        target: {
+          kind: "text",
+          blockId: candidate.nodeId,
+          range: { start: textLength, end: textLength }
+        },
+        range
+      };
+    }
+  }
+  if (doc.content.size > 0) {
+    return { kind: "structural-end", insertPos: doc.content.size };
+  }
+  return null;
+}
+function insertParagraphAtEnd(editor, pos, text, applyMeta) {
+  const schema = editor.state.schema;
+  const textNode = schema.text(text);
+  const paragraph = schema.nodes.paragraph.create(null, textNode);
+  const tr = editor.state.tr;
+  tr.insert(pos, paragraph);
+  if (applyMeta)
+    applyMeta(tr);
+  editor.dispatch(tr);
+}
+function resolveWriteTarget(editor, request) {
+  const requestedTarget = request.target;
+  if (request.kind === "insert" && !request.target) {
+    const fallback = resolveDefaultInsertTarget(editor);
+    if (!fallback)
+      return null;
+    if (fallback.kind === "structural-end") {
+      const pos = fallback.insertPos;
+      const syntheticRange = { from: pos, to: pos };
+      const syntheticTarget = { kind: "text", blockId: "", range: { start: 0, end: 0 } };
+      return {
+        requestedTarget,
+        effectiveTarget: syntheticTarget,
+        range: syntheticRange,
+        resolution: buildTextMutationResolution({
+          requestedTarget,
+          target: syntheticTarget,
+          range: syntheticRange,
+          text: ""
+        }),
+        structuralEnd: true
+      };
+    }
+    const text2 = readTextAtResolvedRange(editor, fallback.range);
+    return {
+      requestedTarget,
+      effectiveTarget: fallback.target,
+      range: fallback.range,
+      resolution: buildTextMutationResolution({
+        requestedTarget,
+        target: fallback.target,
+        range: fallback.range,
+        text: text2
+      })
+    };
+  }
+  const target = request.target;
+  if (!target)
     return null;
-  const range = resolveTextRangeInBlock(firstTextBlock.node, firstTextBlock.pos, { start: 0, end: 0 });
+  const range = resolveTextTarget(editor, target);
   if (!range)
     return null;
+  const text = readTextAtResolvedRange(editor, range);
   return {
-    target: {
-      kind: "text",
-      blockId: firstTextBlock.nodeId,
-      range: { start: 0, end: 0 }
-    },
-    range
+    requestedTarget,
+    effectiveTarget: target,
+    range,
+    resolution: buildTextMutationResolution({ requestedTarget, target, range, text })
   };
 }
 function addDiagnostic(diagnostics, message) {
@@ -24670,21 +24825,6 @@ var init_executor = __esm(() => {
   TEXT_STYLE_KEYS = ["color", "fontSize", "letterSpacing", "vertAlign", "position"];
 });
 
-// ../../packages/super-editor/src/document-api-adapters/helpers/text-mutation-resolution.ts
-function readTextAtResolvedRange(editor, range) {
-  return editor.state.doc.textBetween(range.from, range.to, `
-`, OBJECT_REPLACEMENT_CHAR);
-}
-function buildTextMutationResolution(input) {
-  return {
-    ...input.requestedTarget ? { requestedTarget: input.requestedTarget } : {},
-    target: input.target,
-    range: { from: input.range.from, to: input.range.to },
-    text: input.text
-  };
-}
-var OBJECT_REPLACEMENT_CHAR = "";
-
 // ../../node_modules/.pnpm/bail@2.0.2/node_modules/bail/index.js
 function bail(error) {
   if (error) {
@@ -70722,39 +70862,6 @@ function normalizeFormatLocator(input) {
   };
   return { target };
 }
-function resolveWriteTarget(editor, request) {
-  const requestedTarget = request.target;
-  if (request.kind === "insert" && !request.target) {
-    const fallback = resolveDefaultInsertTarget(editor);
-    if (!fallback)
-      return null;
-    const text6 = readTextAtResolvedRange(editor, fallback.range);
-    return {
-      requestedTarget,
-      effectiveTarget: fallback.target,
-      range: fallback.range,
-      resolution: buildTextMutationResolution({
-        requestedTarget,
-        target: fallback.target,
-        range: fallback.range,
-        text: text6
-      })
-    };
-  }
-  const target = request.target;
-  if (!target)
-    return null;
-  const range = resolveTextTarget(editor, target);
-  if (!range)
-    return null;
-  const text5 = readTextAtResolvedRange(editor, range);
-  return {
-    requestedTarget,
-    effectiveTarget: target,
-    range,
-    resolution: buildTextMutationResolution({ requestedTarget, target, range, text: text5 })
-  };
-}
 function mapPlanReceiptToTextReceipt(_receipt, resolution) {
   return { success: true, resolution };
 }
@@ -70829,6 +70936,16 @@ function writeWrapper(editor, request, options) {
   if (options?.dryRun) {
     return { success: true, resolution: resolved.resolution };
   }
+  if (resolved.structuralEnd && normalizedRequest.kind === "insert") {
+    const insertPos = resolved.range.from;
+    const text5 = normalizedRequest.text ?? "";
+    const receipt3 = executeDomainCommand(editor, () => {
+      const meta = mode === "tracked" ? applyTrackedMutationMeta : applyDirectMutationMeta;
+      insertParagraphAtEnd(editor, insertPos, text5, meta);
+      return true;
+    }, { expectedRevision: options?.expectedRevision });
+    return mapPlanReceiptToTextReceipt(receipt3, resolved.resolution);
+  }
   const stepId = v4();
   let op;
   let stepDef;
@@ -70989,8 +71106,14 @@ function insertStructuredWrapper(editor, input, options) {
     if (!fallback) {
       throw new DocumentApiAdapterError("TARGET_NOT_FOUND", "No default insertion point available.");
     }
-    resolvedRange = fallback.range;
-    effectiveTarget = fallback.target;
+    if (fallback.kind === "structural-end") {
+      const pos = fallback.insertPos;
+      resolvedRange = { from: pos, to: pos };
+      effectiveTarget = { kind: "text", blockId: "", range: { start: 0, end: 0 } };
+    } else {
+      resolvedRange = fallback.range;
+      effectiveTarget = fallback.target;
+    }
   }
   const resolution = buildTextMutationResolution({
     requestedTarget: target,
@@ -83665,18 +83788,35 @@ function parseCollaborationInput(value) {
   if ("params" in value) {
     throw new CliError("VALIDATION_ERROR", "collaboration.params is not supported in v1.");
   }
-  const allowedKeys = new Set(["providerType", "url", "documentId", "tokenEnv", "syncTimeoutMs"]);
+  const allowedKeys = new Set([
+    "providerType",
+    "url",
+    "documentId",
+    "tokenEnv",
+    "syncTimeoutMs",
+    "onMissing",
+    "bootstrapSettlingMs"
+  ]);
   for (const key of Object.keys(value)) {
     if (!allowedKeys.has(key)) {
       throw new CliError("VALIDATION_ERROR", `collaboration.${key} is not supported.`);
     }
   }
+  let onMissing;
+  if (value.onMissing != null) {
+    if (value.onMissing !== "seedFromDoc" && value.onMissing !== "blank" && value.onMissing !== "error") {
+      throw new CliError("VALIDATION_ERROR", 'collaboration.onMissing must be "seedFromDoc", "blank", or "error".');
+    }
+    onMissing = value.onMissing;
+  }
   return {
     providerType: normalizeProviderType(value.providerType, "collaboration.providerType"),
     url: expectNonEmptyString(value.url, "collaboration.url").trim(),
     documentId: value.documentId != null ? expectNonEmptyString(value.documentId, "collaboration.documentId") : undefined,
     tokenEnv: expectOptionalEnvVarName(value.tokenEnv, "collaboration.tokenEnv"),
-    syncTimeoutMs: expectOptionalPositiveNumber(value.syncTimeoutMs, "collaboration.syncTimeoutMs")
+    syncTimeoutMs: expectOptionalPositiveNumber(value.syncTimeoutMs, "collaboration.syncTimeoutMs"),
+    onMissing,
+    bootstrapSettlingMs: expectOptionalPositiveNumber(value.bootstrapSettlingMs, "collaboration.bootstrapSettlingMs")
   };
 }
 function resolveCollaborationProfile(input, sessionId) {
@@ -83686,7 +83826,9 @@ function resolveCollaborationProfile(input, sessionId) {
     url: input.url,
     documentId,
     tokenEnv: input.tokenEnv,
-    syncTimeoutMs: input.syncTimeoutMs
+    syncTimeoutMs: input.syncTimeoutMs,
+    onMissing: input.onMissing,
+    bootstrapSettlingMs: input.bootstrapSettlingMs
   };
 }
 function resolveCollaborationToken(profile) {
@@ -83786,6 +83928,119 @@ var init_collaboration = __esm(() => {
   ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 });
 
+// src/lib/bootstrap.ts
+function detectRoomState(ydoc) {
+  const fragment = ydoc.getXmlFragment("supereditor");
+  if (fragment.length > 0)
+    return "populated";
+  const metaMap = ydoc.getMap("meta");
+  for (const [key, value] of metaMap.entries()) {
+    if (key === "bootstrap") {
+      const marker = value;
+      if (marker && marker.source !== "pending")
+        return "populated";
+      continue;
+    }
+    return "populated";
+  }
+  return "empty";
+}
+function resolveBootstrapDecision(roomState, onMissing, hasDoc) {
+  if (roomState === "populated")
+    return { action: "join" };
+  switch (onMissing) {
+    case "seedFromDoc":
+      return { action: "seed", source: hasDoc ? "doc" : "blank" };
+    case "blank":
+      return { action: "seed", source: "blank" };
+    case "error":
+      return { action: "error", reason: 'Collaboration room is empty and onMissing is set to "error".' };
+  }
+}
+function writeBootstrapMarker(ydoc, source) {
+  const metaMap = ydoc.getMap("meta");
+  const marker = {
+    version: 1,
+    clientId: ydoc.clientID,
+    seededAt: new Date().toISOString(),
+    source
+  };
+  metaMap.set("bootstrap", marker);
+}
+function readBootstrapMarker(ydoc) {
+  return ydoc.getMap("meta").get("bootstrap");
+}
+function snapshotCompetitor(marker) {
+  return {
+    observedOtherClientId: marker.clientId,
+    observedSource: marker.source,
+    observedAt: new Date().toISOString()
+  };
+}
+function observeCompetitor(ydoc) {
+  const myClientId = ydoc.clientID;
+  const metaMap = ydoc.getMap("meta");
+  let competitor = null;
+  const handler2 = (event) => {
+    if (!event.keysChanged.has("bootstrap"))
+      return;
+    const marker = metaMap.get("bootstrap");
+    if (marker && marker.clientId !== myClientId && !competitor) {
+      competitor = snapshotCompetitor(marker);
+    }
+  };
+  metaMap.observe(handler2);
+  return {
+    getCompetitor: () => competitor,
+    dispose: () => metaMap.unobserve(handler2)
+  };
+}
+function sleep2(ms) {
+  if (ms <= 0)
+    return Promise.resolve();
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function claimBootstrap(ydoc, settlingMs, jitterMs = DEFAULT_BOOTSTRAP_JITTER_MS) {
+  await sleep2(Math.floor(Math.random() * jitterMs));
+  const metaMap = ydoc.getMap("meta");
+  metaMap.set("bootstrap", {
+    version: 1,
+    clientId: ydoc.clientID,
+    seededAt: new Date().toISOString(),
+    source: "pending"
+  });
+  const observer = observeCompetitor(ydoc);
+  try {
+    await sleep2(settlingMs);
+    const competitor = observer.getCompetitor();
+    if (competitor)
+      return { granted: false, competitor };
+    const marker = readBootstrapMarker(ydoc);
+    if (marker?.clientId === ydoc.clientID) {
+      return { granted: true };
+    }
+    return {
+      granted: false,
+      competitor: marker ? snapshotCompetitor(marker) : { observedOtherClientId: 0, observedSource: "unknown", observedAt: new Date().toISOString() }
+    };
+  } finally {
+    observer.dispose();
+  }
+}
+async function detectBootstrapRace(ydoc, observeMs = POST_SEED_OBSERVE_MS) {
+  const observer = observeCompetitor(ydoc);
+  try {
+    await sleep2(observeMs);
+    const competitor = observer.getCompetitor();
+    if (competitor)
+      return { raceSuspected: true, competitor };
+    return { raceSuspected: false };
+  } finally {
+    observer.dispose();
+  }
+}
+var DEFAULT_BOOTSTRAP_SETTLING_MS = 1500, DEFAULT_BOOTSTRAP_JITTER_MS = 150, POST_SEED_OBSERVE_MS = 200;
+
 // src/lib/document.ts
 import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
 import { createHash as createHash2 } from "node:crypto";
@@ -83879,10 +84134,11 @@ async function openDocument(doc, io, options = {}) {
     const isTest = false;
     editor = await EditorRuntime.open(Buffer.from(source), {
       documentId: options.documentId ?? meta.path ?? "blank.docx",
-      user: { id: "cli", name: "CLI" },
+      user: options.user ? { name: options.user.name, email: options.user.email, image: null } : { id: "cli", name: "CLI" },
       ...isTest ? { telemetry: { enabled: false } } : {},
       ydoc: options.ydoc,
       ...options.collaborationProvider != null ? { collaborationProvider: options.collaborationProvider } : {},
+      ...options.isNewFile != null ? { isNewFile: options.isNewFile } : {},
       ...passThroughEditorOpts
     });
   } catch (error) {
@@ -83939,18 +84195,48 @@ async function openDocument(doc, io, options = {}) {
     }
   };
 }
-async function openCollaborativeDocument(doc, io, profile) {
+async function openCollaborativeDocument(doc, io, profile, options = {}) {
   const runtime = createCollaborationRuntime(profile);
   try {
     await runtime.waitForSync();
-    const opened = await openDocument(doc, io, {
+    const onMissing = profile.onMissing ?? "seedFromDoc";
+    let finalRoomState = detectRoomState(runtime.ydoc);
+    let decision = resolveBootstrapDecision(finalRoomState, onMissing, doc != null);
+    if (decision.action === "seed") {
+      const claim = await claimBootstrap(runtime.ydoc, profile.bootstrapSettlingMs ?? DEFAULT_BOOTSTRAP_SETTLING_MS);
+      if (!claim.granted) {
+        finalRoomState = detectRoomState(runtime.ydoc);
+        decision = { action: "join" };
+      }
+    }
+    if (decision.action === "error") {
+      throw new CliError("COLLABORATION_ROOM_EMPTY", decision.reason);
+    }
+    const shouldSeed = decision.action === "seed";
+    const docForEditor = shouldSeed ? doc : undefined;
+    const opened = await openDocument(docForEditor, io, {
       documentId: profile.documentId,
       ydoc: runtime.ydoc,
-      collaborationProvider: runtime.provider
+      collaborationProvider: runtime.provider,
+      isNewFile: shouldSeed,
+      user: options.user
     });
+    let raceDetection;
+    if (shouldSeed) {
+      writeBootstrapMarker(runtime.ydoc, decision.source);
+      raceDetection = await detectBootstrapRace(runtime.ydoc);
+    }
+    const bootstrap = {
+      roomState: finalRoomState,
+      bootstrapApplied: shouldSeed,
+      bootstrapSource: shouldSeed ? decision.source : undefined,
+      raceSuspected: raceDetection?.raceSuspected,
+      raceCompetitor: raceDetection?.raceSuspected ? raceDetection.competitor : undefined
+    };
     return {
       editor: opened.editor,
       meta: opened.meta,
+      bootstrap,
       dispose() {
         try {
           opened.dispose();
@@ -83966,7 +84252,7 @@ async function openCollaborativeDocument(doc, io, profile) {
 }
 async function openSessionDocument(doc, io, metadata, options = {}) {
   if (metadata.sessionType !== "collab") {
-    return openDocument(doc, io);
+    return openDocument(doc, io, { user: metadata.user });
   }
   if (!metadata.collaboration) {
     throw new CliError("COMMAND_FAILED", "Session is marked as collaborative but has no collaboration profile.");
@@ -83981,11 +84267,12 @@ async function openSessionDocument(doc, io, metadata, options = {}) {
       sessionType: metadata.sessionType,
       collaboration: metadata.collaboration,
       sourcePath: metadata.sourcePath,
-      workingDocPath: metadata.workingDocPath
+      workingDocPath: metadata.workingDocPath,
+      user: metadata.user
     };
     return options.collabSessionPool.acquire(sessionId, doc, metadataForPool, io);
   }
-  return openCollaborativeDocument(doc, io, metadata.collaboration);
+  return openCollaborativeDocument(doc, io, metadata.collaboration, { user: metadata.user });
 }
 async function getFileChecksum(path2) {
   let bytes;
@@ -85445,7 +85732,7 @@ async function executeReadOperation(request) {
         opened2.dispose();
       }
     }
-    const opened = await openDocument(paths.workingDocPath, context.io);
+    const opened = await openDocument(paths.workingDocPath, context.io, { user: metadata.user });
     try {
       const result = invokeOperation(opened.editor, operationId, input);
       const document4 = {
@@ -85635,7 +85922,7 @@ async function executeMutationOperation(request) {
         opened2.dispose();
       }
     }
-    const opened = await openDocument(paths.workingDocPath, context.io);
+    const opened = await openDocument(paths.workingDocPath, context.io, { user: metadata.user });
     try {
       const result = invokeOperation2(opened.editor, operationId, input, invokeOptions);
       const document4 = {
@@ -86344,7 +86631,7 @@ function deriveOptionSpecs(params3) {
   }
   return specs;
 }
-var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, INSERT_FLAT_PARAMS, LIST_TARGET_FLAT_PARAMS, FORMAT_OPERATION_IDS, EXTRA_CLI_PARAMS, CLI_ONLY_METADATA, CLI_OPERATION_METADATA, CLI_OPERATION_OPTION_SPECS;
+var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, USER_NAME_PARAM, USER_EMAIL_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, INSERT_FLAT_PARAMS, LIST_TARGET_FLAT_PARAMS, FORMAT_OPERATION_IDS, EXTRA_CLI_PARAMS, CLI_ONLY_METADATA, CLI_OPERATION_METADATA, CLI_OPERATION_OPTION_SPECS;
 var init_operation_params = __esm(() => {
   init_src();
   init_operation_set();
@@ -86375,6 +86662,18 @@ var init_operation_params = __esm(() => {
     type: "number",
     agentVisible: false
   };
+  USER_NAME_PARAM = {
+    name: "userName",
+    kind: "flag",
+    flag: "user-name",
+    type: "string"
+  };
+  USER_EMAIL_PARAM = {
+    name: "userEmail",
+    kind: "flag",
+    flag: "user-email",
+    type: "string"
+  };
   AGENT_HIDDEN_PARAM_NAMES = new Set(["out", "expectedRevision", "changeMode", "dryRun"]);
   OPERATION_CONSTRAINTS = {
     "doc.find": {
@@ -86501,7 +86800,11 @@ var init_operation_params = __esm(() => {
         { name: "collabDocumentId", kind: "flag", flag: "collab-document-id", type: "string" },
         { name: "collabUrl", kind: "flag", flag: "collab-url", type: "string" },
         { name: "contentOverride", kind: "flag", flag: "content-override", type: "string" },
-        { name: "overrideType", kind: "flag", flag: "override-type", type: "string" }
+        { name: "overrideType", kind: "flag", flag: "override-type", type: "string" },
+        { name: "onMissing", kind: "flag", flag: "on-missing", type: "string" },
+        { name: "bootstrapSettlingMs", kind: "flag", flag: "bootstrap-settling-ms", type: "number" },
+        USER_NAME_PARAM,
+        USER_EMAIL_PARAM
       ],
       constraints: null
     },
@@ -87800,6 +88103,10 @@ async function runOpen(tokens, context) {
   const collabDocumentId = getStringOption(parsed, "collab-document-id");
   const contentOverride = getStringOption(parsed, "content-override");
   const overrideType = getStringOption(parsed, "override-type");
+  const onMissing = getStringOption(parsed, "on-missing");
+  const bootstrapSettlingMs = getNumberOption(parsed, "bootstrap-settling-ms");
+  const userName = getStringOption(parsed, "user-name");
+  const userEmail = getStringOption(parsed, "user-email");
   if (contentOverride != null && !overrideType) {
     throw new CliError("INVALID_ARGUMENT", "open: --content-override requires --override-type.");
   }
@@ -87809,6 +88116,9 @@ async function runOpen(tokens, context) {
   if (overrideType && !VALID_OVERRIDE_TYPES.has(overrideType)) {
     throw new CliError("INVALID_ARGUMENT", `open: --override-type must be one of: markdown, html, text. Got "${overrideType}".`);
   }
+  if (onMissing != null && !VALID_ON_MISSING.has(onMissing)) {
+    throw new CliError("INVALID_ARGUMENT", `open: --on-missing must be one of: seedFromDoc, blank, error. Got "${onMissing}".`);
+  }
   if (collaborationPayload != null && (collabUrl || collabDocumentId)) {
     throw new CliError("INVALID_ARGUMENT", "open: do not combine --collaboration-json with --collab-url / --collab-document-id.");
   }
@@ -87817,18 +88127,32 @@ async function runOpen(tokens, context) {
   }
   let collaborationInput;
   if (collaborationPayload != null) {
-    collaborationInput = parseCollaborationInput(collaborationPayload);
+    if (typeof collaborationPayload !== "object" || Array.isArray(collaborationPayload)) {
+      throw new CliError("VALIDATION_ERROR", "open: --collaboration-json must be a JSON object.");
+    }
+    const payload = collaborationPayload;
+    if (onMissing != null && !("onMissing" in payload))
+      payload.onMissing = onMissing;
+    if (bootstrapSettlingMs != null && !("bootstrapSettlingMs" in payload))
+      payload.bootstrapSettlingMs = bootstrapSettlingMs;
+    collaborationInput = parseCollaborationInput(payload);
   } else if (collabUrl) {
     collaborationInput = parseCollaborationInput({
       providerType: "hocuspocus",
       url: collabUrl,
-      documentId: collabDocumentId
+      documentId: collabDocumentId,
+      ...onMissing != null ? { onMissing } : {},
+      ...bootstrapSettlingMs != null ? { bootstrapSettlingMs } : {}
     });
   } else if (collabDocumentId) {
     throw new CliError("MISSING_REQUIRED", "open: --collab-document-id requires --collab-url.");
   }
   const collaboration = collaborationInput ? resolveCollaborationProfile(collaborationInput, sessionId) : undefined;
   const sessionType = collaboration ? "collab" : "local";
+  if (!collaboration && (onMissing != null || bootstrapSettlingMs != null)) {
+    throw new CliError("INVALID_ARGUMENT", "open: --on-missing and --bootstrap-settling-ms require collaboration mode (--collaboration-json or --collab-url).");
+  }
+  const user = userName != null || userEmail != null ? { name: userName ?? "CLI", email: userEmail ?? "" } : undefined;
   const editorOpenOptions = {};
   if (contentOverride != null && overrideType) {
     if (overrideType === "markdown") {
@@ -87854,10 +88178,8 @@ async function runOpen(tokens, context) {
         revision: existing.revision
       });
     }
-    if (collaboration && doc == null) {
-      throw new CliError("MISSING_REQUIRED", "open: a document path is required when using collaboration.");
-    }
-    const opened = collaboration ? await openCollaborativeDocument(doc, context.io, collaboration) : await openDocument(doc, context.io, { editorOpenOptions });
+    const opened = collaboration ? await openCollaborativeDocument(doc, context.io, collaboration, { user }) : await openDocument(doc, context.io, { editorOpenOptions, user });
+    const bootstrap = "bootstrap" in opened ? opened.bootstrap : undefined;
     let adoptedToHostPool = false;
     try {
       const output = await exportToPath(opened.editor, paths.workingDocPath, true);
@@ -87868,7 +88190,8 @@ async function runOpen(tokens, context) {
         sourcePath,
         sourceSnapshot,
         sessionType,
-        collaboration
+        collaboration,
+        user
       });
       await writeContextMetadata(paths, metadata);
       await setActiveSessionId(metadata.contextId);
@@ -87890,6 +88213,7 @@ async function runOpen(tokens, context) {
           dirty: metadata.dirty,
           sessionType: metadata.sessionType,
           collaboration: metadata.collaboration,
+          bootstrap,
           openedAt: metadata.openedAt,
           updatedAt: metadata.updatedAt
         },
@@ -87902,7 +88226,7 @@ async function runOpen(tokens, context) {
     }
   }, undefined, sessionId);
 }
-var VALID_OVERRIDE_TYPES;
+var VALID_OVERRIDE_TYPES, VALID_ON_MISSING;
 var init_open = __esm(() => {
   init_args();
   init_collaboration();
@@ -87912,6 +88236,7 @@ var init_open = __esm(() => {
   init_operation_args();
   init_session();
   VALID_OVERRIDE_TYPES = new Set(["markdown", "html", "text"]);
+  VALID_ON_MISSING = new Set(["seedFromDoc", "blank", "error"]);
 });
 
 // src/commands/save.ts
@@ -94374,7 +94699,9 @@ function profileToKey(profile) {
     url: profile.url,
     documentId: profile.documentId,
     tokenEnv: profile.tokenEnv ?? null,
-    syncTimeoutMs: profile.syncTimeoutMs ?? null
+    syncTimeoutMs: profile.syncTimeoutMs ?? null,
+    onMissing: profile.onMissing ?? null,
+    bootstrapSettlingMs: profile.bootstrapSettlingMs ?? null
   });
 }
 function buildFingerprint(metadata) {
@@ -94417,7 +94744,7 @@ class InMemoryCollaborationSessionPool {
       await this.disposeSession(sessionId);
     }
     const profile = metadata.collaboration;
-    const opened = await this.openCollaborative(docPath, io, profile);
+    const opened = await this.openCollaborative(docPath, io, profile, { user: metadata.user });
     const created = {
       opened,
       fingerprint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli",
-  "version": "0.2.0-next.53",
+  "version": "0.2.0-next.55",
   "type": "module",
   "bin": {
     "superdoc": "./dist/index.js"
@@ -20,8 +20,8 @@
     "@types/node": "22.19.2",
     "typescript": "^5.9.2",
     "@superdoc/document-api": "0.0.1",
-    "superdoc": "1.16.0",
     "@superdoc/pm-adapter": "0.0.0",
+    "superdoc": "1.16.0",
     "@superdoc/super-editor": "0.0.1"
   },
   "module": "src/index.ts",
@@ -29,11 +29,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc-dev/cli-darwin-arm64": "0.2.0-next.53",
-    "@superdoc-dev/cli-darwin-x64": "0.2.0-next.53",
-    "@superdoc-dev/cli-linux-x64": "0.2.0-next.53",
-    "@superdoc-dev/cli-windows-x64": "0.2.0-next.53",
-    "@superdoc-dev/cli-linux-arm64": "0.2.0-next.53"
+    "@superdoc-dev/cli-darwin-arm64": "0.2.0-next.55",
+    "@superdoc-dev/cli-darwin-x64": "0.2.0-next.55",
+    "@superdoc-dev/cli-linux-x64": "0.2.0-next.55",
+    "@superdoc-dev/cli-linux-arm64": "0.2.0-next.55",
+    "@superdoc-dev/cli-windows-x64": "0.2.0-next.55"
   },
   "scripts": {
     "dev": "bun run src/index.ts",