@bendyline/squisq-editor-react 1.2.2 → 1.4.0

package/src/WysiwygEditor.tsx

@@ -10,7 +10,7 @@
  * and code blocks.
  */
 
-import { useEffect, useRef } from 'react';
+import { useEffect, useMemo, useRef } from 'react';
 import { useEditor, EditorContent } from '@tiptap/react';
 import StarterKit from '@tiptap/starter-kit';
 import Table from '@tiptap/extension-table';
@@ -23,7 +23,10 @@ import Placeholder from '@tiptap/extension-placeholder';
 import { HeadingWithTemplate } from './TemplateAnnotation';
 import { ImageWithMediaProvider } from './ImageNodeView';
 import { useEditorContext } from './EditorContext';
+import { buildMentionExtension } from './MentionExtension';
 import { markdownToTiptap, tiptapToMarkdown } from './tiptapBridge';
+import { looksLikeMarkdown } from './detectMarkdown';
+import { SQUISQ_MEDIA_MIME, parseSquisqMediaPayload } from './mediaDragMime';
 
 // ── Frontmatter helpers ────────────────────────────────────────────
 
@@ -37,11 +40,44 @@ function stripFrontmatter(md: string): { body: string; frontmatter: string } {
   return { body: md.slice(m[0].length), frontmatter: m[0] };
 }
 
+/**
+ * Rotating placeholder prompts shown when the editor is empty. One is
+ * picked at random per editor mount. Hosts can override by passing the
+ * `placeholder` prop with a fixed string.
+ */
+const EMPTY_PROMPTS = [
+  'Start typing your content, or drop images on top of me…',
+  'Write anything — paste markdown, drag in images, or just start typing…',
+  'Type away. Markdown syntax works too…',
+  'Chapter 1 begins here…',
+  'Once upon a time…',
+  'A blank page. Exciting, isn\u2019t it?',
+  'The first word is always the hardest…',
+  'Plot twist: this is where it all starts…',
+  'Write something the future you will thank you for…',
+  'Begin at the beginning…',
+];
+
+function pickEmptyPrompt(): string {
+  return EMPTY_PROMPTS[Math.floor(Math.random() * EMPTY_PROMPTS.length)];
+}
+
 export interface WysiwygEditorProps {
-  /** Placeholder text when editor is empty */
+  /**
+   * Placeholder text when the editor is empty. If omitted, one of several
+   * rotating prompts is picked at random on mount. Pass a fixed string to
+   * override with a host-specific call to action.
+   */
   placeholder?: string;
   /** Additional class name for the container */
   className?: string;
+  /**
+   * If set, a plain Enter keypress fires this callback instead of inserting
+   * a newline, and Cmd/Ctrl+Enter inserts a soft break. Chat-composer UX.
+   */
+  submitOnEnter?: () => void;
+  /** Disable Tiptap editing — renders content but blocks input. */
+  readOnly?: boolean;
 }
 
 /**
@@ -49,16 +85,42 @@ export interface WysiwygEditorProps {
  * Binds to the shared EditorContext for source synchronization.
  */
 export function WysiwygEditor({
-  placeholder = 'Start typing your markdown…',
+  placeholder,
   className,
+  submitOnEnter,
+  readOnly = false,
 }: WysiwygEditorProps) {
-  const { markdownSource, setMarkdownSource, setTiptapEditor } = useEditorContext();
+  const { markdownSource, setMarkdownSource, setTiptapEditor, mediaProvider, mentionProvider } =
+    useEditorContext();
+  // Keep a ref so the mention extension — created once at editor mount —
+  // always sees the latest provider. Swapping projects or gezels changes
+  // the provider without remounting the editor.
+  const mentionProviderRef = useRef(mentionProvider);
+  useEffect(() => {
+    mentionProviderRef.current = mentionProvider;
+  }, [mentionProvider]);
+  // Stable per mount: either the host-supplied string, or a random pick
+  // from EMPTY_PROMPTS. Re-renders don't reshuffle.
+  const resolvedPlaceholder = useMemo(() => placeholder ?? pickEmptyPrompt(), [placeholder]);
   const isExternalUpdate = useRef(false);
   const lastSourceRef = useRef(markdownSource);
+  // Keep a ref so the editor's drop/paste handlers (created once) always
+  // see the current MediaProvider without needing to recreate the editor.
+  const mediaProviderRef = useRef(mediaProvider);
+  useEffect(() => {
+    mediaProviderRef.current = mediaProvider;
+  }, [mediaProvider]);
   // Preserve frontmatter across edits — hidden from WYSIWYG but prepended on save
   const frontmatterRef = useRef(stripFrontmatter(markdownSource).frontmatter);
+  // Stash the latest submit callback so the editor's handleKeyDown (bound
+  // once at creation) always sees the current value.
+  const submitOnEnterRef = useRef(submitOnEnter);
+  useEffect(() => {
+    submitOnEnterRef.current = submitOnEnter;
+  }, [submitOnEnter]);
 
   const editor = useEditor({
+    editable: !readOnly,
     extensions: [
       StarterKit.configure({
         // Disable built-in heading; we use HeadingWithTemplate instead
@@ -75,7 +137,8 @@ export function WysiwygEditor({
       TaskList,
       TaskItem.configure({ nested: true }),
       ImageWithMediaProvider.configure({ inline: false }),
-      Placeholder.configure({ placeholder }),
+      Placeholder.configure({ placeholder: resolvedPlaceholder }),
+      buildMentionExtension(() => mentionProviderRef.current),
     ],
     content: markdownToTiptap(stripFrontmatter(markdownSource).body),
     onUpdate: ({ editor: ed }) => {
@@ -91,6 +154,85 @@ export function WysiwygEditor({
         class: 'squisq-wysiwyg-editor',
         'data-testid': 'wysiwyg-editor',
       },
+      // Chat-composer mode: Enter commits via submitOnEnter(), Cmd/Ctrl+Enter
+      // inserts a soft break. When no callback is set, fall through to Tiptap's
+      // normal behavior (Enter = paragraph break, Shift+Enter = soft break).
+      handleKeyDown: (view, event) => {
+        if (event.key !== 'Enter' || !submitOnEnterRef.current) return false;
+        if (event.metaKey || event.ctrlKey) {
+          // User wants a newline. Insert a hard-break and stop propagation so
+          // we don't also create a new paragraph.
+          event.preventDefault();
+          view.dispatch(
+            view.state.tr.replaceSelectionWith(view.state.schema.nodes.hardBreak.create()),
+          );
+          return true;
+        }
+        if (event.shiftKey) {
+          // Preserve the conventional Shift+Enter soft break.
+          return false;
+        }
+        // Plain Enter — submit.
+        event.preventDefault();
+        submitOnEnterRef.current();
+        return true;
+      },
+      // When the clipboard's plain-text payload looks like markdown source,
+      // convert it via tiptapBridge before pasting. This applies even when
+      // the clipboard also contains HTML (most rich-text sources do), since
+      // the markdown-looking text is usually what the user actually wants.
+      // Without this, pasted markdown shows up as literal "# Heading" text
+      // instead of becoming a real heading.
+      handlePaste: (view, event) => {
+        const clipboard = event.clipboardData;
+        if (!clipboard) return false;
+
+        // Image files in the clipboard → upload via MediaProvider and insert
+        const imageFiles = filesFromClipboard(clipboard);
+        if (imageFiles.length > 0 && mediaProviderRef.current) {
+          event.preventDefault();
+          uploadAndInsertImages(view, imageFiles, mediaProviderRef.current);
+          return true;
+        }
+
+        const text = clipboard.getData('text/plain');
+        if (!text || !looksLikeMarkdown(text)) return false;
+        const html = markdownToTiptap(text);
+        if (!html) return false;
+        event.preventDefault();
+        view.pasteHTML(html);
+        return true;
+      },
+      // When image files are dropped onto the editor, upload them via the
+      // MediaProvider and insert <img> nodes referencing the relative paths.
+      // Also handles drags from the MediaBin, which reference existing
+      // entries via a custom MIME type and skip the upload step.
+      // Falls through to default handling for non-image drops or when no
+      // MediaProvider is available.
+      handleDrop: (view, event, _slice, _moved) => {
+        const dt = event.dataTransfer;
+        if (!dt) return false;
+
+        // In-app drag from the MediaBin — insert without uploading
+        const squisqRaw = dt.getData(SQUISQ_MEDIA_MIME);
+        if (squisqRaw) {
+          const payload = parseSquisqMediaPayload(squisqRaw);
+          if (payload && payload.mimeType.startsWith('image/')) {
+            event.preventDefault();
+            moveSelectionToDropPoint(view, event);
+            insertImageNode(view, payload.name, payload.alt);
+            return true;
+          }
+        }
+
+        const imageFiles = filesFromDataTransfer(dt);
+        if (imageFiles.length === 0 || !mediaProviderRef.current) return false;
+
+        event.preventDefault();
+        moveSelectionToDropPoint(view, event);
+        uploadAndInsertImages(view, imageFiles, mediaProviderRef.current);
+        return true;
+      },
     },
   });
 
@@ -102,6 +244,13 @@ export function WysiwygEditor({
     return () => setTiptapEditor(null);
   }, [editor, setTiptapEditor]);
 
+  // Tiptap reads `editable` only at creation; mirror later changes via
+  // setEditable so flipping readOnly from the host takes effect without
+  // remounting the editor.
+  useEffect(() => {
+    if (editor) editor.setEditable(!readOnly);
+  }, [editor, readOnly]);
+
   // Sync external changes into Tiptap
   useEffect(() => {
     if (!editor) return;
@@ -128,6 +277,122 @@ export function WysiwygEditor({
   );
 }
 
+// ── Image drop / paste helpers ─────────────────────────────────────
+
+/** Extract image File objects from a DataTransfer (drop event). */
+function filesFromDataTransfer(dt: DataTransfer): File[] {
+  const files: File[] = [];
+  for (let i = 0; i < dt.files.length; i++) {
+    const file = dt.files[i];
+    if (file.type.startsWith('image/')) files.push(file);
+  }
+  return files;
+}
+
+/** Extract image File objects from a clipboard's items (paste event). */
+function filesFromClipboard(clipboard: DataTransfer): File[] {
+  const files: File[] = [];
+  // clipboardData.items is the most reliable source for pasted images
+  if (clipboard.items) {
+    for (let i = 0; i < clipboard.items.length; i++) {
+      const item = clipboard.items[i];
+      if (item.kind === 'file' && item.type.startsWith('image/')) {
+        const file = item.getAsFile();
+        if (file) files.push(file);
+      }
+    }
+  }
+  return files;
+}
+
+/**
+ * Upload image files to the MediaProvider and insert <img> nodes at the
+ * current selection. Inserts a placeholder name when files lack one
+ * (e.g., screenshots from the system clipboard).
+ */
+async function uploadAndInsertImages(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  view: any,
+  files: File[],
+  mediaProvider: import('@bendyline/squisq/schemas').MediaProvider,
+): Promise<void> {
+  for (const file of files) {
+    try {
+      const buffer = await file.arrayBuffer();
+      const mimeType = file.type || 'image/png';
+      const name =
+        file.name && file.name !== 'image.png'
+          ? file.name
+          : `pasted-${uniquePasteToken()}.${extFromMime(mimeType)}`;
+      const relativePath = await mediaProvider.addMedia(name, buffer, mimeType);
+      const altText = name.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
+      insertImageNode(view, relativePath, altText);
+    } catch (err) {
+      console.error('Failed to upload dropped image:', err);
+    }
+  }
+}
+
+/** Insert an image node at the current selection using the schema image type. */
+function insertImageNode(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  view: any,
+  src: string,
+  alt: string,
+): void {
+  const { schema } = view.state;
+  const imageType = schema.nodes.image;
+  if (!imageType) return;
+  const node = imageType.create({ src, alt });
+  const tr = view.state.tr.replaceSelectionWith(node);
+  view.dispatch(tr);
+}
+
+/** Move the selection to the document position under the drop event's coordinates. */
+function moveSelectionToDropPoint(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  view: any,
+  event: DragEvent,
+): void {
+  const coords = view.posAtCoords({ left: event.clientX, top: event.clientY });
+  if (!coords) return;
+  const tr = view.state.tr.setSelection(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (view.state.selection.constructor as any).near(view.state.doc.resolve(coords.pos)),
+  );
+  view.dispatch(tr);
+}
+
+/**
+ * Produce a unique token for a pasted-file name. `Date.now()` alone can
+ * collide when a user pastes several clipboard images in the same tick
+ * (multi-image paste from a screenshot grid, for example), which would make
+ * `MediaProvider.addMedia` overwrite or reject later entries. Prefer
+ * `crypto.randomUUID()` when available and fall back to a counter so the
+ * helper stays pure-JS-everywhere.
+ */
+let pasteCounter = 0;
+function uniquePasteToken(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  pasteCounter = (pasteCounter + 1) % 1_000_000;
+  return `${Date.now()}-${pasteCounter.toString(36)}`;
+}
+
+function extFromMime(mime: string): string {
+  const map: Record<string, string> = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/jpg': 'jpg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'image/avif': 'avif',
+  };
+  return map[mime.toLowerCase()] ?? 'png';
+}
+
 /**
  * Hook to access the Tiptap editor instance for toolbar commands.
  * The WysiwygEditor must be mounted as a sibling or descendant.

package/src/__tests__/detectMarkdown.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { looksLikeMarkdown } from '../detectMarkdown';
+
+describe('looksLikeMarkdown', () => {
+  it('returns false for empty / trivial text', () => {
+    expect(looksLikeMarkdown('')).toBe(false);
+    expect(looksLikeMarkdown(' ')).toBe(false);
+    expect(looksLikeMarkdown('Hello')).toBe(false);
+  });
+
+  it('returns false for plain prose', () => {
+    expect(looksLikeMarkdown('Hello world. This is just a sentence.')).toBe(false);
+    expect(looksLikeMarkdown('Multiple\nlines of\nplain text without any markdown syntax.')).toBe(
+      false,
+    );
+  });
+
+  it('detects ATX headings', () => {
+    expect(looksLikeMarkdown('# Heading')).toBe(true);
+    expect(looksLikeMarkdown('## Subheading')).toBe(true);
+    expect(looksLikeMarkdown('###### Tiny heading')).toBe(true);
+    expect(looksLikeMarkdown('Some intro\n\n## A heading\n\nBody text')).toBe(true);
+  });
+
+  it('does not treat hash in middle of line as a heading', () => {
+    expect(looksLikeMarkdown('See issue #123 for details.')).toBe(false);
+  });
+
+  it('detects bullet lists', () => {
+    expect(looksLikeMarkdown('- first\n- second\n- third')).toBe(true);
+    expect(looksLikeMarkdown('* item one\n* item two')).toBe(true);
+    expect(looksLikeMarkdown('+ plus item')).toBe(true);
+  });
+
+  it('detects ordered lists', () => {
+    expect(looksLikeMarkdown('1. step one\n2. step two')).toBe(true);
+  });
+
+  it('detects blockquotes', () => {
+    expect(looksLikeMarkdown('> A quoted line')).toBe(true);
+  });
+
+  it('detects code fences', () => {
+    expect(looksLikeMarkdown('```\nconst x = 1;\n```')).toBe(true);
+    expect(looksLikeMarkdown('```ts\nlet y = 2;\n```')).toBe(true);
+  });
+
+  it('detects GFM tables', () => {
+    expect(looksLikeMarkdown('| Col1 | Col2 |\n| --- | --- |\n| a | b |')).toBe(true);
+  });
+
+  it('detects task lists', () => {
+    expect(looksLikeMarkdown('- [ ] todo\n- [x] done')).toBe(true);
+  });
+
+  it('detects mixed inline patterns (2+ hits)', () => {
+    expect(looksLikeMarkdown('**Important:** see [the docs](http://example.com) for more')).toBe(
+      true,
+    );
+    expect(looksLikeMarkdown('Use `foo()` and read [the page](http://x.com)')).toBe(true);
+  });
+
+  it('does not trigger on a single inline pattern in plain prose', () => {
+    expect(looksLikeMarkdown('Visit https://example.com or [the docs](http://docs.com)')).toBe(
+      false,
+    );
+    expect(looksLikeMarkdown('She said `hello` to him')).toBe(false);
+  });
+
+  it('detects markdown with windows line endings', () => {
+    expect(looksLikeMarkdown('# Heading\r\n\r\nBody text')).toBe(true);
+  });
+
+  it('detects a full resume-style document', () => {
+    const text = `# Mike Ammerlaan
+
+## Projects
+
+Qualla (qualla.com) - Designed and built a map-driven storytelling platform.
+
+## **Experience**
+
+**Principal Product Manager, Minecraft**
+Jan 2021 - Present
+Driving the creator platform.`;
+    expect(looksLikeMarkdown(text)).toBe(true);
+  });
+});

package/src/__tests__/fileKind.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { detectLanguageFromFileName, resolveFileKind } from '../fileKind';
+
+describe('detectLanguageFromFileName', () => {
+  it('detects common extensions', () => {
+    expect(detectLanguageFromFileName('foo.ts')).toBe('typescript');
+    expect(detectLanguageFromFileName('app.py')).toBe('python');
+    expect(detectLanguageFromFileName('data.json')).toBe('json');
+    expect(detectLanguageFromFileName('index.html')).toBe('html');
+    expect(detectLanguageFromFileName('styles.css')).toBe('css');
+    expect(detectLanguageFromFileName('README.md')).toBe('markdown');
+  });
+
+  it('uses the final extension for multi-dot names', () => {
+    expect(detectLanguageFromFileName('archive.tar.gz')).toBe(null);
+    expect(detectLanguageFromFileName('component.test.ts')).toBe('typescript');
+  });
+
+  it('accepts bare extensions with or without a leading dot', () => {
+    expect(detectLanguageFromFileName('.ts')).toBe('typescript');
+    expect(detectLanguageFromFileName('ts')).toBe('typescript');
+  });
+
+  it('matches extensionless names like Dockerfile', () => {
+    expect(detectLanguageFromFileName('Dockerfile')).toBe('dockerfile');
+    expect(detectLanguageFromFileName('dockerfile')).toBe('dockerfile');
+  });
+
+  it('is case-insensitive for extensions', () => {
+    expect(detectLanguageFromFileName('foo.TS')).toBe('typescript');
+    expect(detectLanguageFromFileName('App.JSX')).toBe('javascript');
+  });
+
+  it('strips leading paths', () => {
+    expect(detectLanguageFromFileName('src/lib/foo.ts')).toBe('typescript');
+    expect(detectLanguageFromFileName('C:\\Users\\me\\app.py')).toBe('python');
+  });
+
+  it('returns null for unknown extensions', () => {
+    expect(detectLanguageFromFileName('foo.xyz')).toBe(null);
+    expect(detectLanguageFromFileName('mystery.blob')).toBe(null);
+  });
+
+  it('returns null for empty or trailing-dot inputs', () => {
+    expect(detectLanguageFromFileName('')).toBe(null);
+    expect(detectLanguageFromFileName('   ')).toBe(null);
+    expect(detectLanguageFromFileName('foo.')).toBe(null);
+  });
+});
+
+describe('resolveFileKind', () => {
+  it('defaults to markdown mode when nothing is supplied', () => {
+    expect(resolveFileKind()).toEqual({ mode: 'markdown', language: 'markdown' });
+  });
+
+  it('returns code mode for recognized code extensions', () => {
+    expect(resolveFileKind('foo.ts')).toEqual({ mode: 'code', language: 'typescript' });
+    expect(resolveFileKind('app.py')).toEqual({ mode: 'code', language: 'python' });
+    expect(resolveFileKind('data.json')).toEqual({ mode: 'code', language: 'json' });
+  });
+
+  it('keeps markdown extensions in markdown mode', () => {
+    expect(resolveFileKind('README.md')).toEqual({ mode: 'markdown', language: 'markdown' });
+    expect(resolveFileKind('doc.markdown')).toEqual({ mode: 'markdown', language: 'markdown' });
+  });
+
+  it('keeps .txt in markdown mode with plaintext language', () => {
+    expect(resolveFileKind('notes.txt')).toEqual({ mode: 'markdown', language: 'plaintext' });
+  });
+
+  it('falls back to markdown mode for unknown extensions', () => {
+    expect(resolveFileKind('foo.xyz')).toEqual({ mode: 'markdown', language: 'markdown' });
+  });
+
+  it('lets the explicit language override fileName detection', () => {
+    expect(resolveFileKind('foo.md', 'typescript')).toEqual({
+      mode: 'code',
+      language: 'typescript',
+    });
+  });
+
+  it('stays in markdown mode when language override is markdown or plaintext', () => {
+    expect(resolveFileKind('foo.ts', 'markdown')).toEqual({
+      mode: 'markdown',
+      language: 'markdown',
+    });
+    expect(resolveFileKind(undefined, 'plaintext')).toEqual({
+      mode: 'markdown',
+      language: 'plaintext',
+    });
+  });
+
+  it('accepts a language with no fileName', () => {
+    expect(resolveFileKind(undefined, 'rust')).toEqual({ mode: 'code', language: 'rust' });
+  });
+});

package/src/__tests__/mediaAttachmentFlow.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import type { MediaProvider } from '@bendyline/squisq/schemas';
+import { markdownToTiptap, tiptapToMarkdown } from '../tiptapBridge';
+
+/**
+ * Attachment-flow regression: earlier versions of MediaBin dropped
+ * uploaded files into the bin without inserting a markdown ref into
+ * the editor body. A user would upload an image, hit Send in the
+ * downstream chat composer, and the outgoing markdown would have no
+ * image reference — the gezel would reply "nothing came through."
+ *
+ * The fix: after `mediaProvider.addMedia(...)` succeeds, MediaBin
+ * fires `onMediaUploaded(relativePath, name, mimeType)`. The
+ * EditorShell wires this to an `insertAtCursor` that emits
+ * `![alt](attachments/<filename>)` so the file actually participates
+ * in the outgoing markdown.
+ *
+ * These tests exercise the contract directly: the markdown snippet
+ * produced by the upload callback, once round-tripped through the
+ * editor's markdown↔HTML bridge, must round-trip back to a form
+ * the gezel service's image-extraction regex can see.
+ */
+
+function fakeMediaProvider(records: string[]): MediaProvider {
+  let counter = 0;
+  return {
+    async addMedia(name: string, _data: ArrayBuffer | Blob | Uint8Array, _mime: string) {
+      counter += 1;
+      const relative = `attachments/${counter}-${name}`;
+      records.push(relative);
+      return relative;
+    },
+    async resolveUrl(relPath: string) {
+      return relPath;
+    },
+    async listMedia() {
+      return [];
+    },
+    async removeMedia(_relPath: string) {
+      /* no-op */
+    },
+    dispose() {
+      /* no-op */
+    },
+  };
+}
+
+/**
+ * Re-implements the exact snippet EditorShell's `insertMediaRef`
+ * builds. Keeping this aligned with the real impl would ordinarily
+ * rely on directly importing the helper; since it's currently inline
+ * in EditorShell, mirror the logic here and lean on the test to
+ * alert us if we drift apart.
+ */
+function buildAttachmentSnippet(relativePath: string, name: string, mimeType: string): string {
+  const alt = name.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
+  return mimeType.startsWith('image/') ? `![${alt}](${relativePath})` : `[${alt}](${relativePath})`;
+}
+
+describe('media attachment flow', () => {
+  it('addMedia → buildAttachmentSnippet → markdown round-trip keeps the ref', async () => {
+    const records: string[] = [];
+    const provider = fakeMediaProvider(records);
+
+    // Simulate MediaBin.handleFileChange for a single PNG drop.
+    const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const relative = await provider.addMedia('my_screenshot.png', pngBytes, 'image/png');
+
+    expect(records).toEqual([relative]);
+    const snippet = buildAttachmentSnippet(relative, 'my_screenshot.png', 'image/png');
+    expect(snippet).toBe(`![my screenshot](${relative})`);
+
+    // Insert snippet into the editor: markdown → HTML → markdown.
+    // This is the path a real insertAtCursor + tiptap onUpdate goes
+    // through. The outbound markdown must still contain the ref.
+    const html = markdownToTiptap(snippet);
+    expect(html).toMatch(/<img\b/);
+    expect(html).toContain(`src="${relative}"`);
+
+    const back = tiptapToMarkdown(html);
+    expect(back).toContain(`![my screenshot](${relative})`);
+  });
+
+  it('handles empty-alt (most common pasted-image shape)', async () => {
+    const records: string[] = [];
+    const provider = fakeMediaProvider(records);
+    const relative = await provider.addMedia('pasted.png', new Uint8Array([0]), 'image/png');
+
+    // Simulate what happens when alt is empty — common for bare pastes
+    // where the user hasn't typed a caption.
+    const snippet = `![](${relative})`;
+    const html = markdownToTiptap(snippet);
+    expect(html).toMatch(/<img\b/);
+    expect(html).toContain(`src="${relative}"`);
+    const back = tiptapToMarkdown(html);
+    expect(back).toContain(`![](${relative})`);
+  });
+
+  it('non-image files fall back to a plain link, still preserving the ref', async () => {
+    const records: string[] = [];
+    const provider = fakeMediaProvider(records);
+    const relative = await provider.addMedia('design.pdf', new Uint8Array([0]), 'application/pdf');
+    const snippet = buildAttachmentSnippet(relative, 'design.pdf', 'application/pdf');
+    expect(snippet).toBe(`[design](${relative})`);
+    // Non-images don't go through the `<img>` regex — they stay as
+    // plain markdown links, which the service-side extractor ignores
+    // but the UI renders as normal hyperlinks.
+    expect(snippet).not.toContain('!');
+  });
+});