@echovisionlab/geul-common 0.1.0

package/src/editor/link-normalization.ts

@@ -0,0 +1,212 @@
+const PLACEHOLDER_PROTOCOL_RE = /^(https?:\/\/)(\{\{[^{}]+\}\})$/i;
+const DUPLICATE_PROTOCOL_RE = /^(https?:\/\/)(https?:\/\/)(.+)$/i;
+const HREF_ATTR_RE =
+  /(^|[\s])href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/gi;
+const HREF_ATTR_LOOKUP_RE = /href\s*=/i;
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+const OBFUSCATED_SCHEME_RE = /^([a-z][a-z0-9+.-]*):/i;
+const SCHEME_COMPACT_RE = /[\u0000-\u0020\u007f]+/g;
+const SCHEME_ENTITY_RE =
+  /&(?:(?:#(\d+)|#x([0-9a-f]+));?|((?:colon|tab|newline));)/gi;
+const MAX_UNICODE_CODE_POINT = 0x10ffff;
+const ALLOWED_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
+
+type LinkableInlineProps = Record<string, unknown> & {
+  href?: string;
+};
+
+type LinkableInlineNode<TInline extends LinkableInlineNode<TInline>> = {
+  type?: string;
+  href?: string;
+  props?: LinkableInlineProps;
+  content?: readonly TInline[];
+};
+
+type LinkableBlockNode<
+  TInline extends LinkableInlineNode<TInline>,
+  TBlock extends LinkableBlockNode<TInline, TBlock>,
+> = {
+  content?: readonly TInline[] | string | object;
+  children?: readonly TBlock[];
+};
+
+export function normalizeRichTextHref(href: string): string {
+  const original = href;
+  let normalized = href.trim();
+
+  for (;;) {
+    const before = normalized;
+    const placeholderMatch = normalized.match(PLACEHOLDER_PROTOCOL_RE);
+    if (placeholderMatch) {
+      normalized = placeholderMatch[2];
+    }
+
+    normalized = normalized.replace(DUPLICATE_PROTOCOL_RE, "$1$3");
+    if (normalized === before) {
+      break;
+    }
+  }
+
+  if (!isAllowedRichTextHref(normalized)) {
+    return "";
+  }
+
+  return normalized === original ? original : normalized;
+}
+
+function isAllowedRichTextHref(href: string): boolean {
+  if (href === "") {
+    return true;
+  }
+
+  const compacted = decodeSchemeEntities(href).replace(SCHEME_COMPACT_RE, "");
+  const schemeMatch = compacted.match(OBFUSCATED_SCHEME_RE);
+  if (!schemeMatch) {
+    return true;
+  }
+
+  return ALLOWED_SCHEMES.has(schemeMatch[1].toLowerCase());
+}
+
+function decodeSchemeEntities(value: string): string {
+  return value.replace(
+    SCHEME_ENTITY_RE,
+    (
+      match: string,
+      decimal: string | undefined,
+      hex: string | undefined,
+      named: string | undefined,
+    ) => {
+      if (decimal) {
+        return decodeSchemeCodePoint(decimal, 10, match);
+      }
+      if (hex) {
+        return decodeSchemeCodePoint(hex, 16, match);
+      }
+      const normalizedNamed = named!.toLowerCase();
+      return normalizedNamed === "colon"
+        ? ":"
+        : normalizedNamed === "tab"
+          ? "\t"
+          : "\n";
+    },
+  );
+}
+
+function decodeSchemeCodePoint(
+  value: string,
+  radix: number,
+  fallback: string,
+): string {
+  const codePoint = Number.parseInt(value, radix);
+  if (codePoint > MAX_UNICODE_CODE_POINT) {
+    return fallback;
+  }
+
+  return String.fromCodePoint(codePoint);
+}
+
+export function normalizeRichTextHtmlLinks(html: string): string {
+  if (!html || !HREF_ATTR_LOOKUP_RE.test(html)) {
+    return html;
+  }
+
+  return html.replace(
+    HREF_ATTR_RE,
+    (match, prefix: string, ...groups: string[]) => {
+      const { href, quote } = readHrefAttributeGroups(
+        groups[0],
+        groups[1],
+        groups[2],
+      );
+      const normalizedHref = normalizeRichTextHref(href);
+      if (normalizedHref === "" && href.trim() !== "") {
+        return prefix;
+      }
+      if (normalizedHref === href) {
+        return match;
+      }
+
+      return `${prefix}href=${quote}${normalizedHref}${quote}`;
+    },
+  );
+}
+
+function readHrefAttributeGroups(
+  doubleQuotedHref: string | undefined,
+  singleQuotedHref: string | undefined,
+  unquotedHref: string | undefined,
+): { href: string; quote: string } {
+  if (doubleQuotedHref !== undefined) {
+    return { href: doubleQuotedHref, quote: '"' };
+  }
+  if (singleQuotedHref !== undefined) {
+    return { href: singleQuotedHref, quote: "'" };
+  }
+  return { href: unquotedHref!, quote: "" };
+}
+
+function collectRestorableLinkHrefPairs<
+  TInline extends LinkableInlineNode<TInline>,
+>(content: readonly TInline[], pairs: Map<string, string>): void {
+  for (const node of content) {
+    const rawHref = node.href ?? node.props?.href;
+    const normalizedHref =
+      typeof rawHref === "string" ? normalizeRichTextHref(rawHref) : null;
+    if (
+      normalizedHref &&
+      normalizedHref.length > 0 &&
+      !SCHEME_RE.test(normalizedHref)
+    ) {
+      pairs.set(`https://${normalizedHref}`, normalizedHref);
+    }
+
+    if (Array.isArray(node.content) && node.content.length > 0) {
+      collectRestorableLinkHrefPairs(node.content, pairs);
+    }
+  }
+}
+
+function collectRestorableBlockHrefPairs<
+  TInline extends LinkableInlineNode<TInline>,
+  TBlock extends LinkableBlockNode<TInline, TBlock>,
+>(blocks: readonly TBlock[], pairs: Map<string, string>): void {
+  for (const block of blocks) {
+    if (Array.isArray(block.content) && block.content.length > 0) {
+      collectRestorableLinkHrefPairs(block.content, pairs);
+    }
+    if (Array.isArray(block.children) && block.children.length > 0) {
+      collectRestorableBlockHrefPairs(block.children, pairs);
+    }
+  }
+}
+
+export function normalizeRichTextHtmlLinksFromBlocks<
+  TInline extends LinkableInlineNode<TInline>,
+  TBlock extends LinkableBlockNode<TInline, TBlock>,
+>(blocks: readonly TBlock[], html: string): string {
+  if (!html || blocks.length === 0 || !HREF_ATTR_LOOKUP_RE.test(html)) {
+    return normalizeRichTextHtmlLinks(html);
+  }
+
+  const replacementPairs = new Map<string, string>();
+  collectRestorableBlockHrefPairs(blocks, replacementPairs);
+
+  const restored = html.replace(
+    HREF_ATTR_RE,
+    (match, prefix: string, ...groups: string[]) => {
+      const { href, quote } = readHrefAttributeGroups(
+        groups[0],
+        groups[1],
+        groups[2],
+      );
+      const restoredHref = replacementPairs.get(href);
+      if (!restoredHref) {
+        return match;
+      }
+      return `${prefix}href=${quote}${restoredHref}${quote}`;
+    },
+  );
+
+  return normalizeRichTextHtmlLinks(restored);
+}

package/src/editor/materialized-blocks.ts

@@ -0,0 +1,58 @@
+export type MaterializedInlineNode = {
+  text?: string;
+  content?: readonly MaterializedInlineNode[];
+};
+
+export type MaterializedBlockLike<
+  TBlock extends MaterializedBlockLike<TBlock>,
+> = {
+  type?: string;
+  content?: readonly MaterializedInlineNode[] | string | object | null;
+  children?: readonly TBlock[];
+};
+
+function inlineContentHasText(
+  content: readonly MaterializedInlineNode[],
+): boolean {
+  return content.some((node) => {
+    if (typeof node.text === "string" && node.text.trim().length > 0) {
+      return true;
+    }
+
+    return Array.isArray(node.content) && inlineContentHasText(node.content);
+  });
+}
+
+export function isEmptyParagraphBlock<
+  TBlock extends MaterializedBlockLike<TBlock>,
+>(block: TBlock): boolean {
+  if (block.type !== "paragraph") {
+    return false;
+  }
+
+  if (Array.isArray(block.children) && block.children.length > 0) {
+    return false;
+  }
+
+  if (typeof block.content === "string") {
+    return block.content.trim().length === 0;
+  }
+
+  if (Array.isArray(block.content)) {
+    return !inlineContentHasText(block.content);
+  }
+
+  return block.content == null;
+}
+
+export function stripTrailingEmptyParagraphBlocks<
+  TBlock extends MaterializedBlockLike<TBlock>,
+>(blocks: readonly TBlock[]): TBlock[] {
+  let end = blocks.length;
+
+  while (end > 0 && isEmptyParagraphBlock(blocks[end - 1])) {
+    end -= 1;
+  }
+
+  return blocks.slice(0, end);
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+// Collaboration schemas
+export * from "./collaboration/artist.ts";
+export * from "./collaboration/block-room-codec.ts";
+export * from "./collaboration/document-layout.ts";
+export * from "./collaboration/document.ts";
+export * from "./collaboration/form.ts";
+export * from "./collaboration/label.ts";
+export * from "./collaboration/map-theme.ts";
+export * from "./collaboration/metadata-ai.ts";
+export * from "./collaboration/page.ts";
+export * from "./collaboration/post.ts";
+export * from "./collaboration/release.ts";
+export * from "./collaboration/runtime-events.ts";
+export * from "./collaboration/work.ts";
+
+// Common types
+export * from "./editor/materialized-blocks.ts";
+export * from "./editor/link-normalization.ts";
+export * from "./page/index.ts";
+export * from "./post/index.ts";
+export * from "./media/block-schemas.ts";
+export * from "./translation/release.ts";

package/src/media/block-schemas.ts

@@ -0,0 +1,78 @@
+export const fileBlockType = "file" as const;
+
+export const EXTERNAL_VIDEO_ASPECT_RATIO_VALUES = [
+  "auto",
+  "16:9",
+  "4:3",
+  "1:1",
+  "9:16",
+] as const;
+
+export type ExternalVideoAspectRatio =
+  (typeof EXTERNAL_VIDEO_ASPECT_RATIO_VALUES)[number];
+
+export const EXTERNAL_VIDEO_PREVIEW_WIDTH_MIN_PERCENT = 10;
+export const EXTERNAL_VIDEO_PREVIEW_WIDTH_MAX_PERCENT = 100;
+export const EXTERNAL_VIDEO_PREVIEW_WIDTH_DEFAULT = "100";
+
+export interface ExternalVideoLinkLayoutProps {
+  previewWidth: string;
+  aspectRatio: ExternalVideoAspectRatio;
+}
+
+export function deriveMediaDisplayName(fileName: string): string {
+  const trimmed = fileName.trim();
+  if (!trimmed) {
+    return "";
+  }
+
+  const basename = trimmed.split(/[\\/]/).pop() || trimmed;
+  const dotIndex = basename.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    return basename;
+  }
+
+  const displayName = basename.slice(0, dotIndex).trim();
+  return displayName || basename;
+}
+
+/**
+ * A rich-text File becomes public content only after the authoritative File
+ * projection has attached a non-empty File identity. Upload names, slots and
+ * temporary delivery URLs are editor state and never make a placeholder
+ * publishable by themselves.
+ */
+export function hasAttachedFileId(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Durable layout props composed into rich-text paragraph specs that preview a
+ * standalone external-video link. The URL and label remain ordinary inline
+ * link content, while the document textAlignment prop owns alignment.
+ */
+export const externalVideoLinkLayoutPropSchema = {
+  previewWidth: { default: EXTERNAL_VIDEO_PREVIEW_WIDTH_DEFAULT },
+  aspectRatio: {
+    default: "auto" as ExternalVideoAspectRatio,
+    values: EXTERNAL_VIDEO_ASPECT_RATIO_VALUES,
+  },
+} as const;
+
+/**
+ * Canonical durable rich-text attachment schema. File MIME is resolved from
+ * the verified File record at runtime and is intentionally not persisted.
+ */
+export const fileBlockPropSchema = {
+  fileId: { default: "" },
+  name: { default: "" },
+  alt: { default: "" },
+  caption: { default: "" },
+  width: { default: "0" },
+  height: { default: "0" },
+  previewWidth: { default: "100" },
+  textAlignment: {
+    default: "left" as const,
+    values: ["left", "center", "right"] as const,
+  },
+} as const;

package/src/media/hydration.ts

@@ -0,0 +1,226 @@
+export const MEDIA_HYDRATION_DOM_ATTRS = {
+  mediaKind: "data-media-kind",
+  fileId: "data-file-id",
+  entityType: "data-entity-type",
+  entityId: "data-entity-id",
+  playbackUrl: "data-playback-url",
+  playbackSource: "data-playback-source",
+  originalUrl: "data-original-url",
+  waveformUrl: "data-waveform-url",
+  spectrogramUrl: "data-spectrogram-url",
+  hlsUrl: "data-hls-src",
+  posterUrl: "data-poster-url",
+} as const;
+
+export type MediaHydrationDomAttrs = Record<string, string | undefined>;
+export type AudioPlaybackSource = "hls";
+
+export interface AudioMediaHydrationInput {
+  fileId?: string;
+  entityType?: string;
+  entityId?: string;
+  playbackUrl?: string;
+  playbackSource?: string | null;
+  originalUrl?: string;
+  hlsUrl?: string;
+  waveformUrl?: string;
+  spectrogramUrl?: string;
+}
+
+export interface VideoMediaHydrationInput {
+  fileId?: string;
+  entityType?: string;
+  entityId?: string;
+  originalUrl?: string;
+  hlsUrl?: string;
+  posterUrl?: string;
+}
+
+export interface HydratedAudioMedia {
+  fileId: string;
+  entityType: string;
+  entityId: string;
+  playbackUrl: string;
+  playbackSource: AudioPlaybackSource | null;
+  originalUrl: string;
+  hlsUrl: string;
+  waveformUrl: string;
+  spectrogramUrl: string;
+}
+
+export interface HydratedVideoMedia {
+  fileId: string;
+  entityType: string;
+  entityId: string;
+  originalUrl: string;
+  hlsUrl: string;
+  posterUrl: string;
+}
+
+export interface AudioPlaybackHydrationInput {
+  originalUrl?: string;
+  hlsUrl?: string;
+}
+
+export interface AudioPlaybackHydration {
+  originalUrl: string;
+  hlsUrl: string;
+  playbackUrl: string;
+  playbackSource: AudioPlaybackSource | null;
+  hasOriginal: boolean;
+  canPlayHls: boolean;
+}
+
+export function normalizeHydrationUrl(
+  value: string | undefined | null,
+): string {
+  const trimmed = (value ?? "").trim();
+  return !trimmed || trimmed === "undefined" || trimmed === "null"
+    ? ""
+    : trimmed;
+}
+
+function getHydrationAttr(
+  primary: Element | null | undefined,
+  attr: string,
+  secondary?: Element | null,
+): string {
+  return normalizeHydrationUrl(
+    primary?.getAttribute(attr) ?? secondary?.getAttribute(attr) ?? "",
+  );
+}
+
+function looksLikeHlsUrl(url: string): boolean {
+  return /\.m3u8(?:$|[?#])/i.test(url);
+}
+
+export function resolveAudioPlaybackHydration(
+  input: AudioPlaybackHydrationInput,
+): AudioPlaybackHydration {
+  const originalUrl = normalizeHydrationUrl(input.originalUrl);
+  const hlsUrl = normalizeHydrationUrl(input.hlsUrl);
+  const hasOriginal = originalUrl.length > 0;
+  const canPlayHls = hlsUrl.length > 0;
+
+  return {
+    originalUrl,
+    hlsUrl,
+    playbackUrl: canPlayHls ? hlsUrl : "",
+    playbackSource: canPlayHls ? "hls" : null,
+    hasOriginal,
+    canPlayHls,
+  };
+}
+
+export function applyMediaHydrationDomAttrs(
+  element: HTMLElement,
+  attrs: MediaHydrationDomAttrs,
+): void {
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value) {
+      element.setAttribute(key, value);
+    } else {
+      element.removeAttribute(key);
+    }
+  }
+}
+
+export function buildAudioMediaHydrationAttrs(
+  input: AudioMediaHydrationInput,
+): MediaHydrationDomAttrs {
+  return {
+    [MEDIA_HYDRATION_DOM_ATTRS.mediaKind]: "audio",
+    [MEDIA_HYDRATION_DOM_ATTRS.fileId]:
+      normalizeHydrationUrl(input.fileId) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.entityType]:
+      normalizeHydrationUrl(input.entityType) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.entityId]:
+      normalizeHydrationUrl(input.entityId) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.playbackUrl]:
+      normalizeHydrationUrl(input.playbackUrl) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.playbackSource]:
+      input.playbackSource === "hls" ? "hls" : undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.originalUrl]:
+      normalizeHydrationUrl(input.originalUrl) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.hlsUrl]:
+      normalizeHydrationUrl(input.hlsUrl) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.waveformUrl]:
+      normalizeHydrationUrl(input.waveformUrl) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.spectrogramUrl]:
+      normalizeHydrationUrl(input.spectrogramUrl) || undefined,
+  };
+}
+
+export function buildVideoMediaHydrationAttrs(
+  input: VideoMediaHydrationInput,
+): MediaHydrationDomAttrs {
+  return {
+    [MEDIA_HYDRATION_DOM_ATTRS.mediaKind]: "video",
+    [MEDIA_HYDRATION_DOM_ATTRS.fileId]:
+      normalizeHydrationUrl(input.fileId) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.entityType]:
+      normalizeHydrationUrl(input.entityType) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.entityId]:
+      normalizeHydrationUrl(input.entityId) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.originalUrl]:
+      normalizeHydrationUrl(input.originalUrl) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.hlsUrl]:
+      normalizeHydrationUrl(input.hlsUrl) || undefined,
+    [MEDIA_HYDRATION_DOM_ATTRS.posterUrl]:
+      normalizeHydrationUrl(input.posterUrl) || undefined,
+  };
+}
+
+export function readAudioMediaHydration(
+  root: HTMLElement,
+  audio?: HTMLAudioElement | null,
+): HydratedAudioMedia {
+  const playbackUrl =
+    getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.playbackUrl, audio) ||
+    normalizeHydrationUrl(audio?.getAttribute("src"));
+  const playbackSource =
+    getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.playbackSource) === "hls"
+      ? "hls"
+      : null;
+
+  return {
+    fileId: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.fileId, audio),
+    entityType: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.entityType),
+    entityId: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.entityId),
+    playbackUrl,
+    playbackSource,
+    originalUrl: getHydrationAttr(
+      root,
+      MEDIA_HYDRATION_DOM_ATTRS.originalUrl,
+      audio,
+    ),
+    hlsUrl: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.hlsUrl, audio),
+    waveformUrl: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.waveformUrl),
+    spectrogramUrl: getHydrationAttr(
+      root,
+      MEDIA_HYDRATION_DOM_ATTRS.spectrogramUrl,
+    ),
+  };
+}
+
+export function readVideoMediaHydration(
+  root: HTMLElement,
+  video?: HTMLVideoElement | null,
+): HydratedVideoMedia {
+  const currentSrc = normalizeHydrationUrl(video?.getAttribute("src"));
+
+  return {
+    fileId: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.fileId, video),
+    entityType: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.entityType),
+    entityId: getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.entityId),
+    originalUrl:
+      getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.originalUrl, video) ||
+      currentSrc,
+    hlsUrl:
+      getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.hlsUrl, video) ||
+      (looksLikeHlsUrl(currentSrc) ? currentSrc : ""),
+    posterUrl:
+      getHydrationAttr(root, MEDIA_HYDRATION_DOM_ATTRS.posterUrl, video) ||
+      normalizeHydrationUrl(video?.getAttribute("poster")),
+  };
+}