@echovisionlab/geul-common 0.1.0

package/LICENSE.md

@@ -0,0 +1,6 @@
+Required Notice: Copyright 2026 Echo Vision Lab. All rights reserved.
+
+Licensed under the PolyForm Noncommercial License 1.0.0:
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+Commercial use requires a separate license from Echo Vision Lab.

package/README.md

@@ -0,0 +1,37 @@
+# Geul common
+
+Shared TypeScript contracts and helpers for Geul editors, collaboration,
+localized content, media blocks, pages, posts, and runtime events.
+
+```sh
+pnpm add @echovisionlab/geul-common
+```
+
+The package exports TypeScript source. Consumers must support `.ts` package
+exports. `yjs` is a peer dependency.
+
+## Development
+
+```sh
+corepack enable
+pnpm install --frozen-lockfile
+pnpm format:check
+pnpm lint
+pnpm typecheck
+pnpm test:coverage
+pnpm package:smoke
+```
+
+`@echovisionlab/geul-proto` is the contract source of truth. For coordinated
+local changes, `typecheck:local-contracts` and `test:local-contracts` resolve it
+from the sibling `geul-event-contracts` checkout.
+
+## Release
+
+Release Please creates releases from `main`. npm publication uses GitHub
+Actions trusted publishing without a repository npm token.
+
+## License
+
+PolyForm Noncommercial 1.0.0. Commercial use requires a separate license from
+Echo Vision Lab. See [LICENSE.md](LICENSE.md).

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@echovisionlab/geul-common",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/echovisionlab/geul-common.git"
+  },
+  "engines": {
+    "node": "24.19.0"
+  },
+  "packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
+  "files": [
+    "README.md",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint --cache .",
+    "lint-fix": "eslint --cache . --fix",
+    "deadcode": "knip --include files,dependencies,unlisted,exports,types",
+    "typecheck": "tsc --noEmit",
+    "typecheck:local-contracts": "tsc --noEmit -p tsconfig.local-contracts.json",
+    "test": "vitest run",
+    "test:local-contracts": "vitest run --config vitest.local-contracts.config.mjs",
+    "test:coverage": "vitest run --coverage",
+    "package:smoke": "npm pack --dry-run"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./collaboration/artist": "./src/collaboration/artist.ts",
+    "./collaboration/block-room-codec": "./src/collaboration/block-room-codec.ts",
+    "./collaboration/campaign": "./src/collaboration/campaign.ts",
+    "./collaboration/document-layout": "./src/collaboration/document-layout.ts",
+    "./collaboration/document": "./src/collaboration/document.ts",
+    "./collaboration/email-layout": "./src/collaboration/email-layout.ts",
+    "./collaboration/form": "./src/collaboration/form.ts",
+    "./collaboration/label": "./src/collaboration/label.ts",
+    "./collaboration/map-theme": "./src/collaboration/map-theme.ts",
+    "./collaboration/menu": "./src/collaboration/menu.ts",
+    "./collaboration/metadata-ai": "./src/collaboration/metadata-ai.ts",
+    "./collaboration/page": "./src/collaboration/page.ts",
+    "./collaboration/post": "./src/collaboration/post.ts",
+    "./collaboration/post-series": "./src/collaboration/post-series.ts",
+    "./collaboration/release": "./src/collaboration/release.ts",
+    "./collaboration/runtime-events": "./src/collaboration/runtime-events.ts",
+    "./collaboration/work": "./src/collaboration/work.ts",
+    "./editor/materialized-blocks": "./src/editor/materialized-blocks.ts",
+    "./editor/link-normalization": "./src/editor/link-normalization.ts",
+    "./page": "./src/page/index.ts",
+    "./media/block-schemas": "./src/media/block-schemas.ts",
+    "./media/hydration": "./src/media/hydration.ts",
+    "./post": "./src/post/index.ts",
+    "./test/random-id": "./src/test/random-id.ts",
+    "./translation/release": "./src/translation/release.ts",
+    "./types": "./src/types.ts"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.14.0",
+    "@echovisionlab/geul-proto": "^0.1.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "yjs": "^13.6.32"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@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",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.10",
+    "yjs": "^13.6.32"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "homepage": "https://github.com/echovisionlab/geul-common#readme",
+  "bugs": {
+    "url": "https://github.com/echovisionlab/geul-common/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/collaboration/artist.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+export const artistCollabFieldsSchema = z
+  .object({
+    status: z.enum(["draft", "published"]).optional(),
+    realName: z.string().optional(),
+    countryCode: z.string().optional(),
+    website: z.string().optional(),
+    socialLinks: z.record(z.string(), z.string()).optional(),
+    slug: z.string().optional(),
+    labelIds: z.array(z.string()).optional(),
+    parentArtistId: z.string().nullable().optional(),
+  })
+  .strict();
+
+export const ARTIST_JSON_KEYS: ReadonlySet<
+  keyof z.infer<typeof artistCollabFieldsSchema>
+> = new Set(["socialLinks", "labelIds"]);
+
+export const ARTIST_SOURCE_OWNED_FIELD_KEYS = ["name"] as const;
+export const ARTIST_SHARED_FIELD_KEYS = [
+  "status",
+  "realName",
+  "countryCode",
+  "website",
+  "socialLinks",
+  "slug",
+  "labelIds",
+  "parentArtistId",
+] as const;
+
+export type ArtistCollabFields = z.infer<typeof artistCollabFieldsSchema>;
+export type ArtistSourceOwnedFieldKey =
+  (typeof ARTIST_SOURCE_OWNED_FIELD_KEYS)[number];
+export type ArtistFieldValue =
+  string | string[] | Record<string, string> | null;
+
+export function extractArtistFields(fieldsMap: {
+  get(key: string): ArtistFieldValue | undefined;
+}): ArtistCollabFields {
+  const raw: Record<string, unknown> = {};
+
+  for (const key of Object.keys(artistCollabFieldsSchema.shape)) {
+    let value = fieldsMap.get(key);
+
+    if (
+      ARTIST_JSON_KEYS.has(key as keyof ArtistCollabFields) &&
+      typeof value === "string"
+    ) {
+      try {
+        value = JSON.parse(value) as ArtistFieldValue;
+      } catch {
+        throw new Error(`Failed to parse JSON for artist field "${key}"`);
+      }
+    }
+
+    if (value !== undefined) {
+      raw[key] = value;
+    }
+  }
+
+  return artistCollabFieldsSchema.parse(raw);
+}

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

@@ -0,0 +1,319 @@
+import { create, fromJson } from "@bufbuild/protobuf";
+import {
+  richTextBlockCatalog,
+  richTextBlockKindByProtoCase,
+  type RichTextBlockKind,
+} from "@echovisionlab/geul-proto/content/block_catalog.ts";
+import {
+  RichTextBlockDataSchema,
+  RichTextBlockLocaleDataSchema,
+  RichTextBlockLocaleSchema,
+  RichTextBlockNodeSchema,
+  type RichTextBlockData,
+  type RichTextBlockLocale,
+  type RichTextBlockLocaleData,
+  type RichTextBlockNode,
+} from "@echovisionlab/geul-proto/content/block_content_pb.ts";
+import {
+  AIDocumentFieldTargetSchema,
+  type AIDocumentOperation,
+} from "@echovisionlab/geul-proto/secure/ai_pb.ts";
+import * as Y from "yjs";
+import {
+  attachAIDocumentFile,
+  detachAIDocumentFile,
+  setAIDocumentField,
+  unsetAIDocumentField,
+} from "./ai-document-field-mutations.ts";
+import { applyPageStructureAIDocumentOperation } from "./ai-document-page-structure-mutations.ts";
+import { operationFail, requiredHandle } from "./ai-document-values.ts";
+import { yMap, type BlockRoomDocumentType } from "./internal.ts";
+import { assertBlockRoomLocaleChangeAllowed } from "./locale-change-validation.ts";
+import {
+  canonicalBlockRoomLocaleValueTarget,
+  markBlockRoomLocaleValuePresent,
+} from "./locale-presence.ts";
+import {
+  decodeCanonicalBlockRoom,
+  materializeCanonicalBlockRoom,
+} from "./materialization.ts";
+import { replaceRichTextBlockData } from "./payload-mutations.ts";
+import {
+  roomDocumentType,
+  roomLocale,
+  roomLocaleRole,
+  roomNode,
+} from "./room-access.ts";
+import {
+  deleteBlockRoomBaseNode,
+  insertRichTextBlockNode,
+  insertRichTextBlockLocale,
+  moveRichTextBlockNode,
+} from "./structure-mutations.ts";
+
+export interface ApplyAIDocumentOperationsOptions {
+  expectedRoomLocale: string;
+  origin: object;
+}
+
+const richTextProtoCaseByKind = new Map<string, string>(
+  Object.entries(richTextBlockKindByProtoCase).map(([protoCase, kind]) => [
+    kind,
+    protoCase,
+  ]),
+);
+
+function siblingPosition(
+  yDocument: Y.Doc,
+  parentId: string | null,
+  afterId: string | undefined,
+  movingId?: string,
+): number {
+  const snapshot = decodeCanonicalBlockRoom(
+    yDocument,
+    roomDocumentType(yDocument),
+  );
+  const siblings = snapshot.baseNodes
+    .filter((node) => node.parentId === parentId && node.id !== movingId)
+    .sort((left, right) => left.position - right.position);
+  if (afterId === undefined) return 0;
+  const after = siblings.findIndex(({ id }) => id === afterId);
+  return after < 0
+    ? operationFail(`after_block:${afterId}:not_sibling`)
+    : after + 1;
+}
+
+function richTextNode(
+  blockId: string,
+  kind: string,
+  parentId: string | undefined,
+  index: number,
+): { node: RichTextBlockNode; locale: RichTextBlockLocale } {
+  const protoCase = richTextProtoCaseByKind.get(kind);
+  if (!protoCase) return operationFail(`block_kind:${kind}`);
+  return {
+    node: fromJson(RichTextBlockNodeSchema, {
+      block: { id: blockId, [protoCase]: {} },
+      placement: {
+        index,
+        ...(parentId ? { parentBlockId: parentId } : {}),
+      },
+    }) as RichTextBlockNode,
+    locale: fromJson(RichTextBlockLocaleSchema, {
+      blockId,
+      [protoCase]: {},
+    }) as RichTextBlockLocale,
+  };
+}
+
+function insertBlock(
+  yDocument: Y.Doc,
+  value: Extract<
+    AIDocumentOperation["operation"],
+    { case: "insertBlock" }
+  >["value"],
+): void {
+  const id = requiredHandle(value.blockHandle, "insert:block");
+  const kind = requiredHandle(value.kind, "insert:kind");
+  const parentId = value.parentBlockHandle ?? null;
+  const index = siblingPosition(yDocument, parentId, value.afterBlockHandle);
+  const created = richTextNode(id, kind, value.parentBlockHandle, index);
+  insertRichTextBlockNode(yDocument, created.node);
+  insertRichTextBlockLocale(yDocument, created.locale);
+  const content = (
+    richTextBlockCatalog as Readonly<
+      Record<string, { readonly content: string }>
+    >
+  )[kind]?.content;
+  if (
+    roomLocaleRole(yDocument) === "source" &&
+    roomDocumentType(yDocument) === "page" &&
+    (content === "inline" || content === "locale_text")
+  ) {
+    const localePayload = yMap(
+      roomNode(yDocument, {
+        id,
+        family: "rich_text",
+        locale: true,
+      }).get("payload"),
+      "insert:locale",
+    );
+    localePayload.set(
+      "content",
+      content === "inline" ? new Y.Array<unknown>() : new Y.Text(),
+    );
+    markBlockRoomLocaleValuePresent(
+      yDocument,
+      create(AIDocumentFieldTargetSchema, {
+        owner: { case: "blockHandle", value: id },
+        fieldHandle: "content",
+      }),
+    );
+  }
+}
+
+function moveBlock(
+  yDocument: Y.Doc,
+  blockId: string,
+  parentId: string | undefined,
+  afterId: string | undefined,
+): void {
+  const snapshot = decodeCanonicalBlockRoom(
+    yDocument,
+    roomDocumentType(yDocument),
+  );
+  const node = snapshot.baseNodes.find(({ id }) => id === blockId);
+  if (!node) return operationFail(`move:block:${blockId}`);
+  const index = siblingPosition(yDocument, parentId ?? null, afterId, blockId);
+  moveRichTextBlockNode(yDocument, blockId, {
+    ...(parentId ? { parentBlockId: parentId } : {}),
+    index,
+  });
+}
+
+function replaceBlockKind(
+  yDocument: Y.Doc,
+  blockId: string,
+  kind: string,
+): void {
+  const snapshot = decodeCanonicalBlockRoom(
+    yDocument,
+    roomDocumentType(yDocument),
+  );
+  const current = snapshot.baseNodes.find(({ id }) => id === blockId);
+  if (!current) return operationFail(`replace:block:${blockId}`);
+  const protoCase = richTextProtoCaseByKind.get(kind);
+  const currentCatalogKind =
+    richTextBlockKindByProtoCase[
+      current.kind as keyof typeof richTextBlockKindByProtoCase
+    ];
+  if (!protoCase) return operationFail(`replace:kind:${kind}`);
+  const data = fromJson(RichTextBlockDataSchema, {
+    [protoCase]: {},
+  }) as RichTextBlockData;
+  const locale = fromJson(RichTextBlockLocaleDataSchema, {
+    [protoCase]: {},
+  }) as RichTextBlockLocaleData;
+  replaceRichTextBlockData(yDocument, blockId, data, {
+    expectedKind: currentCatalogKind as RichTextBlockKind,
+    localeData: locale,
+  });
+}
+
+function applyOperation(
+  yDocument: Y.Doc,
+  documentType: BlockRoomDocumentType,
+  operation: AIDocumentOperation,
+): void {
+  if (
+    documentType === "page" &&
+    applyPageStructureAIDocumentOperation(yDocument, operation)
+  ) {
+    return;
+  }
+  switch (operation.operation.case) {
+    case "setField":
+      setAIDocumentField(
+        yDocument,
+        operation.operation.value.target,
+        operation.operation.value.value,
+      );
+      return;
+    case "unsetField":
+      unsetAIDocumentField(yDocument, operation.operation.value.target);
+      return;
+    case "insertBlock":
+      insertBlock(yDocument, operation.operation.value);
+      return;
+    case "deleteBlock":
+      deleteBlockRoomBaseNode(
+        yDocument,
+        requiredHandle(operation.operation.value.blockHandle, "delete:block"),
+      );
+      return;
+    case "moveBlock":
+      moveBlock(
+        yDocument,
+        requiredHandle(operation.operation.value.blockHandle, "move:block"),
+        operation.operation.value.parentBlockHandle,
+        operation.operation.value.afterBlockHandle,
+      );
+      return;
+    case "replaceBlockKind":
+      replaceBlockKind(
+        yDocument,
+        requiredHandle(operation.operation.value.blockHandle, "replace:block"),
+        requiredHandle(operation.operation.value.kind, "replace:kind"),
+      );
+      return;
+    case "attachFile":
+      attachAIDocumentFile(
+        yDocument,
+        operation.operation.value.target,
+        operation.operation.value.fileHandle,
+      );
+      return;
+    case "detachFile":
+      detachAIDocumentFile(yDocument, operation.operation.value.target);
+      return;
+    case "insertRelationItem":
+    case "deleteRelationItem":
+    case "moveRelationItem":
+    case "createTranslation":
+    case "deleteTranslation":
+      operationFail(`unsupported:${operation.operation.case}`);
+    case undefined:
+      operationFail("missing_kind");
+  }
+}
+
+/**
+ * Applies one already-authorized and normalized DCDP batch to a Block Room.
+ * The resident document stays untouched unless the complete result validates.
+ */
+export function applyAIDocumentOperationsToBlockRoom(
+  yDocument: Y.Doc,
+  documentType: BlockRoomDocumentType,
+  operations: readonly AIDocumentOperation[],
+  options: ApplyAIDocumentOperationsOptions,
+): boolean {
+  if (roomDocumentType(yDocument) !== documentType)
+    operationFail("document_type");
+  if (
+    !options.expectedRoomLocale ||
+    roomLocale(yDocument) !== options.expectedRoomLocale
+  )
+    operationFail("room_locale");
+  if (!options.origin || typeof options.origin !== "object")
+    operationFail("origin");
+  if (operations.length === 0) return false;
+  if (
+    operations.some(({ operation }) => {
+      if (operation.case !== "unsetField") return false;
+      if (roomLocaleRole(yDocument) === "target") return true;
+      try {
+        canonicalBlockRoomLocaleValueTarget(yDocument, operation.value.target);
+        return true;
+      } catch {
+        return operation.value.target?.fieldHandle === "tableContent";
+      }
+    })
+  ) {
+    operationFail("locale_clear");
+  }
+  const before = Y.encodeStateVector(yDocument);
+  const working = new Y.Doc();
+  let update: Uint8Array;
+  try {
+    Y.applyUpdate(working, Y.encodeStateAsUpdate(yDocument));
+    for (const operation of operations)
+      applyOperation(working, documentType, operation);
+    assertBlockRoomLocaleChangeAllowed(yDocument, working, documentType);
+    materializeCanonicalBlockRoom(working, documentType);
+    update = Y.encodeStateAsUpdate(working, before);
+  } finally {
+    working.destroy();
+  }
+  Y.applyUpdate(yDocument, update, options.origin);
+  return true;
+}