@puredesktop/platform-editor 1.0.0-beta.1 → 1.0.0-beta.2

package/src/extensions/slashCommands.ts

@@ -1,746 +1,746 @@
-import { Extension, type Editor } from '@tiptap/core'
-import { Plugin, PluginKey, type EditorState } from '@tiptap/pm/state'
-import type { EditorView } from '@tiptap/pm/view'
-import {
-  insertEditableBlockMath,
-  insertEditableInlineMath,
-} from './mathEditing.js'
-
-export interface SlashCommandRange {
-  from: number
-  to: number
-}
-
-export interface SlashCommandRunOptions {
-  editor: Editor
-  range: SlashCommandRange
-  query: string
-  source: 'typed' | 'selection'
-}
-
-export interface SlashCommandItem {
-  id: string
-  title: string
-  description?: string
-  keywords?: string[]
-  section?: string
-  run: (options: SlashCommandRunOptions) => void
-}
-
-interface SlashCommandMatch {
-  range: SlashCommandRange
-  query: string
-}
-
-interface ActiveSlashCommandState extends SlashCommandMatch {
-  items: SlashCommandItem[]
-  source: 'typed' | 'selection'
-}
-
-interface SlashCommandsOptions {
-  items: SlashCommandItem[]
-}
-
-const SLASH_COMMAND_LIMIT = 32
-const SLASH_MENU_MARGIN_PX = 12
-const SLASH_MENU_GAP_PX = 8
-const SLASH_MENU_MAX_HEIGHT_PX = 360
-const SLASH_MENU_MIN_HEIGHT_PX = 120
-
-export const SlashCommands = Extension.create<SlashCommandsOptions>({
-  name: 'slashCommands',
-
-  addOptions() {
-    return {
-      items: [],
-    }
-  },
-
-  addProseMirrorPlugins() {
-    const extension = this
-    let active: ActiveSlashCommandState | null = null
-    let selectedIndex = 0
-    let menu: HTMLDivElement | null = null
-    let detachViewportListeners: (() => void) | null = null
-
-    const emitOpenState = (open: boolean): void => {
-      extension.editor?.view?.dom?.dispatchEvent(
-        new CustomEvent('ps-slash-menu-toggle', { detail: { open } }),
-      )
-    }
-
-    const closeMenu = (): void => {
-      const wasOpen = menu !== null
-      active = null
-      selectedIndex = 0
-      detachViewportListeners?.()
-      detachViewportListeners = null
-      menu?.remove()
-      menu = null
-      if (wasOpen) emitOpenState(false)
-    }
-
-    const positionMenu = (view: EditorView): void => {
-      if (!active || !menu) return
-
-      const coords = view.coordsAtPos(active.range.from)
-      const viewportWidth = window.innerWidth
-      const viewportHeight = window.innerHeight
-      const margin = SLASH_MENU_MARGIN_PX
-      const gap = SLASH_MENU_GAP_PX
-      const maxPanelWidth = Math.max(0, viewportWidth - margin * 2)
-
-      menu.style.maxHeight = `${SLASH_MENU_MAX_HEIGHT_PX}px`
-      menu.style.overflowY = 'auto'
-
-      const measured = menu.getBoundingClientRect()
-      const width = Math.min(
-        Math.max(measured.width || 280, 280),
-        maxPanelWidth,
-      )
-      const naturalHeight = Math.min(
-        menu.scrollHeight,
-        SLASH_MENU_MAX_HEIGHT_PX,
-      )
-      const spaceBelow = Math.max(
-        0,
-        viewportHeight - coords.bottom - gap - margin,
-      )
-      const spaceAbove = Math.max(0, coords.top - gap - margin)
-      const openAbove = naturalHeight > spaceBelow && spaceAbove > spaceBelow
-      const availableSpace = openAbove ? spaceAbove : spaceBelow
-      const height = Math.max(
-        Math.min(naturalHeight, availableSpace),
-        Math.min(SLASH_MENU_MIN_HEIGHT_PX, naturalHeight, availableSpace),
-      )
-      const left = Math.min(
-        Math.max(margin, coords.left),
-        Math.max(margin, viewportWidth - width - margin),
-      )
-      const top = openAbove
-        ? Math.max(margin, coords.top - gap - height)
-        : Math.min(coords.bottom + gap, viewportHeight - margin - height)
-
-      menu.style.left = `${left}px`
-      menu.style.top = `${top}px`
-      menu.style.width = `${width}px`
-      menu.style.maxHeight = `${height}px`
-    }
-
-    const attachViewportListeners = (view: EditorView): void => {
-      if (detachViewportListeners) return
-
-      let animationFrame = 0
-      const reposition = (): void => {
-        cancelAnimationFrame(animationFrame)
-        animationFrame = requestAnimationFrame(() => {
-          positionMenu(view)
-        })
-      }
-
-      window.addEventListener('resize', reposition)
-      window.addEventListener('scroll', reposition, true)
-      detachViewportListeners = () => {
-        cancelAnimationFrame(animationFrame)
-        window.removeEventListener('resize', reposition)
-        window.removeEventListener('scroll', reposition, true)
-      }
-    }
-
-    const renderMenu = (view: EditorView): void => {
-      if (!active || !active.items.length) {
-        closeMenu()
-        return
-      }
-
-      const justOpened = !menu
-      if (!menu) {
-        menu = document.createElement('div')
-        menu.className = 'ps-slash-command-menu'
-        document.body.appendChild(menu)
-      }
-      attachViewportListeners(view)
-      if (justOpened) emitOpenState(true)
-
-      menu.replaceChildren()
-
-      let previousSection: string | null = null
-
-      active.items.forEach((item, index) => {
-        const section = item.section ?? 'Writing'
-        if (section !== previousSection) {
-          if (previousSection !== null) {
-            const divider = document.createElement('div')
-            divider.className = 'ps-slash-command-divider'
-            menu?.appendChild(divider)
-          }
-
-          const heading = document.createElement('div')
-          heading.className = 'ps-slash-command-section'
-          heading.textContent = section
-          menu?.appendChild(heading)
-          previousSection = section
-        }
-
-        const button = document.createElement('button')
-        button.type = 'button'
-        button.className = 'ps-slash-command-item'
-        button.dataset.active = String(index === selectedIndex)
-        button.addEventListener('mousedown', event => {
-          event.preventDefault()
-          runItem(view, item)
-        })
-
-        const title = document.createElement('span')
-        title.className = 'ps-slash-command-title'
-        title.textContent = item.title
-        button.appendChild(title)
-
-        if (item.description) {
-          const description = document.createElement('span')
-          description.className = 'ps-slash-command-description'
-          description.textContent = item.description
-          button.appendChild(description)
-        }
-
-        menu?.appendChild(button)
-      })
-
-      positionMenu(view)
-      menu
-        .querySelector<HTMLButtonElement>(
-          '.ps-slash-command-item[data-active="true"]',
-        )
-        ?.scrollIntoView({ block: 'nearest' })
-    }
-
-    const runItem = (view: EditorView, item: SlashCommandItem): void => {
-      if (!active) return
-      const current = active
-      closeMenu()
-      item.run({
-        editor: extension.editor,
-        range: current.range,
-        query: current.query,
-        source: current.source,
-      })
-      view.focus()
-    }
-
-    const updateActiveState = (state: EditorState): void => {
-      // A selection-opened menu has no typed "/" to match, so the typed-match
-      // logic below would close it on the next view update. Keep it open until
-      // the selection collapses (or it's dismissed via Escape/click/run).
-      if (active?.source === 'selection') {
-        if (state.selection.empty) closeMenu()
-        return
-      }
-
-      const match = findSlashCommandMatch(state)
-      if (!match) {
-        closeMenu()
-        return
-      }
-
-      const items = filterSlashCommandItems(
-        extension.options.items,
-        match.query,
-      )
-      if (!items.length) {
-        closeMenu()
-        return
-      }
-
-      active = { ...match, items, source: 'typed' }
-      selectedIndex = Math.min(selectedIndex, items.length - 1)
-    }
-
-    return [
-      new Plugin({
-        key: new PluginKey('slashCommands'),
-        props: {
-          handleKeyDown(view, event) {
-            if (!active && event.key === '/') {
-              const { from, to, empty } = view.state.selection
-              if (!empty) {
-                event.preventDefault()
-                const items = filterSlashCommandItems(extension.options.items, '')
-                if (!items.length) return true
-                active = {
-                  range: { from, to },
-                  query: '',
-                  items,
-                  source: 'selection',
-                }
-                selectedIndex = 0
-                renderMenu(view)
-                return true
-              }
-            }
-
-            if (!active) return false
-
-            if (active.source === 'selection') {
-              if (event.key.length === 1 && !event.metaKey && !event.ctrlKey) {
-                event.preventDefault()
-                active = {
-                  ...active,
-                  query: `${active.query}${event.key}`.trim(),
-                  items: filterSlashCommandItems(
-                    extension.options.items,
-                    `${active.query}${event.key}`.trim(),
-                  ),
-                }
-                selectedIndex = 0
-                renderMenu(view)
-                return true
-              }
-
-              if (event.key === 'Backspace') {
-                event.preventDefault()
-                const query = active.query.slice(0, -1)
-                active = {
-                  ...active,
-                  query,
-                  items: filterSlashCommandItems(extension.options.items, query),
-                }
-                selectedIndex = 0
-                renderMenu(view)
-                return true
-              }
-            }
-
-            if (event.key === 'ArrowDown') {
-              event.preventDefault()
-              selectedIndex = (selectedIndex + 1) % active.items.length
-              renderMenu(view)
-              return true
-            }
-
-            if (event.key === 'ArrowUp') {
-              event.preventDefault()
-              selectedIndex =
-                (selectedIndex - 1 + active.items.length) % active.items.length
-              renderMenu(view)
-              return true
-            }
-
-            if (event.key === 'Enter') {
-              event.preventDefault()
-              runItem(view, active.items[selectedIndex])
-              return true
-            }
-
-            if (event.key === 'Escape') {
-              event.preventDefault()
-              closeMenu()
-              return true
-            }
-
-            return false
-          },
-        },
-        view(view) {
-          injectSlashCommandStyles()
-          updateActiveState(view.state)
-          renderMenu(view)
-
-          return {
-            update(nextView) {
-              updateActiveState(nextView.state)
-              renderMenu(nextView)
-            },
-            destroy() {
-              closeMenu()
-            },
-          }
-        },
-      }),
-    ]
-  },
-})
-
-interface DefaultSlashCommandOptions {
-  includePrompts?: boolean
-}
-
-type ChainWithOptionalCommands = ReturnType<Editor['chain']> & {
-  toggleUnderline?: () => ChainWithOptionalCommands
-  toggleCode?: () => ChainWithOptionalCommands
-  toggleTaskList?: () => ChainWithOptionalCommands
-  sinkListItem?: (type: string) => ChainWithOptionalCommands
-  liftListItem?: (type: string) => ChainWithOptionalCommands
-  insertTable?: (options: {
-    rows: number
-    cols: number
-    withHeaderRow: boolean
-  }) => ChainWithOptionalCommands
-  insertFootnote?: () => ChainWithOptionalCommands
-  toggleIndexMarker?: () => ChainWithOptionalCommands
-  insertInlineMath?: (options: { latex: string }) => ChainWithOptionalCommands
-  insertBlockMath?: (options: { latex: string }) => ChainWithOptionalCommands
-  insertMermaidBlock?: () => ChainWithOptionalCommands
-  setLink?: (attributes: { href: string }) => ChainWithOptionalCommands
-}
-
-function commandChain(
-  editor: Editor,
-  range: SlashCommandRange,
-  source: SlashCommandRunOptions['source'],
-): ChainWithOptionalCommands {
-  const chain = editor.chain().focus() as ChainWithOptionalCommands
-  if (source === 'typed') return chain.deleteRange(range)
-  // Opened from a selection: re-assert the original range so toggles like
-  // bold/italic actually transform the selected text (a bare focus() can land
-  // on a collapsed cursor and no-op).
-  if (source === 'selection') return chain.setTextSelection(range)
-  return chain
-}
-
-export function createDefaultSlashCommands(
-  options: DefaultSlashCommandOptions = {},
-): SlashCommandItem[] {
-  const promptEnabled = options.includePrompts ?? true
-  return [
-    {
-      id: 'paragraph',
-      title: 'Text',
-      description: 'Start a normal paragraph',
-      keywords: ['paragraph', 'normal'],
-      section: 'Writing',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).setParagraph().run()
-      },
-    },
-    {
-      id: 'heading-1',
-      title: 'Heading 1',
-      description: 'Large section heading',
-      keywords: ['title', 'h1'],
-      section: 'Writing',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).setNode('heading', { level: 1 }).run()
-      },
-    },
-    {
-      id: 'heading-2',
-      title: 'Heading 2',
-      description: 'Medium section heading',
-      keywords: ['subtitle', 'h2'],
-      section: 'Writing',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).setNode('heading', { level: 2 }).run()
-      },
-    },
-    {
-      id: 'heading-3',
-      title: 'Heading 3',
-      description: 'Small section heading',
-      keywords: ['subtitle', 'h3'],
-      section: 'Writing',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).setNode('heading', { level: 3 }).run()
-      },
-    },
-    {
-      id: 'bold',
-      title: 'Bold',
-      description: 'Emphasize the selected text',
-      keywords: ['strong'],
-      section: 'Formatting',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleBold().run()
-      },
-    },
-    {
-      id: 'italic',
-      title: 'Italic',
-      description: 'Italicize the selected text',
-      keywords: ['emphasis'],
-      section: 'Formatting',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleItalic().run()
-      },
-    },
-    {
-      id: 'underline',
-      title: 'Underline',
-      description: 'Underline the selected text',
-      section: 'Formatting',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleUnderline?.()?.run()
-      },
-    },
-    {
-      id: 'inline-code',
-      title: 'Inline code',
-      description: 'Mark text as code',
-      keywords: ['code'],
-      section: 'Formatting',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleCode?.()?.run()
-      },
-    },
-    {
-      id: 'link',
-      title: 'Link',
-      description: 'Add a link to the selected text',
-      keywords: ['url', 'href'],
-      section: 'Formatting',
-      run: ({ editor, range, source }) => {
-        if (!promptEnabled) return
-        const href = window.prompt('Link URL')?.trim()
-        if (!href) return
-        commandChain(editor, range, source).setLink?.({ href })?.run()
-      },
-    },
-    {
-      id: 'bullet-list',
-      title: 'Bullet list',
-      description: 'Create a simple list',
-      keywords: ['unordered', 'list'],
-      section: 'Lists',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleBulletList().run()
-      },
-    },
-    {
-      id: 'numbered-list',
-      title: 'Numbered list',
-      description: 'Create an ordered list',
-      keywords: ['ordered', 'list'],
-      section: 'Lists',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleOrderedList().run()
-      },
-    },
-    {
-      id: 'task-list',
-      title: 'Task list',
-      description: 'Create a checklist',
-      keywords: ['todo', 'checkbox'],
-      section: 'Lists',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleTaskList?.()?.run()
-      },
-    },
-    {
-      id: 'indent-list',
-      title: 'Indent list item',
-      description: 'Nest the current list item',
-      keywords: ['sink', 'nest'],
-      section: 'Lists',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).sinkListItem?.('listItem')?.run()
-      },
-    },
-    {
-      id: 'outdent-list',
-      title: 'Outdent list item',
-      description: 'Lift the current list item',
-      keywords: ['lift', 'unnest'],
-      section: 'Lists',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).liftListItem?.('listItem')?.run()
-      },
-    },
-    {
-      id: 'quote',
-      title: 'Quote',
-      description: 'Call out a quoted passage',
-      keywords: ['blockquote', 'citation'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleBlockquote().run()
-      },
-    },
-    {
-      id: 'code-block',
-      title: 'Code block',
-      description: 'Insert a code section',
-      keywords: ['code', 'pre'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleCodeBlock().run()
-      },
-    },
-    {
-      id: 'table',
-      title: 'Table',
-      description: 'Insert a simple table',
-      keywords: ['grid'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source)
-          .insertTable?.({ rows: 3, cols: 3, withHeaderRow: true })
-          ?.run()
-      },
-    },
-    {
-      id: 'footnote',
-      title: 'Footnote',
-      description: 'Insert a footnote marker',
-      keywords: ['note', 'reference'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).insertFootnote?.()?.run()
-      },
-    },
-    {
-      id: 'index-marker',
-      title: 'Index marker',
-      description: 'Mark selected text for the index',
-      keywords: ['index'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).toggleIndexMarker?.()?.run()
-      },
-    },
-    {
-      id: 'inline-equation',
-      title: 'Inline equation',
-      description: 'Insert an editable inline equation',
-      keywords: ['math', 'latex'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        // Remove the typed "/…" text, then insert an empty equation and open
-        // its editor immediately (live preview; renders in place on blur).
-        commandChain(editor, range, source).run()
-        insertEditableInlineMath(editor)
-      },
-    },
-    {
-      id: 'display-equation',
-      title: 'Display equation',
-      description: 'Insert an editable centered equation',
-      keywords: ['math', 'latex', 'block'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).run()
-        insertEditableBlockMath(editor)
-      },
-    },
-    {
-      id: 'mermaid',
-      title: 'Mermaid diagram',
-      description: 'Insert a diagram block',
-      keywords: ['diagram', 'flowchart'],
-      section: 'Blocks',
-      run: ({ editor, range, source }) => {
-        commandChain(editor, range, source).insertMermaidBlock?.()?.run()
-      },
-    },
-  ]
-}
-
-function findSlashCommandMatch(state: EditorState): SlashCommandMatch | null {
-  const { selection } = state
-  if (!selection.empty) return null
-
-  const { $from } = selection
-  const textBefore = $from.parent.textBetween(0, $from.parentOffset, '\0', '\0')
-  const match = /(?:^|\s)\/([\w\s-]{0,48})$/.exec(textBefore)
-  if (!match) return null
-
-  const fullMatch = match[0]
-  const slashOffset = fullMatch.lastIndexOf('/')
-  const from = $from.pos - (fullMatch.length - slashOffset)
-
-  return {
-    range: { from, to: $from.pos },
-    query: match[1]?.trim() ?? '',
-  }
-}
-
-function filterSlashCommandItems(
-  items: SlashCommandItem[],
-  query: string,
-): SlashCommandItem[] {
-  const normalizedQuery = query.toLowerCase()
-  if (!normalizedQuery) return items
-
-  return items
-    .filter(item => {
-      const haystack = [
-        item.title,
-        item.description ?? '',
-        ...(item.keywords ?? []),
-      ]
-        .join(' ')
-        .toLowerCase()
-      return haystack.includes(normalizedQuery)
-    })
-    .slice(0, SLASH_COMMAND_LIMIT)
-}
-
-function injectSlashCommandStyles(): void {
-  if (document.getElementById('ps-slash-command-styles')) return
-
-  const style = document.createElement('style')
-  style.id = 'ps-slash-command-styles'
-  style.textContent = `
-    .ps-slash-command-menu {
-      position: fixed;
-      z-index: var(--platform-z-index-zi-app-menus, 1000);
-      box-sizing: border-box;
-      min-width: 280px;
-      max-width: 340px;
-      padding: 6px;
-      border: 1px solid var(--platform-colors-border, #d7dbe0);
-      border-radius: 10px;
-      background: var(--platform-colors-surface, #fff);
-      box-shadow: 0 14px 34px rgb(23 29 36 / 0.14);
-      color: var(--platform-colors-text, #2e3338);
-      font-family: var(--platform-typography-font-family, system-ui, sans-serif);
-      overflow-x: hidden;
-      overscroll-behavior: contain;
-    }
-
-    .ps-slash-command-item {
-      display: grid;
-      width: 100%;
-      gap: 2px;
-      padding: 8px 10px;
-      border: 0;
-      border-radius: 7px;
-      background: transparent;
-      color: inherit;
-      font: inherit;
-      text-align: left;
-      cursor: pointer;
-    }
-
-    .ps-slash-command-section {
-      color: var(--platform-colors-text-tertiary, #8a9097);
-      font-size: 10px;
-      font-weight: 700;
-      letter-spacing: 0.08em;
-      line-height: 1.2;
-      padding: 9px 10px 5px;
-      text-transform: uppercase;
-    }
-
-    .ps-slash-command-divider {
-      border-top: 1px solid var(--platform-colors-border, #d7dbe0);
-      margin: 6px 4px 2px;
-    }
-
-    .ps-slash-command-item[data-active="true"],
-    .ps-slash-command-item:hover {
-      background: var(--platform-colors-surface-active, #edeff2);
-    }
-
-    .ps-slash-command-title {
-      font-size: 13px;
-      font-weight: 650;
-      line-height: 1.25;
-    }
-
-    .ps-slash-command-description {
-      color: var(--platform-colors-text-secondary, #6e737a);
-      font-size: 12px;
-      line-height: 1.25;
-    }
-  `
-  document.head.appendChild(style)
-}
+import { Extension, type Editor } from '@tiptap/core'
+import { Plugin, PluginKey, type EditorState } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+import {
+  insertEditableBlockMath,
+  insertEditableInlineMath,
+} from './mathEditing.js'
+
+export interface SlashCommandRange {
+  from: number
+  to: number
+}
+
+export interface SlashCommandRunOptions {
+  editor: Editor
+  range: SlashCommandRange
+  query: string
+  source: 'typed' | 'selection'
+}
+
+export interface SlashCommandItem {
+  id: string
+  title: string
+  description?: string
+  keywords?: string[]
+  section?: string
+  run: (options: SlashCommandRunOptions) => void
+}
+
+interface SlashCommandMatch {
+  range: SlashCommandRange
+  query: string
+}
+
+interface ActiveSlashCommandState extends SlashCommandMatch {
+  items: SlashCommandItem[]
+  source: 'typed' | 'selection'
+}
+
+interface SlashCommandsOptions {
+  items: SlashCommandItem[]
+}
+
+const SLASH_COMMAND_LIMIT = 32
+const SLASH_MENU_MARGIN_PX = 12
+const SLASH_MENU_GAP_PX = 8
+const SLASH_MENU_MAX_HEIGHT_PX = 360
+const SLASH_MENU_MIN_HEIGHT_PX = 120
+
+export const SlashCommands = Extension.create<SlashCommandsOptions>({
+  name: 'slashCommands',
+
+  addOptions() {
+    return {
+      items: [],
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const extension = this
+    let active: ActiveSlashCommandState | null = null
+    let selectedIndex = 0
+    let menu: HTMLDivElement | null = null
+    let detachViewportListeners: (() => void) | null = null
+
+    const emitOpenState = (open: boolean): void => {
+      extension.editor?.view?.dom?.dispatchEvent(
+        new CustomEvent('ps-slash-menu-toggle', { detail: { open } }),
+      )
+    }
+
+    const closeMenu = (): void => {
+      const wasOpen = menu !== null
+      active = null
+      selectedIndex = 0
+      detachViewportListeners?.()
+      detachViewportListeners = null
+      menu?.remove()
+      menu = null
+      if (wasOpen) emitOpenState(false)
+    }
+
+    const positionMenu = (view: EditorView): void => {
+      if (!active || !menu) return
+
+      const coords = view.coordsAtPos(active.range.from)
+      const viewportWidth = window.innerWidth
+      const viewportHeight = window.innerHeight
+      const margin = SLASH_MENU_MARGIN_PX
+      const gap = SLASH_MENU_GAP_PX
+      const maxPanelWidth = Math.max(0, viewportWidth - margin * 2)
+
+      menu.style.maxHeight = `${SLASH_MENU_MAX_HEIGHT_PX}px`
+      menu.style.overflowY = 'auto'
+
+      const measured = menu.getBoundingClientRect()
+      const width = Math.min(
+        Math.max(measured.width || 280, 280),
+        maxPanelWidth,
+      )
+      const naturalHeight = Math.min(
+        menu.scrollHeight,
+        SLASH_MENU_MAX_HEIGHT_PX,
+      )
+      const spaceBelow = Math.max(
+        0,
+        viewportHeight - coords.bottom - gap - margin,
+      )
+      const spaceAbove = Math.max(0, coords.top - gap - margin)
+      const openAbove = naturalHeight > spaceBelow && spaceAbove > spaceBelow
+      const availableSpace = openAbove ? spaceAbove : spaceBelow
+      const height = Math.max(
+        Math.min(naturalHeight, availableSpace),
+        Math.min(SLASH_MENU_MIN_HEIGHT_PX, naturalHeight, availableSpace),
+      )
+      const left = Math.min(
+        Math.max(margin, coords.left),
+        Math.max(margin, viewportWidth - width - margin),
+      )
+      const top = openAbove
+        ? Math.max(margin, coords.top - gap - height)
+        : Math.min(coords.bottom + gap, viewportHeight - margin - height)
+
+      menu.style.left = `${left}px`
+      menu.style.top = `${top}px`
+      menu.style.width = `${width}px`
+      menu.style.maxHeight = `${height}px`
+    }
+
+    const attachViewportListeners = (view: EditorView): void => {
+      if (detachViewportListeners) return
+
+      let animationFrame = 0
+      const reposition = (): void => {
+        cancelAnimationFrame(animationFrame)
+        animationFrame = requestAnimationFrame(() => {
+          positionMenu(view)
+        })
+      }
+
+      window.addEventListener('resize', reposition)
+      window.addEventListener('scroll', reposition, true)
+      detachViewportListeners = () => {
+        cancelAnimationFrame(animationFrame)
+        window.removeEventListener('resize', reposition)
+        window.removeEventListener('scroll', reposition, true)
+      }
+    }
+
+    const renderMenu = (view: EditorView): void => {
+      if (!active || !active.items.length) {
+        closeMenu()
+        return
+      }
+
+      const justOpened = !menu
+      if (!menu) {
+        menu = document.createElement('div')
+        menu.className = 'ps-slash-command-menu'
+        document.body.appendChild(menu)
+      }
+      attachViewportListeners(view)
+      if (justOpened) emitOpenState(true)
+
+      menu.replaceChildren()
+
+      let previousSection: string | null = null
+
+      active.items.forEach((item, index) => {
+        const section = item.section ?? 'Writing'
+        if (section !== previousSection) {
+          if (previousSection !== null) {
+            const divider = document.createElement('div')
+            divider.className = 'ps-slash-command-divider'
+            menu?.appendChild(divider)
+          }
+
+          const heading = document.createElement('div')
+          heading.className = 'ps-slash-command-section'
+          heading.textContent = section
+          menu?.appendChild(heading)
+          previousSection = section
+        }
+
+        const button = document.createElement('button')
+        button.type = 'button'
+        button.className = 'ps-slash-command-item'
+        button.dataset.active = String(index === selectedIndex)
+        button.addEventListener('mousedown', event => {
+          event.preventDefault()
+          runItem(view, item)
+        })
+
+        const title = document.createElement('span')
+        title.className = 'ps-slash-command-title'
+        title.textContent = item.title
+        button.appendChild(title)
+
+        if (item.description) {
+          const description = document.createElement('span')
+          description.className = 'ps-slash-command-description'
+          description.textContent = item.description
+          button.appendChild(description)
+        }
+
+        menu?.appendChild(button)
+      })
+
+      positionMenu(view)
+      menu
+        .querySelector<HTMLButtonElement>(
+          '.ps-slash-command-item[data-active="true"]',
+        )
+        ?.scrollIntoView({ block: 'nearest' })
+    }
+
+    const runItem = (view: EditorView, item: SlashCommandItem): void => {
+      if (!active) return
+      const current = active
+      closeMenu()
+      item.run({
+        editor: extension.editor,
+        range: current.range,
+        query: current.query,
+        source: current.source,
+      })
+      view.focus()
+    }
+
+    const updateActiveState = (state: EditorState): void => {
+      // A selection-opened menu has no typed "/" to match, so the typed-match
+      // logic below would close it on the next view update. Keep it open until
+      // the selection collapses (or it's dismissed via Escape/click/run).
+      if (active?.source === 'selection') {
+        if (state.selection.empty) closeMenu()
+        return
+      }
+
+      const match = findSlashCommandMatch(state)
+      if (!match) {
+        closeMenu()
+        return
+      }
+
+      const items = filterSlashCommandItems(
+        extension.options.items,
+        match.query,
+      )
+      if (!items.length) {
+        closeMenu()
+        return
+      }
+
+      active = { ...match, items, source: 'typed' }
+      selectedIndex = Math.min(selectedIndex, items.length - 1)
+    }
+
+    return [
+      new Plugin({
+        key: new PluginKey('slashCommands'),
+        props: {
+          handleKeyDown(view, event) {
+            if (!active && event.key === '/') {
+              const { from, to, empty } = view.state.selection
+              if (!empty) {
+                event.preventDefault()
+                const items = filterSlashCommandItems(extension.options.items, '')
+                if (!items.length) return true
+                active = {
+                  range: { from, to },
+                  query: '',
+                  items,
+                  source: 'selection',
+                }
+                selectedIndex = 0
+                renderMenu(view)
+                return true
+              }
+            }
+
+            if (!active) return false
+
+            if (active.source === 'selection') {
+              if (event.key.length === 1 && !event.metaKey && !event.ctrlKey) {
+                event.preventDefault()
+                active = {
+                  ...active,
+                  query: `${active.query}${event.key}`.trim(),
+                  items: filterSlashCommandItems(
+                    extension.options.items,
+                    `${active.query}${event.key}`.trim(),
+                  ),
+                }
+                selectedIndex = 0
+                renderMenu(view)
+                return true
+              }
+
+              if (event.key === 'Backspace') {
+                event.preventDefault()
+                const query = active.query.slice(0, -1)
+                active = {
+                  ...active,
+                  query,
+                  items: filterSlashCommandItems(extension.options.items, query),
+                }
+                selectedIndex = 0
+                renderMenu(view)
+                return true
+              }
+            }
+
+            if (event.key === 'ArrowDown') {
+              event.preventDefault()
+              selectedIndex = (selectedIndex + 1) % active.items.length
+              renderMenu(view)
+              return true
+            }
+
+            if (event.key === 'ArrowUp') {
+              event.preventDefault()
+              selectedIndex =
+                (selectedIndex - 1 + active.items.length) % active.items.length
+              renderMenu(view)
+              return true
+            }
+
+            if (event.key === 'Enter') {
+              event.preventDefault()
+              runItem(view, active.items[selectedIndex])
+              return true
+            }
+
+            if (event.key === 'Escape') {
+              event.preventDefault()
+              closeMenu()
+              return true
+            }
+
+            return false
+          },
+        },
+        view(view) {
+          injectSlashCommandStyles()
+          updateActiveState(view.state)
+          renderMenu(view)
+
+          return {
+            update(nextView) {
+              updateActiveState(nextView.state)
+              renderMenu(nextView)
+            },
+            destroy() {
+              closeMenu()
+            },
+          }
+        },
+      }),
+    ]
+  },
+})
+
+interface DefaultSlashCommandOptions {
+  includePrompts?: boolean
+}
+
+type ChainWithOptionalCommands = ReturnType<Editor['chain']> & {
+  toggleUnderline?: () => ChainWithOptionalCommands
+  toggleCode?: () => ChainWithOptionalCommands
+  toggleTaskList?: () => ChainWithOptionalCommands
+  sinkListItem?: (type: string) => ChainWithOptionalCommands
+  liftListItem?: (type: string) => ChainWithOptionalCommands
+  insertTable?: (options: {
+    rows: number
+    cols: number
+    withHeaderRow: boolean
+  }) => ChainWithOptionalCommands
+  insertFootnote?: () => ChainWithOptionalCommands
+  toggleIndexMarker?: () => ChainWithOptionalCommands
+  insertInlineMath?: (options: { latex: string }) => ChainWithOptionalCommands
+  insertBlockMath?: (options: { latex: string }) => ChainWithOptionalCommands
+  insertMermaidBlock?: () => ChainWithOptionalCommands
+  setLink?: (attributes: { href: string }) => ChainWithOptionalCommands
+}
+
+function commandChain(
+  editor: Editor,
+  range: SlashCommandRange,
+  source: SlashCommandRunOptions['source'],
+): ChainWithOptionalCommands {
+  const chain = editor.chain().focus() as ChainWithOptionalCommands
+  if (source === 'typed') return chain.deleteRange(range)
+  // Opened from a selection: re-assert the original range so toggles like
+  // bold/italic actually transform the selected text (a bare focus() can land
+  // on a collapsed cursor and no-op).
+  if (source === 'selection') return chain.setTextSelection(range)
+  return chain
+}
+
+export function createDefaultSlashCommands(
+  options: DefaultSlashCommandOptions = {},
+): SlashCommandItem[] {
+  const promptEnabled = options.includePrompts ?? true
+  return [
+    {
+      id: 'paragraph',
+      title: 'Text',
+      description: 'Start a normal paragraph',
+      keywords: ['paragraph', 'normal'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setParagraph().run()
+      },
+    },
+    {
+      id: 'heading-1',
+      title: 'Heading 1',
+      description: 'Large section heading',
+      keywords: ['title', 'h1'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setNode('heading', { level: 1 }).run()
+      },
+    },
+    {
+      id: 'heading-2',
+      title: 'Heading 2',
+      description: 'Medium section heading',
+      keywords: ['subtitle', 'h2'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setNode('heading', { level: 2 }).run()
+      },
+    },
+    {
+      id: 'heading-3',
+      title: 'Heading 3',
+      description: 'Small section heading',
+      keywords: ['subtitle', 'h3'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setNode('heading', { level: 3 }).run()
+      },
+    },
+    {
+      id: 'bold',
+      title: 'Bold',
+      description: 'Emphasize the selected text',
+      keywords: ['strong'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleBold().run()
+      },
+    },
+    {
+      id: 'italic',
+      title: 'Italic',
+      description: 'Italicize the selected text',
+      keywords: ['emphasis'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleItalic().run()
+      },
+    },
+    {
+      id: 'underline',
+      title: 'Underline',
+      description: 'Underline the selected text',
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleUnderline?.()?.run()
+      },
+    },
+    {
+      id: 'inline-code',
+      title: 'Inline code',
+      description: 'Mark text as code',
+      keywords: ['code'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleCode?.()?.run()
+      },
+    },
+    {
+      id: 'link',
+      title: 'Link',
+      description: 'Add a link to the selected text',
+      keywords: ['url', 'href'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        if (!promptEnabled) return
+        const href = window.prompt('Link URL')?.trim()
+        if (!href) return
+        commandChain(editor, range, source).setLink?.({ href })?.run()
+      },
+    },
+    {
+      id: 'bullet-list',
+      title: 'Bullet list',
+      description: 'Create a simple list',
+      keywords: ['unordered', 'list'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleBulletList().run()
+      },
+    },
+    {
+      id: 'numbered-list',
+      title: 'Numbered list',
+      description: 'Create an ordered list',
+      keywords: ['ordered', 'list'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleOrderedList().run()
+      },
+    },
+    {
+      id: 'task-list',
+      title: 'Task list',
+      description: 'Create a checklist',
+      keywords: ['todo', 'checkbox'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleTaskList?.()?.run()
+      },
+    },
+    {
+      id: 'indent-list',
+      title: 'Indent list item',
+      description: 'Nest the current list item',
+      keywords: ['sink', 'nest'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).sinkListItem?.('listItem')?.run()
+      },
+    },
+    {
+      id: 'outdent-list',
+      title: 'Outdent list item',
+      description: 'Lift the current list item',
+      keywords: ['lift', 'unnest'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).liftListItem?.('listItem')?.run()
+      },
+    },
+    {
+      id: 'quote',
+      title: 'Quote',
+      description: 'Call out a quoted passage',
+      keywords: ['blockquote', 'citation'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleBlockquote().run()
+      },
+    },
+    {
+      id: 'code-block',
+      title: 'Code block',
+      description: 'Insert a code section',
+      keywords: ['code', 'pre'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleCodeBlock().run()
+      },
+    },
+    {
+      id: 'table',
+      title: 'Table',
+      description: 'Insert a simple table',
+      keywords: ['grid'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source)
+          .insertTable?.({ rows: 3, cols: 3, withHeaderRow: true })
+          ?.run()
+      },
+    },
+    {
+      id: 'footnote',
+      title: 'Footnote',
+      description: 'Insert a footnote marker',
+      keywords: ['note', 'reference'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).insertFootnote?.()?.run()
+      },
+    },
+    {
+      id: 'index-marker',
+      title: 'Index marker',
+      description: 'Mark selected text for the index',
+      keywords: ['index'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleIndexMarker?.()?.run()
+      },
+    },
+    {
+      id: 'inline-equation',
+      title: 'Inline equation',
+      description: 'Insert an editable inline equation',
+      keywords: ['math', 'latex'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        // Remove the typed "/…" text, then insert an empty equation and open
+        // its editor immediately (live preview; renders in place on blur).
+        commandChain(editor, range, source).run()
+        insertEditableInlineMath(editor)
+      },
+    },
+    {
+      id: 'display-equation',
+      title: 'Display equation',
+      description: 'Insert an editable centered equation',
+      keywords: ['math', 'latex', 'block'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).run()
+        insertEditableBlockMath(editor)
+      },
+    },
+    {
+      id: 'mermaid',
+      title: 'Mermaid diagram',
+      description: 'Insert a diagram block',
+      keywords: ['diagram', 'flowchart'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).insertMermaidBlock?.()?.run()
+      },
+    },
+  ]
+}
+
+function findSlashCommandMatch(state: EditorState): SlashCommandMatch | null {
+  const { selection } = state
+  if (!selection.empty) return null
+
+  const { $from } = selection
+  const textBefore = $from.parent.textBetween(0, $from.parentOffset, '\0', '\0')
+  const match = /(?:^|\s)\/([\w\s-]{0,48})$/.exec(textBefore)
+  if (!match) return null
+
+  const fullMatch = match[0]
+  const slashOffset = fullMatch.lastIndexOf('/')
+  const from = $from.pos - (fullMatch.length - slashOffset)
+
+  return {
+    range: { from, to: $from.pos },
+    query: match[1]?.trim() ?? '',
+  }
+}
+
+function filterSlashCommandItems(
+  items: SlashCommandItem[],
+  query: string,
+): SlashCommandItem[] {
+  const normalizedQuery = query.toLowerCase()
+  if (!normalizedQuery) return items
+
+  return items
+    .filter(item => {
+      const haystack = [
+        item.title,
+        item.description ?? '',
+        ...(item.keywords ?? []),
+      ]
+        .join(' ')
+        .toLowerCase()
+      return haystack.includes(normalizedQuery)
+    })
+    .slice(0, SLASH_COMMAND_LIMIT)
+}
+
+function injectSlashCommandStyles(): void {
+  if (document.getElementById('ps-slash-command-styles')) return
+
+  const style = document.createElement('style')
+  style.id = 'ps-slash-command-styles'
+  style.textContent = `
+    .ps-slash-command-menu {
+      position: fixed;
+      z-index: var(--platform-z-index-zi-app-menus, 1000);
+      box-sizing: border-box;
+      min-width: 280px;
+      max-width: 340px;
+      padding: 6px;
+      border: 1px solid var(--platform-colors-border, #d7dbe0);
+      border-radius: 10px;
+      background: var(--platform-colors-surface, #fff);
+      box-shadow: 0 14px 34px rgb(23 29 36 / 0.14);
+      color: var(--platform-colors-text, #2e3338);
+      font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+      overflow-x: hidden;
+      overscroll-behavior: contain;
+    }
+
+    .ps-slash-command-item {
+      display: grid;
+      width: 100%;
+      gap: 2px;
+      padding: 8px 10px;
+      border: 0;
+      border-radius: 7px;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      text-align: left;
+      cursor: pointer;
+    }
+
+    .ps-slash-command-section {
+      color: var(--platform-colors-text-tertiary, #8a9097);
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      line-height: 1.2;
+      padding: 9px 10px 5px;
+      text-transform: uppercase;
+    }
+
+    .ps-slash-command-divider {
+      border-top: 1px solid var(--platform-colors-border, #d7dbe0);
+      margin: 6px 4px 2px;
+    }
+
+    .ps-slash-command-item[data-active="true"],
+    .ps-slash-command-item:hover {
+      background: var(--platform-colors-surface-active, #edeff2);
+    }
+
+    .ps-slash-command-title {
+      font-size: 13px;
+      font-weight: 650;
+      line-height: 1.25;
+    }
+
+    .ps-slash-command-description {
+      color: var(--platform-colors-text-secondary, #6e737a);
+      font-size: 12px;
+      line-height: 1.25;
+    }
+  `
+  document.head.appendChild(style)
+}