collavre 0.22.0 → 0.24.0

data/app/javascript/lib/lexical/list_tab_indent.js

@@ -0,0 +1,210 @@
+import {
+  $createParagraphNode,
+  $getSelection,
+  $isRangeSelection,
+  COMMAND_PRIORITY_LOW,
+  INDENT_CONTENT_COMMAND,
+  KEY_TAB_COMMAND,
+  OUTDENT_CONTENT_COMMAND
+} from "lexical"
+import { $createListNode, $isListItemNode, $isListNode } from "@lexical/list"
+
+/**
+ * Tab / Shift+Tab indentation scoped to list items.
+ *
+ * Inside a list, Tab nests the current item (INDENT_CONTENT_COMMAND).
+ * Shift+Tab un-nests it (OUTDENT_CONTENT_COMMAND) when the item is nested;
+ * @lexical/list turns those indent changes into real nested <ul>/<ol> structure.
+ *
+ * At the OUTERMOST level OUTDENT_CONTENT_COMMAND is a no-op (there is no shallower
+ * indent to drop to), so Shift+Tab on a top-level item would do nothing. Other
+ * editors instead remove the list formatting for that item — the item leaves the
+ * list and becomes a normal paragraph. We replicate that here so Shift+Tab always
+ * has a visible, expected effect.
+ *
+ * Outside a list the command is ignored (returns false) so Tab keeps its default
+ * behaviour (moving focus out of the editor) and plain paragraphs never gain an
+ * indent the Markdown-canonical store can't represent cleanly.
+ *
+ * Returns the editor.registerCommand teardown so callers can clean up.
+ */
+export function registerListTabIndentation(editor) {
+  return editor.registerCommand(
+    KEY_TAB_COMMAND,
+    (event) => {
+      const selection = $getSelection()
+      if (!$isRangeSelection(selection)) return false
+      const listItem = $findListItemAncestor(selection)
+      if (!listItem) return false
+
+      event.preventDefault()
+
+      if (event.shiftKey) {
+        // Top-level item: drop out of the list entirely (other editors' behaviour),
+        // because OUTDENT has nothing shallower to move to. Nested item: un-nest one
+        // level via OUTDENT, which @lexical/list collapses back into flat structure.
+        if ($isTopLevelListItem(listItem)) {
+          // A selection can span several top-level items; un-list each so multi-item
+          // Shift+Tab matches the range-aware OUTDENT path instead of only dropping
+          // the anchor's item. Collect the items up front (converting one mutates the
+          // tree) and convert in document order — each conversion splits the list and
+          // leaves the next selected item at the head of the trailing list, so the
+          // result is clean sequential paragraphs.
+          $selectedTopLevelListItems(selection, listItem).forEach(
+            $convertListItemToParagraph
+          )
+          return true
+        }
+        return editor.dispatchCommand(OUTDENT_CONTENT_COMMAND, undefined)
+      }
+
+      return editor.dispatchCommand(INDENT_CONTENT_COMMAND, undefined)
+    },
+    COMMAND_PRIORITY_LOW
+  )
+}
+
+// A list item that exists only to hold a nested list (its first/only child is a
+// ListNode). @lexical/list uses this wrapper to represent indentation.
+function $isNestedListItemWrapper(node) {
+  return $isListItemNode(node) && $isListNode(node.getFirstChild())
+}
+
+function $findListItemAncestor(selection) {
+  const anchorNode = selection.anchor.getNode()
+  if ($isListItemNode(anchorNode)) return anchorNode
+  return anchorNode.getParents().find($isListItemNode) || null
+}
+
+// The distinct top-level list items the selection touches, in document order.
+// getNodes() returns the range's nodes in document order; we map each to its
+// owning list item and keep only top-level, non-wrapper ones (nested items go
+// through OUTDENT instead). Falls back to the anchor item when the range yields
+// nothing useful (e.g. a collapsed selection on an empty item).
+function $selectedTopLevelListItems(selection, fallbackItem) {
+  const seen = new Set()
+  const items = []
+  selection.getNodes().forEach((node) => {
+    const listItem = $isListItemNode(node)
+      ? node
+      : node.getParents().find($isListItemNode)
+    if (!listItem || seen.has(listItem.getKey())) return
+    if (!$isTopLevelListItem(listItem) || $isNestedListItemWrapper(listItem)) return
+    seen.add(listItem.getKey())
+    items.push(listItem)
+  })
+  if (items.length === 0 && fallbackItem) items.push(fallbackItem)
+  return items
+}
+
+// A list item is "top level" when its parent list is not nested inside another
+// list item. This holds both at the document root and inside a blockquote (where
+// the list's parent is the QuoteNode, not the root) — in both cases OUTDENT has
+// nothing shallower to drop to, so the item should leave the list instead.
+function $isTopLevelListItem(listItem) {
+  const parentList = listItem.getParent()
+  if (!$isListNode(parentList)) return false
+  return !$isListItemNode(parentList.getParent())
+}
+
+// Remove a single top-level list item from its list, turning it into a paragraph
+// in the same position. Items before it stay in the original list; items after it
+// move into a fresh trailing list so the surrounding list is split, not flattened.
+function $convertListItemToParagraph(listItem) {
+  const parentList = listItem.getParent()
+  if (!$isListNode(parentList)) return
+
+  const following = listItem.getNextSiblings()
+  // An item can hold both inline content (text) and a nested child list. Only the
+  // inline content belongs in the paragraph — a nested ListNode inside a paragraph
+  // is invalid block structure, so it is promoted to a sibling list block instead.
+  const children = listItem.getChildren()
+  const nestedLists = children.filter($isListNode)
+  const inlineChildren = children.filter((child) => !$isListNode(child))
+  const paragraph = $createParagraphNode()
+
+  parentList.insertAfter(paragraph)
+
+  // Keep block order: paragraph, then any promoted nested lists, then the split-off
+  // trailing items, by chaining insertAfter off the previously inserted block.
+  let anchor = paragraph
+  nestedLists.forEach((nestedList) => {
+    anchor.insertAfter(nestedList)
+    anchor = nestedList
+  })
+
+  if (following.length > 0) {
+    const listType = parentList.getListType()
+    // @lexical/list stores a nested child list as a *wrapper* list item (its only
+    // child is a ListNode) placed right after the parent item. The leading run of
+    // such wrappers are the removed item's own children: promote each wrapper's
+    // inner ListNode up one level as its own block, then drop the emptied wrapper.
+    // Moving the whole ListNode (not just its items) preserves the child list's own
+    // marker type — a bullet child of a numbered parent must stay a bullet list, not
+    // get renumbered. Promoting items rather than the wrapper also empties parentList
+    // so the cleanup below can remove it, avoiding an orphan <li><ul>. Once a real
+    // item appears the run ends; later wrappers belong to it and must stay nested.
+    let promotingChildren = true
+    const trailingItems = []
+    following.forEach((sibling) => {
+      if (promotingChildren && $isNestedListItemWrapper(sibling)) {
+        const childList = sibling.getFirstChild()
+        anchor.insertAfter(childList)
+        anchor = childList
+        sibling.remove()
+      } else {
+        promotingChildren = false
+        trailingItems.push(sibling)
+      }
+    })
+    if (trailingItems.length > 0) {
+      // For ordered lists the trailing items must keep their original numbers
+      // (e.g. "1. a / 2. b / 3. c" → outdent b → c stays 3, not restart at 1).
+      //
+      // When a same-type list was promoted directly before these items (the removed
+      // item's own ordered child list), Lexical's ListNode transform merges the two
+      // adjacent same-type lists and keeps the *first* list's start — a separate
+      // trailing list's start would be silently discarded. So append the trailing
+      // items into that promoted list instead and set its start so the first trailing
+      // item lands on its original value, with the promoted children filling the slots
+      // leading up to it ("1. a / 2. b / [1.] b1 / 3. c" → outdent b → "2. b1 / 3. c").
+      const mergesWithPromoted =
+        $isListNode(anchor) && anchor.getListType() === listType
+      if (mergesWithPromoted) {
+        if (listType === "number") {
+          // Count real items already in the promoted list (nested wrappers don't
+          // advance numbering) so the first trailing item keeps its original value.
+          const promotedItems = anchor
+            .getChildren()
+            .filter((child) => !$isNestedListItemWrapper(child)).length
+          // Clamp to 1: when more children are promoted than the removed item's
+          // value frees up (e.g. "1. b" with children b1, b2 → 1 + 1 - 2 = 0),
+          // a 0/negative start would render literally as "0."/"-1.". Falling back
+          // to 1 just renumbers the merged list sequentially from the top.
+          anchor.setStart(Math.max(1, listItem.getValue() + 1 - promotedItems))
+        }
+        trailingItems.forEach((sibling) => anchor.append(sibling))
+      } else {
+        const trailingStart =
+          listType === "number" ? listItem.getValue() + 1 : undefined
+        const trailingList = $createListNode(listType, trailingStart)
+        trailingItems.forEach((sibling) => trailingList.append(sibling))
+        anchor.insertAfter(trailingList)
+      }
+    }
+  }
+
+  if (inlineChildren.length > 0) {
+    // Moving the existing nodes (not cloning) keeps any caret pointing into them
+    // valid, so the cursor stays where the user was typing.
+    inlineChildren.forEach((child) => paragraph.append(child))
+  } else {
+    paragraph.select()
+  }
+
+  listItem.remove()
+
+  if (parentList.getChildrenSize() === 0) {
+    parentList.remove()
+  }
+}

data/app/javascript/lib/lexical/markdown_serialize.js

@@ -0,0 +1,320 @@
+import {
+  $isTextNode,
+  $isParagraphNode,
+  $isLineBreakNode,
+  $createParagraphNode
+} from "lexical"
+import { $convertToMarkdownString, TRANSFORMERS } from "@lexical/markdown"
+import { TABLE, setCellTransformers } from "./table_transformer"
+
+// Serializes the Lexical editor state to Markdown as the canonical storage
+// format. Standard block/inline features (headings, lists, quotes, code,
+// bold/italic/strikethrough, inline code, links) round-trip through Markdown
+// via the upstream TRANSFORMERS. Features Markdown can't express are emitted as
+// a SMALL, FIXED set of normalized inline HTML fragments:
+//
+//   - text color / background-color  -> <span style="...">
+//   - images / videos / attachments  -> raw <img>/<video>/<a download> tags
+//
+// The HTML shape is normalized (one canonical form per feature) and the CSS
+// values are validated, so the server-side sanitizer can safelist exactly these
+// and the import path (markdown -> HTML -> Lexical) reconstructs them losslessly.
+
+// Only these CSS color values are allowed inside an emitted <span>. Anything
+// else (url(), expression(), javascript:, <, >) is dropped so a crafted inline
+// style can't smuggle script or external requests into stored Markdown.
+const SAFE_COLOR_VALUE =
+  /^(#[0-9a-fA-F]{3,8}|rgba?\([0-9.,%\s]+\)|hsla?\([0-9.,%\s]+\)|var\(--[a-zA-Z0-9-_]+\)|[a-zA-Z]+)$/
+
+function safeColorValue(value) {
+  if (!value) return null
+  const v = value.trim().replace(/;+$/, "").trim()
+  if (!v) return null
+  if (/url\(|expression|javascript:|@import|[<>]/i.test(v)) return null
+  return SAFE_COLOR_VALUE.test(v) ? v : null
+}
+
+function colorBgFromStyle(styleText) {
+  let color = null
+  let background = null
+  ;(styleText || "").split(";").forEach((decl) => {
+    const idx = decl.indexOf(":")
+    if (idx === -1) return
+    const key = decl.slice(0, idx).trim().toLowerCase()
+    const value = decl.slice(idx + 1)
+    if (key === "color") color = safeColorValue(value)
+    else if (key === "background-color") background = safeColorValue(value)
+  })
+  return { color, background }
+}
+
+function escapeHtmlAttr(value) {
+  return String(value == null ? "" : value)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+}
+
+function escapeHtmlText(value) {
+  return String(value == null ? "" : value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+}
+
+// Wrap already-formatted inner Markdown text in a normalized colored <span>, or
+// return null when the style carries no (safe) color/background. The declaration
+// order is fixed (color first) so the same selection always serializes to the
+// same bytes — line-diff/snapshot stability depends on this.
+export function colorSpanMarkup(styleText, inner) {
+  const { color, background } = colorBgFromStyle(styleText)
+  if (!color && !background) return null
+  const decls = []
+  if (color) decls.push(`color: ${color}`)
+  if (background) decls.push(`background-color: ${background}`)
+  // `inner` is the Markdown-formatted text of a colored node. Lexical's export
+  // escapes Markdown punctuation but NOT HTML metacharacters, so colored text
+  // like `<foo>` would become raw markup inside the <span> and get reinterpreted
+  // (and stripped) by the Markdown renderer/sanitizer. Escape <, >, & so user
+  // text stays text. Markdown syntax chars (*, _, `, ~) are left untouched.
+  return `<span style="${decls.join("; ")}">${escapeHtmlText(inner)}</span>`
+}
+
+// Canonical inline HTML for the decorator nodes, matching the shapes the import
+// path (markdown_to_html -> $generateNodesFromDOM) and the server sanitizer
+// expect. Numeric width/height only — Lexical's "inherit" sentinel is dropped.
+export function imageMarkup({ src, altText, width, height }) {
+  let html = `<img src="${escapeHtmlAttr(src)}" alt="${escapeHtmlAttr(altText)}"`
+  if (Number.isFinite(Number(width)) && Number(width) > 0) {
+    html += ` width="${escapeHtmlAttr(width)}"`
+  }
+  if (Number.isFinite(Number(height)) && Number(height) > 0) {
+    html += ` height="${escapeHtmlAttr(height)}"`
+  }
+  return `${html}>`
+}
+
+export function videoMarkup({ src }) {
+  return `<video controls src="${escapeHtmlAttr(src)}"></video>`
+}
+
+export function attachmentMarkup({ src, filename, filesize }) {
+  let html = `<a href="${escapeHtmlAttr(src)}" download="${escapeHtmlAttr(filename)}"`
+  if (filesize != null && filesize !== "") {
+    html += ` data-filesize="${escapeHtmlAttr(filesize)}"`
+  }
+  return `${html}>${escapeHtmlText(filename)}</a>`
+}
+
+// Boilerplate so a transformer can be export-only: import never fires.
+const NEVER = /(?!)/
+
+function exportOnlyTransformer(exportFn, { dependencies = [], type = "text-match" } = {}) {
+  return {
+    dependencies,
+    export: exportFn,
+    importRegExp: NEVER,
+    regExp: NEVER,
+    replace: () => false,
+    trigger: "",
+    type
+  }
+}
+
+// Decorator nodes -> raw HTML. Duck-typed via getType() so this module stays
+// free of the .jsx node classes (kept importable under native-ESM Jest).
+function decoratorMarkup(node) {
+  const type = node.getType ? node.getType() : null
+  if (type === "image") {
+    return imageMarkup({
+      src: node.getSrc?.(),
+      altText: node.getAltText?.(),
+      width: node.__width,
+      height: node.__height
+    })
+  }
+  if (type === "video") {
+    return videoMarkup({ src: node.getSrc?.() })
+  }
+  if (type === "attachment") {
+    return attachmentMarkup({
+      src: node.getSrc?.(),
+      filename: node.getFilename?.(),
+      filesize: node.__filesize
+    })
+  }
+  return null
+}
+
+// A paragraph the user left blank: it carries no real text, only empty text
+// nodes and/or line breaks. (Decorator- or text-bearing paragraphs are NOT
+// blank, so media and real content keep their normal export.) An empty
+// paragraph from pressing Enter has zero children; a run of blank lines that
+// was reopened comes back as ONE paragraph holding N LineBreakNodes (the
+// importer groups consecutive <br> markers together).
+function isBlankParagraph(node) {
+  if (!$isParagraphNode(node)) return false
+  // A blank paragraph inside a table cell is just an empty cell — it must stay
+  // empty (`|  |`), not become a `<br>`. The cell serializer reuses this
+  // transformer set, so exclude paragraphs nested in a cell (duck-typed by type
+  // to keep this module free of the @lexical/table import).
+  const parent = node.getParent ? node.getParent() : null
+  if (parent && parent.getType && parent.getType() === "tablecell") return false
+  return node
+    .getChildren()
+    .every((child) => $isLineBreakNode(child) || ($isTextNode(child) && !child.getTextContent().trim()))
+}
+
+// How many blank lines a blank paragraph represents: one per LineBreakNode, but
+// at least one (a freshly-typed empty paragraph has no line breaks yet still
+// stands for a single blank line). This exact count is what keeps multiple
+// blank lines from multiplying on every save — the reopened paragraph holds N
+// line breaks and must re-emit N markers, not N+1.
+function blankParagraphBreakCount(node) {
+  const breaks = node.getChildren().filter($isLineBreakNode).length
+  return Math.max(1, breaks)
+}
+
+// Blank paragraphs -> one `<br>` per blank line. A `<br>` is a semantic empty
+// line (not a stray space or NBSP): the hard-break renderers keep it as a
+// visible blank line, and because each marker sits in its own block separated
+// by the standard `\n\n`, a blank line after a list no longer gets pulled into
+// the last <li> via lazy continuation. Round-trips: the importer regroups the
+// rendered <br> elements into a blank paragraph that re-exports identically.
+const BLANK_PARAGRAPH_TRANSFORMER = exportOnlyTransformer(
+  (node) =>
+    isBlankParagraph(node) ? Array(blankParagraphBreakCount(node)).fill("<br>").join("\n\n") : null,
+  { type: "element" }
+)
+
+// Colored / highlighted text -> normalized <span>. Falls through (returns null)
+// for uncolored text so the default text-format export still applies.
+const COLOR_TRANSFORMER = exportOnlyTransformer((node, _exportChildren, exportFormat) => {
+  if (!$isTextNode(node)) return null
+  const style = node.getStyle ? node.getStyle() : ""
+  if (!style) return null
+  return colorSpanMarkup(style, exportFormat(node, node.getTextContent()))
+})
+
+// Decorator handler registered as a TEXT-MATCH transformer for media that lives
+// INLINE inside a paragraph (claimed during exportChildren).
+const DECORATOR_TEXT_TRANSFORMER = exportOnlyTransformer((node) => decoratorMarkup(node))
+
+// The SAME handler registered as an ELEMENT transformer for media that is a
+// direct child of the root (the upload plugin's no-selection append path, and
+// imported block-level <img> nodes). $convertToMarkdownString only runs element
+// transformers on top-level nodes — a top-level decorator that matches no element
+// transformer falls back to DecoratorNode#getTextContent() (empty for media),
+// silently dropping it from markdown_source. Without this, the first rich save
+// loses every top-level image/video/file.
+const DECORATOR_ELEMENT_TRANSFORMER = exportOnlyTransformer((node) => decoratorMarkup(node), {
+  type: "element"
+})
+
+// Our custom transformers run first so colored text and decorator nodes are
+// claimed before the upstream defaults (which would drop their style/content).
+export const MARKDOWN_TRANSFORMERS = [
+  TABLE,
+  DECORATOR_ELEMENT_TRANSFORMER,
+  BLANK_PARAGRAPH_TRANSFORMER,
+  DECORATOR_TEXT_TRANSFORMER,
+  COLOR_TRANSFORMER,
+  ...TRANSFORMERS
+]
+
+// Tables serialize their cell content with the same transformer set. Injected
+// here (rather than imported into table_transformer.js) to break the cycle.
+setCellTransformers(MARKDOWN_TRANSFORMERS)
+
+// Fenced code blocks may legitimately contain consecutive blank lines; guard
+// them so the blank-line normalization below never touches a code sample.
+const FENCE_BLOCK = /(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\1[ \t]*(?=\n|$)/g
+
+// Inline code spans (`...`) may legitimately contain the literal text `<br>` or
+// a lone NBSP; guard them too so the blank-line normalization never rewrites the
+// span (which would break it on save). Matched after fences are stashed, so the
+// remaining backtick runs are genuine inline code.
+const INLINE_CODE = /(`+)[^\n]*?\1/g
+
+// Normalize the canonical Markdown projection. Enter produces a real paragraph
+// break (standard `\n\n` separation); a blank line the user typed is preserved
+// as a `<br>` marker (see BLANK_PARAGRAPH_TRANSFORMER). This pass only:
+//   - returns "" for a document with no real content (only whitespace and/or
+//     `<br>` markers), keeping the empty-state placeholder/presence contract,
+//   - migrates legacy NBSP-only blank-line markers (pre-`<br>` content) to a
+//     real `<br>` marker so they stop acting as a CommonMark lazy continuation,
+//   - isolates every `<br>` marker as its own block,
+//   - collapses runs of 3+ newlines to one blank line so block separation stays
+//     canonical and the very first save is round-trip stable,
+//   - trims trailing whitespace.
+// Blank lines and literal `<br>`/NBSP inside code (fenced or inline) are
+// preserved verbatim.
+export function normalizeMarkdownBlankLines(markdown) {
+  // A document of only blank lines (each now a `<br>`) carries no real content,
+  // so strip the markers before the emptiness check.
+  if (!String(markdown).replace(/<br\s*\/?>/gi, "").trim()) return ""
+
+  const guards = []
+  const stash = (match) => `\x00MDGUARD${guards.push(match) - 1}\x00`
+  const guarded = String(markdown)
+    .replace(FENCE_BLOCK, stash)
+    .replace(INLINE_CODE, stash)
+
+  const normalized = guarded
+    // Legacy blank-line markers stored a line of only NBSP (U+00A0). CommonMark
+    // treats NBSP as content — a lazy list continuation — re-introducing the
+    // list-indent bug, so migrate such lines to a real `<br>` marker on save.
+    // (A regular whitespace-only line is already a CommonMark blank line.)
+    .replace(/^[ \t]*\u00A0[ \t\u00A0]*$/gm, "<br>")
+    // Each blank-line marker is its own block: isolate every `<br>` with a blank
+    // line on both sides. Lexical's exporter joins a freshly-typed empty
+    // paragraph to its neighbours with a single `\n`, while a reopened (grouped)
+    // blank paragraph gets `\n\n`; canonicalizing here makes the very first save
+    // byte-identical to the reopen fixpoint regardless of which path produced it.
+    // BLANK_PARAGRAPH_TRANSFORMER always emits a marker alone on its line, so we
+    // only match a `<br>` that is the WHOLE line (anchored ^…$ under /m). A
+    // `<br>` embedded in other content (an in-paragraph hard break or raw inline
+    // HTML such as `<span>foo<br>bar</span>`) is not a marker and is left
+    // untouched — isolating it would rewrite user HTML on save.
+    .replace(/\n*^[ \t]*<br>[ \t]*$\n*/gm, "\n\n<br>\n\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/^\n+/, "")
+    .replace(/\s+$/, "")
+
+  return normalized.replace(/\x00MDGUARD(\d+)\x00/g, (_, n) => guards[Number(n)])
+}
+
+// On reopen, a run of blank-line markers (<br>) comes back grouped into ONE
+// paragraph holding N LineBreakNodes. Lexical renders such a paragraph as N+1
+// visual lines — each break starts a new line on top of the paragraph's own
+// line — so a single typed blank line reopens as TWO, growing by one on every
+// reopen (the "blank lines keep multiplying" bug). Freshly typed blank lines are EMPTY
+// paragraphs instead (zero children, one visual line each). Re-create that
+// structure: replace every all-LineBreakNode paragraph with N empty paragraphs
+// so reopened blank lines match typed ones. Export is unaffected — each empty
+// paragraph still emits exactly one <br> (blankParagraphBreakCount), so the
+// canonical Markdown round-trips byte-for-byte. Paragraphs that mix text with a
+// break (real soft breaks) are left untouched.
+export function splitBlankLineParagraphs(root) {
+  if (!root || !root.getChildren) return
+  root.getChildren().forEach((node) => {
+    if (!$isParagraphNode(node)) return
+    const children = node.getChildren()
+    if (children.length === 0) return
+    if (!children.every($isLineBreakNode)) return
+    for (let i = 0; i < children.length; i++) {
+      node.insertBefore($createParagraphNode())
+    }
+    node.remove()
+  })
+}
+
+// Read the editor state and return canonical Markdown.
+export function lexicalToMarkdown(editor) {
+  let markdown = ""
+  editor.getEditorState().read(() => {
+    markdown = $convertToMarkdownString(MARKDOWN_TRANSFORMERS)
+  })
+  return normalizeMarkdownBlankLines(markdown)
+}

data/app/javascript/lib/lexical/selection_boundary.js

@@ -0,0 +1,58 @@
+import {
+  $isRangeSelection,
+  $isTextNode,
+  $isRootOrShadowRoot
+} from "lexical"
+
+// True when a collapsed selection sits at the very start of the whole document
+// (offset 0 of the first leaf, with no previous siblings up the tree).
+//
+// NOTE: checking `$getCharacterOffsets() === [0, 0]` is NOT enough — that only
+// reports the offset within the current node, so the start of the *second*
+// paragraph (e.g. right after pressing Enter) also reads as [0, 0]. We must walk
+// up the tree confirming there is no earlier content, mirroring
+// isSelectionAtDocumentEnd.
+export function isSelectionAtDocumentStart(selection) {
+  if (!$isRangeSelection(selection) || !selection.isCollapsed()) return false
+
+  const anchor = selection.anchor
+  let node = anchor.getNode()
+  if (!node) return false
+
+  if (anchor.offset !== 0) return false
+
+  while (node && !$isRootOrShadowRoot(node)) {
+    if (node.getPreviousSibling()) return false
+    node = node.getParent()
+  }
+
+  return !!node && $isRootOrShadowRoot(node)
+}
+
+// True when a collapsed selection sits at the very end of the whole document
+// (end of the last leaf, with no following siblings up the tree).
+export function isSelectionAtDocumentEnd(selection) {
+  if (!$isRangeSelection(selection) || !selection.isCollapsed()) return false
+
+  const focus = selection.focus
+  let node = focus.getNode()
+  if (!node) return false
+
+  const offset = focus.offset
+  if ($isTextNode(node)) {
+    if (offset !== node.getTextContentSize()) return false
+  } else if (typeof node.getChildrenSize === "function") {
+    if (offset !== node.getChildrenSize()) return false
+  } else {
+    // Fallback for nodes without children size (e.g., line breaks)
+    const textSize = node.getTextContentSize?.() ?? 0
+    if (offset !== textSize) return false
+  }
+
+  while (node && !$isRootOrShadowRoot(node)) {
+    if (node.getNextSibling()) return false
+    node = node.getParent()
+  }
+
+  return !!node && $isRootOrShadowRoot(node)
+}