@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/runtime/collab/runtime-collab-sync.ts

@@ -261,6 +261,22 @@ export interface RuntimeCollabSyncHandle {
    * enforces write permissions per §7 of the lane plan.
    */
   getWorkflowShared(): WorkflowSharedHandle;
+  /**
+   * R3 — AbortSignal that fires whenever a remote command batch is applied
+   * locally. Long-running idle tasks (e.g. Phase 2.5 prerender cache
+   * warmups, Phase 2.2 ranged-snapshot prep) should pass this into
+   * `loadScheduler.scheduleIdle(task, { signal })` so remote arrivals
+   * cancel stale prep before the document moves under it. The signal is
+   * recycled after each drain — callers must call this getter on every
+   * `scheduleIdle` call rather than caching the result. On `destroy()`
+   * the current signal also aborts so consumers detect shutdown.
+   *
+   * Stability: advanced-supported (v2.0.0). See
+   * `docs/reference/public-api.md` §createRuntimeCollabSync for the
+   * consumer contract and `docs/wiki/collaboration.md` §"Remote-activity
+   * abort signal (R3)" for the end-to-end narrative.
+   */
+  getRemoteActivitySignal(): AbortSignal;
 }
 
 export function createRuntimeCommandAppliedBridge(): RuntimeCommandAppliedBridge {
@@ -300,8 +316,19 @@ export function createRuntimeCollabSync(
   let rafHandle: number | null = null;
   let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
 
+  // R3 — remote-activity abort controller. Recycled on every scheduled
+  // drain so consumers that registered an idle task with the prior
+  // signal get cancelled before the upcoming commit lands. First signal
+  // is created eagerly so `getRemoteActivitySignal()` is always safe to
+  // call before any remote traffic.
+  let remoteActivityController = new AbortController();
+
   function scheduleDrain(): void {
     if (rafHandle !== null || timeoutHandle !== null) return;
+    // Abort the prior signal BEFORE firing the host hook so any consumer
+    // work that branches on the hook sees the fresh signal.
+    remoteActivityController.abort();
+    remoteActivityController = new AbortController();
     options.onRemoteReplayScheduled?.();
     if (typeof requestAnimationFrame === "function") {
       rafHandle = requestAnimationFrame(() => {
@@ -572,6 +599,9 @@ export function createRuntimeCollabSync(
       workflowShared.destroy();
       runtime.setSharedWorkflowState(null);
       listeners.clear();
+      // R3 — abort the current remote-activity signal so any lingering
+      // idle consumers detect the shutdown.
+      remoteActivityController.abort();
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -602,6 +632,9 @@ export function createRuntimeCollabSync(
     getWorkflowShared() {
       return workflowShared;
     },
+    getRemoteActivitySignal() {
+      return remoteActivityController.signal;
+    },
   };
 
   function onYEventsChange(event: Y.YArrayEvent<CommandEvent>): void {

package/src/runtime/diagnostics/build-diagnostic.ts

@@ -0,0 +1,151 @@
+// v2.0.0 — centralized diagnostic factory. Every error / warning /
+// blocked-command path in the runtime builds its `EditorDiagnostic`
+// through `buildDiagnostic()` so the LLM-metadata defaults from
+// `code-metadata-table.ts` stay consistent.
+//
+// Emitters may override any llmMetadata field on a per-call basis.
+
+import type {
+  EditorAnchorProjection,
+  EditorDiagnostic,
+  EditorDiagnosticCode,
+  EditorDiagnosticLlmMetadata,
+  EditorDiagnosticTechnical,
+} from "../../api/public-types.ts";
+import { CODE_METADATA_TABLE } from "./code-metadata-table.ts";
+
+export interface BuildDiagnosticParams {
+  code: EditorDiagnosticCode;
+  /** Optional override of the technical payload. `message` + `source` default from the table. */
+  technical?: Partial<EditorDiagnosticTechnical> & { message?: string };
+  /** Optional override of llmMetadata fields. Spreads over table defaults. */
+  llmMetadata?: Partial<EditorDiagnosticLlmMetadata>;
+  /** Severity override — defaults to the table's severity for this code. */
+  severity?: EditorDiagnostic["severity"];
+  /** Convenience: short-hand for technical.affectedAnchor. */
+  affectedAnchor?: EditorAnchorProjection;
+  /** Convenience: short-hand for technical.cause; accepts a raw Error. */
+  cause?: Error | EditorDiagnosticTechnical["cause"];
+  /** Convenience: short-hand for technical.details. */
+  details?: Record<string, unknown>;
+  /** Explicit diagnosticId; auto-generated when omitted. */
+  diagnosticId?: string;
+  /** Explicit emittedAt ISO string; `new Date().toISOString()` when omitted. */
+  emittedAt?: string;
+}
+
+let diagnosticIdCounter = 0;
+
+const nextDiagnosticId = (): string => {
+  diagnosticIdCounter = (diagnosticIdCounter + 1) | 0;
+  return `diag-${Date.now().toString(36)}-${diagnosticIdCounter.toString(36)}`;
+};
+
+const normalizeCause = (
+  cause: BuildDiagnosticParams["cause"],
+): EditorDiagnosticTechnical["cause"] | undefined => {
+  if (!cause) return undefined;
+  if (cause instanceof Error) {
+    return {
+      message: cause.message,
+      name: cause.name,
+      stack: cause.stack,
+    };
+  }
+  return cause;
+};
+
+export function buildDiagnostic(params: BuildDiagnosticParams): EditorDiagnostic {
+  const row = CODE_METADATA_TABLE[params.code];
+  if (!row) {
+    throw new Error(
+      `buildDiagnostic: unknown EditorDiagnosticCode "${params.code}" — add a row to code-metadata-table.ts`,
+    );
+  }
+
+  const severity = params.severity ?? row.severity;
+  const technical: EditorDiagnosticTechnical = {
+    message: params.technical?.message ?? row.llmMetadata.userSummary,
+    source: params.technical?.source ?? row.source,
+    stack: params.technical?.stack,
+    cause: normalizeCause(params.cause ?? params.technical?.cause),
+    details: params.details ?? params.technical?.details,
+    affectedAnchor: params.affectedAnchor ?? params.technical?.affectedAnchor,
+    featureEntryId: params.technical?.featureEntryId,
+  };
+
+  const llmMetadata: EditorDiagnosticLlmMetadata = {
+    userSummary: params.llmMetadata?.userSummary ?? row.llmMetadata.userSummary,
+    recoveryClass:
+      params.llmMetadata?.recoveryClass ?? row.llmMetadata.recoveryClass,
+    remediation: params.llmMetadata?.remediation ?? row.llmMetadata.remediation,
+    echoedInput: params.llmMetadata?.echoedInput,
+    docsUrl: params.llmMetadata?.docsUrl ?? row.llmMetadata.docsUrl,
+    tags: params.llmMetadata?.tags ?? row.llmMetadata.tags,
+  };
+
+  return {
+    diagnosticId: params.diagnosticId ?? nextDiagnosticId(),
+    severity,
+    code: params.code,
+    technical,
+    llmMetadata,
+    emittedAt: params.emittedAt ?? new Date().toISOString(),
+  };
+}
+
+/**
+ * Convenience: build a diagnostic whose legacy `EditorError.code` is one of
+ * the pre-v2.0.0 codes, by mapping to the canonical v2.0.0 code.
+ */
+export function buildDiagnosticFromLegacyErrorCode(
+  legacyCode:
+    | "import_failed"
+    | "export_failed"
+    | "package_corrupt"
+    | "validation_failed"
+    | "datastore_failed"
+    | "internal_invariant",
+  params: Omit<BuildDiagnosticParams, "code"> = {},
+): EditorDiagnostic {
+  const mapping: Record<string, EditorDiagnosticCode> = {
+    import_failed: "import.failed",
+    export_failed: "export.failed",
+    package_corrupt: "import.package_corrupt",
+    validation_failed: "validation.failed",
+    datastore_failed: "datastore.failed",
+    internal_invariant: "runtime.internal_invariant",
+  };
+  return buildDiagnostic({ ...params, code: mapping[legacyCode] });
+}
+
+/**
+ * Convenience: build a diagnostic whose legacy `EditorWarning.code` is one
+ * of the pre-v2.0.0 codes.
+ */
+export function buildDiagnosticFromLegacyWarningCode(
+  legacyCode:
+    | "unsupported_ooxml_preserved"
+    | "unsupported_ooxml_locked"
+    | "import_normalized"
+    | "export_roundtrip_risk"
+    | "comment_anchor_detached"
+    | "revision_anchor_detached"
+    | "large_document_degraded"
+    | "font_substitution"
+    | "image_missing",
+  params: Omit<BuildDiagnosticParams, "code"> = {},
+): EditorDiagnostic {
+  const mapping: Record<string, EditorDiagnosticCode> = {
+    unsupported_ooxml_preserved: "import.unsupported_ooxml_preserved",
+    unsupported_ooxml_locked: "import.unsupported_ooxml_locked",
+    import_normalized: "import.normalized",
+    export_roundtrip_risk: "export.roundtrip_risk",
+    comment_anchor_detached: "review.comment_anchor_detached",
+    revision_anchor_detached: "review.revision_anchor_detached",
+    large_document_degraded: "runtime.large_document_degraded",
+    font_substitution: "runtime.font_substitution",
+    image_missing: "runtime.image_missing",
+  };
+  return buildDiagnostic({ ...params, code: mapping[legacyCode] });
+}

package/src/runtime/diagnostics/code-metadata-table.ts

@@ -0,0 +1,221 @@
+// v2.0.0 — canonical LLM-metadata + remediation defaults for every
+// EditorDiagnosticCode. One row per code. The build-diagnostic factory
+// reads this table to populate `EditorDiagnostic.llmMetadata` defaults;
+// emitters may override any field on a per-call basis.
+//
+// Stability: advanced-supported. Changes ship with an updated snapshot
+// in test/api/diagnostic-shape.test.ts.
+
+import type {
+  EditorDiagnosticCode,
+  EditorDiagnosticLlmMetadata,
+  EditorDiagnosticSource,
+} from "../../api/public-types.ts";
+
+const DOCS_BASE = "docs/wiki/error-catalog.md";
+
+interface CodeMetadataRow {
+  readonly source: EditorDiagnosticSource;
+  readonly severity: "fatal" | "error" | "warning" | "info";
+  readonly llmMetadata: EditorDiagnosticLlmMetadata;
+}
+
+const row = (
+  source: EditorDiagnosticSource,
+  severity: "fatal" | "error" | "warning" | "info",
+  userSummary: string,
+  recoveryClass: EditorDiagnosticLlmMetadata["recoveryClass"],
+  remediation: EditorDiagnosticLlmMetadata["remediation"],
+  tags: string[],
+  anchor: string,
+): CodeMetadataRow => ({
+  source,
+  severity,
+  llmMetadata: {
+    userSummary,
+    recoveryClass,
+    remediation,
+    tags,
+    docsUrl: `${DOCS_BASE}#${anchor}`,
+  },
+});
+
+export const CODE_METADATA_TABLE: Readonly<
+  Record<EditorDiagnosticCode, CodeMetadataRow>
+> = {
+  "import.failed": row("import", "error",
+    "The document could not be opened — the .docx package appears to be corrupt or incomplete.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Ask the user to re-export the document from Word and retry." },
+    ["import", "package"], "import-failed"),
+  "import.package_corrupt": row("import", "error",
+    "The .docx package structure is invalid and cannot be loaded.",
+    "unrecoverable",
+    { kind: "escalate", to: "author", reason: "Package corruption — source must be regenerated." },
+    ["import", "package", "corrupt"], "import-package-corrupt"),
+  "import.normalized": row("import", "info",
+    "The document was loaded successfully with minor automatic repairs.",
+    "retry-safe", { kind: "none" }, ["import", "normalized"], "import-normalized"),
+  "import.unsupported_ooxml_preserved": row("import", "info",
+    "Some advanced content was preserved but cannot be edited — it will round-trip unchanged on export.",
+    "retry-safe", { kind: "none" }, ["import", "preserve-only"], "import-unsupported-preserved"),
+  "import.unsupported_ooxml_locked": row("import", "warning",
+    "Some content is locked for editing because the editor cannot render it.",
+    "requires-human",
+    { kind: "escalate", to: "reviewer", reason: "Locked content region requires reviewer acknowledgment." },
+    ["import", "locked"], "import-unsupported-locked"),
+  "export.failed": row("export", "error",
+    "The document could not be saved — a serialization step failed.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 250, maxAttempts: 2 },
+    ["export"], "export-failed"),
+  "export.roundtrip_risk": row("export", "warning",
+    "The document was saved, but some content may not open identically in other editors.",
+    "requires-human",
+    { kind: "escalate", to: "author", reason: "Roundtrip-risk content flagged; author should verify." },
+    ["export", "roundtrip"], "export-roundtrip-risk"),
+  "review.comment_anchor_detached": row("review", "info",
+    "A comment's anchor text was removed; the comment is now detached but still preserved.",
+    "retry-safe", { kind: "none" }, ["review", "comment"], "review-comment-anchor-detached"),
+  "review.revision_anchor_detached": row("review", "info",
+    "A tracked change's anchor was invalidated by a structural edit.",
+    "retry-safe", { kind: "none" }, ["review", "tracked-change"], "review-revision-anchor-detached"),
+  "runtime.large_document_degraded": row("runtime", "warning",
+    "The document is large enough that some rendering optimizations have been relaxed.",
+    "retry-safe", { kind: "none" }, ["runtime", "perf"], "runtime-large-document-degraded"),
+  "runtime.font_substitution": row("runtime", "info",
+    "A requested font was unavailable; a substitute was used.",
+    "retry-safe", { kind: "none" }, ["runtime", "font"], "runtime-font-substitution"),
+  "runtime.image_missing": row("runtime", "warning",
+    "An embedded image could not be loaded — a placeholder is shown.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Verify the image media part exists in the package." },
+    ["runtime", "image"], "runtime-image-missing"),
+  "runtime.internal_invariant": row("runtime", "fatal",
+    "The editor reached an unexpected state and cannot continue safely.",
+    "unrecoverable",
+    { kind: "escalate", to: "admin", reason: "Internal invariant violated — file a bug with the full diagnostic." },
+    ["runtime", "bug"], "runtime-internal-invariant"),
+  "host.adapter_rejected": row("host", "error",
+    "A host integration call failed.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 3 },
+    ["host", "adapter"], "host-adapter-rejected"),
+  "host.load_rejected": row("host", "error",
+    "Loading the document from the host failed.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 3 },
+    ["host", "load"], "host-load-rejected"),
+  "host.save_rejected": row("host", "error",
+    "Saving the document to the host failed.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 3 },
+    ["host", "save"], "host-save-rejected"),
+  "host.chart_preview_rejected": row("host", "warning",
+    "A chart preview could not be rendered by the host — a badge is shown instead.",
+    "retry-safe", { kind: "none" }, ["host", "chart"], "host-chart-preview-rejected"),
+  "datastore.failed": row("datastore", "error",
+    "A datastore operation failed.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 3 },
+    ["datastore"], "datastore-failed"),
+  "datastore.load_rejected": row("datastore", "error",
+    "The datastore could not load the requested snapshot.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 3 },
+    ["datastore", "load"], "datastore-load-rejected"),
+  "datastore.save_rejected": row("datastore", "error",
+    "The datastore could not save the snapshot.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 3 },
+    ["datastore", "save"], "datastore-save-rejected"),
+  "validation.failed": row("validation", "error",
+    "A document validation invariant failed.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Inspect technical.details.reason for the failing invariant." },
+    ["validation"], "validation-failed"),
+  "validation.invariant_violated": row("validation", "fatal",
+    "A critical document invariant was violated.",
+    "unrecoverable",
+    { kind: "escalate", to: "admin", reason: "Invariant violated — document state may be corrupt." },
+    ["validation", "bug"], "validation-invariant-violated"),
+  "api.invalid_regex": row("api", "error",
+    "The search pattern is not a valid regular expression.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Retry with a valid JavaScript regex, or disable the regex flag." },
+    ["api", "search"], "api-invalid-regex"),
+  "api.invalid_anchor": row("api", "error",
+    "The provided position is invalid for this document.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Resolve a fresh anchor via getCurrentLocation() or findFirstText()." },
+    ["api", "anchor"], "api-invalid-anchor"),
+  "api.invalid_argument": row("api", "error",
+    "An argument passed to the editor API is invalid.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Check technical.details.argument for the offending field." },
+    ["api"], "api-invalid-argument"),
+  "api.metadata_resolver_missing": row("api", "error",
+    "External metadata mode requires a resolver — register one via setScopeMetadataResolver() first.",
+    "requires-resolver",
+    { kind: "fallback", suggestion: "Call setScopeMetadataResolver(...) then retry." },
+    ["api", "metadata", "resolver"], "api-metadata-resolver-missing"),
+  "api.metadata_resolver_rejected": row("api", "error",
+    "The registered metadata resolver rejected a request.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 500, maxAttempts: 2 },
+    ["api", "metadata", "resolver"], "api-metadata-resolver-rejected"),
+  "api.scope_not_found": row("api", "error",
+    "The requested workflow scope does not exist in the current overlay.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Call queryScopes() to enumerate available scopeIds." },
+    ["api", "scope"], "api-scope-not-found"),
+  "api.collab_role_restricted": row("api", "error",
+    "The current user's role does not permit this action.",
+    "requires-permission",
+    { kind: "escalate", to: "author", reason: "Role-gated action; requires elevated permissions." },
+    ["api", "collab", "role"], "api-collab-role-restricted"),
+  "api.workflow_comment_only": row("api", "warning",
+    "This location only allows comments — edits are blocked by the active workflow overlay.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Use addComment() instead, or target a scoped location." },
+    ["api", "workflow"], "api-workflow-comment-only"),
+  "api.command_blocked": row("api", "warning",
+    "This command is blocked by the current workflow policy.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Check technical.details.reasons for the blocking policy." },
+    ["api", "workflow", "blocked"], "api-command-blocked"),
+  // Lane 8 Track H (v2.x) — agent-helper widening.
+  "api.projection_unavailable": row("api", "error",
+    "A text projection could not be built — the runtime is still loading or the story target is unknown.",
+    "retry-with-backoff",
+    { kind: "retry", afterMs: 100, maxAttempts: 3 },
+    ["api", "agent-helpers", "projection"], "api-projection-unavailable"),
+  "api.batch_edit_collision": row("api", "error",
+    "A batched-edit operation targeted a range that had already been mutated by an earlier edit in the batch.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Rebuild the batch with non-overlapping ranges, or switch to mode: \"atomic\" to abort on conflict." },
+    ["api", "agent-helpers", "batch"], "api-batch-edit-collision"),
+  "api.workflow_patch_invalid": row("api", "error",
+    "A workflow-overlay patch referenced an unknown scopeId or candidateId.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Call getWorkflowOverlay() to enumerate live ids before patching." },
+    ["api", "agent-helpers", "workflow"], "api-workflow-patch-invalid"),
+  "api.change_id_unknown": row("api", "warning",
+    "The provided changeId did not match any comment or tracked-change revision.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Call findAllChanges() to enumerate live change ids." },
+    ["api", "agent-helpers", "change-lookup"], "api-change-id-unknown"),
+  "api.ai_explanation_anchor_invalid": row("api", "error",
+    "An AI-explanation scope could not be anchored — the referenced change is detached or the overlay refused the range.",
+    "requires-input",
+    { kind: "fallback", suggestion: "Filter findAllChanges() by liveOnly: true before attaching explanations." },
+    ["api", "agent-helpers", "ai-annotation"], "api-ai-explanation-anchor-invalid"),
+};
+
+/**
+ * Every key in this object is a valid {@link EditorDiagnosticCode}. Exported
+ * so test harnesses can assert exhaustiveness without importing the
+ * internal row shape.
+ */
+export const KNOWN_DIAGNOSTIC_CODES: ReadonlyArray<EditorDiagnosticCode> =
+  Object.freeze(Object.keys(CODE_METADATA_TABLE) as EditorDiagnosticCode[]);