@llui/markdown-editor 0.2.12 → 0.2.14

package/src/plugins/mention.ts

@@ -0,0 +1,224 @@
+// Mention plugin — an `@`-triggered typeahead. Same shape as the slash menu, but
+// the candidates come from a configurable `source`, and choosing inserts the
+// mention text (`@label`) rather than running a command. Demonstrates a second
+// typeahead built on the plugin-UI seam with no new machinery.
+
+import {
+  $getSelection,
+  $isRangeSelection,
+  $isTextNode,
+  COMMAND_PRIORITY_HIGH,
+  KEY_ARROW_DOWN_COMMAND,
+  KEY_ARROW_UP_COMMAND,
+  KEY_ENTER_COMMAND,
+  KEY_ESCAPE_COMMAND,
+} from 'lexical'
+import { mergeRegister } from '@lexical/utils'
+import { div, each, text, type Signal } from '@llui/dom'
+import { definePluginUI } from './ui.js'
+import { OVERLAY_Z, hideOverlay, overlayRoot } from './overlay.js'
+import type { MarkdownPlugin } from './types.js'
+
+export interface Mention {
+  id: string
+  label: string
+}
+
+interface Row {
+  id: string
+  label: string
+  active: boolean
+}
+
+interface MentionState {
+  open: boolean
+  query: string
+  items: Row[]
+  index: number
+  x: number
+  y: number
+}
+
+type MentionMsg =
+  | { type: 'show'; query: string; items: Mention[]; x: number; y: number }
+  | { type: 'hide' }
+  | { type: 'move'; delta: number }
+  | { type: 'choose' }
+  | { type: 'click'; index: number }
+
+type MentionEffect = { type: 'insert'; label: string; query: string }
+
+const TRIGGER = /(?:^|\s)@(\w*)$/
+
+const DEFAULT_MENTIONS: readonly Mention[] = [
+  { id: 'franco', label: 'Franco' },
+  { id: 'ada', label: 'Ada' },
+  { id: 'grace', label: 'Grace' },
+  { id: 'linus', label: 'Linus' },
+  { id: 'margaret', label: 'Margaret' },
+]
+
+function withActive(items: readonly Mention[], index: number): Row[] {
+  return items.map((it, i) => ({ id: it.id, label: it.label, active: i === index }))
+}
+
+function $readQuery(): string | null {
+  const selection = $getSelection()
+  if (!$isRangeSelection(selection) || !selection.isCollapsed()) return null
+  const node = selection.anchor.getNode()
+  if (!$isTextNode(node)) return null
+  const before = node.getTextContent().slice(0, selection.anchor.offset)
+  const match = before.match(TRIGGER)
+  return match ? (match[1] ?? '') : null
+}
+
+function caretXY(): { x: number; y: number } {
+  if (typeof window === 'undefined') return { x: 0, y: 0 }
+  const sel = window.getSelection()
+  if (sel && sel.rangeCount > 0) {
+    const rect = sel.getRangeAt(0).getBoundingClientRect()
+    return { x: rect.left, y: rect.bottom + 4 }
+  }
+  return { x: 0, y: 0 }
+}
+
+export interface MentionPluginOptions {
+  /** Resolve candidates for a query (default: a small sample list). */
+  source?: (query: string) => readonly Mention[]
+}
+
+export function mentionPlugin(opts: MentionPluginOptions = {}): MarkdownPlugin {
+  const source =
+    opts.source ??
+    ((query: string) =>
+      DEFAULT_MENTIONS.filter((m) => m.label.toLowerCase().includes(query.toLowerCase())))
+
+  return {
+    name: 'mention',
+    register: (editor, ctx) => {
+      const isActive = (): boolean => editor.getEditorState().read(() => $readQuery() !== null)
+
+      const refresh = (): void => {
+        const query = editor.getEditorState().read(() => $readQuery())
+        if (query === null) {
+          ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'hide' } })
+          return
+        }
+        const items = [...source(query)].slice(0, 8)
+        const { x, y } = caretXY()
+        ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'show', query, items, x, y } })
+      }
+
+      const nav = (delta: number, e: KeyboardEvent | null): boolean => {
+        if (!isActive()) return false
+        e?.preventDefault()
+        ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'move', delta } })
+        return true
+      }
+
+      return mergeRegister(
+        editor.registerUpdateListener(() => refresh()),
+        editor.registerCommand(KEY_ARROW_DOWN_COMMAND, (e) => nav(1, e), COMMAND_PRIORITY_HIGH),
+        editor.registerCommand(KEY_ARROW_UP_COMMAND, (e) => nav(-1, e), COMMAND_PRIORITY_HIGH),
+        editor.registerCommand(
+          KEY_ENTER_COMMAND,
+          (e) => {
+            if (!isActive()) return false
+            e?.preventDefault()
+            ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'choose' } })
+            return true
+          },
+          COMMAND_PRIORITY_HIGH,
+        ),
+        editor.registerCommand(
+          KEY_ESCAPE_COMMAND,
+          () => {
+            if (!isActive()) return false
+            ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'hide' } })
+            return true
+          },
+          COMMAND_PRIORITY_HIGH,
+        ),
+      )
+    },
+    ui: definePluginUI<MentionState, MentionMsg, MentionEffect>({
+      init: () => ({ open: false, query: '', items: [], index: 0, x: 0, y: 0 }),
+      update: (state, msg) => {
+        switch (msg.type) {
+          case 'show':
+            return {
+              open: msg.items.length > 0,
+              query: msg.query,
+              items: withActive(msg.items, 0),
+              index: 0,
+              x: msg.x,
+              y: msg.y,
+            }
+          case 'hide':
+            return hideOverlay(state)
+          case 'move': {
+            if (!state.open || state.items.length === 0) return state
+            const index = (state.index + msg.delta + state.items.length) % state.items.length
+            return { ...state, index, items: withActive(state.items, index) }
+          }
+          case 'choose': {
+            const item = state.items[state.index]
+            if (!state.open || !item) return hideOverlay(state)
+            return [
+              { ...state, open: false },
+              [{ type: 'insert', label: item.label, query: state.query }],
+            ]
+          }
+          case 'click': {
+            const item = state.items[msg.index]
+            if (!item) return state
+            return [
+              { ...state, open: false },
+              [{ type: 'insert', label: item.label, query: state.query }],
+            ]
+          }
+        }
+      },
+      onEffect: (effect, ctx) => {
+        const editor = ctx.editor()
+        if (!editor) return
+        editor.update(() => {
+          const selection = $getSelection()
+          if (!$isRangeSelection(selection) || !selection.isCollapsed()) return
+          const node = selection.anchor.getNode()
+          if (!$isTextNode(node)) return
+          const offset = selection.anchor.offset
+          const start = offset - effect.query.length - 1
+          if (start >= 0) node.spliceText(start, effect.query.length + 1, `@${effect.label} `, true)
+        })
+      },
+      view: ({ state, send }) =>
+        overlayRoot({
+          open: state.at('open'),
+          x: state.at('x'),
+          y: state.at('y'),
+          zIndex: OVERLAY_Z.typeahead,
+          attrs: { 'data-scope': 'md-slash', 'data-part': 'root' },
+          children: () => [
+            each(state.at('items') as Signal<Row[]>, {
+              key: (it) => it.id,
+              render: (item, index) => [
+                div(
+                  {
+                    'data-scope': 'md-slash',
+                    'data-part': 'option',
+                    'data-active': item.map((it) => (it.active ? '' : undefined)),
+                    onMouseDown: (e: MouseEvent) => {
+                      e.preventDefault()
+                      send({ type: 'click', index: index.peek() })
+                    },
+                  },
+                  [text(item.map((it) => `@${it.label}`))],
+                ),
+              ],
+            }),
+          ],
+        }),
+    }),
+  }
+}

package/src/plugins/mermaid.ts

@@ -0,0 +1,115 @@
+// Mermaid plugin — a fenced ```mermaid block rendered via the decorator bridge.
+// The diagram source is editable (persists on blur); an optional `render` callback
+// (e.g. the mermaid library) produces the diagram. Round-trips to a ```mermaid
+// fence.
+//
+// NOTE: place `mermaidPlugin()` BEFORE `corePlugin()` in the plugins array so its
+// multiline transformer matches ```mermaid before the generic code-block one.
+
+import { type LexicalNode } from 'lexical'
+import { $insertNodeToNearestRoot } from '@lexical/utils'
+import type { MultilineElementTransformer } from '@lexical/markdown'
+import {
+  $createLLuiDecoratorNode,
+  $isLLuiDecoratorNode,
+  LLuiDecoratorNode,
+  decoratorBridge,
+} from '@llui/lexical'
+import { div, text, type Mountable, type Signal } from '@llui/dom'
+import type { MarkdownPlugin } from './types.js'
+import { renderedPreview, type PreviewRender } from './_preview.js'
+
+const BRIDGE_TYPE = 'mermaid'
+
+interface MermaidData {
+  code: string
+}
+
+function isMermaidData(value: unknown): value is MermaidData {
+  return (
+    typeof value === 'object' && value !== null && typeof (value as MermaidData).code === 'string'
+  )
+}
+
+const stop = (e: Event): void => e.stopPropagation()
+
+export interface MermaidPluginOptions {
+  /** Render the diagram source to an HTML string (e.g. mermaid). When omitted,
+   * the raw source is shown in a styled box. */
+  /** Render the mermaid source to a preview. Return a DOM `Node` (mounted
+   * directly, no sanitization) or a **trusted HTML string** (injected as-is
+   * — sanitize it yourself, e.g. via DOMPurify, since it carries document
+   * content). See `renderedPreview`. */
+  render?: PreviewRender
+}
+
+export function mermaidPlugin(opts: MermaidPluginOptions = {}): MarkdownPlugin {
+  const bridge = decoratorBridge<MermaidData>(BRIDGE_TYPE, (data, api) => {
+    const children: Mountable[] = [
+      div(
+        {
+          'data-part': 'source',
+          contenteditable: 'true',
+          role: 'textbox',
+          'aria-label': 'Mermaid source',
+          onKeyDown: stop,
+          onBeforeInput: stop,
+          onPaste: stop,
+          onBlur: (e: FocusEvent) => {
+            const code = (e.target as HTMLElement).textContent ?? ''
+            if (code !== data.peek().code) api.update({ code })
+          },
+        },
+        [text(data.at('code') as Signal<string>)],
+      ),
+    ]
+    if (opts.render) {
+      children.push(renderedPreview(data.at('code') as Signal<string>, opts.render))
+    }
+    return [
+      div({ 'data-scope': 'md-mermaid', 'data-part': 'root', contenteditable: 'false' }, children),
+    ]
+  })
+
+  const transformer: MultilineElementTransformer = {
+    dependencies: [LLuiDecoratorNode],
+    export: (node: LexicalNode): string | null => {
+      if (!$isLLuiDecoratorNode(node) || node.getBridgeType() !== BRIDGE_TYPE) return null
+      const data = node.getData()
+      return isMermaidData(data) ? '```mermaid\n' + data.code + '\n```' : null
+    },
+    regExpStart: /^```mermaid$/,
+    regExpEnd: /^```$/,
+    replace: (rootNode, _children, _startMatch, _endMatch, linesInBetween): boolean => {
+      const lines = [...(linesInBetween ?? [])]
+      while (lines.length > 0 && lines[0] === '') lines.shift()
+      while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+      rootNode.append($createLLuiDecoratorNode(BRIDGE_TYPE, { code: lines.join('\n') }))
+      return true
+    },
+    type: 'multiline-element',
+  }
+
+  return {
+    name: 'mermaid',
+    nodes: [LLuiDecoratorNode],
+    decorators: [bridge],
+    transformers: [transformer],
+    items: [
+      {
+        id: 'mermaid',
+        label: 'Diagram',
+        icon: 'mermaid',
+        group: 'insert',
+        keywords: ['mermaid', 'diagram', 'flowchart', 'graph'],
+        run: (editor) =>
+          editor.update(() =>
+            $insertNodeToNearestRoot(
+              $createLLuiDecoratorNode(BRIDGE_TYPE, { code: 'graph TD\n  A --> B' }),
+            ),
+          ),
+        surfaces: ['slash', 'context'],
+      },
+    ],
+  }
+}

package/src/plugins/overlay.ts

@@ -0,0 +1,138 @@
+// Shared overlay primitive for plugin-UI surfaces (context menu, slash/mention
+// typeaheads, floating toolbar, table tools). Every one of these is a portaled,
+// viewport-positioned panel whose `{ open, x, y }` lives in pure, JSON state and
+// is rendered with `show → portal → fixed-positioned div`. Factoring that single
+// shape here keeps positioning testable (a plain style string, not imperative
+// floating-ui calls) and removes the copy-paste that otherwise accumulates one
+// near-identical state machine per overlay plugin.
+//
+// Anchored positioning via `@llui/components`' `attachFloating` (floating-ui) was
+// considered: it gives flip/shift/auto-update for free but needs a live element
+// ref and async, jsdom-untestable DOM writes — a poor fit for overlays whose
+// position is derived from a transient caret/pointer/element rect each `register`
+// tick. The pure-state idiom below covers scroll/resize via {@link onViewportChange}.
+//
+// ## Stacking order (z-index)
+// A single documented scale so overlays never tie and obscure each other:
+//   60 — typeaheads (slash, mention)        — caret-anchored, lowest
+//   61 — context menu                        — pointer-anchored
+//   62 — floating selection toolbar          — selection-anchored bubble
+//   63 — table tools                         — element-anchored, sits over a table
+// The values live with each plugin's view; this comment is the source of truth.
+
+import {
+  div,
+  derived,
+  onMount,
+  portal,
+  show,
+  type Mountable,
+  type Renderable,
+  type Signal,
+} from '@llui/dom'
+import { registerNestedLayer } from '@llui/components/utils'
+
+export const OVERLAY_Z = {
+  typeahead: 60,
+  contextMenu: 61,
+  floatingToolbar: 62,
+  tableTools: 63,
+} as const
+
+const toMountables = (r: Renderable): Mountable[] => [...r]
+
+// Unique marker per overlay instance so its portal root can be located while
+// open. Every overlayRoot is a body-level sibling portal; without declaring it
+// as a nested layer, a host `dialog.overlay()` mis-reads an interaction inside
+// it as "outside" and dismisses (see @llui/components registerNestedLayer).
+let layerSeq = 0
+const NESTED_LAYER_ATTR = 'data-llui-nested-layer'
+
+export interface OverlayRootConfig {
+  /** Whether the overlay is shown. */
+  open: Signal<boolean>
+  /** Viewport x of the anchor point (px). */
+  x: Signal<number>
+  /** Viewport y of the anchor point (px). */
+  y: Signal<number>
+  /** Stacking level — use {@link OVERLAY_Z}. */
+  zIndex: number
+  /** Extra CSS appended after positioning (e.g. a centering/lift transform). */
+  transform?: string
+  /** Attributes for the positioned element (`data-scope`/`data-part`, handlers). */
+  attrs: Record<string, unknown>
+  /** Optional siblings rendered inside the portal before the root (e.g. a backdrop). */
+  before?: () => Renderable
+  /** The positioned element's children. */
+  children: () => Renderable
+}
+
+/**
+ * A portaled, `position:fixed` overlay placed at `(x, y)` and shown while `open`.
+ * Returns the `Renderable` a plugin's `view` yields directly. The emitted style is
+ * a deterministic string — `position:fixed;left:${x}px;top:${y}px;z-index:${z}` plus
+ * an optional `transform` — so positioning is unit-testable.
+ */
+export function overlayRoot(cfg: OverlayRootConfig): Renderable {
+  const style = derived(
+    cfg.x,
+    cfg.y,
+    (x, y) =>
+      `position:fixed;left:${x}px;top:${y}px;z-index:${cfg.zIndex}` +
+      (cfg.transform ? `;${cfg.transform}` : ''),
+  ) as Signal<string>
+  const layerId = `mdo-${++layerSeq}`
+  return [
+    // Register once for the overlay's lifetime; the resolver returns the live
+    // portal root only while open (and nothing when closed/unmounted), so the
+    // single registration tracks open/closed without per-toggle churn.
+    onMount(() =>
+      registerNestedLayer(() => {
+        if (typeof document === 'undefined') return []
+        const el = document.querySelector(`[${NESTED_LAYER_ATTR}="${layerId}"]`)
+        return el ? [el] : []
+      }),
+    ),
+    show(cfg.open, () => [
+      portal(() => [
+        ...(cfg.before ? toMountables(cfg.before()) : []),
+        div({ ...cfg.attrs, [NESTED_LAYER_ATTR]: layerId, style }, toMountables(cfg.children())),
+      ]),
+    ]),
+  ]
+}
+
+/** Guarded close: collapse `open` to false, preserving the reference when already
+ * closed so the host doesn't reconcile a no-op. */
+export function hideOverlay<S extends { open: boolean }>(state: S): S {
+  return state.open ? { ...state, open: false } : state
+}
+
+/**
+ * Run `run` (debounced to one call per animation frame) whenever the viewport
+ * changes — any ancestor scroll or a window resize. Overlays anchored to a
+ * persistent element (a table) or a live selection must reposition on scroll;
+ * editor update listeners alone never fire for a plain scroll. Returns a cleanup
+ * that removes the listeners. No-op (and cleanup is a no-op) outside the browser.
+ */
+export function onViewportChange(run: () => void): () => void {
+  if (typeof window === 'undefined' || typeof requestAnimationFrame !== 'function') {
+    return () => {}
+  }
+  let pending = 0
+  const handler = (): void => {
+    if (pending) return
+    pending = requestAnimationFrame(() => {
+      pending = 0
+      run()
+    })
+  }
+  // Capture phase so scrolls in any nested scroll container are caught.
+  window.addEventListener('scroll', handler, true)
+  window.addEventListener('resize', handler)
+  return () => {
+    window.removeEventListener('scroll', handler, true)
+    window.removeEventListener('resize', handler)
+    if (pending) cancelAnimationFrame(pending)
+  }
+}

package/src/plugins/single-block.ts

@@ -0,0 +1,193 @@
+// The single-block plugin: constrains the editor to exactly ONE paragraph that
+// holds only inline content (bold / italic / strikethrough / code, optionally
+// links). No headings, lists, quotes, code blocks, or multiple paragraphs.
+//
+// It enforces the invariant two ways, so it holds no matter how content arrives
+// (typing, the markdown seed, or a paste):
+//   1. The transformer set contributes ONLY inline text-format transformers, so
+//      block markdown (`# `, `- `, `> `, fenced code) is never parsed into block
+//      nodes — `registerMarkdownShortcuts` and `$convertFromMarkdownString` both
+//      read from this set.
+//   2. A RootNode transform coalesces the document back to a single paragraph of
+//      inline leaves whenever anything slips through (a multi-paragraph paste, a
+//      multi-line seed). Enter is intercepted so it never splits the paragraph.
+//
+// `singleBlockPlugin()` REPLACES the default plugin set — pass it instead of
+// `corePlugin()`. A dev-only guard warns when block-contributing plugins are
+// composed alongside it (since a plugin is additive and can't un-register them).
+
+import {
+  $createLineBreakNode,
+  $createParagraphNode,
+  $createTextNode,
+  $getSelection,
+  $isElementNode,
+  $isLineBreakNode,
+  $isParagraphNode,
+  $isRangeSelection,
+  $isTextNode,
+  COMMAND_PRIORITY_HIGH,
+  KEY_ENTER_COMMAND,
+  RootNode,
+  type ElementNode,
+  type LexicalNode,
+  type ParagraphNode,
+} from 'lexical'
+import { mergeRegister } from '@lexical/utils'
+import { LinkNode } from '@lexical/link'
+import { LINK, type Transformer } from '@lexical/markdown'
+import type { CommandItem, MarkdownPlugin } from './types.js'
+import { inlineItems, type InlineFormat } from './inline.js'
+import { INLINE_TEXT_TRANSFORMERS } from '../transformers/gfm.js'
+
+export type { InlineFormat }
+
+// `import.meta.env.DEV` is substituted by Vite/Rollup at build time; raw tsc /
+// vitest see it as undefined, so the dev guard stays off there unless the
+// bundler sets it. (Augmented locally so the package carries no build-tool dep.)
+declare global {
+  interface ImportMeta {
+    env?: { DEV?: boolean; MODE?: string }
+  }
+}
+
+export interface SingleBlockPluginOptions {
+  /** Inline formats surfaced as toolbar items.
+   * Default `['bold', 'italic', 'strikethrough', 'code']`. NOTE: this limits the
+   * toolbar buttons only — markdown syntax (`*x*`) and Ctrl/⌘ shortcuts still
+   * apply every inline format, and all inline markdown round-trips regardless. */
+  formats?: readonly InlineFormat[]
+  /** Allow soft line breaks within the single paragraph. When `false` (default)
+   * Enter is inert and pasted/seeded line breaks collapse to spaces — a strict
+   * single-line field. When `true`, Enter inserts a `\n` and merged lines are
+   * joined with a line break instead of a space. A new paragraph is never made. */
+  allowLineBreaks?: boolean
+  /** Register `LinkNode` + the markdown link transformer so inline links
+   * round-trip. Default `false`. Compose with `linkPlugin()` for the toolbar
+   * button + insert dialog. */
+  link?: boolean
+}
+
+/** Is this node an inline leaf that belongs directly inside a paragraph? */
+function isInlineLeaf(node: LexicalNode): boolean {
+  return $isTextNode(node) || $isLineBreakNode(node) || ($isElementNode(node) && node.isInline())
+}
+
+/** Decompose a block element into "lines" — each line is the inline content of
+ * one leaf block (paragraph, heading, list item, …). Recurses through nested
+ * block containers (a list → its items) so every leaf block becomes its own
+ * line; this is what lets adjacent list items be separator-joined rather than
+ * mashed together. */
+function blockLines(node: ElementNode): LexicalNode[][] {
+  const children = node.getChildren()
+  const hasBlockChildren = children.some((c) => $isElementNode(c) && !c.isInline())
+  if (!hasBlockChildren) {
+    return [children.filter(isInlineLeaf)]
+  }
+  const lines: LexicalNode[][] = []
+  for (const child of children) {
+    if ($isElementNode(child) && !child.isInline()) lines.push(...blockLines(child))
+    else if (isInlineLeaf(child)) lines.push([child])
+  }
+  return lines
+}
+
+/** Collapse every line break in a paragraph to a single space (single-line
+ * mode) so adjacent lines don't mash into one word. */
+function collapseLineBreaks(para: ParagraphNode): void {
+  for (const child of para.getChildren()) {
+    if ($isLineBreakNode(child)) child.replace($createTextNode(' '))
+  }
+}
+
+/** Coalesce the document to exactly one paragraph of inline content. Returns the
+ * `RootNode` transform the plugin registers. */
+function makeEnforce(allowLineBreaks: boolean): (root: RootNode) => void {
+  return (root) => {
+    const children = root.getChildren()
+
+    // Fast path: already a single paragraph — only fix stray line breaks.
+    if (children.length === 1 && $isParagraphNode(children[0])) {
+      if (!allowLineBreaks) collapseLineBreaks(children[0])
+      return
+    }
+
+    // Gather the inline content of every leaf block as a separate line.
+    const lines: LexicalNode[][] = []
+    for (const child of children) {
+      if ($isElementNode(child)) {
+        if (child.isInline()) lines.push([child])
+        else lines.push(...blockLines(child))
+      } else if (isInlineLeaf(child)) {
+        lines.push([child])
+      }
+    }
+
+    const para = $createParagraphNode()
+    let first = true
+    for (const line of lines) {
+      if (line.length === 0) continue
+      if (!first) para.append(allowLineBreaks ? $createLineBreakNode() : $createTextNode(' '))
+      for (const node of line) para.append(node)
+      first = false
+    }
+    if (!allowLineBreaks) collapseLineBreaks(para)
+    root.clear()
+    root.append(para)
+  }
+}
+
+export function singleBlockPlugin(opts: SingleBlockPluginOptions = {}): MarkdownPlugin {
+  const allowLineBreaks = opts.allowLineBreaks ?? false
+  const linkEnabled = opts.link ?? false
+
+  const items: CommandItem[] = inlineItems(opts.formats)
+
+  const transformers: Transformer[] = [...INLINE_TEXT_TRANSFORMERS]
+  if (linkEnabled) transformers.push(LINK)
+
+  const enforce = makeEnforce(allowLineBreaks)
+
+  const onEnter = (event: KeyboardEvent | null): boolean => {
+    if (!allowLineBreaks) {
+      // Inert: never split the paragraph, never insert a break.
+      event?.preventDefault()
+      return true
+    }
+    // Convert a plain Enter (which would split the paragraph) into a soft line
+    // break; let Shift+Enter fall through to the default soft-break handler.
+    if (event && event.shiftKey) return false
+    event?.preventDefault()
+    const selection = $getSelection()
+    if ($isRangeSelection(selection)) selection.insertLineBreak()
+    return true
+  }
+
+  return {
+    name: 'single-block',
+    ...(linkEnabled ? { nodes: [LinkNode] } : {}),
+    transformers,
+    items,
+    // Dev guard: single-block REPLACES the default plugin set, but a plugin is
+    // additive and can't un-register a sibling's block contributions. If another
+    // plugin's command items introduce block/structural content, warn loudly so
+    // the silently-broken `[corePlugin(), singleBlockPlugin()]` combo is caught.
+    onItems: (all) => {
+      if (import.meta.env?.DEV !== true) return
+      const structural = all.filter((i) => i.group && i.group !== 'inline' && i.group !== 'history')
+      if (structural.length === 0) return
+      const ids = structural.map((i) => i.id).join(', ')
+      console.warn(
+        `[llui] singleBlockPlugin: other plugins contribute block/structural commands (${ids}). ` +
+          `single-block REPLACES the default plugin set — pass it INSTEAD OF corePlugin (and any ` +
+          `block/insert plugins). Block content may otherwise reappear and the single-paragraph ` +
+          `constraint won't hold.`,
+      )
+    },
+    register: (editor) =>
+      mergeRegister(
+        editor.registerNodeTransform(RootNode, enforce),
+        editor.registerCommand(KEY_ENTER_COMMAND, onEnter, COMMAND_PRIORITY_HIGH),
+      ),
+  }
+}