@echovisionlab/geul-common 0.6.1 → 0.7.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.6.1",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "repository": {
@@ -59,13 +59,14 @@
     "./media/block-schemas": "./src/media/block-schemas.ts",
     "./media/hydration": "./src/media/hydration.ts",
     "./post": "./src/post/index.ts",
+    "./site-variables": "./src/site-variables.ts",
     "./test/random-id": "./src/test/random-id.ts",
     "./translation/release": "./src/translation/release.ts",
     "./types": "./src/types.ts"
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.16.0",
-    "@echovisionlab/geul-proto": "^0.6.0",
+    "@echovisionlab/geul-proto": "^0.7.0",
     "diff": "9.0.0",
     "zod": "^4.6.5"
   },

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

@@ -1,4 +1,8 @@
 import type { JsonValue } from "@bufbuild/protobuf";
+import {
+  isSiteVariableKey,
+  type SiteVariableKey,
+} from "@echovisionlab/geul-proto/content/block_catalog.ts";
 import { fail } from "./internal.ts";
 
 export const RICH_TEXT_STYLE_KEYS = [
@@ -34,6 +38,13 @@ interface DesiredMathGroup {
   readonly source: string;
 }
 
+interface DesiredSiteVariableGroup {
+  readonly kind: "siteVariable";
+  readonly key: SiteVariableKey;
+  readonly linked: boolean;
+  readonly styles: Style;
+}
+
 interface DesiredHardBreakGroup {
   readonly kind: "hardBreak";
 }
@@ -42,6 +53,7 @@ export type DesiredGroup =
   | DesiredTextGroup
   | DesiredLinkGroup
   | DesiredMathGroup
+  | DesiredSiteVariableGroup
   | DesiredHardBreakGroup;
 
 function object(value: unknown, reason: string): Record<string, unknown> {
@@ -119,15 +131,47 @@ export function styledInput(value: unknown, reason: string): StyledRun {
   };
 }
 
+export function siteVariableInput(
+  value: unknown,
+  reason: string,
+): DesiredSiteVariableGroup {
+  const variable = object(value, reason);
+  if (typeof variable.key !== "string" || !isSiteVariableKey(variable.key)) {
+    return fail(`${reason}:key`);
+  }
+  if (variable.linked !== undefined && typeof variable.linked !== "boolean") {
+    return fail(`${reason}:linked`);
+  }
+  if (
+    variable.linked &&
+    (variable.key === "site.title" || variable.key === "site.companyName")
+  ) {
+    return fail(`${reason}:linked_key`);
+  }
+  return {
+    kind: "siteVariable",
+    key: variable.key,
+    linked: variable.linked === true,
+    styles: checkedStyles(variable.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,
-  );
+  const cases = [
+    "text",
+    "link",
+    "mathInline",
+    "hardBreak",
+    "siteVariable",
+  ].filter((key) => item[key] !== undefined);
   if (cases.length !== 1) {
     return fail(`${reason}:oneof`);
   }
   const selected = cases[0]!;
+  if (selected === "siteVariable") {
+    return siteVariableInput(item.siteVariable, `${reason}:siteVariable`);
+  }
   if (selected === "text") {
     const run = styledInput(item.text, `${reason}:text`);
     return { kind: "text", runs: run.text ? [run] : [] };
@@ -207,6 +251,15 @@ export function normalizeInlineContent(values: readonly JsonValue[]): string {
         },
       };
     }
+    if (group.kind === "siteVariable") {
+      return {
+        siteVariable: {
+          key: group.key,
+          linked: group.linked,
+          styles: normalizeStyles(group.styles),
+        },
+      };
+    }
     if (group.kind === "mathInline") {
       return { mathInline: { source: group.source } };
     }

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

@@ -16,6 +16,7 @@ import {
   projectedStyledTextRuns,
 } from "./inline-content-projection.ts";
 import {
+  RICH_TEXT_STYLE_KEYS,
   changedStyleAttributes,
   desiredGroups,
   minimalDiff,
@@ -70,13 +71,25 @@ interface RawMathGroup {
   readonly text: Y.Text;
 }
 
+interface RawSiteVariableGroup {
+  readonly kind: "siteVariable";
+  readonly rawStart: number;
+  readonly rawEnd: number;
+  readonly variable: Y.Map<unknown>;
+}
+
 interface RawHardBreakGroup {
   readonly kind: "hardBreak";
   readonly rawStart: number;
   readonly rawEnd: number;
 }
 
-type RawGroup = RawTextGroup | RawLinkGroup | RawMathGroup | RawHardBreakGroup;
+type RawGroup =
+  | RawTextGroup
+  | RawLinkGroup
+  | RawMathGroup
+  | RawHardBreakGroup
+  | RawSiteVariableGroup;
 
 function yMap(value: unknown, reason: string): Y.Map<unknown> {
   if (!(value instanceof Y.Map)) {
@@ -110,9 +123,21 @@ function rawInlineItem(
   // 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),
-  )!;
+  const selected = [
+    "text",
+    "link",
+    "mathInline",
+    "hardBreak",
+    "siteVariable",
+  ].find((key) => item.has(key))!;
+  if (selected === "siteVariable") {
+    return {
+      kind: "siteVariable",
+      rawStart: index,
+      rawEnd: index + 1,
+      variable: yMap(item.get("siteVariable"), `${reason}:siteVariable`),
+    };
+  }
   if (selected === "text") {
     const segment = rawStyledText(item.get("text"), index, `${reason}:text`);
     return {
@@ -376,6 +401,25 @@ function reconcileRawGroup(
     );
     return;
   }
+  if (raw.kind === "siteVariable" && desired.kind === "siteVariable") {
+    if (raw.variable.get("key") !== desired.key)
+      raw.variable.set("key", desired.key);
+    if ((raw.variable.get("linked") === true) !== desired.linked)
+      raw.variable.set("linked", desired.linked);
+    let styles = raw.variable.get("styles") as Y.Map<unknown> | undefined;
+    if (!styles && Object.keys(desired.styles).length > 0) {
+      styles = new Y.Map<unknown>();
+      raw.variable.set("styles", styles);
+    }
+    if (styles)
+      for (const key of RICH_TEXT_STYLE_KEYS) {
+        const value = desired.styles[key];
+        if (value === undefined || value === false || value === "")
+          styles.delete(key);
+        else if (styles.get(key) !== value) styles.set(key, value);
+      }
+    return;
+  }
   if (raw.kind === "mathInline" && desired.kind === "mathInline") {
     const diff = minimalDiff(raw.text.toString(), desired.source);
     if (diff.oldTo > diff.from) {
@@ -402,6 +446,15 @@ function createRawValue(group: DesiredGroup): JsonValue {
       },
     };
   }
+  if (group.kind === "siteVariable") {
+    return {
+      siteVariable: {
+        key: group.key,
+        linked: group.linked,
+        styles: group.styles,
+      },
+    };
+  }
   if (group.kind === "mathInline") {
     return { mathInline: { source: group.source } };
   }

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

@@ -8,12 +8,14 @@ import * as Y from "yjs";
 import {
   fail,
   fromYValue,
+  yMap,
   type BlockRoomNodeFamily,
   type JsonObject,
 } from "./internal.ts";
 
 import {
   RICH_TEXT_STYLE_KEYS,
+  siteVariableInput,
   type RichTextStyleKey,
 } from "./inline-content-model.ts";
 type RichTextStyleValue = boolean | string;
@@ -205,13 +207,52 @@ 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),
-  );
+  const cases = [
+    "text",
+    "link",
+    "mathInline",
+    "hardBreak",
+    "siteVariable",
+  ].filter((key) => value.has(key));
   if (cases.length !== 1) {
     return fail(`${reason}:oneof`);
   }
   const selected = cases[0]!;
+  if (selected === "siteVariable") {
+    const raw = yMap(value.get("siteVariable"), `${reason}:siteVariable`);
+    const rawStyles = raw.get("styles");
+    const key = raw.get("key");
+    const linked = raw.get("linked");
+    const variable = siteVariableInput(
+      {
+        key,
+        // Independently valid key/link writes can merge into a forbidden pair.
+        // Normalize only that pair here; authored inputs stay strictly checked.
+        linked:
+          linked === true &&
+          (key === "site.title" || key === "site.companyName")
+            ? false
+            : linked,
+        styles:
+          rawStyles === undefined
+            ? undefined
+            : Object.fromEntries(
+                yMap(rawStyles, `${reason}:siteVariable:styles`).entries(),
+              ),
+      },
+      `${reason}:siteVariable`,
+    );
+    const styles = jsonStyle(variable.styles);
+    return [
+      {
+        siteVariable: {
+          key: variable.key,
+          ...(variable.linked ? { linked: true } : {}),
+          ...(styles ? { styles } : {}),
+        },
+      },
+    ];
+  }
   if (selected === "text") {
     return projectedStyledText(value.get("text"), `${reason}:text`).map(
       (styledText) => ({ text: styledText }),

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

@@ -170,6 +170,16 @@ export function toYValue(
   }
   if (value && typeof value === "object") {
     const map = new Y.Map<unknown>();
+    if (
+      /^content(?:\.rows\[\d+\]\.cells\[\d+\]\.content)?\[\d+\]\.siteVariable$/.test(
+        path,
+      ) &&
+      value.styles === undefined
+    ) {
+      // Establish one shared map before replicas fork, even for unstyled atoms.
+      // Creating it during each client's first style edit loses one whole map.
+      map.set("styles", new Y.Map<unknown>());
+    }
     for (const [key, child] of Object.entries(value).sort(([left], [right]) =>
       left.localeCompare(right),
     )) {

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

@@ -5,6 +5,7 @@ import { desiredGroups, type Style } from "./inline-content-model.ts";
 type Attributes = Record<string, string | boolean>;
 type Token =
   | { kind: "text"; value: string; attributes: Attributes }
+  | { kind: "siteVariable"; attributes: Attributes }
   | { kind: "mathInline"; attributes: Attributes }
   | { kind: "hardBreak"; attributes: Attributes }
   | { kind: "emptyLink"; attributes: Attributes }
@@ -117,11 +118,96 @@ function withAttributes(token: Token, attributes: Attributes): Token {
 }
 
 function insertionIdentity(token: Token): string {
+  if (token.kind === "siteVariable")
+    return `siteVariable:${token.attributes.key}`;
   if (token.kind === "mathInline") return `math:${token.attributes.source}`;
   if (token.kind === "emptyLink") return `emptyLink:${token.attributes.href}`;
   return tokenIdentity(token);
 }
 
+/** Align surviving keys with text anchors; equal occurrence counts retain edits. */
+function siteVariableAnchors(
+  before: readonly Token[],
+  after: readonly Token[],
+): Map<number, Token> {
+  const base = before.filter((token) => token.kind === "siteVariable");
+  const variables = after.filter((token) => token.kind === "siteVariable");
+  if (base.length === variables.length)
+    return new Map(variables.map((token, index) => [index, token]));
+  // Filtering first discards the text separating equal keys and can identify
+  // a deleted occurrence as the survivor. Diff the complete inline sequence.
+  const retained = project(before, after, insertionIdentity).retained;
+  const anchors = new Map<number, Token>();
+  let occurrence = 0;
+  before.forEach((token, position) => {
+    if (token.kind !== "siteVariable") return;
+    const survivor = retained.get(position);
+    if (survivor) anchors.set(occurrence, survivor);
+    occurrence++;
+  });
+  return anchors;
+}
+
+function occurrenceIdentity(
+  before: readonly Token[],
+  local: readonly Token[],
+  peer: readonly Token[],
+): (token: Token) => string {
+  const variables = (tokens: readonly Token[]) =>
+    tokens.filter((token) => token.kind === "siteVariable");
+  const base = variables(before);
+  const localVariables = variables(local);
+  const peerVariables = variables(peer);
+  const localAnchors = siteVariableAnchors(before, local);
+  const peerAnchors = siteVariableAnchors(before, peer);
+  const identities = new Map<Token, string>();
+  base.forEach((token, index) =>
+    identities.set(token, `siteVariable:${index}`),
+  );
+
+  const align = (
+    tokens: readonly Token[],
+    anchors: Map<number, Token>,
+    otherAnchors: Map<number, Token>,
+  ) => {
+    const tokenPositions = new Map(
+      tokens.map((token, index) => [token, index]),
+    );
+    let baseStart = 0;
+    let start = 0;
+    for (const [position, token] of [
+      ...anchors,
+      [base.length, undefined] as const,
+    ]) {
+      const end =
+        token === undefined ? tokens.length : tokenPositions.get(token)!;
+      // If this deletion was already replayed, the other side's retained
+      // occurrences also anchor peer keys that have since changed.
+      const candidates = Array.from(
+        { length: position - baseStart },
+        (_, index) => baseStart + index,
+      );
+      const hinted = candidates.filter((index) => otherAnchors.has(index));
+      const positions = hinted.length === end - start ? hinted : candidates;
+      for (let index = start; index < end; index++) {
+        const baseIndex = positions[index - start];
+        if (baseIndex !== undefined)
+          identities.set(tokens[index]!, `siteVariable:${baseIndex}`);
+      }
+      if (token !== undefined)
+        identities.set(token, `siteVariable:${position}`);
+      baseStart = position + 1;
+      start = end + 1;
+    }
+  };
+  align(localVariables, localAnchors, peerAnchors);
+  align(peerVariables, peerAnchors, localAnchors);
+  return (token) =>
+    token.kind === "siteVariable"
+      ? (identities.get(token) ?? insertionIdentity(token))
+      : 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;
@@ -211,8 +297,9 @@ function mergeTokens(
   local: readonly Token[],
   peer: readonly Token[],
 ): Token[] {
-  const localProjection = project(before, local, tokenIdentity);
-  const peerProjection = project(before, peer, tokenIdentity);
+  const identity = occurrenceIdentity(before, local, peer);
+  const localProjection = project(before, local, identity);
+  const peerProjection = project(before, peer, identity);
   const result: Token[] = [];
   for (let position = 0; position <= before.length; position++) {
     for (const token of mergeInsertions(
@@ -266,6 +353,15 @@ function inlineTokens(content: readonly JsonValue[]): Token[] {
         for (const value of run.text)
           tokens.push({ kind: "text", value, attributes });
       }
+    } else if (group.kind === "siteVariable") {
+      tokens.push({
+        kind: "siteVariable",
+        attributes: {
+          ...normalizedStyles(group.styles),
+          key: group.key,
+          linked: group.linked,
+        },
+      });
     } else if (group.kind === "mathInline") {
       tokens.push({ kind: "mathInline", attributes: { source: group.source } });
     } else {
@@ -283,6 +379,19 @@ function inlineContent(tokens: readonly Token[]): JsonValue[] {
     if (token.kind !== "text") {
       runs = undefined;
       if (token.kind === "linkBoundary") continue;
+      if (token.kind === "siteVariable") {
+        const { key, linked, ...styles } = token.attributes;
+        result.push({
+          siteVariable: {
+            key,
+            ...(linked && key !== "site.title" && key !== "site.companyName"
+              ? { linked: true }
+              : {}),
+            ...(Object.keys(styles).length ? { styles } : {}),
+          },
+        });
+        continue;
+      }
       result.push(
         token.kind === "emptyLink"
           ? { link: { href: token.attributes.href as string, content: [] } }

package/src/site-variables.ts

@@ -0,0 +1,26 @@
+import type { SiteVariableKey } from "@echovisionlab/geul-proto/content/block_catalog.ts";
+
+export interface SiteVariableContext {
+  readonly siteTitle: string;
+  readonly siteUrl: string;
+  readonly companyName: string;
+  readonly legalEmail: string;
+  readonly supportEmail: string;
+  readonly privacyEmail: string;
+}
+
+const contextFields = {
+  "site.title": "siteTitle",
+  "site.url": "siteUrl",
+  "site.companyName": "companyName",
+  "contact.legalEmail": "legalEmail",
+  "contact.supportEmail": "supportEmail",
+  "contact.privacyEmail": "privacyEmail",
+} as const satisfies Record<SiteVariableKey, keyof SiteVariableContext>;
+
+export function resolveSiteVariable(
+  key: SiteVariableKey,
+  context: SiteVariableContext,
+): string {
+  return context[contextFields[key]];
+}