@echovisionlab/geul-common 0.2.4 → 0.3.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@echovisionlab/geul-common",
   "description": "Shared TypeScript contracts and helpers for Geul editors, collaboration, localized content, media blocks, pages, posts, and runtime events.",
   "author": "state303 <state303@dsub.io>",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "repository": {
@@ -40,6 +40,7 @@
     "./collaboration/document": "./src/collaboration/document.ts",
     "./collaboration/email-layout": "./src/collaboration/email-layout.ts",
     "./collaboration/form": "./src/collaboration/form.ts",
+    "./collaboration/form-schema-delta": "./src/collaboration/form-schema-delta.ts",
     "./collaboration/label": "./src/collaboration/label.ts",
     "./collaboration/map-theme": "./src/collaboration/map-theme.ts",
     "./collaboration/menu": "./src/collaboration/menu.ts",
@@ -62,7 +63,8 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.14.0",
-    "@echovisionlab/geul-proto": "^0.2.0",
+    "@echovisionlab/geul-proto": "^0.3.0",
+    "diff": "9.0.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/collaboration/block-room-codec/internal.ts

@@ -354,24 +354,50 @@ function identityArray(
   value: JsonValue,
   collection: string,
   identity: string,
-  nestedCollection?: string,
-  nestedIdentity?: string,
 ): unknown[] {
   const object = jsonObject(value, "locale_identity:payload");
   const children = object[collection];
   if (!Array.isArray(children)) return [];
+  return children.map(
+    (child) => jsonObject(child, "locale_identity:item")[identity],
+  );
+}
+
+const tableIdentityPattern =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+function tableIdentityArray(
+  value: JsonValue,
+  collection: string,
+  identity: string,
+  nestedIdentity: string,
+): unknown[] {
+  const object = jsonObject(value, "locale_identity:payload");
+  const children = object[collection];
+  if (!Array.isArray(children)) return [];
+  const seenRows = new Set<string>();
+  const seenCells = new Set<string>();
   return children.map((child) => {
     const item = jsonObject(child, "locale_identity:item");
-    if (!nestedCollection || !nestedIdentity) return item[identity];
-    const nested = item[nestedCollection];
+    const rowId = item[identity];
+    if (typeof rowId !== "string" || !tableIdentityPattern.test(rowId))
+      fail("locale_identity:table_row_id");
+    if (seenRows.has(rowId)) fail("locale_identity:table_duplicate_row_id");
+    seenRows.add(rowId);
+    const nested = item.cells;
+    const cells = Array.isArray(nested) ? nested : [];
     return {
-      id: item[identity],
-      children: Array.isArray(nested)
-        ? nested.map(
-            (entry) =>
-              jsonObject(entry, "locale_identity:nested")[nestedIdentity],
-          )
-        : [],
+      id: rowId,
+      children: cells.map((entry) => {
+        const cell = jsonObject(entry, "locale_identity:nested");
+        const cellId = cell[nestedIdentity];
+        if (typeof cellId !== "string" || !tableIdentityPattern.test(cellId))
+          fail("locale_identity:table_cell_id");
+        if (seenCells.has(cellId))
+          fail("locale_identity:table_duplicate_cell_id");
+        seenCells.add(cellId);
+        return cellId;
+      }),
     };
   });
 }
@@ -402,18 +428,11 @@ export function assertBlockRoomLocaleProjectionParity(yDocument: Y.Doc): void {
         jsonObject(localePayload, `locale:${id}:payload`).content,
         `locale:${id}:content`,
       );
-      const baseIdentity = identityArray(
-        baseContent,
-        "rows",
-        "id",
-        "cells",
-        "id",
-      );
-      const localeIdentity = identityArray(
+      const baseIdentity = tableIdentityArray(baseContent, "rows", "id", "id");
+      const localeIdentity = tableIdentityArray(
         localeContent,
         "rows",
         "rowId",
-        "cells",
         "cellId",
       );
       if (JSON.stringify(baseIdentity) !== JSON.stringify(localeIdentity))

package/src/collaboration/block-room-codec/replay-base.ts

@@ -0,0 +1,195 @@
+import * as Y from "yjs";
+import {
+  blockRoomBaseNodes,
+  type CanonicalBlockRoomSnapshot,
+} from "./materialization.ts";
+import {
+  deleteBlockRoomBaseNode,
+  movePageSectionNode,
+  moveRichTextBlockNode,
+} from "./structure-mutations.ts";
+import { fail, type BlockRoomDocumentType } from "./internal.ts";
+import { applyPayloadRootDiff } from "./replay-payload.ts";
+import {
+  baseDepth,
+  currentBaseNodes,
+  currentNodeType,
+  insertBaseNode,
+  movedBaseIds,
+  nodeMap,
+  safeIndex,
+  sameContainer,
+  sameNodeType,
+  sameValue,
+  stableTreeAnchor,
+  destinationUnderDeletedObservedAncestor,
+} from "./replay-structure.ts";
+
+export function applyBaseAdditions(
+  document: Y.Doc,
+  type: BlockRoomDocumentType,
+  before: CanonicalBlockRoomSnapshot,
+  after: CanonicalBlockRoomSnapshot,
+): void {
+  const beforeBase = nodeMap(before.baseNodes);
+  const afterBase = nodeMap(after.baseNodes);
+  const newlyAddedIds = new Set(
+    [...afterBase.keys()].filter((id) => !beforeBase.has(id)),
+  );
+  const currentBeforeChanges = currentBaseNodes(document, type);
+  for (const [id, node] of afterBase) {
+    if (beforeBase.has(id)) continue;
+    const current = currentBeforeChanges.get(id);
+    if (current) {
+      if (!sameNodeType(current, node)) fail(`replay:kind_changed:${id}`);
+      // A replay may be retried after its prior insert became resident. Keep
+      // that already-existing node and its later peer edits intact.
+      newlyAddedIds.delete(id);
+    }
+  }
+  const additions = [...newlyAddedIds]
+    .map((id) => afterBase.get(id)!)
+    .sort(
+      (left, right) =>
+        baseDepth(afterBase, left.id) - baseDepth(afterBase, right.id) ||
+        left.position - right.position ||
+        left.id.localeCompare(right.id),
+    );
+  for (const node of additions) {
+    if (blockRoomBaseNodes(document).has(node.id)) continue;
+    if (
+      destinationUnderDeletedObservedAncestor(
+        node.id,
+        node.parentId,
+        beforeBase,
+        afterBase,
+        new Set(blockRoomBaseNodes(document).keys()),
+      )
+    )
+      continue;
+    insertBaseNode(document, type, after, node, newlyAddedIds);
+  }
+}
+
+export function applyBaseChanges(
+  document: Y.Doc,
+  before: CanonicalBlockRoomSnapshot,
+  after: CanonicalBlockRoomSnapshot,
+): void {
+  const beforeBase = nodeMap(before.baseNodes);
+  const afterBase = nodeMap(after.baseNodes);
+  const moved = movedBaseIds(before.baseNodes, after.baseNodes);
+  const escaping = [...moved]
+    .filter((id) => {
+      const oldNode = beforeBase.get(id)!;
+      const newNode = afterBase.get(id)!;
+      let ancestor = oldNode.parentId;
+      while (ancestor !== null) {
+        if (!afterBase.has(ancestor)) return true;
+        ancestor = beforeBase.get(ancestor)?.parentId ?? null;
+      }
+      return (
+        !sameContainer(oldNode, newNode) &&
+        !afterBase.has(oldNode.parentId ?? "")
+      );
+    })
+    .sort(
+      (left, right) =>
+        baseDepth(beforeBase, left) - baseDepth(beforeBase, right),
+    );
+  const moveNode = (id: string) => {
+    const desired = afterBase.get(id)!;
+    if (
+      destinationUnderDeletedObservedAncestor(
+        id,
+        desired.parentId,
+        beforeBase,
+        afterBase,
+        new Set(blockRoomBaseNodes(document).keys()),
+      )
+    )
+      return;
+    const existing = currentNodeType(blockRoomBaseNodes(document), id);
+    if (!existing) return;
+    const baseline = beforeBase.get(id)!;
+    if (!sameNodeType(existing, baseline)) fail(`replay:kind_changed:${id}`);
+    if (desired.family === "page_section") {
+      const anchor = stableTreeAnchor(document, after.baseNodes, desired);
+      movePageSectionNode(
+        document,
+        id,
+        {
+          ...(desired.parentId ? { parentSectionId: desired.parentId } : {}),
+          ...(desired.columnId ? { columnId: desired.columnId } : {}),
+          index: anchor ? desired.position : safeIndex(document, desired),
+        },
+        anchor ? { anchor } : {},
+      );
+    } else {
+      const anchor = stableTreeAnchor(document, after.baseNodes, desired);
+      moveRichTextBlockNode(
+        document,
+        id,
+        {
+          ...(desired.parentId &&
+          afterBase.get(desired.parentId)?.family === "rich_text"
+            ? { parentBlockId: desired.parentId }
+            : {}),
+          index: anchor ? desired.position : safeIndex(document, desired),
+        },
+        {
+          ...(desired.parentId &&
+          afterBase.get(desired.parentId)?.family === "page_section"
+            ? { pageSectionId: desired.parentId }
+            : {}),
+          ...(anchor ? { anchor } : {}),
+        },
+      );
+    }
+  };
+  for (const id of escaping) moveNode(id);
+
+  const deletedIds = new Set(
+    [...beforeBase.keys()].filter((id) => !afterBase.has(id)),
+  );
+  const topLevelDeletes = [...deletedIds]
+    .filter((id) => {
+      let parentId = beforeBase.get(id)!.parentId;
+      while (parentId !== null) {
+        if (deletedIds.has(parentId)) return false;
+        parentId = beforeBase.get(parentId)?.parentId ?? null;
+      }
+      return true;
+    })
+    .sort(
+      (left, right) =>
+        baseDepth(beforeBase, left) - baseDepth(beforeBase, right),
+    );
+  for (const id of topLevelDeletes) {
+    if (blockRoomBaseNodes(document).has(id))
+      deleteBlockRoomBaseNode(document, id);
+  }
+
+  const movedInAfterOrder = [...moved]
+    .filter((id) => !escaping.includes(id))
+    .sort(
+      (left, right) =>
+        afterBase.get(right)!.position - afterBase.get(left)!.position,
+    );
+  for (const id of movedInAfterOrder) moveNode(id);
+
+  for (const [id, oldNode] of beforeBase) {
+    const next = afterBase.get(id);
+    if (!next || sameValue(oldNode.payload, next.payload)) continue;
+    const existing = currentNodeType(blockRoomBaseNodes(document), id);
+    if (!existing) continue;
+    if (!sameNodeType(existing, oldNode) || !sameNodeType(next, oldNode))
+      fail(`replay:kind_changed:${id}`);
+    applyPayloadRootDiff(
+      document,
+      { id, family: oldNode.family },
+      oldNode.payload,
+      next.payload,
+    );
+  }
+}

package/src/collaboration/block-room-codec/replay-inline-merge.ts

@@ -0,0 +1,341 @@
+import type { JsonValue } from "@bufbuild/protobuf";
+import { diffArrays } from "diff";
+import { desiredGroups, type Style } from "./inline-content-model.ts";
+
+type Attributes = Record<string, string | boolean>;
+type Token =
+  | { kind: "text"; value: string; attributes: Attributes }
+  | { kind: "mathInline"; attributes: Attributes }
+  | { kind: "hardBreak"; attributes: Attributes }
+  | { kind: "emptyLink"; attributes: Attributes }
+  | { kind: "linkBoundary"; attributes: Attributes };
+
+const MAX_EXACT_EDIT_DISTANCE = 128;
+
+interface Projection<T> {
+  readonly retained: Map<number, T>;
+  readonly inserted: Map<number, T[]>;
+}
+
+function tokenIdentity(token: Token): string {
+  return token.kind === "text" ? `text:${token.value}` : token.kind;
+}
+
+/** Align text by Unicode code point; style/link changes remain attribute edits. */
+function project<T>(
+  before: readonly T[],
+  after: readonly T[],
+  identity: (token: T) => string,
+): Projection<T> {
+  const retained = new Map<number, T>();
+  const inserted = new Map<number, T[]>();
+  let position = 0;
+  const changes = diffArrays([...before], [...after], {
+    comparator: (left, right) => identity(left) === identity(right),
+    maxEditLength: MAX_EXACT_EDIT_DISTANCE,
+  });
+  if (!changes) return projectByForwardAnchors(before, after, identity);
+  for (const change of changes) {
+    if (change.added) {
+      inserted.set(position, change.value);
+    } else if (change.removed) {
+      position += change.count;
+    } else {
+      for (const token of change.value) retained.set(position++, token);
+    }
+  }
+  return { retained, inserted };
+}
+
+/**
+ * Large replacements do not need an optimal edit script. Forward occurrence
+ * indexes retain a monotonic common subsequence in linear time, so recovery
+ * remains bounded while still replaying insertions/deletions as author intent.
+ * Exact Myers alignment remains the normal path for ordinary editing.
+ */
+function projectByForwardAnchors<T>(
+  before: readonly T[],
+  after: readonly T[],
+  identity: (token: T) => string,
+): Projection<T> {
+  const occurrences = new Map<string, { positions: number[]; next: number }>();
+  before.forEach((token, index) => {
+    const key = identity(token);
+    let entry = occurrences.get(key);
+    if (!entry) {
+      entry = { positions: [], next: 0 };
+      occurrences.set(key, entry);
+    }
+    entry.positions.push(index);
+  });
+  const retained = new Map<number, T>();
+  const inserted = new Map<number, T[]>();
+  let cursor = 0;
+  let pending: T[] = [];
+  for (const token of after) {
+    const entry = occurrences.get(identity(token));
+    if (entry) {
+      while (
+        entry.next < entry.positions.length &&
+        entry.positions[entry.next]! < cursor
+      )
+        entry.next++;
+    }
+    const position = entry?.positions[entry.next];
+    if (position === undefined) {
+      pending.push(token);
+      continue;
+    }
+    if (pending.length) {
+      inserted.set(position, pending);
+      pending = [];
+    }
+    retained.set(position, token);
+    cursor = position + 1;
+    entry!.next++;
+  }
+  if (pending.length) inserted.set(before.length, pending);
+  return { retained, inserted };
+}
+
+function mergeAttributes(
+  before: Attributes,
+  local: Attributes,
+  peer: Attributes,
+): Attributes {
+  const result = { ...peer };
+  for (const key of new Set([...Object.keys(before), ...Object.keys(local)])) {
+    if (before[key] === local[key]) continue;
+    if (local[key] === undefined) delete result[key];
+    else result[key] = local[key];
+  }
+  return result;
+}
+
+function withAttributes(token: Token, attributes: Attributes): Token {
+  return { ...token, attributes };
+}
+
+function insertionIdentity(token: Token): string {
+  if (token.kind === "mathInline") return `math:${token.attributes.source}`;
+  if (token.kind === "emptyLink") return `emptyLink:${token.attributes.href}`;
+  return tokenIdentity(token);
+}
+
+/** Preserve each newly inserted adjacent link as a semantic group. */
+function linkedInsertionGroups(tokens: readonly Token[]): Token[][] | null {
+  if (!tokens.some((token) => token.kind === "linkBoundary")) return null;
+  if (
+    tokens.some(
+      (token) =>
+        token.kind !== "linkBoundary" &&
+        token.kind !== "emptyLink" &&
+        (token.kind !== "text" || token.attributes.href === undefined),
+    )
+  )
+    return null;
+  const groups: Token[][] = [[]];
+  for (const token of tokens) {
+    if (token.kind === "linkBoundary") groups.push([]);
+    else groups[groups.length - 1]!.push(token);
+  }
+  return groups;
+}
+
+function linkGroupIdentity(group: readonly Token[]): string {
+  return JSON.stringify(
+    group.map((token) => [insertionIdentity(token), token.attributes.href]),
+  );
+}
+
+/** An ordered union retains accepted inserts and appends only missing intent. */
+function mergeInsertionSequences<T>(
+  peer: readonly T[],
+  local: readonly T[],
+  identity: (value: T) => string,
+  merge: (peerValue: T, localValue: T) => T,
+): T[] {
+  if (local.length === 0) return [...peer];
+  if (peer.length === 0) return [...local];
+  const localProjection = project(peer, local, identity);
+  const result: T[] = [];
+  for (let position = 0; position <= peer.length; position++) {
+    for (const value of localProjection.inserted.get(position) ?? [])
+      result.push(value);
+    const peerValue = peer[position];
+    if (peerValue === undefined) continue;
+    const localValue = localProjection.retained.get(position);
+    result.push(
+      localValue === undefined ? peerValue : merge(peerValue, localValue),
+    );
+  }
+  return result;
+}
+
+function mergeInsertions(
+  peer: readonly Token[],
+  local: readonly Token[],
+): Token[] {
+  const peerGroups = linkedInsertionGroups(peer);
+  const localGroups = linkedInsertionGroups(local);
+  if (peerGroups && localGroups) {
+    // Matching separator tokens alone would join unrelated links from two
+    // insertion streams. Align whole link groups, then merge their run intent.
+    const groups = mergeInsertionSequences(
+      peerGroups,
+      localGroups,
+      linkGroupIdentity,
+      (peerGroup, localGroup) => mergeInsertions(peerGroup, localGroup),
+    );
+    const result: Token[] = [];
+    for (const group of groups) {
+      if (result.length) result.push({ kind: "linkBoundary", attributes: {} });
+      for (const token of group) result.push(token);
+    }
+    return result;
+  }
+  return mergeInsertionSequences(
+    peer,
+    local,
+    insertionIdentity,
+    (peerToken, localToken) =>
+      withAttributes(
+        peerToken,
+        mergeAttributes({}, localToken.attributes, peerToken.attributes),
+      ),
+  );
+}
+
+function mergeTokens(
+  before: readonly Token[],
+  local: readonly Token[],
+  peer: readonly Token[],
+): Token[] {
+  const localProjection = project(before, local, tokenIdentity);
+  const peerProjection = project(before, peer, tokenIdentity);
+  const result: Token[] = [];
+  for (let position = 0; position <= before.length; position++) {
+    for (const token of mergeInsertions(
+      peerProjection.inserted.get(position) ?? [],
+      localProjection.inserted.get(position) ?? [],
+    ))
+      result.push(token);
+    const localToken = localProjection.retained.get(position);
+    const peerToken = peerProjection.retained.get(position);
+    // An observed character removed on either side is never resurrected by
+    // formatting or another edit to the old projection.
+    if (localToken && peerToken) {
+      result.push(
+        withAttributes(
+          peerToken,
+          mergeAttributes(
+            before[position]!.attributes,
+            localToken.attributes,
+            peerToken.attributes,
+          ),
+        ),
+      );
+    }
+  }
+  return result;
+}
+
+function normalizedStyles(styles: Style): Attributes {
+  return Object.fromEntries(
+    Object.entries(styles).filter(
+      ([, value]) => value !== false && value !== "",
+    ),
+  );
+}
+
+function inlineTokens(content: readonly JsonValue[]): Token[] {
+  const tokens: Token[] = [];
+  let previousKind: string | undefined;
+  for (const group of desiredGroups(content)) {
+    if (group.kind === "link" && previousKind === "link")
+      tokens.push({ kind: "linkBoundary", attributes: {} });
+    previousKind = group.kind;
+    if (group.kind === "text" || group.kind === "link") {
+      if (group.kind === "link" && group.runs.length === 0)
+        tokens.push({ kind: "emptyLink", attributes: { href: group.href } });
+      for (const run of group.runs) {
+        const attributes = {
+          ...normalizedStyles(run.styles),
+          ...(group.kind === "link" ? { href: group.href } : {}),
+        };
+        for (const value of run.text)
+          tokens.push({ kind: "text", value, attributes });
+      }
+    } else if (group.kind === "mathInline") {
+      tokens.push({ kind: "mathInline", attributes: { source: group.source } });
+    } else {
+      tokens.push({ kind: "hardBreak", attributes: {} });
+    }
+  }
+  return tokens;
+}
+
+function inlineContent(tokens: readonly Token[]): JsonValue[] {
+  const result: JsonValue[] = [];
+  let runs: Array<{ text: string; styles?: Attributes }> | undefined;
+  let previousHref: string | boolean | undefined;
+  for (const token of tokens) {
+    if (token.kind !== "text") {
+      runs = undefined;
+      if (token.kind === "linkBoundary") continue;
+      result.push(
+        token.kind === "emptyLink"
+          ? { link: { href: token.attributes.href as string, content: [] } }
+          : token.kind === "mathInline"
+            ? { mathInline: { source: token.attributes.source as string } }
+            : { hardBreak: {} },
+      );
+      continue;
+    }
+    const { href, ...styles } = token.attributes;
+    if (!runs || previousHref !== href) {
+      runs = [];
+      if (href !== undefined) result.push({ link: { href, content: runs } });
+      previousHref = href;
+    }
+    const last = runs[runs.length - 1];
+    if (last && JSON.stringify(last.styles ?? {}) === JSON.stringify(styles)) {
+      last.text += token.value;
+    } else {
+      const run = {
+        text: token.value,
+        ...(Object.keys(styles).length ? { styles } : {}),
+      };
+      runs.push(run);
+      if (href === undefined) result.push({ text: run });
+    }
+  }
+  return result;
+}
+
+/** Replay only local character/attribute intent over the canonical projection. */
+export function mergeInlineIntent(
+  before: readonly JsonValue[],
+  local: readonly JsonValue[],
+  peer: readonly JsonValue[],
+): JsonValue[] {
+  return inlineContent(
+    mergeTokens(inlineTokens(before), inlineTokens(local), inlineTokens(peer)),
+  );
+}
+
+export function mergeTextIntent(
+  before: string,
+  local: string,
+  peer: string,
+): string {
+  const tokens = (value: string): Token[] =>
+    Array.from(value, (character) => ({
+      kind: "text",
+      value: character,
+      attributes: {},
+    }));
+  return mergeTokens(tokens(before), tokens(local), tokens(peer))
+    .map((token) => (token as Extract<Token, { kind: "text" }>).value)
+    .join("");
+}