@echovisionlab/geul-common 0.2.4 → 0.3.0

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.0",
   "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,7 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.14.0",
-    "@echovisionlab/geul-proto": "^0.2.0",
+    "@echovisionlab/geul-proto": "^0.3.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-locale.ts

@@ -0,0 +1,182 @@
+import type { JsonValue } from "@bufbuild/protobuf";
+import * as Y from "yjs";
+import {
+  allBlockRoomLocaleValueTargets,
+  blockRoomLocaleValueIsEncoded,
+  markBlockRoomLocaleValuePresent,
+} from "./locale-presence.ts";
+import {
+  blockRoomBaseNodes,
+  blockRoomLocaleOverlay,
+  type CanonicalBlockRoomSnapshot,
+} from "./materialization.ts";
+import { applyPayloadRootDiff } from "./replay-payload.ts";
+import {
+  currentNodeType,
+  insertLocaleNode,
+  nodeMap,
+  sameNodeType,
+  sameValue,
+} from "./replay-structure.ts";
+import { fail } from "./internal.ts";
+
+interface LocaleIntentTarget {
+  target: ReturnType<typeof allBlockRoomLocaleValueTargets>[number];
+}
+
+function jsonObject(
+  value: JsonValue | undefined,
+): Record<string, JsonValue> | undefined {
+  return value === undefined ? undefined : (value as Record<string, JsonValue>);
+}
+
+function targetPath(
+  target: LocaleIntentTarget["target"],
+): Array<readonly ["field" | "item", string]> {
+  return target.path.map(({ selector }) => {
+    if (selector.case === "fieldHandle")
+      return ["field", selector.value] as const;
+    // Locale targets are generated by allBlockRoomLocaleValueTargets from
+    // canonical field/item handles, so the only other selector is itemHandle.
+    return ["item", selector.value as string] as const;
+  });
+}
+
+function rawLocaleValue(
+  snapshot: CanonicalBlockRoomSnapshot,
+  target: LocaleIntentTarget["target"],
+): JsonValue | undefined {
+  const ownerId = target.owner.value as string;
+  const overlay = snapshot.localeOverlay.find((node) => node.id === ownerId);
+  if (!overlay) return undefined;
+  const payload = jsonObject(overlay.payload)!;
+  const path = targetPath(target);
+  if (overlay.family === "rich_text") {
+    if (target.fieldHandle === "content") return payload.content;
+    if (target.fieldHandle === "tableContent") {
+      const rows = jsonObject(payload.content)!.rows as JsonValue[];
+      const row = rows.find(
+        (candidate) => jsonObject(candidate)!.rowId === path[1]?.[1],
+      );
+      if (row === undefined) return undefined;
+      const cells = jsonObject(row)!.cells as JsonValue[];
+      const cell = cells.find(
+        (candidate) => jsonObject(candidate)!.cellId === path[3]?.[1],
+      );
+      if (cell === undefined) return undefined;
+      return jsonObject(cell)!.content;
+    }
+    return jsonObject(payload.props)?.[target.fieldHandle];
+  }
+  if (path[0]?.[1] === "props") return jsonObject(payload.props)?.[path[1]![1]];
+  const units = payload.units as JsonValue[];
+  const unit = units.find(
+    (candidate) => jsonObject(candidate)!.unitId === path[1]![1],
+  );
+  if (unit === undefined) return undefined;
+  return jsonObject(jsonObject(unit)!.props)?.[path[3]![1]];
+}
+
+function changedLocaleIntentTargets(
+  document: Y.Doc,
+  before: CanonicalBlockRoomSnapshot,
+  after: CanonicalBlockRoomSnapshot,
+): LocaleIntentTarget[] {
+  const oldNodes = nodeMap(before.localeOverlay);
+  const nextNodes = nodeMap(after.localeOverlay);
+  const changedNodeIds = new Set<string>();
+  for (const id of new Set([...oldNodes.keys(), ...nextNodes.keys()])) {
+    const oldNode = oldNodes.get(id);
+    const nextNode = nextNodes.get(id);
+    if (
+      !oldNode ||
+      !nextNode ||
+      !sameNodeType(oldNode, nextNode) ||
+      !sameValue(oldNode.payload, nextNode.payload)
+    )
+      changedNodeIds.add(id);
+  }
+  if (changedNodeIds.size === 0) return [];
+  const changed: LocaleIntentTarget[] = [];
+  for (const target of allBlockRoomLocaleValueTargets(document)) {
+    if (!changedNodeIds.has(target.owner.value as string)) continue;
+    const nextValue = rawLocaleValue(after, target);
+    const oldValue = rawLocaleValue(before, target);
+    if (
+      !sameValue(oldValue, nextValue) &&
+      blockRoomLocaleValueIsEncoded(document, target)
+    )
+      changed.push({ target });
+  }
+  return changed;
+}
+
+export function applyLocaleAdditions(
+  document: Y.Doc,
+  before: CanonicalBlockRoomSnapshot,
+  after: CanonicalBlockRoomSnapshot,
+  isTarget: boolean,
+): void {
+  // Canonical source rooms add shared base nodes and their locale projections
+  // together. Target rooms cannot add base nodes (replay.ts checks parity).
+  if (isTarget) return;
+
+  const beforeLocale = nodeMap(before.localeOverlay);
+  const afterLocale = nodeMap(after.localeOverlay);
+  const newlyAddedLocaleIds = new Set(
+    [...afterLocale.keys()].filter((id) => !beforeLocale.has(id)),
+  );
+  for (const id of afterLocale.keys()) {
+    if (beforeLocale.has(id)) continue;
+    // Base insertion may have been skipped because a peer deleted an observed
+    // ancestor. Keep that subtree absent in both projections.
+    if (!blockRoomBaseNodes(document).has(id)) continue;
+    if (blockRoomLocaleOverlay(document).has(id)) {
+      newlyAddedLocaleIds.delete(id);
+    }
+  }
+  const localeAdds = [...newlyAddedLocaleIds]
+    .map((id) => afterLocale.get(id)!)
+    .sort(
+      (left, right) =>
+        (left.family === "page_section" ? 0 : 1) -
+        (right.family === "page_section" ? 0 : 1),
+    );
+  for (const node of localeAdds) {
+    // Inserting a Page section can include all newly-added descendant locale
+    // nodes, so a later entry in this same pass may already be resident.
+    if (blockRoomLocaleOverlay(document).has(node.id)) continue;
+    insertLocaleNode(document, after, node, newlyAddedLocaleIds);
+  }
+}
+
+export function applyLocaleChanges(
+  document: Y.Doc,
+  before: CanonicalBlockRoomSnapshot,
+  after: CanonicalBlockRoomSnapshot,
+): void {
+  const beforeLocale = nodeMap(before.localeOverlay);
+  const afterLocale = nodeMap(after.localeOverlay);
+  const currentBaseIds = new Set(blockRoomBaseNodes(document).keys());
+  // Canonical snapshots have one locale overlay per base node. Source base
+  // deletion already removes that projection; target snapshots cannot delete
+  // it without changing the base, which replay.ts rejects.
+
+  for (const [id, oldNode] of beforeLocale) {
+    const next = afterLocale.get(id);
+    if (!next || sameValue(oldNode.payload, next.payload)) continue;
+    if (!currentBaseIds.has(id)) continue;
+    const existing = currentNodeType(blockRoomLocaleOverlay(document), id)!;
+    if (!sameNodeType(existing, oldNode) || !sameNodeType(next, oldNode))
+      fail(`replay:kind_changed:${id}`);
+    applyPayloadRootDiff(
+      document,
+      { id, family: oldNode.family, locale: true },
+      oldNode.payload,
+      next.payload,
+    );
+  }
+
+  for (const { target } of changedLocaleIntentTargets(document, before, after))
+    markBlockRoomLocaleValuePresent(document, target);
+}