@echovisionlab/geul-common 0.3.0 → 0.3.2

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.3.0",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "repository": {
@@ -10,9 +10,9 @@
     "url": "git+https://github.com/echovisionlab/geul-common.git"
   },
   "engines": {
-    "node": "24.19.0"
+    "node": "24.21.0"
   },
-  "packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
+  "packageManager": "pnpm@12.9.1",
   "files": [
     "README.md",
     "src",
@@ -62,24 +62,25 @@
     "./types": "./src/types.ts"
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.14.0",
-    "@echovisionlab/geul-proto": "^0.3.0",
-    "zod": "^4.4.3"
+    "@bufbuild/protobuf": "^2.16.0",
+    "@echovisionlab/geul-proto": "^0.4.1",
+    "diff": "9.0.0",
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "yjs": "^13.6.32"
+    "yjs": "^13.6.33"
   },
   "devDependencies": {
-    "@types/node": "^24.13.3",
+    "@types/node": "^24.19.1",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.8.1",
-    "knip": "6.32.2",
-    "prettier": "3.9.6",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
+    "knip": "6.39.0",
+    "prettier": "3.9.9",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.10",
-    "yjs": "^13.6.32"
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3",
+    "yjs": "^13.6.33"
   },
   "license": "PolyForm-Noncommercial-1.0.0",
   "homepage": "https://github.com/echovisionlab/geul-common#readme",

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

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

@@ -18,6 +18,12 @@ import {
   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;
 
@@ -239,12 +245,7 @@ function writePayloadValue(
     replaceBlockRoomPayloadArray(document, ref, value);
     return;
   }
-  const node = roomNode(document, ref);
-  if (typeof value === "string" && nodeTextPredicate(node, ref)(ref.path)) {
-    replaceBlockRoomCollaborativeText(document, ref, value);
-  } else {
-    setBlockRoomAtomicValue(document, ref, value);
-  }
+  setBlockRoomAtomicValue(document, ref, value);
 }
 
 function applyPayloadDiff(
@@ -253,6 +254,36 @@ function applyPayloadDiff(
   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;

package/src/collaboration/form-schema-delta.ts

@@ -4,8 +4,7 @@ export type FormSchemaPatchErrorReason =
   | "invalid_schema"
   | "schema_identity_changed"
   | "target_topology_changed"
-  | "schema_identity_collision"
-  | "schema_add_parent_missing";
+  | "schema_identity_collision";
 
 export class FormSchemaPatchError extends Error {
   constructor(readonly reason: FormSchemaPatchErrorReason) {
@@ -335,6 +334,7 @@ export function applyFormSchemaPatch(
   }
 
   const added = new Set<string>();
+  const skippedAdditions = new Set<string>();
   for (const [key, node] of next.nodes) {
     if (previous.nodes.has(key)) continue;
     if (result.nodes.has(key)) {
@@ -344,8 +344,15 @@ export function applyFormSchemaPatch(
       }
       continue;
     }
-    if (node.parent !== ROOT_PARENT && !result.nodes.has(node.parent)) {
-      throw new FormSchemaPatchError("schema_add_parent_missing");
+    // Schemas are indexed parent-first. A missing parent here is an observed
+    // peer deletion or a new parent already skipped beneath one.
+    if (
+      node.parent !== ROOT_PARENT &&
+      (skippedAdditions.has(node.parent) ||
+        (previous.nodes.has(node.parent) && !current.nodes.has(node.parent)))
+    ) {
+      skippedAdditions.add(key);
+      continue;
     }
     result.nodes.set(key, structuredClone(node));
     added.add(key);

package/src/collaboration/menu.ts

@@ -158,6 +158,7 @@ export function replaceMenuCanonicalSource(
     sourceLabels.delete(id);
   }
   for (const [id, item] of nextById) {
+    if (!document.getMap<string>(MENU_ITEMS_MAP_NAME).has(id)) continue;
     const before = previousById.get(id);
     const previouslyOwned = before
       ? menuItemOwnsLocaleLabel(before, locale)
@@ -242,6 +243,10 @@ function replaceMenuStructure(
   const items = document.getMap<string>(MENU_ITEMS_MAP_NAME);
   const parents = document.getMap<string>(MENU_PARENTS_MAP_NAME);
   const orders = document.getMap<number>(MENU_ORDERS_MAP_NAME);
+  const liveIDs = new Set(items.keys());
+  const peerDeletedObservedIDs = new Set(
+    [...previousIDs].filter((id) => !liveIDs.has(id)),
+  );
   const childrenByParent = new Map<string, string[]>();
   for (const id of items.keys()) {
     const parent = parents.get(id) ?? MENU_ROOT_PARENT;
@@ -251,11 +256,25 @@ function replaceMenuStructure(
   }
 
   const deletedIDs = new Set([...previousIDs].filter((id) => !nextIDs.has(id)));
+  for (const id of peerDeletedObservedIDs) deletedIDs.add(id);
+  const skippedNextIDs = new Set<string>();
+  const blockedNextParents = new Set(peerDeletedObservedIDs);
+  for (const { item, parent } of flattened) {
+    if (blockedNextParents.has(parent) || peerDeletedObservedIDs.has(item.id)) {
+      skippedNextIDs.add(item.id);
+      blockedNextParents.add(item.id);
+    }
+  }
   const pendingDeletedIDs = [...deletedIDs];
   for (let index = 0; index < pendingDeletedIDs.length; index += 1) {
     const deletedParent = pendingDeletedIDs[index]!;
     for (const childId of childrenByParent.get(deletedParent) ?? []) {
-      if (nextIDs.has(childId) || deletedIDs.has(childId)) continue;
+      if (
+        (nextIDs.has(childId) && !skippedNextIDs.has(childId)) ||
+        deletedIDs.has(childId)
+      ) {
+        continue;
+      }
       deletedIDs.add(childId);
       pendingDeletedIDs.push(childId);
     }
@@ -266,6 +285,7 @@ function replaceMenuStructure(
     orders.delete(id);
   }
   for (const { item, parent, order } of flattened) {
+    if (skippedNextIDs.has(item.id)) continue;
     const before = previousById.get(item.id);
     const stored = menuItemStructure(item);
     if (