@arbidocs/coedit 0.5.21 → 0.5.23

package/dist/encoding.d.cts

@@ -2,6 +2,28 @@ import * as _docx_editor_dev_core_store from '@docx-editor.dev/core/store';
 import { OoxmlPackage } from '@docx-editor.dev/core/store';
 import * as Y from 'yjs';
 
+/**
+ * Elements of the mirror, in both directions: plain `XmlEl` objects to Yjs types and back, and
+ * `XmlEl` to XML text.
+ *
+ * Three forms:
+ *
+ * - A paragraph is held as a rich paragraph (see rich.ts) whenever it can be represented exactly:
+ *   its properties stay in `children`, and its inline content is the single Y.Text `inline`.
+ * - An element with no editable text anywhere below it (a style, a numbering definition, a font, a
+ *   setting, a theme, paragraph or table properties, a section's setup) is packed: the map holds
+ *   its whole subtree as one XML string under `xml`. It is opened into a plain tree when an edit
+ *   touches it and written back whole, so concurrent edits to the same packed element are last
+ *   writer wins, while different elements (two styles) still merge. Held as a tree, every element,
+ *   attribute and namespace URI was its own CRDT item: a 350 KB styles part took 3.2 MB of room
+ *   state and over 100 MB of heap to load.
+ * - Every other element (the body, a table, a cell, a footnote: the path to editable text) is a
+ *   generic map with a `children` array.
+ */
+
+/** Prefixes in scope for an element; innermost binding wins. */
+type Scope = ReadonlyMap<string, string>;
+
 /**
  * Identity registry between core's logical node ids and the Yjs mirror.
  *
@@ -14,10 +36,12 @@ import * as Y from 'yjs';
  * under construction, detached, or about to move are therefore held as plain objects and converted
  * to Yjs types when they are attached to a live parent. `snapshot` is the live to plain direction.
  *
- * Rich paragraphs (see rich.ts) hold their runs as attributes on one Y.Text, so their inner nodes
- * have no Yjs type of their own. The first effect that touches one opens it: it is read into a plain
- * tree, the journal's effects change that tree, and `flushRich` writes the result back as a minimal
- * edit of the text. The tree stays open, mirroring the editor's own, until a remote change re-reads it.
+ * Rich paragraphs (see rich.ts) hold their runs as attributes on one Y.Text, and packed elements
+ * (see mirror.ts) hold their subtree as one XML string, so their inner nodes have no Yjs type of
+ * their own. The first effect that touches one opens it: it is read into a plain tree, the journal's
+ * effects change that tree, and `flushRich` writes the result back (a minimal edit of the text, or
+ * the packed element's new XML). The tree stays open, mirroring the editor's own, until a remote
+ * change re-reads it.
  */
 
 interface PlainElement {
@@ -69,7 +93,7 @@ declare class NodeRegistry {
     /**
      * Walk a mirror root and register every node under its positional id, `${part}#0` for the root and
      * `${parent}.${index}` below it. This is the id scheme core assigns when it reads a part. A rich
-     * paragraph is registered as one node; its inner nodes appear when it is opened.
+     * paragraph or a packed element is registered as one node; its inner nodes appear when it is opened.
      */
     registerTree(partName: string, root: Y.Map<unknown>): void;
     private own;
@@ -85,10 +109,10 @@ declare class NodeRegistry {
     touch(node: PlainNode): void;
     /** Nodes just placed under `parent` belong to the same paragraph as it, if any. */
     adopt(parent: PlainElement, children: readonly PlainNode[]): void;
-    /** Write every changed open paragraph back into the mirror. Call at the end of a journal. */
+    /** Write every changed open paragraph or packed element back into the mirror. Call at the end of a journal. */
     flushRich(): void;
     private writeBack;
-    /** The paragraph can no longer be held as rich text: store it as plain elements instead. */
+    /** The paragraph can no longer be held as rich text, or the element packed: store it as a tree. */
     private degrade;
     /** Deep copy of a node into plain objects carrying the same ids. */
     snapshot(id: string): PlainNode;
@@ -99,17 +123,28 @@ declare class NodeRegistry {
      */
     detach(node: LiveNode): void;
     private detachInto;
-    /** Build Yjs types for a plain subtree and register every node as live. */
-    toLive(plain: PlainNode): LiveNode;
+    /**
+     * Build Yjs types for a plain subtree placed where `scope` is in force, and register every node as
+     * live. A rich paragraph or packed element stays open on the plain tree, which is already current.
+     * A part's `root` is never packed.
+     */
+    toLive(plain: PlainNode, scope?: Scope, root?: boolean): LiveNode;
     private toGenericLive;
     /**
-     * A live node that can be inserted into a parent. Anything not yet attached is built fresh; an
-     * attached node is copied, because a Yjs type cannot have two parents.
+     * A live node that can be inserted into a parent (`scope` is in force there), or a part's `root`.
+     * Anything not yet attached is built fresh; an attached node is copied, because a Yjs type cannot
+     * have two parents.
      */
-    attachable(id: string): LiveNode;
+    attachable(id: string, scope?: Scope, root?: boolean): LiveNode;
 }
 
-declare const COLLAB_FORMAT = "arbi-docx/1";
+/**
+ * The room format this build writes. `arbi-docx/2` holds elements without editable text packed (see
+ * mirror.ts); it reads `arbi-docx/1` rooms, whose elements are all trees, unchanged. A build that
+ * only knows `/1` cannot read a packed element, so the client handshake requires this exact format.
+ */
+declare const COLLAB_FORMAT = "arbi-docx/2";
+declare function isReadableFormat(format: string | undefined): boolean;
 interface AttrJson {
     ns: string;
     local: string;
@@ -150,6 +185,7 @@ interface CanonicalText {
     readonly kind: 'textValue';
     readonly value: string;
 }
+/** The Yjs form of a part's root element. */
 declare function encodeElement(el: CanonicalElement): Y.Map<unknown>;
 declare function encodeText(value: string): Y.Text;
 /** Seed an empty Yjs document from a loaded package. Call once, inside a transaction. */
@@ -191,4 +227,4 @@ declare function materializeBytes(doc: Y.Doc): Uint8Array;
 /** Load DOCX bytes and seed an empty room from them. */
 declare function bootstrapFromBytes(doc: Y.Doc, bytes: Uint8Array): OoxmlPackage;
 
-export { type AttrJson, type BindingJson, COLLAB_FORMAT, MaterializeCache, MaterializeError, type RelationshipJson, bootstrap, bootstrapFromBytes, contentTypeOf, encodeElement, encodeText, isBootstrapped, materialize, materializeBytes, readFormat, registerMirror, serializePart };
+export { type AttrJson, type BindingJson, COLLAB_FORMAT, MaterializeCache, MaterializeError, type RelationshipJson, bootstrap, bootstrapFromBytes, contentTypeOf, encodeElement, encodeText, isBootstrapped, isReadableFormat, materialize, materializeBytes, readFormat, registerMirror, serializePart };

package/dist/encoding.d.ts

@@ -2,6 +2,28 @@ import * as _docx_editor_dev_core_store from '@docx-editor.dev/core/store';
 import { OoxmlPackage } from '@docx-editor.dev/core/store';
 import * as Y from 'yjs';
 
+/**
+ * Elements of the mirror, in both directions: plain `XmlEl` objects to Yjs types and back, and
+ * `XmlEl` to XML text.
+ *
+ * Three forms:
+ *
+ * - A paragraph is held as a rich paragraph (see rich.ts) whenever it can be represented exactly:
+ *   its properties stay in `children`, and its inline content is the single Y.Text `inline`.
+ * - An element with no editable text anywhere below it (a style, a numbering definition, a font, a
+ *   setting, a theme, paragraph or table properties, a section's setup) is packed: the map holds
+ *   its whole subtree as one XML string under `xml`. It is opened into a plain tree when an edit
+ *   touches it and written back whole, so concurrent edits to the same packed element are last
+ *   writer wins, while different elements (two styles) still merge. Held as a tree, every element,
+ *   attribute and namespace URI was its own CRDT item: a 350 KB styles part took 3.2 MB of room
+ *   state and over 100 MB of heap to load.
+ * - Every other element (the body, a table, a cell, a footnote: the path to editable text) is a
+ *   generic map with a `children` array.
+ */
+
+/** Prefixes in scope for an element; innermost binding wins. */
+type Scope = ReadonlyMap<string, string>;
+
 /**
  * Identity registry between core's logical node ids and the Yjs mirror.
  *
@@ -14,10 +36,12 @@ import * as Y from 'yjs';
  * under construction, detached, or about to move are therefore held as plain objects and converted
  * to Yjs types when they are attached to a live parent. `snapshot` is the live to plain direction.
  *
- * Rich paragraphs (see rich.ts) hold their runs as attributes on one Y.Text, so their inner nodes
- * have no Yjs type of their own. The first effect that touches one opens it: it is read into a plain
- * tree, the journal's effects change that tree, and `flushRich` writes the result back as a minimal
- * edit of the text. The tree stays open, mirroring the editor's own, until a remote change re-reads it.
+ * Rich paragraphs (see rich.ts) hold their runs as attributes on one Y.Text, and packed elements
+ * (see mirror.ts) hold their subtree as one XML string, so their inner nodes have no Yjs type of
+ * their own. The first effect that touches one opens it: it is read into a plain tree, the journal's
+ * effects change that tree, and `flushRich` writes the result back (a minimal edit of the text, or
+ * the packed element's new XML). The tree stays open, mirroring the editor's own, until a remote
+ * change re-reads it.
  */
 
 interface PlainElement {
@@ -69,7 +93,7 @@ declare class NodeRegistry {
     /**
      * Walk a mirror root and register every node under its positional id, `${part}#0` for the root and
      * `${parent}.${index}` below it. This is the id scheme core assigns when it reads a part. A rich
-     * paragraph is registered as one node; its inner nodes appear when it is opened.
+     * paragraph or a packed element is registered as one node; its inner nodes appear when it is opened.
      */
     registerTree(partName: string, root: Y.Map<unknown>): void;
     private own;
@@ -85,10 +109,10 @@ declare class NodeRegistry {
     touch(node: PlainNode): void;
     /** Nodes just placed under `parent` belong to the same paragraph as it, if any. */
     adopt(parent: PlainElement, children: readonly PlainNode[]): void;
-    /** Write every changed open paragraph back into the mirror. Call at the end of a journal. */
+    /** Write every changed open paragraph or packed element back into the mirror. Call at the end of a journal. */
     flushRich(): void;
     private writeBack;
-    /** The paragraph can no longer be held as rich text: store it as plain elements instead. */
+    /** The paragraph can no longer be held as rich text, or the element packed: store it as a tree. */
     private degrade;
     /** Deep copy of a node into plain objects carrying the same ids. */
     snapshot(id: string): PlainNode;
@@ -99,17 +123,28 @@ declare class NodeRegistry {
      */
     detach(node: LiveNode): void;
     private detachInto;
-    /** Build Yjs types for a plain subtree and register every node as live. */
-    toLive(plain: PlainNode): LiveNode;
+    /**
+     * Build Yjs types for a plain subtree placed where `scope` is in force, and register every node as
+     * live. A rich paragraph or packed element stays open on the plain tree, which is already current.
+     * A part's `root` is never packed.
+     */
+    toLive(plain: PlainNode, scope?: Scope, root?: boolean): LiveNode;
     private toGenericLive;
     /**
-     * A live node that can be inserted into a parent. Anything not yet attached is built fresh; an
-     * attached node is copied, because a Yjs type cannot have two parents.
+     * A live node that can be inserted into a parent (`scope` is in force there), or a part's `root`.
+     * Anything not yet attached is built fresh; an attached node is copied, because a Yjs type cannot
+     * have two parents.
      */
-    attachable(id: string): LiveNode;
+    attachable(id: string, scope?: Scope, root?: boolean): LiveNode;
 }
 
-declare const COLLAB_FORMAT = "arbi-docx/1";
+/**
+ * The room format this build writes. `arbi-docx/2` holds elements without editable text packed (see
+ * mirror.ts); it reads `arbi-docx/1` rooms, whose elements are all trees, unchanged. A build that
+ * only knows `/1` cannot read a packed element, so the client handshake requires this exact format.
+ */
+declare const COLLAB_FORMAT = "arbi-docx/2";
+declare function isReadableFormat(format: string | undefined): boolean;
 interface AttrJson {
     ns: string;
     local: string;
@@ -150,6 +185,7 @@ interface CanonicalText {
     readonly kind: 'textValue';
     readonly value: string;
 }
+/** The Yjs form of a part's root element. */
 declare function encodeElement(el: CanonicalElement): Y.Map<unknown>;
 declare function encodeText(value: string): Y.Text;
 /** Seed an empty Yjs document from a loaded package. Call once, inside a transaction. */
@@ -191,4 +227,4 @@ declare function materializeBytes(doc: Y.Doc): Uint8Array;
 /** Load DOCX bytes and seed an empty room from them. */
 declare function bootstrapFromBytes(doc: Y.Doc, bytes: Uint8Array): OoxmlPackage;
 
-export { type AttrJson, type BindingJson, COLLAB_FORMAT, MaterializeCache, MaterializeError, type RelationshipJson, bootstrap, bootstrapFromBytes, contentTypeOf, encodeElement, encodeText, isBootstrapped, materialize, materializeBytes, readFormat, registerMirror, serializePart };
+export { type AttrJson, type BindingJson, COLLAB_FORMAT, MaterializeCache, MaterializeError, type RelationshipJson, bootstrap, bootstrapFromBytes, contentTypeOf, encodeElement, encodeText, isBootstrapped, isReadableFormat, materialize, materializeBytes, readFormat, registerMirror, serializePart };

package/dist/encoding.js

@@ -312,6 +312,20 @@ function writeUnits(text, units) {
 function isRichParagraph(map) {
   return map.has("inline");
 }
+var PACKED = "xml";
+function isPackedElement(map) {
+  return map.has(PACKED);
+}
+var TEXT_BEARING = /* @__PURE__ */ new Set(["p", "t", "delText", "instrText", "delInstrText"]);
+function packable(xml) {
+  if (xml.ns === WML && TEXT_BEARING.has(xml.local)) return false;
+  return xml.children.every((c) => typeof c === "string" || packable(c));
+}
+function createPacked(xml, scope) {
+  const map = new Y.Map();
+  map.set(PACKED, serializeXml(xml, scope));
+  return map;
+}
 function isParagraphEl(el) {
   return el.ns === WML && el.local === "p";
 }
@@ -331,57 +345,47 @@ function newText(value) {
   text.insert(0, value);
   return text;
 }
-function createRichParagraph(xml, encoded) {
+function createRichParagraph(xml, encoded, scope = /* @__PURE__ */ new Map()) {
   const map = new Y.Map();
   fieldsOf(map, xml);
+  const inner = withBindings(scope, xml.bindings);
   const children = new Y.Array();
-  children.push(encoded.head.map((el) => xmlToLive(el)));
+  children.push(encoded.head.map((el) => xmlToLive(el, inner)));
   map.set("children", children);
   const inline = new Y.Text();
   writeUnits(inline, encoded.units);
   map.set("inline", inline);
   return map;
 }
-function xmlToLive(xml) {
+function withBindings(scope, bindings) {
+  const inner = new Map(scope);
+  for (const b of bindings) inner.set(b.prefix, b.ns);
+  return inner;
+}
+function xmlToLive(xml, scope = /* @__PURE__ */ new Map(), root = false) {
   if (isParagraphEl(xml)) {
     const encoded = encodeParagraph(xml.children);
-    if (encoded) return createRichParagraph(xml, encoded);
+    if (encoded) return createRichParagraph(xml, encoded, scope);
   }
-  return xmlToGenericLive(xml);
-}
-function xmlToGenericLive(xml) {
+  if (!root && packable(xml)) return createPacked(xml, scope);
   const map = new Y.Map();
   fieldsOf(map, xml);
+  const inner = withBindings(scope, xml.bindings);
   const children = new Y.Array();
-  children.push(xml.children.map((c) => typeof c === "string" ? newText(c) : xmlToLive(c)));
+  children.push(xml.children.map((c) => typeof c === "string" ? newText(c) : xmlToLive(c, inner)));
   map.set("children", children);
   return map;
 }
-function liveToXml(map) {
-  const prefix = map.get("prefix");
-  const stored = map.get("children").toArray().map((child) => child instanceof Y.Text ? child.toString() : liveToXml(child));
-  const children = isRichParagraph(map) ? [...stored, ...decodeInline(readUnits(map.get("inline")))] : stored;
-  const xml = {
-    ns: map.get("ns"),
-    local: map.get("local"),
-    attrs: map.get("attrs").toArray().map((a) => ({ ...a })),
-    bindings: map.get("bindings").toArray().map((b) => ({ ...b })),
-    children
-  };
-  if (prefix !== void 0) xml.prefix = prefix;
-  return xml;
-}
 var escapeText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 var escapeAttr = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/\t/g, "&#9;").replace(/\n/g, "&#10;").replace(/\r/g, "&#13;");
 var qualified = (prefix, local) => prefix ? `${prefix}:${local}` : local;
-function serializeXml(el, scope) {
-  const inScope = new Map(scope);
-  for (const b of el.bindings) inScope.set(b.prefix, b.ns);
-  let out = `<${qualified(el.prefix, el.local)}`;
-  for (const b of el.bindings) {
+function startTag(prefix, local, bindings, attrs, scope) {
+  const inScope = withBindings(scope, bindings);
+  let out = `<${qualified(prefix, local)}`;
+  for (const b of bindings) {
     out += b.prefix === "" ? ` xmlns="${escapeAttr(b.ns)}"` : ` xmlns:${b.prefix}="${escapeAttr(b.ns)}"`;
   }
-  for (const a of el.attrs) {
+  for (const a of attrs) {
     let p = a.prefix;
     if (a.ns !== "" && !p) {
       for (const [candidate, uri] of inScope) {
@@ -393,48 +397,41 @@ function serializeXml(el, scope) {
     }
     out += ` ${qualified(p, a.local)}="${escapeAttr(a.value)}"`;
   }
+  return [out, inScope];
+}
+function serializeXml(el, scope) {
+  const [out, inScope] = startTag(el.prefix, el.local, el.bindings, el.attrs, scope);
   if (el.children.length === 0) return `${out}/>`;
-  out += ">";
+  let body = "";
   for (const child of el.children) {
-    out += typeof child === "string" ? escapeText(child) : serializeXml(child, inScope);
+    body += typeof child === "string" ? escapeText(child) : serializeXml(child, inScope);
   }
-  return `${out}</${qualified(el.prefix, el.local)}>`;
+  return `${out}>${body}</${qualified(el.prefix, el.local)}>`;
 }
 function serializeLive(el, scope) {
-  if (isRichParagraph(el)) return serializeXml(liveToXml(el), scope);
+  if (isPackedElement(el)) return el.get(PACKED);
   const prefix = el.get("prefix");
   const local = el.get("local");
   const bindings = el.get("bindings").toArray();
   const attrs = el.get("attrs").toArray();
   const children = el.get("children").toArray();
-  const inScope = new Map(scope);
-  for (const b of bindings) inScope.set(b.prefix, b.ns);
-  let out = `<${qualified(prefix, local)}`;
-  for (const b of bindings) {
-    out += b.prefix === "" ? ` xmlns="${escapeAttr(b.ns)}"` : ` xmlns:${b.prefix}="${escapeAttr(b.ns)}"`;
-  }
-  for (const a of attrs) {
-    let p = a.prefix;
-    if (a.ns !== "" && !p) {
-      for (const [candidate, uri] of inScope) {
-        if (candidate !== "" && uri === a.ns) {
-          p = candidate;
-          break;
-        }
-      }
-    }
-    out += ` ${qualified(p, a.local)}="${escapeAttr(a.value)}"`;
-  }
-  if (children.length === 0) return `${out}/>`;
-  out += ">";
+  const [out, inScope] = startTag(prefix, local, bindings, attrs, scope);
+  const inline = isRichParagraph(el) ? decodeInline(readUnits(el.get("inline"))) : [];
+  if (children.length === 0 && inline.length === 0) return `${out}/>`;
+  let body = "";
   for (const child of children) {
-    out += child instanceof Y.Text ? escapeText(child.toString()) : serializeLive(child, inScope);
+    body += child instanceof Y.Text ? escapeText(child.toString()) : serializeLive(child, inScope);
   }
-  return `${out}</${qualified(prefix, local)}>`;
+  for (const child of inline) body += serializeXml(child, inScope);
+  return `${out}>${body}</${qualified(prefix, local)}>`;
 }
 
 // src/encoding.ts
-var COLLAB_FORMAT = "arbi-docx/1";
+var COLLAB_FORMAT = "arbi-docx/2";
+var READABLE_FORMATS = /* @__PURE__ */ new Set(["arbi-docx/1", COLLAB_FORMAT]);
+function isReadableFormat(format) {
+  return format !== void 0 && READABLE_FORMATS.has(format);
+}
 function isText(node) {
   return node.kind === "textValue";
 }
@@ -455,7 +452,7 @@ function canonicalToXml(node) {
   return xml;
 }
 function encodeElement(el) {
-  return xmlToLive(canonicalToXml(el));
+  return xmlToLive(canonicalToXml(el), /* @__PURE__ */ new Map(), true);
 }
 function encodeText(value) {
   return newText(value);
@@ -711,6 +708,6 @@ function bootstrapFromBytes(doc, bytes) {
   return result.package;
 }
 
-export { COLLAB_FORMAT, MaterializeCache, MaterializeError, bootstrap, bootstrapFromBytes, contentTypeOf, encodeElement, encodeText, isBootstrapped, materialize, materializeBytes, readFormat, registerMirror, serializePart };
+export { COLLAB_FORMAT, MaterializeCache, MaterializeError, bootstrap, bootstrapFromBytes, contentTypeOf, encodeElement, encodeText, isBootstrapped, isReadableFormat, materialize, materializeBytes, readFormat, registerMirror, serializePart };
 //# sourceMappingURL=encoding.js.map
 //# sourceMappingURL=encoding.js.map