@bendyline/squisq-editor-react 2.0.0 → 2.1.0

package/src/codeSnippet/CodeSnippetWidget.tsx

@@ -0,0 +1,109 @@
+/** Monaco inset mounted in place of an ordinary language-tagged code fence. */
+
+import { useCallback, useEffect, useState } from 'react';
+import MonacoEditor, { type OnChange } from '@monaco-editor/react';
+import type { Editor } from '@tiptap/react';
+import { Icon } from '../Icon';
+import { useMonacoLoader } from '../useMonacoLoader';
+import { replaceCodeSnippetText } from './codeSnippetCommands';
+import { useCodeSnippetData } from './codeSnippetData';
+import { codeSnippetFenceLanguageToken } from './codeSnippetLanguages';
+
+export interface CodeSnippetWidgetProps {
+  editor: Editor;
+  blockId: string;
+  host?: HTMLElement | null;
+}
+
+function schemeFromHost(host: HTMLElement | null | undefined): 'light' | 'dark' {
+  return host?.closest<HTMLElement>('[data-theme]')?.dataset.theme === 'dark' ? 'dark' : 'light';
+}
+
+function useHostColorScheme(host: HTMLElement | null | undefined): 'light' | 'dark' {
+  const [scheme, setScheme] = useState<'light' | 'dark'>(() => schemeFromHost(host));
+  useEffect(() => {
+    const themedAncestor = host?.closest<HTMLElement>('[data-theme]');
+    setScheme(schemeFromHost(host));
+    if (!themedAncestor || typeof MutationObserver === 'undefined') return;
+    const observer = new MutationObserver(() => setScheme(schemeFromHost(host)));
+    observer.observe(themedAncestor, { attributes: true, attributeFilter: ['data-theme'] });
+    return () => observer.disconnect();
+  }, [host]);
+  return scheme;
+}
+
+function useEditorEditable(editor: Editor): boolean {
+  const [editable, setEditable] = useState(editor.isEditable);
+  useEffect(() => {
+    const sync = () => setEditable(editor.isEditable);
+    editor.on('update', sync);
+    editor.on('transaction', sync);
+    return () => {
+      editor.off('update', sync);
+      editor.off('transaction', sync);
+    };
+  }, [editor]);
+  return editable;
+}
+
+export function CodeSnippetWidget({ editor, blockId, host }: CodeSnippetWidgetProps) {
+  const data = useCodeSnippetData(editor, blockId);
+  const { ready } = useMonacoLoader();
+  const colorScheme = useHostColorScheme(host);
+  const editable = useEditorEditable(editor);
+
+  const handleChange: OnChange = useCallback(
+    (value) => {
+      if (!editable) return;
+      replaceCodeSnippetText(editor, blockId, value ?? '');
+    },
+    [blockId, editable, editor],
+  );
+
+  if (!data) return null;
+  const modelSuffix = codeSnippetFenceLanguageToken(data.fenceLanguage).replace(
+    /[^a-z0-9_-]/g,
+    '-',
+  );
+
+  return (
+    <div className="squisq-code-snippet-shell" data-language={data.fenceLanguage}>
+      <div className="squisq-code-snippet-header">
+        <span className="squisq-code-snippet-title">
+          <Icon icon="fa-solid fa-file-code" />
+          <span>{data.label}</span>
+        </span>
+        <code>{`\`\`\`${data.fenceLanguage}`}</code>
+      </div>
+      <div className="squisq-code-snippet-editor" aria-label={`${data.label} code editor`}>
+        {ready ? (
+          <MonacoEditor
+            path={`inmemory://squisq/code-snippet/${blockId}.${modelSuffix || 'txt'}`}
+            language={data.monacoLanguage}
+            theme={colorScheme === 'dark' ? 'vs-dark' : 'vs'}
+            value={data.source}
+            onChange={handleChange}
+            options={{
+              automaticLayout: true,
+              contextmenu: true,
+              folding: true,
+              fontSize: 13,
+              lineNumbers: 'on',
+              minimap: { enabled: false },
+              padding: { top: 10, bottom: 10 },
+              readOnly: !editable,
+              renderLineHighlight: 'line',
+              scrollBeyondLastLine: false,
+              tabSize: 2,
+              wordWrap: 'off',
+            }}
+          />
+        ) : (
+          <div className="squisq-code-snippet-loading">Loading code editor…</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default CodeSnippetWidget;

package/src/codeSnippet/__tests__/CodeSnippetExtension.test.ts

@@ -0,0 +1,95 @@
+/** @vitest-environment jsdom */
+
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { markdownToTiptap, tiptapToMarkdown } from '../../tiptapBridge';
+import { replaceCodeSnippetText } from '../codeSnippetCommands';
+import {
+  CODE_SNIPPET_KEY,
+  CodeSnippetExtension,
+  findCodeSnippetBlockPos,
+} from '../CodeSnippetExtension';
+
+vi.mock('../CodeSnippetWidget', () => ({
+  CodeSnippetWidget: () => null,
+}));
+
+const editors: Editor[] = [];
+
+function makeEditor(markdown: string, enabled = true): Editor {
+  const editor = new Editor({
+    extensions: [StarterKit, CodeSnippetExtension.configure({ enabled })],
+    content: markdownToTiptap(markdown),
+  });
+  editors.push(editor);
+  return editor;
+}
+
+function entriesOf(editor: Editor) {
+  return CODE_SNIPPET_KEY.getState(editor.state)?.entries ?? [];
+}
+
+afterEach(() => {
+  for (const editor of editors) editor.destroy();
+  editors.length = 0;
+});
+
+describe('CodeSnippetExtension', () => {
+  it('claims all explicit ordinary code languages, including unknown ones', () => {
+    const editor = makeEditor(
+      '```typescript\nconst n = 1;\n```\n\n```kusto\nTable | take 5\n```\n',
+    );
+    expect(entriesOf(editor)).toHaveLength(2);
+  });
+
+  it('does not steal plain, Mermaid, diagram, tree, or timeline fences', () => {
+    const editor = makeEditor(
+      [
+        '```text\nplain\n```',
+        '```mermaid\nflowchart LR\n  a --> b\n```',
+        '```diagram\n+---+\n| A |\n+---+\n```',
+        '```tree\nsrc/\n└── index.ts\n```',
+        '```timeline\nMilestones: ● Start ─►\n```',
+        '```\nuntagged\n```',
+        '',
+      ].join('\n\n'),
+    );
+    expect(entriesOf(editor)).toHaveLength(0);
+  });
+
+  it('keeps a stable block id and rewrites only the fence body', () => {
+    const editor = makeEditor('```typescript\nconst before = true;\n```\n');
+    const [before] = entriesOf(editor);
+    editor.commands.insertContentAt(0, '<p>Intro</p>');
+    const [shifted] = entriesOf(editor);
+    expect(shifted.id).toBe(before.id);
+    expect(shifted.pos).toBeGreaterThan(before.pos);
+    expect(findCodeSnippetBlockPos(editor, before.id)).toBe(shifted.pos);
+
+    expect(replaceCodeSnippetText(editor, before.id, 'const after: number = 2;')).toBe(true);
+    expect(tiptapToMarkdown(editor.getHTML())).toContain(
+      '```typescript\nconst after: number = 2;\n```',
+    );
+  });
+
+  it('supports clearing the Monaco model without losing the fence language', () => {
+    const editor = makeEditor('```json\n{"key": true}\n```\n');
+    const [entry] = entriesOf(editor);
+    expect(replaceCodeSnippetText(editor, entry.id, '')).toBe(true);
+    const node = editor.state.doc.nodeAt(findCodeSnippetBlockPos(editor, entry.id) ?? -1);
+    expect(node?.textContent).toBe('');
+    expect(node?.attrs.language).toBe('json');
+  });
+
+  it('round-trips the language tag and source byte-for-byte', () => {
+    const markdown = '```typescript\nconst n: number = 1;\n```\n';
+    const editor = makeEditor(markdown);
+    expect(tiptapToMarkdown(editor.getHTML())).toBe(markdown);
+  });
+
+  it('can be disabled', () => {
+    const editor = makeEditor('```typescript\nconst n = 1;\n```\n', false);
+    expect(CODE_SNIPPET_KEY.getState(editor.state)).toBeUndefined();
+  });
+});

package/src/codeSnippet/__tests__/codeSnippetLanguages.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CODE_SNIPPET_LANGUAGES,
+  codeSnippetFenceLanguageToken,
+  codeSnippetLanguageLabel,
+  codeSnippetMarkdown,
+  isCodeSnippetFenceLanguage,
+  monacoLanguageForFence,
+} from '../codeSnippetLanguages';
+
+describe('code snippet languages', () => {
+  it('offers unique explicit fence languages', () => {
+    const languages = CODE_SNIPPET_LANGUAGES.map((entry) => entry.fenceLanguage);
+    expect(new Set(languages).size).toBe(languages.length);
+    expect(languages).toContain('typescript');
+    expect(languages).toContain('json');
+    expect(languages).toContain('python');
+  });
+
+  it('keeps specialized authored-view languages out of the Monaco inset', () => {
+    for (const language of [
+      '',
+      'text',
+      'txt',
+      'plaintext',
+      'ascii',
+      'diagram',
+      'tree',
+      'timeline',
+      'mermaid',
+    ]) {
+      expect(isCodeSnippetFenceLanguage(language), language).toBe(false);
+    }
+    expect(isCodeSnippetFenceLanguage('typescript')).toBe(true);
+    expect(isCodeSnippetFenceLanguage('kusto')).toBe(true);
+  });
+
+  it('uses the first fence token for Monaco while preserving metadata for round trips', () => {
+    expect(codeSnippetFenceLanguageToken('  json data  ')).toBe('json');
+    expect(monacoLanguageForFence('ts highlight-lines')).toBe('typescript');
+    expect(monacoLanguageForFence('yml')).toBe('yaml');
+    expect(codeSnippetLanguageLabel('csharp')).toBe('C#');
+  });
+
+  it('creates an explicit language-tagged Markdown fence', () => {
+    expect(codeSnippetMarkdown('typescript', 'const n: number = 1;')).toBe(
+      '\n```typescript\nconst n: number = 1;\n```\n',
+    );
+  });
+});

package/src/codeSnippet/codeSnippetCommands.ts

@@ -0,0 +1,21 @@
+/** Lossless edits for language-tagged code fences. */
+
+import type { Editor } from '@tiptap/react';
+import { findCodeSnippetBlockPos, isCodeSnippetNode } from './CodeSnippetExtension';
+
+export function replaceCodeSnippetText(editor: Editor, blockId: string, nextText: string): boolean {
+  const pos = findCodeSnippetBlockPos(editor, blockId);
+  if (pos === null) return false;
+  const node = editor.state.doc.nodeAt(pos);
+  if (!node || !isCodeSnippetNode(node)) return false;
+  if (node.textContent === nextText) return true;
+
+  const from = pos + 1;
+  const to = pos + node.nodeSize - 1;
+  const tr =
+    nextText.length > 0
+      ? editor.state.tr.replaceWith(from, to, editor.state.schema.text(nextText))
+      : editor.state.tr.delete(from, to);
+  editor.view.dispatch(tr);
+  return true;
+}

package/src/codeSnippet/codeSnippetData.ts

@@ -0,0 +1,43 @@
+/** Live source/language view for one registered code snippet fence. */
+
+import { useEffect, useMemo, useState } from 'react';
+import type { Editor } from '@tiptap/react';
+import { findCodeSnippetBlockPos, isCodeSnippetNode } from './CodeSnippetExtension';
+import { codeSnippetLanguageLabel, monacoLanguageForFence } from './codeSnippetLanguages';
+
+export interface CodeSnippetData {
+  /** Fence language exactly as stored in the ProseMirror node. */
+  fenceLanguage: string;
+  label: string;
+  monacoLanguage: string;
+  /** Source exactly as stored inside the code block. */
+  source: string;
+}
+
+export function useCodeSnippetData(editor: Editor, blockId: string): CodeSnippetData | null {
+  const [version, setVersion] = useState(0);
+  useEffect(() => {
+    const onTransaction = () => setVersion((value) => value + 1);
+    editor.on('transaction', onTransaction);
+    return () => {
+      editor.off('transaction', onTransaction);
+    };
+  }, [editor]);
+
+  return useMemo(() => {
+    const pos = findCodeSnippetBlockPos(editor, blockId);
+    if (pos === null) return null;
+    const node = editor.state.doc.nodeAt(pos);
+    if (!node || !isCodeSnippetNode(node)) return null;
+    const rawLanguage = (node.attrs as { language?: unknown }).language;
+    const fenceLanguage = typeof rawLanguage === 'string' ? rawLanguage : '';
+    return {
+      fenceLanguage,
+      label: codeSnippetLanguageLabel(fenceLanguage),
+      monacoLanguage: monacoLanguageForFence(fenceLanguage),
+      source: node.textContent,
+    };
+    // `version` is the transaction-backed invalidation token.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, blockId, version]);
+}

package/src/codeSnippet/codeSnippetLanguages.ts

@@ -0,0 +1,216 @@
+/** Languages offered by the Insert Code Snippet menu and understood by Monaco. */
+
+export interface CodeSnippetLanguage {
+  /** Language written after the opening Markdown fence. */
+  readonly fenceLanguage: string;
+  /** Human-readable picker/header label. */
+  readonly label: string;
+  /** Monaco language id used for syntax highlighting and language services. */
+  readonly monacoLanguage: string;
+  /** Small, immediately editable body inserted for a new snippet. */
+  readonly starter: string;
+}
+
+export const CODE_SNIPPET_LANGUAGES: readonly CodeSnippetLanguage[] = [
+  {
+    fenceLanguage: 'typescript',
+    label: 'TypeScript',
+    monacoLanguage: 'typescript',
+    starter: "const message: string = 'Hello, world!';",
+  },
+  {
+    fenceLanguage: 'javascript',
+    label: 'JavaScript',
+    monacoLanguage: 'javascript',
+    starter: "const message = 'Hello, world!';",
+  },
+  {
+    fenceLanguage: 'tsx',
+    label: 'TSX',
+    monacoLanguage: 'typescript',
+    starter: 'export function Component() {\n  return <div>Hello, world!</div>;\n}',
+  },
+  {
+    fenceLanguage: 'jsx',
+    label: 'JSX',
+    monacoLanguage: 'javascript',
+    starter: 'export function Component() {\n  return <div>Hello, world!</div>;\n}',
+  },
+  {
+    fenceLanguage: 'json',
+    label: 'JSON',
+    monacoLanguage: 'json',
+    starter: '{\n  "key": "value"\n}',
+  },
+  {
+    fenceLanguage: 'html',
+    label: 'HTML',
+    monacoLanguage: 'html',
+    starter: '<div>Hello, world!</div>',
+  },
+  {
+    fenceLanguage: 'css',
+    label: 'CSS',
+    monacoLanguage: 'css',
+    starter: '.example {\n  color: #2563eb;\n}',
+  },
+  {
+    fenceLanguage: 'python',
+    label: 'Python',
+    monacoLanguage: 'python',
+    starter: 'print("Hello, world!")',
+  },
+  {
+    fenceLanguage: 'bash',
+    label: 'Shell',
+    monacoLanguage: 'shell',
+    starter: 'echo "Hello, world!"',
+  },
+  {
+    fenceLanguage: 'sql',
+    label: 'SQL',
+    monacoLanguage: 'sql',
+    starter: 'SELECT *\nFROM table_name;',
+  },
+  {
+    fenceLanguage: 'yaml',
+    label: 'YAML',
+    monacoLanguage: 'yaml',
+    starter: 'key: value',
+  },
+  {
+    fenceLanguage: 'markdown',
+    label: 'Markdown',
+    monacoLanguage: 'markdown',
+    starter: '# Heading',
+  },
+  {
+    fenceLanguage: 'java',
+    label: 'Java',
+    monacoLanguage: 'java',
+    starter: 'class Main {\n  public static void main(String[] args) {\n  }\n}',
+  },
+  {
+    fenceLanguage: 'csharp',
+    label: 'C#',
+    monacoLanguage: 'csharp',
+    starter: 'Console.WriteLine("Hello, world!");',
+  },
+  {
+    fenceLanguage: 'cpp',
+    label: 'C++',
+    monacoLanguage: 'cpp',
+    starter: '#include <iostream>\n\nint main() {\n  return 0;\n}',
+  },
+  {
+    fenceLanguage: 'go',
+    label: 'Go',
+    monacoLanguage: 'go',
+    starter: 'package main\n\nfunc main() {\n}',
+  },
+  {
+    fenceLanguage: 'rust',
+    label: 'Rust',
+    monacoLanguage: 'rust',
+    starter: 'fn main() {\n  println!("Hello, world!");\n}',
+  },
+  {
+    fenceLanguage: 'ruby',
+    label: 'Ruby',
+    monacoLanguage: 'ruby',
+    starter: 'puts "Hello, world!"',
+  },
+  {
+    fenceLanguage: 'php',
+    label: 'PHP',
+    monacoLanguage: 'php',
+    starter: '<?php\necho "Hello, world!";',
+  },
+  {
+    fenceLanguage: 'swift',
+    label: 'Swift',
+    monacoLanguage: 'swift',
+    starter: 'print("Hello, world!")',
+  },
+  {
+    fenceLanguage: 'kotlin',
+    label: 'Kotlin',
+    monacoLanguage: 'kotlin',
+    starter: 'fun main() {\n  println("Hello, world!")\n}',
+  },
+  {
+    fenceLanguage: 'dockerfile',
+    label: 'Dockerfile',
+    monacoLanguage: 'dockerfile',
+    starter: 'FROM node:22-alpine',
+  },
+] as const;
+
+const BY_FENCE_LANGUAGE: ReadonlyMap<string, CodeSnippetLanguage> = new Map(
+  CODE_SNIPPET_LANGUAGES.map((language) => [language.fenceLanguage, language]),
+);
+
+/** Languages owned by the diagram/tree/timeline editors or their auto-detection gates. */
+const SPECIAL_FENCE_LANGUAGES = new Set([
+  'text',
+  'txt',
+  'plaintext',
+  'plain',
+  'ascii',
+  'diagram',
+  'tree',
+  'timeline',
+  'mermaid',
+]);
+
+const MONACO_LANGUAGE_ALIASES: Readonly<Record<string, string>> = {
+  c: 'c',
+  'c++': 'cpp',
+  'c#': 'csharp',
+  cs: 'csharp',
+  cxx: 'cpp',
+  docker: 'dockerfile',
+  htm: 'html',
+  js: 'javascript',
+  jsx: 'javascript',
+  md: 'markdown',
+  py: 'python',
+  rb: 'ruby',
+  sh: 'shell',
+  shell: 'shell',
+  ts: 'typescript',
+  tsx: 'typescript',
+  yml: 'yaml',
+};
+
+/** The first token is the syntax id; any remaining fence metadata stays untouched. */
+export function codeSnippetFenceLanguageToken(language: string | null | undefined): string {
+  if (typeof language !== 'string') return '';
+  return language.trim().split(/\s+/, 1)[0]?.toLowerCase() ?? '';
+}
+
+/** True for explicit language-tagged fences not owned by a richer Squisq block editor. */
+export function isCodeSnippetFenceLanguage(language: string | null | undefined): boolean {
+  const token = codeSnippetFenceLanguageToken(language);
+  return token.length > 0 && !SPECIAL_FENCE_LANGUAGES.has(token);
+}
+
+export function monacoLanguageForFence(language: string | null | undefined): string {
+  const token = codeSnippetFenceLanguageToken(language);
+  const catalogEntry = BY_FENCE_LANGUAGE.get(token);
+  return (catalogEntry?.monacoLanguage ?? MONACO_LANGUAGE_ALIASES[token] ?? token) || 'plaintext';
+}
+
+export function codeSnippetLanguageLabel(language: string | null | undefined): string {
+  const token = codeSnippetFenceLanguageToken(language);
+  const catalogEntry = BY_FENCE_LANGUAGE.get(token);
+  if (catalogEntry) return catalogEntry.label;
+  return token
+    ? token.replace(/(^|[-_])([a-z])/g, (_match, _prefix, letter) => letter.toUpperCase())
+    : 'Code';
+}
+
+/** Markdown insertion form. The caller decides whether to wrap selected text or use a starter. */
+export function codeSnippetMarkdown(language: string, source: string): string {
+  return `\n\`\`\`${language}\n${source}\n\`\`\`\n`;
+}

package/src/customTemplates/__tests__/useMemoryLayerAdapter.test.ts

@@ -34,6 +34,19 @@ describe('applyCommand', () => {
     expect(after[0].position.height).toBe(80);
   });
 
+  it('resizeLayer applies an optional north/west origin atomically', () => {
+    const before: Layer[] = [rect('a', 10, 20, 100, 50)];
+    const after = applyCommand(before, {
+      kind: 'resizeLayer',
+      id: 'a',
+      x: 0,
+      y: 5,
+      width: 110,
+      height: 65,
+    });
+    expect(after[0].position).toMatchObject({ x: 0, y: 5, width: 110, height: 65 });
+  });
+
   it('addLayer appends', () => {
     const before: Layer[] = [rect('a', 0, 0)];
     const newLayer = rect('b', 100, 100);

package/src/customTemplates/useMemoryLayerAdapter.ts

@@ -69,7 +69,13 @@ export function applyCommand(layers: readonly Layer[], cmd: SceneCommand): Layer
         l.id === cmd.id
           ? ({
               ...l,
-              position: { ...l.position, width: cmd.width, height: cmd.height },
+              position: {
+                ...l.position,
+                ...(cmd.x !== undefined ? { x: cmd.x } : {}),
+                ...(cmd.y !== undefined ? { y: cmd.y } : {}),
+                width: cmd.width,
+                height: cmd.height,
+              },
             } as Layer)
           : l,
       );

package/src/diagram/DiagramCanvas.tsx

@@ -29,7 +29,14 @@ import { DIAGRAM_VIEWPORT, DIAGRAM_TOOLS } from './diagramConstants';
 
 export type DiagramCommand =
   | { kind: 'moveNode'; nodeId: string; x: number; y: number }
-  | { kind: 'resizeNode'; nodeId: string; width: number; height: number }
+  | {
+      kind: 'resizeNode';
+      nodeId: string;
+      width: number;
+      height: number;
+      x?: number;
+      y?: number;
+    }
   | { kind: 'addConnection'; source: string; target: string; type?: string }
   | { kind: 'removeConnection'; source: string; target: string; type?: string }
   | { kind: 'renameNode'; nodeId: string; newLabel: string }
@@ -145,7 +152,14 @@ export function DiagramCanvas({
           if (!cmd.id.startsWith('node-card-')) return;
           const nodeId = nodeIdFromCardLayerId(cmd.id);
           if (!nodeId) return;
-          onCommand({ kind: 'resizeNode', nodeId, width: cmd.width, height: cmd.height });
+          onCommand({
+            kind: 'resizeNode',
+            nodeId,
+            width: cmd.width,
+            height: cmd.height,
+            ...(cmd.x !== undefined ? { x: cmd.x } : {}),
+            ...(cmd.y !== undefined ? { y: cmd.y } : {}),
+          });
           return;
         }
         case 'setLayerAttr':
@@ -208,6 +222,7 @@ export function DiagramCanvas({
         showMaximize={showMaximize}
         maximized={maximized}
         onToggleMaximize={onToggleMaximize}
+        showViewControls
         showToolbar={false}
         textEditing={textConfig}
       />

package/src/find/FindHighlightExtension.ts

@@ -0,0 +1,81 @@
+import { Extension, type Editor } from '@tiptap/core';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+import { findProseMirrorMatches, normalizeFindIndex } from './findModel';
+
+interface FindHighlightState {
+  query: string;
+  selectedIndex: number;
+  decorations: DecorationSet;
+}
+
+interface FindHighlightMeta {
+  query: string;
+  selectedIndex: number;
+}
+
+const FIND_HIGHLIGHT_KEY = new PluginKey<FindHighlightState>('squisq-find-highlight');
+
+function buildState(
+  doc: Parameters<typeof findProseMirrorMatches>[0],
+  query: string,
+  selectedIndex: number,
+): FindHighlightState {
+  const matches = findProseMirrorMatches(doc, query);
+  const selected = normalizeFindIndex(selectedIndex, matches.length);
+  const decorations = matches.map((match, index) =>
+    Decoration.inline(match.from, match.to, {
+      class:
+        index === selected ? 'squisq-find-match squisq-find-match--selected' : 'squisq-find-match',
+    }),
+  );
+  return {
+    query,
+    selectedIndex: selected,
+    decorations: DecorationSet.create(doc, decorations),
+  };
+}
+
+/** ProseMirror decorations used by the shell's host-triggered Find mode. */
+export const FindHighlightExtension = Extension.create({
+  name: 'squisqFindHighlight',
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin<FindHighlightState>({
+        key: FIND_HIGHLIGHT_KEY,
+        state: {
+          init: (_, state) => buildState(state.doc, '', 0),
+          apply: (transaction, previous, _oldState, newState) => {
+            const meta = transaction.getMeta(FIND_HIGHLIGHT_KEY) as FindHighlightMeta | undefined;
+            if (!meta && !transaction.docChanged) return previous;
+            return buildState(
+              newState.doc,
+              meta?.query ?? previous.query,
+              meta?.selectedIndex ?? previous.selectedIndex,
+            );
+          },
+        },
+        props: {
+          decorations: (state) => FIND_HIGHLIGHT_KEY.getState(state)?.decorations ?? null,
+        },
+      }),
+    ];
+  },
+});
+
+/** Update WYSIWYG highlights and return the current number of matches. */
+export function updateTiptapFindHighlights(
+  editor: Editor,
+  query: string,
+  selectedIndex: number,
+): number {
+  const matches = findProseMirrorMatches(editor.state.doc, query);
+  editor.view.dispatch(
+    editor.state.tr.setMeta(FIND_HIGHLIGHT_KEY, {
+      query,
+      selectedIndex: normalizeFindIndex(selectedIndex, matches.length),
+    } satisfies FindHighlightMeta),
+  );
+  return matches.length;
+}