@bendyline/squisq-editor-react 1.5.2 → 1.6.0

package/src/tiptapBridge.ts

@@ -13,6 +13,11 @@
 
 import { templateLabel } from './TemplatePicker';
 import { resolveIcon } from '@bendyline/squisq/icons';
+import {
+  matchTrailingTemplateAnnotation,
+  matchTrailingPandocAttr,
+  tokenizeAttrTokens,
+} from '@bendyline/squisq/markdown';
 
 // Hoisted regex patterns for inline markdown ↔ HTML conversion
 const RE_BOLD_STAR = /\*\*(.+?)\*\*/g;
@@ -194,20 +199,49 @@ export function markdownToTiptap(markdown: string): string {
       let text = headingMatch[2];
       let attrs = '';
 
-      // Extract {[template key=value …]} annotation. Trailing `[\s\]\}]*`
-      // tolerates accidental doubled `]}` that users type while learning
-      // the syntax — must stay in sync with TEMPLATE_ANNOTATION_RE in
-      // packages/core/src/markdown/convert.ts.
-      const annotMatch = text.match(/\s*\{\[([^\]]+)\]\}[\s\]}]*$/);
-      if (annotMatch) {
-        text = text.slice(0, annotMatch.index!).trimEnd();
-        const tokens = annotMatch[1].trim().split(/\s+/);
-        attrs = ` data-template="${escapeHtml(tokens[0])}"`;
+      // Peel off trailing brace-blocks in any order: the squisq-native
+      // `{[template …]}` annotation and the Pandoc `{#id .class key=value}`
+      // attribute block may both appear at the end of the heading line.
+      // Loop until neither matches. The matchers are imported from core so
+      // this stays in sync with packages/core/src/markdown/convert.ts.
+      let templateInner: string | null = null;
+      let pandocInner: string | null = null;
+      for (let pass = 0; pass < 4; pass++) {
+        let matched = false;
+        if (templateInner == null) {
+          const m = matchTrailingTemplateAnnotation(text);
+          if (m) {
+            templateInner = m.inner.trim();
+            text = text.slice(0, m.index).trimEnd();
+            matched = true;
+          }
+        }
+        if (pandocInner == null) {
+          const m = matchTrailingPandocAttr(text);
+          if (m) {
+            pandocInner = m.inner.trim();
+            text = text.slice(0, m.index).trimEnd();
+            matched = true;
+          }
+        }
+        if (!matched) break;
+      }
+
+      if (templateInner != null) {
+        // Quote-aware tokenization (shared with the core parser) keeps a
+        // quoted value like caption="Beach at sunset" as one token. The
+        // tokens are stored raw — quotes included — so tiptapToMarkdown
+        // can re-join them into the annotation verbatim.
+        const tokens = tokenizeAttrTokens(templateInner);
+        attrs += ` data-template="${escapeHtml(tokens[0] ?? '')}"`;
         const params = tokens.slice(1).filter((t) => t.includes('='));
         if (params.length > 0) {
           attrs += ` data-template-params="${escapeHtml(params.join(' '))}"`;
         }
       }
+      if (pandocInner != null) {
+        attrs += ` data-block-attrs="${escapeHtml(pandocInner)}"`;
+      }
 
       outputBlocks.push(`<h${level}${attrs}>${inlineToHtml(text)}</h${level}>`);
       continue;
@@ -227,17 +261,20 @@ export function markdownToTiptap(markdown: string): string {
       continue;
     }
 
-    // Task list item
-    const taskMatch = line.match(/^[-*+]\s+\[([xX ])\]\s+(.+)$/);
+    // Task list item. Text is optional so freshly-typed, still-empty tasks
+    // survive a round-trip. The checkbox itself is drawn by TaskItem's node
+    // view from the data-checked attribute, so we only emit the text content
+    // (in a paragraph, matching Tiptap's own node structure).
+    const taskMatch = line.match(/^[-*+]\s+\[([xX ])\]\s*(.*)$/);
     if (taskMatch) {
       if (!inList || listType !== 'task') {
         flushList();
         inList = true;
         listType = 'task';
       }
-      const checked = taskMatch[1].toLowerCase() === 'x' ? ' data-checked="true"' : '';
+      const checkedAttr = taskMatch[1].toLowerCase() === 'x' ? ' data-checked="true"' : '';
       listItems.push(
-        `<li data-type="taskItem"${checked}><label><input type="checkbox"${checked ? ' checked' : ''}>${inlineToHtml(taskMatch[2])}</label></li>`,
+        `<li data-type="taskItem"${checkedAttr}><p>${inlineToHtml(taskMatch[2])}</p></li>`,
       );
       continue;
     }
@@ -354,19 +391,26 @@ export function tiptapToMarkdown(html: string): string {
       const attrs = headingMatch[2];
       let text = htmlToInline(headingMatch[3]);
 
-      // Re-inject template annotation from data attributes
+      // Re-inject heading annotations from data attributes. Canonical
+      // emit order: Pandoc `{#…}` first, then squisq `{[…]}` template
+      // annotation (matches blockToMdast in core/markdown/convert.ts).
+      const blockAttrsMatch = attrs.match(/data-block-attrs="([^"]*)"/);
       const tmplMatch = attrs.match(/data-template="([^"]+)"/);
       if (tmplMatch) {
-        let annotation = tmplMatch[1];
-        // Defensive: an earlier broken build briefly rendered the
-        // template label as a real text node inside the badge, which
-        // bled the label into the heading's textContent. Strip a
-        // trailing copy of the template's label so existing documents
-        // self-heal on save.
-        const label = templateLabel(annotation);
+        // Strip an accidental trailing copy of the template label that an
+        // earlier broken build briefly rendered as real text inside the
+        // badge. Existing documents self-heal on save.
+        const label = templateLabel(tmplMatch[1]);
         if (label && text.endsWith(label)) {
           text = text.slice(0, -label.length).trimEnd();
         }
+      }
+      if (blockAttrsMatch) {
+        const inner = unescapeHtml(blockAttrsMatch[1]);
+        text += ` {${inner}}`;
+      }
+      if (tmplMatch) {
+        let annotation = tmplMatch[1];
         const paramsMatch = attrs.match(/data-template-params="([^"]+)"/);
         if (paramsMatch) {
           annotation += ' ' + unescapeHtml(paramsMatch[1]);
@@ -484,14 +528,16 @@ export function tiptapToMarkdown(html: string): string {
     // Task list
     const taskListMatch = remaining.match(/^<ul[^>]*data-type="taskList"[^>]*>(.*?)<\/ul>/s);
     if (taskListMatch) {
-      const items = taskListMatch[1].matchAll(
-        /<li[^>]*data-type="taskItem"[^>]*(data-checked="true")?[^>]*>.*?<\/li>/gs,
-      );
+      const items = taskListMatch[1].matchAll(/<li[^>]*data-type="taskItem"[^>]*>.*?<\/li>/gs);
       for (const item of items) {
-        const checked = item[0].includes('data-checked="true"') || item[0].includes('checked');
-        const textMatch = item[0].match(/<label>.*?<\/label>|<p>(.*?)<\/p>/s);
-        const text = textMatch ? htmlToInline(textMatch[0].replace(/<[^>]+>/g, '')) : '';
-        lines.push(`- [${checked ? 'x' : ' '}] ${text}`);
+        // Read checked state from the attribute value only — a bare
+        // includes('checked') matches the substring in data-checked="false".
+        const checked = /data-checked="true"/.test(item[0]);
+        // Drop the checkbox chrome (<label>…</label>) before reading text;
+        // Tiptap puts the task text in the trailing content node, not the label.
+        const body = item[0].replace(/<label\b[^>]*>.*?<\/label>/s, '');
+        const text = htmlToInline(body.replace(/<[^>]+>/g, '').trim());
+        lines.push(`- [${checked ? 'x' : ' '}] ${text}`.trimEnd());
       }
       lines.push('');
       remaining = remaining.slice(taskListMatch[0].length);
@@ -605,12 +651,28 @@ export function tiptapToMarkdown(html: string): string {
 function renderListItem(prefix: string, html: string): string[] {
   const indent = ' '.repeat(prefix.length);
 
+  // Pull out any block-level media nested in the item (e.g. a recording
+  // dropped onto a list bullet, or a clip dragged into one). The inline
+  // paragraph walk below ignores `<video>` / `<audio>` tags, so without
+  // this they'd be silently dropped on serialize and lost from the
+  // markdown source. We collect them and re-emit each as an indented
+  // continuation line so they stay inside the list item and round-trip
+  // through the markdown parser's block-media handler.
+  const media: string[] = [];
+  const htmlWithoutMedia = html.replace(
+    /<(video|audio)\b([^>]*)>(?:[\s\S]*?<\/\1>)?/gi,
+    (_full, tag: string, attrs: string) => {
+      media.push(serializeMediaTag(tag.toLowerCase() === 'video' ? 'video' : 'audio', attrs ?? ''));
+      return '';
+    },
+  );
+
   // Split on </p><p> to detect paragraph breaks within the item
-  const paragraphs = html
+  const paragraphs = htmlWithoutMedia
     .split(/<\/p>\s*<p[^>]*>/i)
     .map((p) => p.replace(/^<p[^>]*>/i, '').replace(/<\/p>\s*$/i, ''));
 
-  const result: string[] = [];
+  const textLines: string[] = [];
   paragraphs.forEach((paragraph, pIdx) => {
     const inline = htmlToInline(paragraph).trim();
     if (!inline) return;
@@ -619,16 +681,35 @@ function renderListItem(prefix: string, html: string): string[] {
     const subLines = inline.split('\n');
     subLines.forEach((sub, sIdx) => {
       if (pIdx === 0 && sIdx === 0) {
-        result.push(prefix + sub);
+        textLines.push(prefix + sub);
       } else {
         // Blank line separator between paragraphs (sIdx === 0 means new paragraph)
-        if (sIdx === 0) result.push('');
-        result.push(indent + sub);
+        if (sIdx === 0) textLines.push('');
+        textLines.push(indent + sub);
       }
     });
   });
 
-  return result.length > 0 ? result : [prefix];
+  if (textLines.length === 0 && media.length === 0) return [prefix];
+
+  // Text first (its first line carries the bullet marker), then each media
+  // tag as its own indented continuation block. If the item is media-only,
+  // the first tag takes the bullet so the item isn't emitted empty.
+  const result: string[] = [];
+  if (textLines.length > 0) {
+    result.push(...textLines);
+    for (const tag of media) {
+      result.push('');
+      result.push(indent + tag);
+    }
+  } else {
+    result.push(prefix + media[0]);
+    for (const tag of media.slice(1)) {
+      result.push('');
+      result.push(indent + tag);
+    }
+  }
+  return result;
 }
 
 // ─── Table helpers ───────────────────────────────────────

package/src/tooltipPlacement.ts

@@ -0,0 +1,13 @@
+const EDGE_PADDING_PX = 8;
+
+export function clampTooltipLeft(
+  anchorX: number,
+  tooltipWidth: number,
+  viewportWidth: number,
+  edgePadding = EDGE_PADDING_PX,
+): number {
+  const minLeft = edgePadding;
+  const maxLeft = Math.max(minLeft, viewportWidth - edgePadding - tooltipWidth);
+  const centeredLeft = anchorX - tooltipWidth / 2;
+  return Math.min(maxLeft, Math.max(minLeft, centeredLeft));
+}

package/src/transitionCatalog.ts

@@ -0,0 +1,159 @@
+/**
+ * transitionCatalog
+ *
+ * Editor-facing, curated presentation of the block transition vocabulary.
+ *
+ * Core's `TRANSITION_TYPES` (packages/core/src/schemas/Transitions.ts) lists
+ * ~80 names, including legacy aliases and near-duplicate spellings. This
+ * catalog hand-picks the distinct, useful transitions, gives each a friendly
+ * label, and groups them for the toolbar's transition flyout — the same
+ * "core holds the truth, the editor holds the presentation" split the block
+ * `TemplatePicker` uses.
+ *
+ * Every `value` here MUST be a real `TransitionType`; `transitionCatalog.test.ts`
+ * enforces that so a renamed/removed core transition fails the build instead
+ * of silently producing an invalid `transition=` annotation. The catalog is
+ * intentionally NOT exhaustive — aliases and redundant spellings are omitted.
+ */
+
+/**
+ * How a transition takes a direction, driving which direction sub-control
+ * the picker shows. Mirrors core's `getTransitionVisualClass` dispatch:
+ * - `lrud`: left / right / up / down (push, wipe, cover, uncover, reveal, pan)
+ * - `axis`: horizontal / vertical (split, blinds)
+ * Entries without a model take no `transitionDirection`.
+ */
+export type DirectionModel = 'lrud' | 'axis';
+
+export interface TransitionCatalogEntry {
+  /** Canonical `transition=` value — must be a core `TransitionType`. */
+  value: string;
+  /** Friendly label shown in the flyout and trigger. */
+  label: string;
+  /** Direction model, when the transition is directional. */
+  direction?: DirectionModel;
+}
+
+export interface TransitionGroup {
+  title: string;
+  entries: TransitionCatalogEntry[];
+}
+
+export const TRANSITION_GROUPS: readonly TransitionGroup[] = [
+  {
+    title: 'Basic',
+    entries: [
+      { value: 'fade', label: 'Fade' },
+      { value: 'dissolve', label: 'Dissolve' },
+      { value: 'flash', label: 'Flash' },
+      { value: 'morph', label: 'Morph' },
+    ],
+  },
+  {
+    title: 'Slide & Push',
+    entries: [
+      { value: 'push', label: 'Push', direction: 'lrud' },
+      { value: 'cover', label: 'Cover', direction: 'lrud' },
+      { value: 'uncover', label: 'Uncover', direction: 'lrud' },
+      { value: 'pan', label: 'Pan', direction: 'lrud' },
+      // Conveyor renders as a fixed-direction slide (no distinct 3D motion),
+      // so it lives with the slides rather than "3D & Motion".
+      { value: 'conveyor', label: 'Conveyor' },
+    ],
+  },
+  {
+    title: 'Reveal & Wipe',
+    entries: [
+      { value: 'wipe', label: 'Wipe', direction: 'lrud' },
+      { value: 'reveal', label: 'Reveal', direction: 'lrud' },
+      { value: 'split', label: 'Split', direction: 'axis' },
+      // Blinds takes no `direction`: its horizontal/vertical web animations
+      // are identical (both map to the generic textured reveal), so a
+      // direction control here would be a visual no-op. Split, by contrast,
+      // has genuinely distinct horizontal/vertical keyframes.
+      { value: 'blinds', label: 'Blinds' },
+      { value: 'wedge', label: 'Wedge' },
+      { value: 'wheel', label: 'Wheel' },
+      { value: 'circle', label: 'Circle' },
+      { value: 'diamond', label: 'Diamond' },
+      { value: 'checkerboard', label: 'Checkerboard' },
+    ],
+  },
+  {
+    title: '3D & Motion',
+    entries: [
+      { value: 'zoom', label: 'Zoom' },
+      { value: 'cube', label: 'Cube' },
+      { value: 'flip', label: 'Flip' },
+      { value: 'rotate', label: 'Rotate' },
+      { value: 'doors', label: 'Doors' },
+      { value: 'box', label: 'Box' },
+      { value: 'gallery', label: 'Gallery' },
+      { value: 'pageCurl', label: 'Page Curl' },
+      { value: 'origami', label: 'Origami' },
+      { value: 'ferrisWheel', label: 'Ferris Wheel' },
+      { value: 'orbit', label: 'Orbit' },
+      { value: 'flyThrough', label: 'Fly Through' },
+    ],
+  },
+  {
+    title: 'Effects',
+    entries: [
+      { value: 'ripple', label: 'Ripple' },
+      { value: 'honeycomb', label: 'Honeycomb' },
+      { value: 'glitter', label: 'Glitter' },
+      { value: 'vortex', label: 'Vortex' },
+      { value: 'shred', label: 'Shred' },
+      { value: 'fracture', label: 'Fracture' },
+      { value: 'crush', label: 'Crush' },
+      { value: 'prestige', label: 'Prestige' },
+      { value: 'curtains', label: 'Curtains' },
+      { value: 'drape', label: 'Drape' },
+      { value: 'wind', label: 'Wind' },
+      { value: 'fallOver', label: 'Fall Over' },
+      { value: 'peelOff', label: 'Peel Off' },
+      { value: 'airplane', label: 'Airplane' },
+    ],
+  },
+];
+
+/** Flat list of every catalog entry, in group order. */
+export const TRANSITION_ENTRIES: readonly TransitionCatalogEntry[] = TRANSITION_GROUPS.flatMap(
+  (g) => g.entries,
+);
+
+const ENTRY_BY_VALUE = new Map(TRANSITION_ENTRIES.map((e) => [e.value, e]));
+
+/** Direction option lists keyed by model. */
+export const DIRECTION_OPTIONS: Record<
+  DirectionModel,
+  readonly { value: string; label: string }[]
+> = {
+  lrud: [
+    { value: 'left', label: 'Left' },
+    { value: 'right', label: 'Right' },
+    { value: 'up', label: 'Up' },
+    { value: 'down', label: 'Down' },
+  ],
+  axis: [
+    { value: 'horizontal', label: 'Horizontal' },
+    { value: 'vertical', label: 'Vertical' },
+  ],
+};
+
+/** Look up a catalog entry by its `transition=` value. */
+export function findTransitionEntry(value: string): TransitionCatalogEntry | undefined {
+  return ENTRY_BY_VALUE.get(value);
+}
+
+/**
+ * Human label for a transition value. Returns 'None' for the empty value and
+ * falls back to a camelCase-humanized form for any valid-but-uncurated type
+ * (e.g. a hand-typed alias) so the trigger still reads sensibly.
+ */
+export function transitionLabel(value: string): string {
+  if (!value) return 'None';
+  const entry = ENTRY_BY_VALUE.get(value);
+  if (entry) return entry.label;
+  return value.replace(/([A-Z])/g, ' $1').replace(/^./, (s) => s.toUpperCase());
+}

package/src/types/monaco-shims.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Monaco ships `editor.main.js` (the full bundle with language contributions)
+ * but only publishes `.d.ts` for `editor.api`. We import the `.main.js`
+ * subpath at runtime to register all languages, then cast through
+ * `as unknown as typeof import('monaco-editor')` at the call site. This
+ * ambient declaration makes the subpath import resolve without a
+ * `@ts-expect-error` (which doesn't survive Prettier's formatting choice
+ * for the surrounding parenthesized expression — see useMonacoLoader.ts).
+ */
+declare module 'monaco-editor/esm/vs/editor/editor.main.js';

package/src/useBlockNavigator.ts

@@ -0,0 +1,153 @@
+/**
+ * useBlockNavigator
+ *
+ * Standalone hook powering the block-at-a-time editing view. Given a
+ * `(source, setSource)` pair it slices the markdown into blocks (via
+ * `blockRange.ts`), tracks which block is active, and exposes a derived
+ * **content channel** (`editorSource` / `setEditorSource`) plus navigation.
+ *
+ * It depends only on its arguments — no `EditorContext`, no `EditorShell` —
+ * so any host (an embedded single-block editor, a chat composer, a review
+ * surface) can drive a block-at-a-time UI by calling it directly.
+ *
+ * When `enabled` is false the channel is an identity passthrough: the editors
+ * see and write the full source exactly as before.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+import {
+  getBlockSlices,
+  spliceBlock,
+  lineToOffset,
+  offsetToLine,
+  sliceIndexAtOffset,
+  type BlockSlice,
+} from './blockRange';
+
+export interface BlockNavigator {
+  /** What the bound editor should show: the active slice (block mode) or the full source. */
+  editorSource: string;
+  /** What the bound editor writes through: splices back into the full source (block mode). */
+  setEditorSource: (s: string) => void;
+  /** Number of navigable blocks in the current source. */
+  blockCount: number;
+  /** Index of the active block (clamped into range). */
+  activeBlockKey: number;
+  /** Jump to a block by index (clamped). */
+  goToBlock: (key: number) => void;
+  /**
+   * Select the block that owns a given 1-based source line — used by the
+   * outline, which knows a heading's source line but not its slice index
+   * (slice order includes the optional preamble, so it needn't match
+   * `flattenBlocks` order).
+   */
+  goToBlockByLine: (line: number) => void;
+  /** 1-based source line where the active block begins (for outline highlight). */
+  activeBlockStartLine: number | null;
+  /** Move to the previous block (no-op at the start). */
+  prevBlock: () => void;
+  /** Move to the next block (no-op at the end). */
+  nextBlock: () => void;
+  /** Insert a new heading-defined block after the active one and move to it. */
+  addBlock: () => void;
+}
+
+export interface UseBlockNavigatorOptions {
+  /**
+   * When false (the default), the channel passes through to the full source
+   * and navigation is inert. Hosts flip this on to enter block-at-a-time mode.
+   */
+  enabled?: boolean;
+}
+
+/** Heading inserted by {@link BlockNavigator.addBlock}. */
+const NEW_BLOCK_MARKDOWN = '## New section\n\n';
+
+export function useBlockNavigator(
+  source: string,
+  setSource: (s: string) => void,
+  opts?: UseBlockNavigatorOptions,
+): BlockNavigator {
+  const enabled = opts?.enabled ?? false;
+
+  // Slices are derived straight from the live `source`, not from any
+  // debounced parse, so they're always consistent with what we splice into.
+  const slices = useMemo<BlockSlice[]>(() => getBlockSlices(source), [source]);
+  const blockCount = slices.length;
+
+  const [rawKey, setRawKey] = useState(0);
+  // Effective key is always in range even when the source shrank under us —
+  // the state can lag a re-slice for a render, but derivations never read a
+  // stale/out-of-bounds slice.
+  const activeBlockKey = blockCount === 0 ? 0 : Math.min(Math.max(rawKey, 0), blockCount - 1);
+  const active = slices[activeBlockKey] ?? null;
+
+  const goToBlock = useCallback((key: number) => {
+    setRawKey(key);
+  }, []);
+  const prevBlock = useCallback(() => {
+    setRawKey(activeBlockKey - 1);
+  }, [activeBlockKey]);
+  const nextBlock = useCallback(() => {
+    setRawKey(activeBlockKey + 1);
+  }, [activeBlockKey]);
+  const goToBlockByLine = useCallback(
+    (line: number) => {
+      const offset = lineToOffset(source, line);
+      const idx = sliceIndexAtOffset(slices, offset);
+      if (idx >= 0) setRawKey(idx);
+    },
+    [source, slices],
+  );
+
+  const activeBlockStartLine = active ? offsetToLine(source, active.range.startOffset) : null;
+
+  const editorSource = enabled && active ? active.text : source;
+
+  const setEditorSource = useCallback(
+    (next: string) => {
+      if (!enabled || !active) {
+        setSource(next);
+        return;
+      }
+      // Keep a blank line before the following block's heading so the splice
+      // can't glue the edited block onto the next one (the editor may emit a
+      // slice with no trailing newline).
+      const hasFollowing = active.range.endOffset < source.length;
+      const normalized = hasFollowing ? next.replace(/\s*$/, '') + '\n\n' : next;
+      setSource(spliceBlock(source, active.range, normalized));
+    },
+    [enabled, active, source, setSource],
+  );
+
+  const addBlock = useCallback(() => {
+    if (!active) {
+      // Empty / heading-less doc — append a heading and select it.
+      const base = source.replace(/\s*$/, '');
+      setSource((base ? base + '\n\n' : '') + NEW_BLOCK_MARKDOWN);
+      setRawKey(blockCount); // becomes the new last slice after re-slice
+      return;
+    }
+    const insertAt = active.range.endOffset;
+    const before = source.slice(0, insertAt);
+    const after = source.slice(insertAt);
+    const lead =
+      before === '' || before.endsWith('\n\n') ? '' : before.endsWith('\n') ? '\n' : '\n\n';
+    setSource(before + lead + NEW_BLOCK_MARKDOWN + after);
+    // The new block sits immediately after the active one.
+    setRawKey(activeBlockKey + 1);
+  }, [active, source, setSource, activeBlockKey, blockCount]);
+
+  return {
+    editorSource,
+    setEditorSource,
+    blockCount,
+    activeBlockKey,
+    goToBlock,
+    goToBlockByLine,
+    activeBlockStartLine,
+    prevBlock,
+    nextBlock,
+    addBlock,
+  };
+}

package/src/useMonacoLoader.ts

@@ -0,0 +1,105 @@
+/**
+ * useMonacoLoader
+ *
+ * Idempotently dynamic-imports `monaco-editor` and points the
+ * `@monaco-editor/react` singleton loader at the bundled copy. Replaces
+ * the historical top-of-module `import * as monaco from 'monaco-editor';
+ * loader.config({ monaco })` pattern, which forced every consumer of
+ * `@bendyline/squisq-editor-react` — including ones that only import
+ * `JsonEditor` or a type — to drag in monaco's ~9MB worth of language
+ * services and workers at module evaluation time.
+ *
+ * Hosts that want the smallest possible bundle can keep aliasing
+ * `monaco-editor` to a slim entry as before; the behavior is identical
+ * once the dynamic import settles.
+ *
+ * The promise is cached at module scope so the first subscriber
+ * anywhere in the app pays the import cost and every later subscriber
+ * reuses the same settled value.
+ */
+
+import { useEffect, useState } from 'react';
+import { loader } from '@monaco-editor/react';
+
+/** In-flight (or settled) dynamic import shared across all callers. */
+let monacoPromise: Promise<typeof import('monaco-editor')> | null = null;
+
+/** Settled namespace once the promise resolves — read synchronously by mount-time consumers. */
+let monacoNamespace: typeof import('monaco-editor') | null = null;
+
+export interface UseMonacoLoaderResult {
+  /** The monaco namespace once loaded, or `null` while the import is in flight. */
+  monaco: typeof import('monaco-editor') | null;
+  /** Flips to `true` after the import settles. Gate `<Editor>` / `<DiffEditor>` renders on this. */
+  ready: boolean;
+}
+
+/**
+ * Subscribe to the lazy-loaded monaco namespace. The first caller
+ * triggers `import('monaco-editor')` and configures the
+ * `@monaco-editor/react` loader; subsequent callers receive the same
+ * cached value.
+ */
+export function useMonacoLoader(): UseMonacoLoaderResult {
+  const [state, setState] = useState<UseMonacoLoaderResult>(() => ({
+    monaco: monacoNamespace,
+    ready: monacoNamespace !== null,
+  }));
+
+  useEffect(() => {
+    if (state.ready) return;
+    if (!monacoPromise) {
+      // Import the explicit ESM entry file rather than the bare
+      // package specifier `'monaco-editor'`. The package's
+      // `package.json` has no `main` / no `exports` (only `module`),
+      // which trips Vite's strict resolver on both static and
+      // dynamic imports of the bare name. Pointing at the file
+      // directly — the same path monaco's `module` field points at —
+      // turns this into a regular file-path resolve that doesn't
+      // care about the manifest's entry fields. Works identically
+      // in Vite dev / build, vitest's transform pipeline, and any
+      // bundler-using downstream consumer.
+      //
+      // Use `editor.main.js`, NOT `editor.api.js`. The `api` entry is
+      // the bare standalone API with zero language contributions —
+      // RawEditor's `defaultLanguage="typescript"` then mounts with
+      // no tokenizer registered, and every file renders as
+      // undifferentiated foreground text (the regression that surfaced
+      // when a `.ts` file in the chat workspace previewer showed up
+      // with no syntax coloring). `editor.main.js` re-exports the API
+      // and additionally pulls in `basic-languages/monaco.contribution`
+      // (TM grammars for ~70 languages) plus the four rich language
+      // services (css / html / json / typescript). This is what makes
+      // `defaultLanguage` actually do anything. The cost is the language
+      // bundle — but since we load it lazily on first EditorShell mount,
+      // it stays out of the resolver graph for consumers that only
+      // import types or `JsonEditor` from this package.
+      // `editor.main.js` ships without a sibling `.d.ts` (only
+      // `editor.api.d.ts` is published), so the subpath import has no
+      // resolvable declaration. The `declare module` shim in
+      // `src/types/monaco-shims.d.ts` makes it import as `any`; the
+      // `as unknown as` cast below pins the surface to the full namespace.
+      // At runtime `main` re-exports the entire `editor.api` surface
+      // alongside the language contributions, so the cast is sound.
+      monacoPromise = (
+        import('monaco-editor/esm/vs/editor/editor.main.js') as unknown as Promise<
+          typeof import('monaco-editor')
+        >
+      ).then((m) => {
+        loader.config({ monaco: m });
+        monacoNamespace = m;
+        return m;
+      });
+    }
+    let cancelled = false;
+    void monacoPromise.then((m) => {
+      if (cancelled) return;
+      setState({ monaco: m, ready: true });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [state.ready]);
+
+  return state;
+}