@echovisionlab/geul-common 0.2.1 → 0.2.2

package/README.md

@@ -26,6 +26,27 @@ pnpm package:smoke
 local changes, `typecheck:local-contracts` and `test:local-contracts` resolve it
 from the sibling `geul-event-contracts` checkout.
 
+## Block Room inline content
+
+Use `reconcileBlockRoomInlineContent` to set rich-text inline runs, including
+their marks. It keeps the existing collaborative `Y.Text` handles and projects
+character-level Y.Text attributes over the legacy per-run `styles` maps.
+Deploy readers of character-level inline attributes before enabling writers.
+The Web and Collab consumers use Block-room protocol version 2 to reject an
+older editor before admission; the persisted canonical protobuf schema stays
+unchanged.
+
+`setAIDocumentField` routes whole inline `content` updates through this same
+reconciler. `setBlockRoomAtomicValue` only writes catalog-declared scalar
+fields; there is no generic payload-field setter for inline styles.
+
+`replaceBlockRoomCollaborativeText` replaces the entire value of one
+collaborative text leaf. It is intended for scalar text fields such as Page
+section captions. On an inline text leaf, replacing the whole value also
+removes that leaf's character-level Y.Text formatting while leaving any legacy
+`styles` map in place. Use the inline reconciler when replacing inline text
+that must retain or change marks.
+
 ## Release
 
 Release Please creates releases from `main`. npm publication uses GitHub

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.1",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
   "repository": {

package/src/collaboration/block-room-codec/ai-document-field-mutations.ts

@@ -15,6 +15,11 @@ import type {
 import * as Y from "yjs";
 import { fromYValue, isCollaborativeTextPath, toYValue } from "./internal.ts";
 import { blockRoomBaseNodes } from "./materialization.ts";
+import { fromYInlineContent } from "./inline-content-projection.ts";
+import {
+  isBlockRoomInlineContentRef,
+  reconcileBlockRoomInlineContent,
+} from "./inline-content-mutations.ts";
 import {
   blockRoomLocaleValueRef,
   deleteBlockRoomLocalePresenceForBlocks,
@@ -166,6 +171,7 @@ function ensureYParent(node: Y.Map<unknown>, path: string): void {
 }
 
 function replaceYValue(
+  yDocument: Y.Doc,
   node: Y.Map<unknown>,
   ref: BlockRoomPayloadRef,
   value: JsonValue,
@@ -185,6 +191,15 @@ function replaceYValue(
     return;
   }
   if (current instanceof Y.Array && Array.isArray(value)) {
+    if (isBlockRoomInlineContentRef(ref)) {
+      reconcileBlockRoomInlineContent(
+        yDocument,
+        ref,
+        fromYInlineContent(current),
+        value,
+      );
+      return;
+    }
     if (current.length > 0) current.delete(0, current.length);
     if (value.length > 0) {
       current.insert(
@@ -301,6 +316,7 @@ function reconcileSourceTableLocale(yDocument: Y.Doc, blockId: string): void {
     };
   });
   replaceYValue(
+    yDocument,
     localeNode,
     { id: blockId, family: "rich_text", locale: true, path: "content" },
     { rows } as JsonValue,
@@ -346,6 +362,7 @@ function reconcileSourceImmersiveLocale(
     },
   );
   replaceYValue(
+    yDocument,
     localeNode,
     {
       id: blockId,
@@ -500,6 +517,7 @@ export function setAIDocumentField(
     operationFail("target_locale_scalar_required");
   }
   replaceYValue(
+    yDocument,
     node,
     ref,
     target.field === "table" ? sourceTableValue(next) : next,
@@ -541,7 +559,7 @@ export function attachAIDocumentFile(
   const target = blockTarget(targetValue);
   const { ref, descriptor } = fieldRef(yDocument, target, targetValue, true);
   if (descriptor?.type !== "file_attachment") operationFail("file:field");
-  replaceYValue(roomNode(yDocument, ref), ref, {
+  replaceYValue(yDocument, roomNode(yDocument, ref), ref, {
     activeFileId: requiredHandle(file, "file:handle"),
   });
 }

package/src/collaboration/block-room-codec/inline-content-mutations.ts

@@ -0,0 +1,857 @@
+import type { JsonValue } from "@bufbuild/protobuf";
+import {
+  richTextBlockCatalog,
+  richTextBlockKindByProtoCase,
+  type RichTextBlockKind,
+} from "@echovisionlab/geul-proto/content/block_catalog.ts";
+import * as Y from "yjs";
+import {
+  arrayPath,
+  fail,
+  isCollaborativeTextPath,
+  toYValue,
+} from "./internal.ts";
+import {
+  fromYInlineContent,
+  projectedStyledTextRuns,
+  richTextStyleKeys,
+} from "./inline-content-projection.ts";
+import {
+  nodeKind,
+  payloadArray,
+  payloadParent,
+  roomNode,
+  type BlockRoomMutationOptions,
+  type BlockRoomPayloadRef,
+} from "./room-access.ts";
+
+type RichTextCatalogEntry = {
+  readonly content: string;
+};
+
+const richTextCatalog = richTextBlockCatalog as Readonly<
+  Record<string, RichTextCatalogEntry>
+>;
+const styleKeys = richTextStyleKeys();
+
+type StyleValue = boolean | string;
+type Style = Partial<Record<(typeof styleKeys)[number], StyleValue>>;
+type StyledRun = { text: string; styles: Style };
+
+interface RawTextSegment {
+  text?: Y.Text;
+  readonly styledText: Y.Map<unknown>;
+  readonly rawIndex: number;
+}
+
+interface RawTextGroup {
+  readonly kind: "text";
+  rawStart: number;
+  rawEnd: number;
+  readonly segments: RawTextSegment[];
+}
+
+interface RawLinkGroup {
+  readonly kind: "link";
+  readonly rawStart: number;
+  readonly rawEnd: number;
+  readonly link: Y.Map<unknown>;
+  readonly content?: Y.Array<unknown>;
+  readonly segments: RawTextSegment[];
+}
+
+interface RawMathGroup {
+  readonly kind: "mathInline";
+  readonly rawStart: number;
+  readonly rawEnd: number;
+  readonly text: Y.Text;
+}
+
+interface RawHardBreakGroup {
+  readonly kind: "hardBreak";
+  readonly rawStart: number;
+  readonly rawEnd: number;
+}
+
+type RawGroup = RawTextGroup | RawLinkGroup | RawMathGroup | RawHardBreakGroup;
+
+interface DesiredTextGroup {
+  readonly kind: "text";
+  readonly runs: StyledRun[];
+}
+
+interface DesiredLinkGroup {
+  readonly kind: "link";
+  readonly href: string;
+  readonly runs: StyledRun[];
+}
+
+interface DesiredMathGroup {
+  readonly kind: "mathInline";
+  readonly source: string;
+}
+
+interface DesiredHardBreakGroup {
+  readonly kind: "hardBreak";
+}
+
+type DesiredGroup =
+  | DesiredTextGroup
+  | DesiredLinkGroup
+  | DesiredMathGroup
+  | DesiredHardBreakGroup;
+
+function object(value: unknown, reason: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return fail(reason);
+  }
+  return value as Record<string, unknown>;
+}
+
+function yMap(value: unknown, reason: string): Y.Map<unknown> {
+  if (!(value instanceof Y.Map)) {
+    return fail(reason);
+  }
+  return value;
+}
+
+function checkedStyles(value: unknown, reason: string): Style {
+  if (value === undefined || value === null) {
+    return {};
+  }
+  const raw = object(value, reason);
+  const result: Style = {};
+  for (const key of styleKeys) {
+    const style = raw[key];
+    if (style === undefined || style === null) {
+      continue;
+    }
+    if (key === "textColor" || key === "backgroundColor") {
+      if (typeof style !== "string") {
+        return fail(`${reason}:${key}`);
+      }
+    } else if (typeof style !== "boolean") {
+      return fail(`${reason}:${key}`);
+    }
+    result[key] = style;
+  }
+  return result;
+}
+
+function normalizeStyles(value: Style): Style {
+  const result: Style = {};
+  for (const key of styleKeys) {
+    const style = value[key];
+    if (style === undefined || style === false || style === "") {
+      continue;
+    }
+    result[key] = style;
+  }
+  return result;
+}
+
+function styleKey(value: Style): string {
+  return JSON.stringify(normalizeStyles(value));
+}
+
+function appendRun(target: StyledRun[], next: StyledRun): void {
+  const previous = target[target.length - 1];
+  if (previous && styleKey(previous.styles) === styleKey(next.styles)) {
+    previous.text += next.text;
+    return;
+  }
+  target.push({ text: next.text, styles: { ...next.styles } });
+}
+
+function appendSourceRun(target: StyledRun[], next: StyledRun): void {
+  if (next.text.length > 0) {
+    target.push({ text: next.text, styles: { ...next.styles } });
+  }
+}
+
+function styledInput(value: unknown, reason: string): StyledRun {
+  if (typeof value === "string") {
+    return { text: value, styles: {} };
+  }
+  const styled = object(value, reason);
+  if (typeof styled.text !== "string") {
+    return fail(`${reason}:text`);
+  }
+  return {
+    text: styled.text,
+    styles: checkedStyles(styled.styles, `${reason}:styles`),
+  };
+}
+
+function inputItem(value: JsonValue, reason: string): DesiredGroup {
+  const item = object(value, reason);
+  const cases = ["text", "link", "mathInline", "hardBreak"].filter(
+    (key) => item[key] !== undefined,
+  );
+  if (cases.length !== 1) {
+    return fail(`${reason}:oneof`);
+  }
+  const selected = cases[0]!;
+  if (selected === "text") {
+    const run = styledInput(item.text, `${reason}:text`);
+    return { kind: "text", runs: run.text ? [run] : [] };
+  }
+  if (selected === "link") {
+    const link = object(item.link, `${reason}:link`);
+    if (typeof link.href !== "string" || !Array.isArray(link.content)) {
+      return fail(`${reason}:link_shape`);
+    }
+    const runs: StyledRun[] = [];
+    link.content.forEach((child, index) => {
+      appendSourceRun(
+        runs,
+        styledInput(child, `${reason}:link_content:${index}`),
+      );
+    });
+    return { kind: "link", href: link.href, runs };
+  }
+  if (selected === "mathInline") {
+    const math = object(item.mathInline, `${reason}:math`);
+    if (math.source !== undefined && typeof math.source !== "string") {
+      return fail(`${reason}:math_source`);
+    }
+    return {
+      kind: "mathInline",
+      source: (math.source as string | undefined) ?? "",
+    };
+  }
+  return { kind: "hardBreak" };
+}
+
+function desiredGroups(values: readonly JsonValue[]): DesiredGroup[] {
+  const result: DesiredGroup[] = [];
+  values.forEach((value, index) => {
+    const group = inputItem(value, `inline_content:input:${index}`);
+    const previous = result[result.length - 1];
+    if (group.kind === "text" && previous?.kind === "text") {
+      for (const run of group.runs) {
+        appendSourceRun(previous.runs, run);
+      }
+      return;
+    }
+    if (group.kind === "text" && group.runs.length === 0) {
+      return;
+    }
+    result.push(group);
+  });
+  return result;
+}
+
+function normalizeInlineContent(values: readonly JsonValue[]): string {
+  const normalized = desiredGroups(values).map((group) => {
+    if (group.kind === "text") {
+      const canonicalRuns: StyledRun[] = [];
+      for (const run of group.runs) {
+        appendRun(canonicalRuns, run);
+      }
+      return {
+        text: canonicalRuns.map((run) => ({
+          text: run.text,
+          styles: normalizeStyles(run.styles),
+        })),
+      };
+    }
+    if (group.kind === "link") {
+      const canonicalRuns: StyledRun[] = [];
+      for (const run of group.runs) {
+        appendRun(canonicalRuns, run);
+      }
+      return {
+        link: {
+          href: group.href,
+          content: canonicalRuns.map((run) => ({
+            text: run.text,
+            styles: normalizeStyles(run.styles),
+          })),
+        },
+      };
+    }
+    if (group.kind === "mathInline") {
+      return { mathInline: { source: group.source } };
+    }
+    return { hardBreak: {} };
+  });
+  return JSON.stringify(normalized);
+}
+
+function rawStyledText(
+  value: unknown,
+  rawIndex: number,
+  reason: string,
+): RawTextSegment {
+  const styledText = yMap(value, reason);
+  const text = styledText.get("text");
+  if (text !== undefined && !(text instanceof Y.Text)) {
+    return fail(`${reason}:text`);
+  }
+  return {
+    ...(text instanceof Y.Text ? { text } : {}),
+    styledText,
+    rawIndex,
+  };
+}
+
+function rawInlineItem(
+  array: Y.Array<unknown>,
+  index: number,
+  reason: string,
+): RawGroup {
+  // reconcileArray first runs fromYInlineContent, which validates this map and
+  // its oneof before the raw handles are resolved.
+  const item = array.get(index) as Y.Map<unknown>;
+  const selected = ["text", "link", "mathInline", "hardBreak"].find((key) =>
+    item.has(key),
+  )!;
+  if (selected === "text") {
+    const segment = rawStyledText(item.get("text"), index, `${reason}:text`);
+    return {
+      kind: "text",
+      rawStart: index,
+      rawEnd: index + 1,
+      segments: [segment],
+    };
+  }
+  if (selected === "link") {
+    const link = yMap(item.get("link"), `${reason}:link`);
+    const rawContent = link.get("content");
+    const content = rawContent as Y.Array<unknown> | undefined;
+    const segments =
+      content
+        ?.toArray()
+        .map((child, childIndex) =>
+          rawStyledText(
+            child,
+            childIndex,
+            `${reason}:link_content:${childIndex}`,
+          ),
+        ) ?? [];
+    return {
+      kind: "link",
+      rawStart: index,
+      rawEnd: index + 1,
+      link,
+      content,
+      segments,
+    };
+  }
+  if (selected === "mathInline") {
+    const math = yMap(item.get("mathInline"), `${reason}:math`);
+    const text = math.get("source");
+    if (!(text instanceof Y.Text)) {
+      return fail(`${reason}:math_source`);
+    }
+    return {
+      kind: "mathInline",
+      rawStart: index,
+      rawEnd: index + 1,
+      text,
+    };
+  }
+  return { kind: "hardBreak", rawStart: index, rawEnd: index + 1 };
+}
+
+function rawGroups(array: Y.Array<unknown>): RawGroup[] {
+  const result: RawGroup[] = [];
+  for (let index = 0; index < array.length; index += 1) {
+    const item = rawInlineItem(array, index, `inline_content:raw:${index}`);
+    const previous = result[result.length - 1];
+    if (item.kind === "text" && previous?.kind === "text") {
+      previous.segments.push(...item.segments);
+      previous.rawEnd = item.rawEnd;
+      continue;
+    }
+    result.push(item);
+  }
+  return result;
+}
+
+function rawGroupKind(group: RawGroup): DesiredGroup["kind"] {
+  return group.kind;
+}
+
+interface StyleSpan {
+  readonly from: number;
+  readonly to: number;
+  readonly styles: Style;
+}
+
+function styleSpans(runs: readonly StyledRun[], start = 0): StyleSpan[] {
+  const result: StyleSpan[] = [];
+  let from = start;
+  for (const run of runs) {
+    const to = from + run.text.length;
+    result.push({ from, to, styles: normalizeStyles(run.styles) });
+    from = to;
+  }
+  return result;
+}
+
+function changedStyleAttributes(
+  before: Style,
+  after: Style,
+): Record<string, StyleValue> {
+  const current = normalizeStyles(before);
+  const desired = normalizeStyles(after);
+  const result: Record<string, StyleValue> = {};
+  for (const key of styleKeys) {
+    if (current[key] === desired[key]) {
+      continue;
+    }
+    const value = desired[key];
+    result[key] =
+      value !== undefined
+        ? value
+        : key === "textColor" || key === "backgroundColor"
+          ? ""
+          : false;
+  }
+  return result;
+}
+
+function minimalDiff(
+  before: string,
+  after: string,
+): {
+  from: number;
+  oldTo: number;
+  newTo: number;
+} {
+  let from = 0;
+  while (
+    from < before.length &&
+    from < after.length &&
+    before[from] === after[from]
+  ) {
+    from += 1;
+  }
+  let oldTo = before.length;
+  let newTo = after.length;
+  while (
+    oldTo > from &&
+    newTo > from &&
+    before[oldTo - 1] === after[newTo - 1]
+  ) {
+    oldTo -= 1;
+    newTo -= 1;
+  }
+  return { from, oldTo, newTo };
+}
+
+function segmentText(segment: RawTextSegment): string {
+  return segment.text?.toString() ?? "";
+}
+
+function ensureText(segment: RawTextSegment): Y.Text {
+  if (segment.text) {
+    return segment.text;
+  }
+  const text = new Y.Text();
+  segment.styledText.set("text", text);
+  segment.text = text;
+  return text;
+}
+
+function applyDesiredTextStyles(
+  segments: readonly RawTextSegment[],
+  runs: readonly StyledRun[],
+): void {
+  const desiredSpans = styleSpans(runs);
+  let globalStart = 0;
+  for (const segment of segments) {
+    const segmentLength = segment.text!.length;
+    const segmentEnd = globalStart + segmentLength;
+    const currentRuns = projectedStyledTextRuns(
+      segment.styledText,
+      "inline_content:current_styles",
+    ).map((value) => styledInput(value, "inline_content:current_style_run"));
+    const currentSpans = styleSpans(currentRuns, globalStart);
+    let position = globalStart;
+    let currentIndex = 0;
+    let desiredIndex = 0;
+    while (position < segmentEnd) {
+      while (
+        currentSpans[currentIndex] &&
+        currentSpans[currentIndex]!.to <= position
+      ) {
+        currentIndex += 1;
+      }
+      while (
+        desiredSpans[desiredIndex] &&
+        desiredSpans[desiredIndex]!.to <= position
+      ) {
+        desiredIndex += 1;
+      }
+      const currentSpan = currentSpans[currentIndex]!;
+      const desiredSpan = desiredSpans[desiredIndex]!;
+      const end = Math.min(segmentEnd, currentSpan.to, desiredSpan.to);
+      const attributes = changedStyleAttributes(
+        currentSpan.styles,
+        desiredSpan.styles,
+      );
+      if (Object.keys(attributes).length > 0) {
+        ensureText(segment).format(
+          position - globalStart,
+          end - position,
+          attributes,
+        );
+      }
+      position = end;
+    }
+    globalStart = segmentEnd;
+  }
+}
+
+function reconcileTextSegments(
+  segments: RawTextSegment[],
+  array: Y.Array<unknown>,
+  rawInsertIndex: number,
+  desiredRuns: readonly StyledRun[],
+  path: string,
+  predicate: (path: string) => boolean,
+): void {
+  const before = segments.map(segmentText).join("");
+  const after = desiredRuns.map((run) => run.text).join("");
+
+  const currentRunsBySegment = segments.map((segment) =>
+    projectedStyledTextRuns(
+      segment.styledText,
+      "inline_content:current_styles",
+    ).map((value) => styledInput(value, "inline_content:current_style_run")),
+  );
+  const projectedRunCount = currentRunsBySegment.reduce(
+    (count, runs) => count + runs.length,
+    0,
+  );
+  if (
+    segments.length === desiredRuns.length &&
+    segments.length === projectedRunCount &&
+    currentRunsBySegment.every((runs) => runs.length === 1)
+  ) {
+    segments.forEach((segment, index) => {
+      const currentText = segmentText(segment);
+      const desiredText = desiredRuns[index]!.text;
+      const diff = minimalDiff(currentText, desiredText);
+      if (diff.oldTo > diff.from) {
+        segment.text!.delete(diff.from, diff.oldTo - diff.from);
+      }
+      const inserted = desiredText.slice(diff.from, diff.newTo);
+      if (inserted.length > 0) {
+        ensureText(segment).insert(diff.from, inserted);
+      }
+    });
+    applyDesiredTextStyles(segments, desiredRuns);
+    return;
+  }
+
+  const diff = minimalDiff(before, after);
+  const starts: number[] = [];
+  let position = 0;
+  for (const segment of segments) {
+    starts.push(position);
+    position += segment.text?.length ?? 0;
+  }
+  for (let index = segments.length - 1; index >= 0; index -= 1) {
+    const segment = segments[index]!;
+    const start = starts[index]!;
+    const end = start + (segment.text?.length ?? 0);
+    const deleteStart = Math.max(start, diff.from);
+    const deleteEnd = Math.min(end, diff.oldTo);
+    if (deleteEnd > deleteStart) {
+      segment.text!.delete(deleteStart - start, deleteEnd - deleteStart);
+    }
+  }
+  const inserted = desiredRuns
+    .map((run) => run.text)
+    .join("")
+    .slice(diff.from, diff.newTo);
+  if (inserted.length > 0) {
+    if (segments.length === 0) {
+      // Only an empty nested link can have no raw text segments. The top-level
+      // inline projection represents an empty text item with one segment.
+      const value = { text: inserted };
+      const raw = toYValue(value, arrayPath(path, rawInsertIndex), predicate);
+      array.insert(rawInsertIndex, [raw]);
+      segments.push(
+        rawStyledText(
+          array.get(rawInsertIndex),
+          rawInsertIndex,
+          "inline_content:new_link_text",
+        ),
+      );
+    } else {
+      let consumed = 0;
+      let target = segments[segments.length - 1]!;
+      let localOffset = target.text?.length ?? 0;
+      for (const segment of segments) {
+        const length = segment.text?.length ?? 0;
+        if (diff.from <= consumed + length) {
+          target = segment;
+          localOffset = diff.from - consumed;
+          break;
+        }
+        consumed += length;
+      }
+      ensureText(target).insert(localOffset, inserted);
+    }
+  }
+  applyDesiredTextStyles(segments, desiredRuns);
+}
+
+function reconcileRawGroup(
+  raw: RawGroup,
+  desired: DesiredGroup,
+  array: Y.Array<unknown>,
+  path: string,
+  predicate: (path: string) => boolean,
+): void {
+  if (raw.kind === "text" && desired.kind === "text") {
+    reconcileTextSegments(
+      raw.segments,
+      array,
+      raw.rawStart,
+      desired.runs,
+      path,
+      predicate,
+    );
+    return;
+  }
+  if (raw.kind === "link" && desired.kind === "link") {
+    raw.link.set("href", desired.href);
+    const content = raw.content ?? new Y.Array<unknown>();
+    if (!raw.content && desired.runs.some((run) => run.text.length > 0)) {
+      raw.link.set("content", content);
+    }
+    reconcileTextSegments(
+      raw.segments,
+      content,
+      0,
+      desired.runs,
+      `${arrayPath(path, raw.rawStart)}.link.content`,
+      predicate,
+    );
+    return;
+  }
+  if (raw.kind === "mathInline" && desired.kind === "mathInline") {
+    const diff = minimalDiff(raw.text.toString(), desired.source);
+    if (diff.oldTo > diff.from) {
+      raw.text.delete(diff.from, diff.oldTo - diff.from);
+    }
+    const inserted = desired.source.slice(diff.from, diff.newTo);
+    if (inserted.length > 0) {
+      raw.text.insert(diff.from, inserted);
+    }
+  }
+}
+
+function createRawValue(group: DesiredGroup): JsonValue {
+  if (group.kind === "text") {
+    const text = group.runs.map((run) => run.text).join("");
+    return { text: { text } };
+  }
+  if (group.kind === "link") {
+    const text = group.runs.map((run) => run.text).join("");
+    return {
+      link: {
+        href: group.href,
+        content: text.length > 0 ? [{ text }] : [],
+      },
+    };
+  }
+  if (group.kind === "mathInline") {
+    return { mathInline: { source: group.source } };
+  }
+  return { hardBreak: {} };
+}
+
+function formatNewGroup(
+  array: Y.Array<unknown>,
+  index: number,
+  group: DesiredGroup,
+): void {
+  if (group.kind !== "text" && group.kind !== "link") {
+    return;
+  }
+  const raw = rawInlineItem(array, index, "inline_content:new_group") as
+    RawTextGroup | RawLinkGroup;
+  applyDesiredTextStyles(raw.segments, group.runs);
+}
+
+function inlinePathKind(kind: string, path: string): "inline" | "table" | null {
+  const catalogKind =
+    richTextBlockKindByProtoCase[
+      kind as keyof typeof richTextBlockKindByProtoCase
+    ];
+  if (!catalogKind) {
+    return null;
+  }
+  const entry = richTextCatalog[catalogKind as RichTextBlockKind]!;
+  if (entry.content === "inline" && path === "content") {
+    return "inline";
+  }
+  if (
+    entry.content === "table" &&
+    /^content\.rows\[\d+\]\.cells\[\d+\]\.content$/.test(path)
+  ) {
+    return "table";
+  }
+  return null;
+}
+
+function canonicalInlinePrevious(
+  current: readonly JsonValue[],
+  previous: readonly JsonValue[],
+): void {
+  const currentKey = normalizeInlineContent(current);
+  const previousKey = normalizeInlineContent(previous);
+  if (currentKey !== previousKey) {
+    fail("stale_inline_content");
+  }
+}
+
+function reconcileArray(
+  array: Y.Array<unknown>,
+  ref: BlockRoomPayloadRef,
+  kind: string,
+  previous: readonly JsonValue[],
+  next: readonly JsonValue[],
+): void {
+  const current = fromYInlineContent(array);
+  canonicalInlinePrevious(current, previous);
+  const currentGroups = rawGroups(array);
+  const nextGroups = desiredGroups(next);
+  if (normalizeInlineContent(current) === normalizeInlineContent(next)) {
+    return;
+  }
+  const predicate = (textPath: string): boolean =>
+    isCollaborativeTextPath(ref.family, kind, textPath);
+  let prefix = 0;
+  while (
+    prefix < currentGroups.length &&
+    prefix < nextGroups.length &&
+    rawGroupKind(currentGroups[prefix]!) === nextGroups[prefix]!.kind
+  ) {
+    reconcileRawGroup(
+      currentGroups[prefix]!,
+      nextGroups[prefix]!,
+      array,
+      ref.path,
+      predicate,
+    );
+    prefix += 1;
+  }
+  let suffix = 0;
+  while (
+    suffix < currentGroups.length - prefix &&
+    suffix < nextGroups.length - prefix &&
+    rawGroupKind(currentGroups[currentGroups.length - 1 - suffix]!) ===
+      nextGroups[nextGroups.length - 1 - suffix]!.kind
+  ) {
+    suffix += 1;
+  }
+  for (let index = 0; index < suffix; index += 1) {
+    const raw = currentGroups[currentGroups.length - suffix + index]!;
+    const desired = nextGroups[nextGroups.length - suffix + index]!;
+    reconcileRawGroup(raw, desired, array, ref.path, predicate);
+  }
+  const removed = currentGroups.slice(prefix, currentGroups.length - suffix);
+  if (removed.length > 0) {
+    const start = removed[0]!.rawStart;
+    const end = removed[removed.length - 1]!.rawEnd;
+    array.delete(start, end - start);
+  }
+  const inserted = nextGroups.slice(prefix, nextGroups.length - suffix);
+  let rawIndex =
+    removed.length > 0
+      ? removed[0]!.rawStart
+      : prefix < currentGroups.length
+        ? currentGroups[prefix]!.rawStart
+        : array.length;
+  for (const group of inserted) {
+    const value = createRawValue(group);
+    const raw = toYValue(value, arrayPath(ref.path, rawIndex), predicate);
+    array.insert(rawIndex, [raw]);
+    formatNewGroup(array, rawIndex, group);
+    rawIndex += 1;
+  }
+}
+
+function ensureMissingInlineArray(
+  node: Y.Map<unknown>,
+  ref: BlockRoomPayloadRef,
+): Y.Array<unknown> {
+  const { parent, key } = payloadParent(
+    node,
+    ref.path,
+    `node:${ref.id}:path:${ref.path}`,
+  );
+  const array = new Y.Array<unknown>();
+  (parent as Y.Map<unknown>).set(key as string, array);
+  return array;
+}
+
+export function isBlockRoomInlineContentRef(ref: BlockRoomPayloadRef): boolean {
+  return (
+    ref.family === "rich_text" &&
+    ref.locale === true &&
+    (ref.path === "content" ||
+      /^content\.rows\[\d+\]\.cells\[\d+\]\.content$/.test(ref.path))
+  );
+}
+
+/**
+ * Reconciles canonical protobuf inline JSON with collaborative inline Y.Text.
+ * Text item indexes in `previous` and `next` are projections, not raw Y.Array
+ * indexes. Reconciliation therefore resolves all raw text handles from the
+ * validated current payload before applying any writes.
+ */
+export function reconcileBlockRoomInlineContent(
+  yDocument: Y.Doc,
+  ref: BlockRoomPayloadRef,
+  previous: readonly JsonValue[],
+  next: readonly JsonValue[],
+  options: BlockRoomMutationOptions = {},
+): void {
+  yDocument.transact(() => {
+    if (ref.family !== "rich_text" || ref.locale !== true) {
+      fail(`node:${ref.id}:inline_content_scope:${ref.path}`);
+    }
+    const node = roomNode(yDocument, ref);
+    const kind = nodeKind(node, ref);
+    const pathKind = inlinePathKind(kind, ref.path);
+    if (!pathKind) {
+      fail(`node:${ref.id}:not_inline_content:${ref.path}`);
+    }
+    const parent = payloadParent(
+      node,
+      ref.path,
+      `node:${ref.id}:path:${ref.path}`,
+    );
+    const rawCurrent = (parent.parent as Y.Map<unknown>).get(
+      parent.key as string,
+    );
+    if (rawCurrent === undefined) {
+      const previousKey = normalizeInlineContent(previous);
+      const nextKey = normalizeInlineContent(next);
+      if (previousKey !== "[]") {
+        fail("stale_inline_content");
+      }
+      if (nextKey === "[]") {
+        return;
+      }
+      const array = ensureMissingInlineArray(node, ref);
+      reconcileArray(array, ref, kind, previous, next);
+      return;
+    }
+    const array = payloadArray(
+      node,
+      ref.path,
+      `node:${ref.id}:path:${ref.path}`,
+    );
+    reconcileArray(array, ref, kind, previous, next);
+  }, options.origin);
+}

package/src/collaboration/block-room-codec/inline-content-projection.ts

@@ -0,0 +1,378 @@
+import type { JsonValue } from "@bufbuild/protobuf";
+import {
+  richTextBlockCatalog,
+  richTextBlockKindByProtoCase,
+  type RichTextBlockKind,
+} from "@echovisionlab/geul-proto/content/block_catalog.ts";
+import * as Y from "yjs";
+import {
+  fail,
+  fromYValue,
+  type BlockRoomNodeFamily,
+  type JsonObject,
+} from "./internal.ts";
+
+const RICH_TEXT_STYLE_KEYS = [
+  "bold",
+  "italic",
+  "underline",
+  "strike",
+  "code",
+  "textColor",
+  "backgroundColor",
+] as const;
+
+type RichTextStyleKey = (typeof RICH_TEXT_STYLE_KEYS)[number];
+type RichTextStyleValue = boolean | string;
+type RichTextStyle = Partial<Record<RichTextStyleKey, RichTextStyleValue>>;
+type ProjectedTextRun = JsonObject & { text: string };
+
+type RichTextCatalogEntry = {
+  readonly content: string;
+};
+
+const richTextCatalog = richTextBlockCatalog as Readonly<
+  Record<string, RichTextCatalogEntry>
+>;
+
+function record(value: unknown, reason: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return fail(reason);
+  }
+  return value as Record<string, unknown>;
+}
+
+function yRecord(value: unknown, reason: string): Record<string, unknown> {
+  if (value instanceof Y.Map) {
+    return Object.fromEntries(value.entries());
+  }
+  return record(value, reason);
+}
+
+function textStyle(value: unknown, reason: string): RichTextStyle {
+  if (value === undefined) {
+    return {};
+  }
+  let raw: Record<string, unknown>;
+  if (value instanceof Y.Map) {
+    raw = Object.fromEntries(value.entries());
+  } else {
+    raw = record(value, reason);
+  }
+  const result: RichTextStyle = {};
+  for (const key of RICH_TEXT_STYLE_KEYS) {
+    const style = raw[key];
+    if (typeof style === "boolean" || typeof style === "string") {
+      result[key] = style;
+    }
+  }
+  return result;
+}
+
+function mergedTextStyle(
+  legacy: RichTextStyle,
+  attributes: Readonly<Record<string, unknown>> | undefined,
+): RichTextStyle {
+  const result: RichTextStyle = { ...legacy };
+  if (attributes === undefined) {
+    return result;
+  }
+  const raw = attributes;
+  for (const key of RICH_TEXT_STYLE_KEYS) {
+    const value = raw[key];
+    if (typeof value === "boolean" || typeof value === "string") {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function jsonStyle(style: RichTextStyle): JsonObject | undefined {
+  const result: JsonObject = {};
+  for (const key of RICH_TEXT_STYLE_KEYS) {
+    const value = style[key];
+    if (value !== undefined && value !== false && value !== "") {
+      result[key] = value;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function appendProjectedText(
+  target: ProjectedTextRun[],
+  value: ProjectedTextRun,
+): void {
+  const text = value.text;
+  if (text.length === 0) {
+    target.push(value);
+    return;
+  }
+  const previous = target[target.length - 1];
+  if (previous) {
+    const previousText = previous.text;
+    if (
+      JSON.stringify(previous.styles ?? {}) ===
+      JSON.stringify(value.styles ?? {})
+    ) {
+      previous.text = previousText + text;
+      return;
+    }
+  }
+  target.push(value);
+}
+
+function styledTextMap(value: unknown, reason: string): Y.Map<unknown> {
+  if (!(value instanceof Y.Map)) {
+    return fail(reason);
+  }
+  return value;
+}
+
+function projectedTextField(
+  value: unknown,
+  styleValue: unknown,
+  reason: string,
+): ProjectedTextRun[] {
+  const text = value;
+  if (
+    text !== undefined &&
+    typeof text !== "string" &&
+    !(text instanceof Y.Text)
+  ) {
+    return fail(`${reason}:text`);
+  }
+  const legacyStyle = textStyle(styleValue, `${reason}:styles`);
+  if (typeof text === "string" || text === undefined) {
+    const emptyOrLegacy: ProjectedTextRun = {
+      text: typeof text === "string" ? text : "",
+    };
+    const style = jsonStyle(legacyStyle);
+    if (style) {
+      emptyOrLegacy.styles = style;
+    }
+    return [emptyOrLegacy];
+  }
+  const result: ProjectedTextRun[] = [];
+  const delta = text.toDelta();
+  if (delta.length === 0) {
+    const empty: ProjectedTextRun = { text: "" };
+    const style = jsonStyle(legacyStyle);
+    if (style) {
+      empty.styles = style;
+    }
+    return [empty];
+  }
+  for (const operation of delta) {
+    if (typeof operation.insert !== "string") {
+      return fail(`${reason}:embed`);
+    }
+    const item: ProjectedTextRun = { text: operation.insert };
+    const style = jsonStyle(mergedTextStyle(legacyStyle, operation.attributes));
+    if (style) {
+      item.styles = style;
+    }
+    appendProjectedText(result, item);
+  }
+  return result;
+}
+
+function projectedStyledText(
+  value: unknown,
+  reason: string,
+): ProjectedTextRun[] {
+  const styled = styledTextMap(value, reason);
+  const text = styled.get("text");
+  if (text === undefined) {
+    return projectedTextField(undefined, styled.get("styles"), reason);
+  }
+  if (text instanceof Y.Text || typeof text === "string") {
+    return projectedTextField(text, styled.get("styles"), reason);
+  }
+  if (!(text instanceof Y.Map)) {
+    return fail(`${reason}:text`);
+  }
+  const nestedText = text.get("text");
+  const legacyStyle = text.get("styles") ?? styled.get("styles");
+  return projectedTextField(nestedText, legacyStyle, reason);
+}
+
+function projectedLinkStyledText(
+  value: unknown,
+  reason: string,
+): ProjectedTextRun[] {
+  const styled = styledTextMap(value, reason);
+  return projectedTextField(styled.get("text"), styled.get("styles"), reason);
+}
+
+function projectedInlineItem(value: unknown, reason: string): JsonValue[] {
+  if (!(value instanceof Y.Map)) {
+    return fail(reason);
+  }
+  const cases = ["text", "link", "mathInline", "hardBreak"].filter((key) =>
+    value.has(key),
+  );
+  if (cases.length !== 1) {
+    return fail(`${reason}:oneof`);
+  }
+  const selected = cases[0]!;
+  if (selected === "text") {
+    return projectedStyledText(value.get("text"), `${reason}:text`).map(
+      (styledText) => ({ text: styledText }),
+    );
+  }
+  if (selected === "link") {
+    const link = yRecord(value.get("link"), `${reason}:link`);
+    const content = link.content;
+    if (content !== undefined && !(content instanceof Y.Array)) {
+      return fail(`${reason}:link_content`);
+    }
+    const projectedContent: ProjectedTextRun[] = [];
+    if (content instanceof Y.Array) {
+      content.toArray().forEach((child, index) => {
+        for (const run of projectedLinkStyledText(
+          child,
+          `${reason}:link_content:${index}`,
+        )) {
+          appendProjectedText(projectedContent, run);
+        }
+      });
+    }
+    const projectedLink: JsonObject = {
+      href: typeof link.href === "string" ? link.href : fail(`${reason}:href`),
+      content: projectedContent,
+    };
+    return [{ link: projectedLink }];
+  }
+  return [fromYValue(value)];
+}
+
+export function fromYInlineContent(value: unknown): JsonValue[] {
+  if (!(value instanceof Y.Array)) {
+    return fail("inline_content:array");
+  }
+  return value
+    .toArray()
+    .flatMap((item, index) =>
+      projectedInlineItem(item, `inline_content:${index}`),
+    );
+}
+
+function decodeOtherFields(
+  value: unknown,
+  excluded: string,
+  reason: string,
+): JsonObject {
+  if (!(value instanceof Y.Map)) {
+    return fail(reason);
+  }
+  return Object.fromEntries(
+    [...value.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .filter(([key]) => key !== excluded)
+      .map(([key, child]) => [key, fromYValue(child)]),
+  );
+}
+
+function projectedTableContent(value: unknown): JsonValue {
+  const rawContent = yRecord(value, "inline_content:table_content");
+  const projected = decodeOtherFields(
+    value,
+    "rows",
+    "inline_content:table_json",
+  );
+  const rows = rawContent.rows;
+  if (!(rows instanceof Y.Array)) {
+    return fail("inline_content:table_rows");
+  }
+  projected.rows = rows.toArray().map((rawRow, rowIndex) => {
+    if (!(rawRow instanceof Y.Map)) {
+      return fail(`inline_content:table_row:${rowIndex}`);
+    }
+    const row = decodeOtherFields(
+      rawRow,
+      "cells",
+      `inline_content:table_row_json:${rowIndex}`,
+    );
+    const rawCells = rawRow.get("cells");
+    if (!(rawCells instanceof Y.Array)) {
+      return fail(`inline_content:table_cells:${rowIndex}`);
+    }
+    row.cells = rawCells.toArray().map((rawCell, cellIndex) => {
+      if (!(rawCell instanceof Y.Map)) {
+        return fail(`inline_content:table_cell:${rowIndex}:${cellIndex}`);
+      }
+      const cell = decodeOtherFields(
+        rawCell,
+        "content",
+        `inline_content:table_cell_json:${rowIndex}:${cellIndex}`,
+      );
+      const cellContent = rawCell.get("content");
+      if (cellContent !== undefined) {
+        cell.content = fromYInlineContent(cellContent);
+      }
+      return cell;
+    });
+    return row;
+  });
+  return projected as JsonValue;
+}
+
+/**
+ * Projects formatted inline Y.Text runs into the existing protobuf JSON shape.
+ * The raw storage decoder intentionally stays one-to-one with physical Y.Array
+ * items so all existing payload paths continue to use physical indexes.
+ */
+export function fromYRichTextBlockPayload(
+  family: BlockRoomNodeFamily,
+  kind: string,
+  value: unknown,
+): JsonValue {
+  if (family !== "rich_text") {
+    return fromYValue(value);
+  }
+  const catalogKind =
+    richTextBlockKindByProtoCase[
+      kind as keyof typeof richTextBlockKindByProtoCase
+    ];
+  if (!catalogKind) {
+    return fromYValue(value);
+  }
+  const entry = richTextCatalog[catalogKind as RichTextBlockKind];
+  if (entry.content !== "inline" && entry.content !== "table") {
+    return fromYValue(value);
+  }
+  if (!(value instanceof Y.Map)) {
+    return record(
+      fromYValue(value),
+      "inline_content:payload_json",
+    ) as JsonValue;
+  }
+  const payload = Object.fromEntries(value.entries());
+  const projected = decodeOtherFields(
+    value,
+    "content",
+    "inline_content:payload_json",
+  );
+  const rawContent = payload.content;
+  if (rawContent === undefined) {
+    return projected as JsonValue;
+  }
+  if (entry.content === "inline") {
+    projected.content = fromYInlineContent(rawContent);
+    return projected as JsonValue;
+  }
+  const content = projectedTableContent(rawContent);
+  projected.content = content;
+  return projected as JsonValue;
+}
+
+export function richTextStyleKeys(): readonly RichTextStyleKey[] {
+  return RICH_TEXT_STYLE_KEYS;
+}
+
+export function projectedStyledTextRuns(
+  value: unknown,
+  reason = "inline_content:styled_text",
+): JsonValue[] {
+  return projectedStyledText(value, reason);
+}

package/src/collaboration/block-room-codec/locale-presence.ts

@@ -19,6 +19,7 @@ import {
   fromYValue,
   type JsonObject,
 } from "./internal.ts";
+import { fromYInlineContent } from "./inline-content-projection.ts";
 import {
   blockRoomBaseNodes,
   blockRoomLocaleOverlay,
@@ -426,9 +427,20 @@ export function blockRoomLocaleValue(
 ): unknown {
   const ref = blockRoomLocaleValueRef(yDocument, target);
   try {
-    return fromYValue(
-      payloadValue(roomNode(yDocument, ref), ref.path, "locale_presence:value"),
+    const value = payloadValue(
+      roomNode(yDocument, ref),
+      ref.path,
+      "locale_presence:value",
     );
+    if (
+      ref.family === "rich_text" &&
+      (target.fieldHandle === "content" ||
+        target.fieldHandle === "tableContent") &&
+      value instanceof Y.Array
+    ) {
+      return fromYInlineContent(value);
+    }
+    return fromYValue(value);
   } catch {
     return localeValueDefault(yDocument, target);
   }

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

@@ -31,11 +31,11 @@ import {
   richTextSlot,
   stringValue,
   yMap,
-  fromYValue,
   type BlockRoomDocumentType,
   type BlockRoomNodeFamily,
   type BlockRoomTypedDocument,
 } from "./internal.ts";
+import { fromYRichTextBlockPayload } from "./inline-content-projection.ts";
 
 export function nodePayload(
   node: Y.Map<unknown>,
@@ -46,10 +46,11 @@ export function nodePayload(
   const family = stringValue(node.get("family"), `${reason}:family`);
   if (family !== "page_section" && family !== "rich_text")
     fail(`${reason}:family`);
+  const kind = stringValue(node.get("kind"), `${reason}:kind`);
   return {
     family,
-    kind: stringValue(node.get("kind"), `${reason}:kind`),
-    payload: fromYValue(node.get("payload")),
+    kind,
+    payload: fromYRichTextBlockPayload(family, kind, node.get("payload")),
   };
 }
 

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

@@ -33,6 +33,7 @@ export {
   type BlockRoomAtomicValue,
   type ReplaceRichTextBlockDataOptions,
 } from "./block-room-codec/payload-mutations.ts";
+export { reconcileBlockRoomInlineContent } from "./block-room-codec/inline-content-mutations.ts";
 export {
   roomDocumentType,
   roomLocale,