@elabs-ai/components-editor 4.0.0

package/src/lib/markdown/merge.ts

@@ -0,0 +1,158 @@
+/**
+ * Normalization-aware merge for WYSIWYG markdown editing (review WI-1).
+ *
+ * Problem: Milkdown serializes the WHOLE document on every edit, normalizing
+ * formatting it never touched (list markers, wrapping, spacing). Feeding that
+ * back into the buffer turns a one-line edit into a whole-file rewrite —
+ * destroying git blame and making PR review impossible.
+ *
+ * Fix: three-way line merge.
+ * - `original`  — the byte-exact source the editor was opened with.
+ * - `baseline`  — the editor's serialization of `original` BEFORE any edit
+ *                 (pure normalization drift).
+ * - `edited`    — the editor's serialization after user edits.
+ *
+ * `diff(baseline, edited)` isolates what the USER changed; an
+ * `original ↔ baseline` alignment maps those hunks back onto `original`.
+ * Everything the user didn't touch keeps its original bytes. Granularity is
+ * the contiguous normalized run — markdown's blank lines survive
+ * serialization byte-exact, so in practice that's a single block.
+ *
+ * Guarantees:
+ * - no user edit (`baseline === edited`) → returns `original` byte-exact;
+ * - no normalization drift (`original === baseline`) → returns `edited`;
+ * - a user hunk inside a normalized block replaces exactly that block;
+ * - oversized inputs (> {@link MAX_DIFF_LINES}) fall back to `edited`.
+ */
+
+import { lcsPairs, MAX_DIFF_LINES } from "./diff";
+
+/** A contiguous span of the baseline mapped to a span of the original. */
+interface Region {
+  /** Baseline range [bStart, bEnd) — may be empty (pure original deletion). */
+  bStart: number;
+  bEnd: number;
+  /** Original lines this region carries. */
+  oLines: string[];
+  /** True when the region is a 1:1 byte-equal line pair. */
+  exact: boolean;
+}
+
+/** Build the ordered original↔baseline region list (covers both fully). */
+function alignRegions(o: string[], b: string[]): Region[] {
+  const pairs = lcsPairs(o, b);
+  const regions: Region[] = [];
+  let prevO = -1;
+  let prevB = -1;
+  const walk: [number, number][] = [...pairs, [o.length, b.length]];
+  for (const [oi, bi] of walk) {
+    if (oi - prevO > 1 || bi - prevB > 1) {
+      // Normalization-changed run (possibly empty on one side).
+      regions.push({
+        bStart: prevB + 1,
+        bEnd: bi,
+        oLines: o.slice(prevO + 1, oi),
+        exact: false,
+      });
+    }
+    if (oi < o.length && bi < b.length) {
+      regions.push({ bStart: bi, bEnd: bi + 1, oLines: [o[oi]!], exact: true });
+    }
+    prevO = oi;
+    prevB = bi;
+  }
+  return regions;
+}
+
+/**
+ * Merge a WYSIWYG serialization back onto the original source, keeping
+ * original bytes for everything the user didn't touch.
+ */
+export function mergeNormalizedEdit(original: string, baseline: string, edited: string): string {
+  if (baseline === edited) return original;
+  if (original === baseline) return edited;
+
+  const o = original.split("\n");
+  const b = baseline.split("\n");
+  const n = edited.split("\n");
+  if (o.length > MAX_DIFF_LINES || b.length > MAX_DIFF_LINES || n.length > MAX_DIFF_LINES) {
+    return edited;
+  }
+
+  // Which baseline lines did the user keep, and where do their insertions go?
+  const keptB = new Uint8Array(b.length);
+  /** N-lines the user inserted, anchored BEFORE baseline index `atB`. */
+  const inserts = new Map<number, string[]>();
+  {
+    const pairs = lcsPairs(b, n);
+    let prevB = -1;
+    let prevN = -1;
+    const walk: [number, number][] = [...pairs, [b.length, n.length]];
+    for (const [bi, ni] of walk) {
+      if (ni - prevN > 1) inserts.set(bi, n.slice(prevN + 1, ni));
+      if (bi < b.length) keptB[bi] = 1;
+      prevB = bi;
+      prevN = ni;
+    }
+    void prevB;
+  }
+
+  const regions = alignRegions(o, b);
+  const out: string[] = [];
+
+  const flushInsertsBefore = (bIndex: number, pendingFrom: number): number => {
+    for (let at = pendingFrom; at <= bIndex; at++) {
+      const ins = inserts.get(at);
+      if (ins) out.push(...ins);
+    }
+    return bIndex + 1;
+  };
+
+  let insertCursor = 0;
+  for (const region of regions) {
+    if (region.bStart === region.bEnd) {
+      // Pure original deletion by normalization (no baseline lines). Keep the
+      // original lines when the surrounding context is untouched by the user.
+      const before = region.bStart - 1;
+      const contextKept =
+        (before < 0 || keptB[before] === 1) &&
+        (region.bStart >= b.length || keptB[region.bStart] === 1);
+      insertCursor = flushInsertsBefore(region.bStart - 1, insertCursor);
+      if (contextKept) out.push(...region.oLines);
+      continue;
+    }
+
+    let allKept = true;
+    for (let bi = region.bStart; bi < region.bEnd; bi++) {
+      if (keptB[bi] !== 1) {
+        allKept = false;
+        break;
+      }
+    }
+
+    if (region.exact || allKept) {
+      // Untouched by the user → original bytes win. (For exact regions the
+      // texts are identical anyway; for normalized runs this UNDOES the
+      // serializer's drift.) Emit interleaved insertions at their anchors.
+      for (let bi = region.bStart; bi < region.bEnd; bi++) {
+        insertCursor = flushInsertsBefore(bi, insertCursor);
+        if (keptB[bi] === 1) {
+          if (region.exact) out.push(...region.oLines);
+        }
+      }
+      if (!region.exact) out.push(...region.oLines);
+    } else {
+      // The user edited inside this region → the edited serialization wins
+      // for the whole region (locally normalized; the rest of the document
+      // stays byte-exact). Kept lines inside it come from the baseline text.
+      for (let bi = region.bStart; bi < region.bEnd; bi++) {
+        insertCursor = flushInsertsBefore(bi, insertCursor);
+        if (keptB[bi] === 1) out.push(b[bi]!);
+      }
+    }
+  }
+  // Trailing insertions (anchored at b.length).
+  flushInsertsBefore(b.length, insertCursor);
+
+  return out.join("\n");
+}

package/src/lib/markdown/slugify.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Unit tests for the shared slugify helpers (#273).
+ *
+ * The key invariant: slugifyHeading + uniqueSlug must produce IDENTICAL ids to
+ * parseMarkdownOutline so that scrollToHeading(slug) finds the right ProseMirror
+ * node when called with an id from the outline.
+ */
+import { describe, expect, test } from "vitest";
+
+import { parseMarkdownOutline } from "../../markdown-outline/markdown-outline";
+import { plainText, slugifyHeading, uniqueSlug } from "./slugify";
+
+// ---------------------------------------------------------------------------
+// plainText
+// ---------------------------------------------------------------------------
+
+describe("plainText", () => {
+  test("strips inline code backticks", () => {
+    expect(plainText("`foo`")).toBe("foo");
+  });
+
+  test("strips links, keeps text", () => {
+    expect(plainText("[My Section](https://example.com)")).toBe("My Section");
+  });
+
+  test("strips images, keeps alt", () => {
+    expect(plainText("![alt text](img.png)")).toBe("alt text");
+  });
+
+  test("strips bold/italic markers", () => {
+    expect(plainText("**bold** and _italic_")).toBe("bold and italic");
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(plainText("  hello  ")).toBe("hello");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// slugifyHeading
+// ---------------------------------------------------------------------------
+
+describe("slugifyHeading", () => {
+  test("lowercases and replaces spaces with hyphens", () => {
+    expect(slugifyHeading("Hello World")).toBe("hello-world");
+  });
+
+  test("strips punctuation that is not letter/number/hyphen", () => {
+    expect(slugifyHeading("Hello, World!")).toBe("hello-world");
+  });
+
+  test("preserves hyphens", () => {
+    expect(slugifyHeading("step-by-step")).toBe("step-by-step");
+  });
+
+  test("falls back to 'section' for empty text", () => {
+    expect(slugifyHeading("")).toBe("section");
+    expect(slugifyHeading("!!!")).toBe("section");
+  });
+
+  test("handles unicode letters", () => {
+    // Unicode letter characters should be kept
+    const slug = slugifyHeading("Über die Änderungen");
+    expect(slug).toContain("ber");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// uniqueSlug — deduplication
+// ---------------------------------------------------------------------------
+
+describe("uniqueSlug", () => {
+  test("first occurrence is the bare slug", () => {
+    const used = new Map<string, number>();
+    expect(uniqueSlug("intro", used)).toBe("intro");
+  });
+
+  test("second occurrence gets -1 suffix", () => {
+    const used = new Map<string, number>();
+    uniqueSlug("intro", used);
+    expect(uniqueSlug("intro", used)).toBe("intro-1");
+  });
+
+  test("third occurrence gets -2 suffix", () => {
+    const used = new Map<string, number>();
+    uniqueSlug("intro", used);
+    uniqueSlug("intro", used);
+    expect(uniqueSlug("intro", used)).toBe("intro-2");
+  });
+
+  test("different base slugs dedupe independently", () => {
+    const used = new Map<string, number>();
+    expect(uniqueSlug("a", used)).toBe("a");
+    expect(uniqueSlug("b", used)).toBe("b");
+    expect(uniqueSlug("a", used)).toBe("a-1");
+    expect(uniqueSlug("b", used)).toBe("b-1");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Invariant: slugifyHeading + uniqueSlug == parseMarkdownOutline ids
+// ---------------------------------------------------------------------------
+
+describe("slug invariant — shared helpers match parseMarkdownOutline ids", () => {
+  /**
+   * Simulate exactly what parseMarkdownOutline does, using the shared helpers.
+   * Must produce identical id sequences.
+   */
+  function simulateSlugs(headingTexts: string[]): string[] {
+    const used = new Map<string, number>();
+    return headingTexts.map((text) => uniqueSlug(slugifyHeading(plainText(text)), used));
+  }
+
+  test("unique headings produce matching slugs", () => {
+    const markdown = `# Introduction\n\n## Getting Started\n\n### Advanced Usage\n`;
+    const outline = parseMarkdownOutline(markdown);
+    const simulated = simulateSlugs(["Introduction", "Getting Started", "Advanced Usage"]);
+    expect(outline.map((i) => i.id)).toEqual(simulated);
+  });
+
+  test("duplicate headings get -1, -2 suffixes in both paths", () => {
+    const markdown = `# Methods\n\n## Methods\n\n### Methods\n`;
+    const outline = parseMarkdownOutline(markdown);
+    const simulated = simulateSlugs(["Methods", "Methods", "Methods"]);
+    expect(outline.map((i) => i.id)).toEqual(simulated);
+    expect(outline[0]!.id).toBe("methods");
+    expect(outline[1]!.id).toBe("methods-1");
+    expect(outline[2]!.id).toBe("methods-2");
+  });
+
+  test("inline-markdown decorated headings produce matching slugs", () => {
+    // parseMarkdownOutline strips inline markdown from the heading text
+    const markdown = `# **Bold** Heading\n\n## [Link](https://example.com) Heading\n`;
+    const outline = parseMarkdownOutline(markdown);
+    const simulated = simulateSlugs(["**Bold** Heading", "[Link](https://example.com) Heading"]);
+    expect(outline.map((i) => i.id)).toEqual(simulated);
+  });
+
+  test("headings inside fenced code blocks are ignored", () => {
+    const markdown = `# Real\n\n\`\`\`\n# Not a heading\n\`\`\`\n\n## Also Real\n`;
+    const outline = parseMarkdownOutline(markdown);
+    expect(outline).toHaveLength(2);
+    expect(outline[0]!.id).toBe("real");
+    expect(outline[1]!.id).toBe("also-real");
+  });
+
+  test("frontmatter headings are excluded, stripped-line coordinates are correct", () => {
+    const markdown = `---\ntitle: Doc\n---\n\n# First\n\n## Second\n`;
+    const outline = parseMarkdownOutline(markdown);
+    // 3 lines frontmatter (---\ntitle\n---) + blank = offset 4
+    // But parseMarkdownOutline operates on the stripped body, so lines start at 1
+    expect(outline[0]!.id).toBe("first");
+    expect(outline[1]!.id).toBe("second");
+    expect(outline[0]!.line).toBe(2); // blank line 1, heading line 2 in stripped body
+  });
+});

package/src/lib/markdown/slugify.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared heading-slug helpers.
+ *
+ * The same slug algorithm is used by:
+ *  - `parseMarkdownOutline` (static markdown → outline items, slug as `id`)
+ *  - `MarkdownEditorHandle.scrollToHeading` (ProseMirror doc walk, WYSIWYG)
+ *
+ * Keeping both on a single helper guarantees the slugs agree so
+ * `scrollToHeading(slug)` finds the right node when called with an id produced
+ * by `parseMarkdownOutline`. (#273)
+ */
+
+/** Strip the inline-markdown syntax that commonly decorates headings. */
+export function plainText(raw: string): string {
+  return raw
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[`*_~]/g, "")
+    .trim();
+}
+
+/**
+ * GitHub-style heading slug: lowercase, strip non-letter/number/space/hyphen,
+ * collapse whitespace to hyphens. Falls back to `"section"` for empty text.
+ */
+export function slugifyHeading(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}\s-]/gu, "")
+      .trim()
+      .replace(/\s+/g, "-") || "section"
+  );
+}
+
+/**
+ * Produce a unique slug for a heading, given a Map of already-used base slugs
+ * (values are the count seen so far). Mutates `used`.
+ *
+ * The algorithm matches `parseMarkdownOutline`: first occurrence is the bare
+ * slug; duplicates get a `-n` numeric suffix starting at 1.
+ */
+export function uniqueSlug(base: string, used: Map<string, number>): string {
+  const seen = used.get(base) ?? 0;
+  used.set(base, seen + 1);
+  return seen === 0 ? base : `${base}-${seen}`;
+}

package/src/lib/monaco-environment.ts

@@ -0,0 +1,103 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- carry the `*?worker` ambient type into any program that imports this module (apps' tsc).
+/// <reference path="../monaco-workers.d.ts" />
+/**
+ * Monaco web-worker wiring for Vite apps.
+ *
+ * Monaco runs language intelligence (TS/JS diagnostics, JSON schema, CSS/HTML
+ * services) in web workers. This module registers a `MonacoEnvironment.getWorker`
+ * factory using Vite's `?worker` import suffix, which makes Vite bundle each
+ * worker entry. Import it ONCE at the app entry, before any editor mounts:
+ *
+ *   import "@elabs-ai/components-editor/monaco-environment";
+ *
+ * Without this, the editor still renders + highlights, but completions,
+ * diagnostics and hovers are unavailable.
+ *
+ * NOTE: `?worker` is a Vite-only transform. Non-Vite consumers must provide
+ * their own `self.MonacoEnvironment.getWorker(Url)` — see the package README.
+ */
+import type { Environment } from "monaco-editor";
+import EditorWorker from "monaco-editor/esm/vs/editor/editor.worker?worker";
+import JsonWorker from "monaco-editor/esm/vs/language/json/json.worker?worker";
+import CssWorker from "monaco-editor/esm/vs/language/css/css.worker?worker";
+import HtmlWorker from "monaco-editor/esm/vs/language/html/html.worker?worker";
+import TsWorker from "monaco-editor/esm/vs/language/typescript/ts.worker?worker";
+
+/**
+ * Monaco mints its Trusted-Types policies through this hook when it is present
+ * (`vs/base/browser/trustedTypes.js`, and the pre-bundled copy in
+ * `vs/common/workers.js`), falling back to `trustedTypes.createPolicy` when it is
+ * not. We supply it to **de-duplicate by name**.
+ *
+ * Why: `monaco-editor@0.55` ships the "mint `defaultWorkerFactory` at module
+ * init" block TWICE, in two different source files —
+ * `vs/base/browser/webWorkerFactory.js` (reached from `editorWorkerService`) and
+ * `vs/common/workers.js` (the pre-bundled `createWebWorker` API surface reached
+ * from `editor.api`). Both are in the main-thread graph, so both run. No bundler
+ * can dedupe them: they are distinct source files, not one module resolved twice.
+ *
+ * Under `require-trusted-types-for 'script'` the second call is refused —
+ * "a TrustedTypePolicy with that name already exists and the directive does not
+ * contain 'allow-duplicates'" — and Monaco reports it through
+ * `onUnexpectedError`. Memoizing here fixes it at the source instead of making
+ * every consumer widen their CSP with `'allow-duplicates'`, which would let ANY
+ * script re-register a policy name.
+ *
+ * A no-op where Trusted Types is unsupported (Firefox, Safari): returns
+ * `undefined`, exactly as Monaco's own fallback does, and Monaco then uses the
+ * raw string. A refused name also returns `undefined` (the browser still logs the
+ * CSP violation, so a missing allowlist entry stays visible) rather than throwing.
+ *
+ * See `docs/CSP-AND-NETWORK.md` §2.6.
+ */
+type TrustedTypesHook = NonNullable<Environment["createTrustedTypesPolicy"]>;
+type MonacoPolicy = ReturnType<TrustedTypesHook>;
+type PolicyOptions = Parameters<TrustedTypesHook>[1];
+
+/** `lib.dom` carries no Trusted-Types types, so the factory is typed structurally. */
+interface TrustedTypesGlobal {
+  trustedTypes?: { createPolicy(name: string, options?: PolicyOptions): MonacoPolicy };
+}
+
+const policyCache = new Map<string, MonacoPolicy>();
+
+const monacoEnvironment: Environment = {
+  createTrustedTypesPolicy(policyName, policyOptions) {
+    if (policyCache.has(policyName)) return policyCache.get(policyName);
+
+    let policy: MonacoPolicy;
+    try {
+      policy = (globalThis as unknown as TrustedTypesGlobal).trustedTypes?.createPolicy(
+        policyName,
+        policyOptions,
+      );
+    } catch {
+      policy = undefined;
+    }
+
+    policyCache.set(policyName, policy);
+    return policy;
+  },
+
+  getWorker(_workerId: string, label: string): Worker {
+    switch (label) {
+      case "json":
+        return new JsonWorker();
+      case "css":
+      case "scss":
+      case "less":
+        return new CssWorker();
+      case "html":
+      case "handlebars":
+      case "razor":
+        return new HtmlWorker();
+      case "typescript":
+      case "javascript":
+        return new TsWorker();
+      default:
+        return new EditorWorker();
+    }
+  },
+};
+
+(globalThis as unknown as { MonacoEnvironment: Environment }).MonacoEnvironment = monacoEnvironment;