@echovisionlab/geul-common 0.2.4 → 0.3.1

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);
+}

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

@@ -0,0 +1,348 @@
+import type { JsonValue } from "@bufbuild/protobuf";
+import * as Y from "yjs";
+import {
+  deleteBlockRoomPayloadArrayItem,
+  insertBlockRoomPayloadArrayItem,
+  moveBlockRoomPayloadArrayItem,
+  replaceBlockRoomCollaborativeText,
+  replaceBlockRoomPayloadArray,
+  setBlockRoomAtomicValue,
+} from "./payload-mutations.ts";
+import { fail, fromYValue } from "./internal.ts";
+import {
+  nodeTextPredicate,
+  payloadParent,
+  payloadValue,
+  roomNode,
+  type BlockRoomNodeRef,
+  type BlockRoomPayloadRef,
+} from "./room-access.ts";
+import { longestCommonSubsequence } from "./replay-structure.ts";
+import {
+  isBlockRoomInlineContentRef,
+  reconcileBlockRoomInlineContent,
+} from "./inline-content-mutations.ts";
+import { fromYInlineContent } from "./inline-content-projection.ts";
+import { mergeInlineIntent, mergeTextIntent } from "./replay-inline-merge.ts";
+
+const STABLE_ARRAY_ID_FIELDS = ["id", "rowId", "cellId", "unitId"] as const;
+
+function sameValue(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function jsonObject(
+  value: JsonValue | undefined,
+): Record<string, JsonValue> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, JsonValue>)
+    : undefined;
+}
+
+function payloadRef(node: BlockRoomNodeRef, path: string): BlockRoomPayloadRef {
+  return { ...node, path };
+}
+
+function readPayload(document: Y.Doc, ref: BlockRoomPayloadRef): unknown {
+  return payloadValue(
+    roomNode(document, ref),
+    ref.path,
+    `replay:payload:${ref.id}:${ref.path}`,
+  );
+}
+
+function isJsonArray(value: unknown): value is JsonValue[] {
+  return Array.isArray(value);
+}
+
+function stableArrayIdentityField(
+  before: readonly JsonValue[],
+  after: readonly JsonValue[],
+): (typeof STABLE_ARRAY_ID_FIELDS)[number] | undefined {
+  const compatible = (values: readonly JsonValue[], field: string) => {
+    const ids = values.map((value) => jsonObject(value)?.[field]);
+    return (
+      ids.every((id) => typeof id === "string" && id.length > 0) &&
+      new Set(ids).size === ids.length
+    );
+  };
+  for (const field of STABLE_ARRAY_ID_FIELDS) {
+    if (compatible(before, field) && compatible(after, field)) return field;
+  }
+  return undefined;
+}
+
+function identityOf(value: JsonValue, field: string): string {
+  const identity = jsonObject(value)?.[field];
+  return typeof identity === "string" && identity.length > 0
+    ? identity
+    : fail(`replay:stable_array_identity:${field}`);
+}
+
+function currentArrayItems(
+  array: Y.Array<unknown>,
+  field: string,
+): JsonValue[] {
+  const values = array.toArray().map((value) => fromYValue(value));
+  const ids = values.map((value) => identityOf(value, field));
+  if (new Set(ids).size !== ids.length)
+    fail(`replay:stable_array_duplicate:${field}`);
+  return values;
+}
+
+function indexOfIdentity(
+  values: readonly JsonValue[],
+  field: string,
+  id: string,
+): number {
+  return values.findIndex((value) => identityOf(value, field) === id);
+}
+
+function arrayPathItem(path: string, index: number): string {
+  return `${path}[${index}]`;
+}
+
+function mergeStableArray(
+  document: Y.Doc,
+  ref: BlockRoomNodeRef,
+  path: string,
+  before: readonly JsonValue[],
+  after: readonly JsonValue[],
+  identityField: string,
+): void {
+  const initial = readPayload(document, payloadRef(ref, path));
+  if (initial === undefined) {
+    replaceBlockRoomPayloadArray(document, payloadRef(ref, path), []);
+  }
+  const inserted = readPayload(document, payloadRef(ref, path));
+  if (!(inserted instanceof Y.Array))
+    fail(`replay:stable_array_shape:${ref.id}:${path}`);
+  const raw: Y.Array<unknown> = inserted;
+  const beforeIds = before.map((value) => identityOf(value, identityField));
+  const afterIds = after.map((value) => identityOf(value, identityField));
+  const beforeSet = new Set(beforeIds);
+  const afterSet = new Set(afterIds);
+  const beforeById = new Map(
+    before.map((value) => [identityOf(value, identityField), value]),
+  );
+  const afterById = new Map(
+    after.map((value) => [identityOf(value, identityField), value]),
+  );
+
+  for (const id of beforeIds) {
+    if (afterSet.has(id)) continue;
+    const values = currentArrayItems(raw, identityField);
+    const index = indexOfIdentity(values, identityField, id);
+    if (index >= 0)
+      deleteBlockRoomPayloadArrayItem(document, payloadRef(ref, path), index);
+  }
+
+  for (const id of beforeIds) {
+    if (!afterSet.has(id)) continue;
+    const values = currentArrayItems(raw, identityField);
+    const index = indexOfIdentity(values, identityField, id);
+    if (index < 0) continue;
+    const oldValue = beforeById.get(id)!;
+    const nextValue = afterById.get(id)!;
+    if (!sameValue(oldValue, nextValue)) {
+      applyPayloadDiff(
+        document,
+        payloadRef(ref, arrayPathItem(path, index)),
+        oldValue,
+        nextValue,
+      );
+    }
+  }
+
+  for (let afterIndex = 0; afterIndex < afterIds.length; afterIndex += 1) {
+    const id = afterIds[afterIndex]!;
+    if (beforeSet.has(id)) continue;
+    const values = currentArrayItems(raw, identityField);
+    if (indexOfIdentity(values, identityField, id) >= 0) continue;
+    const nextId = afterIds
+      .slice(afterIndex + 1)
+      .find(
+        (candidate) => indexOfIdentity(values, identityField, candidate) >= 0,
+      );
+    const insertionIndex = nextId
+      ? indexOfIdentity(values, identityField, nextId)
+      : values.length;
+    insertBlockRoomPayloadArrayItem(
+      document,
+      payloadRef(ref, path),
+      insertionIndex,
+      afterById.get(id)!,
+    );
+  }
+
+  const common = beforeIds.filter((id) => afterSet.has(id));
+  const afterCommon = afterIds.filter((id) => beforeSet.has(id));
+  const retained = longestCommonSubsequence(common, afterCommon);
+  for (const id of [...afterCommon].reverse()) {
+    if (retained.has(id)) continue;
+    const values = currentArrayItems(raw, identityField);
+    const fromIndex = indexOfIdentity(values, identityField, id);
+    if (fromIndex < 0) continue;
+    const afterPosition = afterIds.indexOf(id);
+    const nextId = afterIds
+      .slice(afterPosition + 1)
+      .find(
+        (candidate) => indexOfIdentity(values, identityField, candidate) >= 0,
+      );
+    const nextIndex = nextId
+      ? indexOfIdentity(values, identityField, nextId)
+      : values.length;
+    const toIndex = nextIndex - (fromIndex < nextIndex ? 1 : 0);
+    if (fromIndex === toIndex) continue;
+    moveBlockRoomPayloadArrayItem(
+      document,
+      payloadRef(ref, path),
+      fromIndex,
+      Math.max(0, toIndex),
+    );
+  }
+}
+
+function ensureObjectAtPath(
+  document: Y.Doc,
+  ref: BlockRoomPayloadRef,
+): Y.Map<unknown> {
+  const value = readPayload(document, ref);
+  if (value instanceof Y.Map) return value;
+  const { parent, key } = payloadParent(
+    roomNode(document, ref),
+    ref.path,
+    `replay:payload:${ref.id}:${ref.path}`,
+  );
+  // Object diffs recurse only after ensuring their parent object path.
+  const objectParent = parent as Y.Map<unknown>;
+  const objectKey = key as string;
+  const map = new Y.Map<unknown>();
+  objectParent.set(objectKey, map);
+  return map;
+}
+
+function deletePayloadValue(document: Y.Doc, ref: BlockRoomPayloadRef): void {
+  const value = readPayload(document, ref);
+  if (value === undefined) return;
+  const { parent, key } = payloadParent(
+    roomNode(document, ref),
+    ref.path,
+    `replay:payload:${ref.id}:${ref.path}`,
+  );
+  // Deletion diffs are emitted only for object keys, never array indexes.
+  const objectParent = parent as Y.Map<unknown>;
+  const objectKey = key as string;
+  objectParent.delete(objectKey);
+}
+
+function writePayloadValue(
+  document: Y.Doc,
+  ref: BlockRoomPayloadRef,
+  value: JsonValue[] | string | number | boolean | null,
+): void {
+  if (Array.isArray(value)) {
+    replaceBlockRoomPayloadArray(document, ref, value);
+    return;
+  }
+  setBlockRoomAtomicValue(document, ref, value);
+}
+
+function applyPayloadDiff(
+  document: Y.Doc,
+  ref: BlockRoomPayloadRef,
+  before: JsonValue | undefined,
+  after: JsonValue | undefined,
+): void {
+  if (
+    isBlockRoomInlineContentRef(ref) &&
+    (before === undefined || isJsonArray(before)) &&
+    (after === undefined || isJsonArray(after))
+  ) {
+    const current = readPayload(document, ref);
+    const peer = current instanceof Y.Array ? fromYInlineContent(current) : [];
+    reconcileBlockRoomInlineContent(
+      document,
+      ref,
+      peer,
+      mergeInlineIntent(before ?? [], after ?? [], peer),
+    );
+    return;
+  }
+  if (
+    (before === undefined || typeof before === "string") &&
+    (after === undefined || typeof after === "string") &&
+    nodeTextPredicate(roomNode(document, ref), ref)(ref.path)
+  ) {
+    const current = readPayload(document, ref);
+    if (current !== undefined && !(current instanceof Y.Text))
+      fail(`replay:payload_shape:${ref.id}:${ref.path}`);
+    replaceBlockRoomCollaborativeText(
+      document,
+      ref,
+      mergeTextIntent(before ?? "", after ?? "", current?.toString() ?? ""),
+    );
+    return;
+  }
+  if (after === undefined) {
+    deletePayloadValue(document, ref);
+    return;
+  }
+  const beforeObject = jsonObject(before);
+  if (after !== null && typeof after === "object" && !Array.isArray(after)) {
+    const afterObject = after as Record<string, JsonValue>;
+    const current = (() => {
+      try {
+        return readPayload(document, ref);
+      } catch {
+        return undefined;
+      }
+    })();
+    if (current !== undefined && !(current instanceof Y.Map))
+      fail(`replay:payload_shape:${ref.id}:${ref.path}`);
+    ensureObjectAtPath(document, ref);
+    for (const key of new Set([
+      ...Object.keys(beforeObject ?? {}),
+      ...Object.keys(afterObject),
+    ])) {
+      const oldValue = beforeObject?.[key];
+      const nextValue = afterObject[key];
+      if (sameValue(oldValue, nextValue)) continue;
+      applyPayloadDiff(
+        document,
+        payloadRef(ref, `${ref.path}.${key}`),
+        oldValue,
+        nextValue,
+      );
+    }
+    return;
+  }
+  if (isJsonArray(before) && isJsonArray(after)) {
+    const identityField = stableArrayIdentityField(before, after);
+    if (identityField) {
+      mergeStableArray(document, ref, ref.path, before, after, identityField);
+      return;
+    }
+  }
+  writePayloadValue(document, ref, after);
+}
+
+export function applyPayloadRootDiff(
+  document: Y.Doc,
+  ref: BlockRoomNodeRef,
+  before: JsonValue,
+  after: JsonValue,
+): void {
+  const beforeObject = jsonObject(before);
+  const afterObject = jsonObject(after);
+  if (!beforeObject || !afterObject) fail(`replay:payload_root:${ref.id}`);
+  for (const key of new Set([
+    ...Object.keys(beforeObject),
+    ...Object.keys(afterObject),
+  ])) {
+    const oldValue = beforeObject[key];
+    const nextValue = afterObject[key];
+    if (sameValue(oldValue, nextValue)) continue;
+    applyPayloadDiff(document, payloadRef(ref, key), oldValue, nextValue);
+  }
+}